-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Finalise names of everything in preparation for the first release
- Loading branch information
Showing
6 changed files
with
122 additions
and
119 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,119 +1,80 @@ | ||
| # Project is under migration | ||
| The installation instructions still point to the old binaries, the project has changed owners but I haven't had a chance to publish binaries under my name yet. Apologies. | ||
|
|
||
| # bs-atdgen-generator | ||
| # rescript-atdgen-generator | ||
|
|
||
| [Atdgen](https://github.com/ahrefs/atd) prebuilt binaries for 3 major OS platforms. | ||
|
|
||
| This is capped at version 2.15.0, after that | ||
| This is capped at version 2.15.0, after which BuckleScript support (which ReScript relies on) was removed. | ||
| https://github.com/ahrefs/atd/pull/375 | ||
|
|
||
| If `atd` proves to be a popular tool for ReScript projects it can be restored fairly easily. | ||
|
|
||
| ## Getting started | ||
|
|
||
| (Prefer example? Check the [test](./test) folder) | ||
|
|
||
| With yarn: | ||
| ### Runtime library installation | ||
|
|
||
| ``` | ||
| yarn add -D @jchavarri/bs-atdgen-generator | ||
| yarn --check-files | ||
| ``` | ||
| This tool will not work without a library that implements the ATD BuckleScript runtime API. A ReScript implementation is in progress, in the meantime [`bs-atdgen-codec-runtime`](https://www.npmjs.com/package/@ahrefs/bs-atdgen-codec-runtime) still works - but not on ReScript 11. | ||
|
|
||
| Tell bsb which files need to be processed: | ||
| ### Generator installation | ||
|
|
||
| ```json | ||
| "generators": [ | ||
| { | ||
| "name": "atd_t", | ||
| "command": "yarn run atdgen -t $in" | ||
| }, | ||
| { | ||
| "name": "atd_bs", | ||
| "command": "yarn run atdgen -bs $in" | ||
| } | ||
| ], | ||
| ``` | ||
| With yarn or npm: | ||
|
|
||
| Or with node: | ||
| ``` | ||
| npm install @jchavarri/bs-atdgen-generator --save-dev | ||
| yarn add -D rescript-atdgen-generator | ||
| ``` | ||
| ``` | ||
| npm i -D rescript-atdgen-generator | ||
| ``` | ||
|
|
||
| And then: | ||
| We then need to define `atd` as a generator in `rescript.json`. For compatibility with windows development, the recommended approach is a direct reference to `atdgen.exe`. Generators are run in the `lib/bs` folder context, so a leading `../..` is required: | ||
|
|
||
| ```json | ||
| "generators": [ | ||
| { | ||
| "name": "atd_t", | ||
| "command": "npx atdgen -t $in" | ||
| "name": "atd_types", | ||
| "command": "../../node_modules/rescript-atdgen-generator/atdgen.exe -t $in" | ||
| }, | ||
| { | ||
| "name": "atd_bs", | ||
| "command": "npx atdgen -bs $in" | ||
| "name": "atd_runtime", | ||
| "command": "../../node_modules/rescript-atdgen-generator/atdgen.exe -bs $in" | ||
| } | ||
| ], | ||
| ``` | ||
|
|
||
| Now that the generator is defined, add the files that need to be processed to `sources` (still in `bsconfig`): | ||
| If windows compatibility is not required, or for more complex monorepo scenarios, these commands can be replaced by the shorter `npx atdgen -t $in` and `npx atdgen -bs $in` (or using `yarn run` instead of `npx`). This approach is however a little slower due to the extra nodejs invocations. | ||
|
|
||
| Now that the generator is defined, add the files that need to be processed to `sources`. ReScript requires a manual definition for every file that the generator will process. For `atd`, this means a pair of entries must be defined for _every_ `.atd` file in your project. Both "types" and "runtime" representations are required, and each generates both an interface and a code file. | ||
|
|
||
| ```json | ||
| "sources": { | ||
| "dir" : "src", | ||
| "subdirs" : true, | ||
| "generators": [ | ||
| { | ||
| "name": "atd_t", | ||
| "edge": ["meetup_t.ml", "meetup_t.mli", ":", "meetup.atd"] | ||
| }, | ||
| { | ||
| "name": "atd_bs", | ||
| "edge": ["meetup_bs.ml", "meetup_bs.mli", ":", "meetup.atd"] | ||
| } | ||
| ] | ||
| // given a `my-generated-source` folder, define generators for the file `meetup.atd` in that folder. | ||
| // it is not necessary to have a dedicated folder for generated sources, | ||
| // but it does help avoid generated files getting in the way. | ||
| { | ||
| "dir": "my-generated-source", | ||
| "generators": [ | ||
| { | ||
| "name": "atd_types", | ||
| "edge": ["meetup_t.ml", "meetup_t.mli", ":", "meetup.atd"] | ||
| }, | ||
| { | ||
| "name": "atd_runtime", | ||
| "edge": ["meetup_bs.ml", "meetup_bs.mli", ":", "meetup.atd"] | ||
| } | ||
| ] | ||
| }, | ||
| // ...other source folders | ||
| "src1", | ||
| "src2" | ||
| }, | ||
| ``` | ||
|
|
||
| ## For Windows users | ||
|
|
||
| Unfortunately, it's not possible for `npx` or `yarn run` to work directly in Windows environments, due to | ||
| the way [ninja calls CreateProcess](https://github.com/jchavarri/bs-atdgen-generator/pull/3#issue-415706268). | ||
| The syntax here is a little weird, the `edge` array defines a build syntax recognised by the compiler. The order of this array is very important; it must be the two files that `atd` generates, a `:`, and then the source file that serves as the input to the generator command. | ||
|
|
||
| In order to use atdgen for this platform, there are two options: | ||
| Updates to the source file are what the compiler uses to determine whether the generator needs to run. The generated files can freely be ignored by source control. | ||
|
|
||
| #### 1. Use relative path | ||
| ## License and Credits | ||
|
|
||
| In `bsconfig.json`: | ||
|
|
||
| ```diff | ||
| "generators": [ | ||
| { | ||
| "name": "atd_t", | ||
| - "command": "npx atdgen -t $in" | ||
| + "command": "../../node_modules/\@jchavarri/bs-atdgen-generator/atdgen.exe -t $in" | ||
| }, | ||
| { | ||
| "name": "atd_bs", | ||
| - "command": "npx atdgen -bs $in" | ||
| + "command": "../../node_modules/\@jchavarri/bs-atdgen-generator/atdgen.exe -bs $in" | ||
| } | ||
| ], | ||
| ``` | ||
|
|
||
| #### 2. Use `cmd /c`: | ||
|
|
||
| ```diff | ||
| "generators": [ | ||
| { | ||
| "name": "atd_t", | ||
| - "command": "npx atdgen -t $in" | ||
| + "command": "cmd /c npx atdgen -t $in" | ||
| }, | ||
| { | ||
| "name": "atd_bs", | ||
| - "command": "npx atdgen -bs $in" | ||
| + "command": "cmd /c npx atdgen -bs $in" | ||
| } | ||
| ], | ||
| ``` | ||
| All code is licensed as MIT. See [LICENSE](LICENSE). | ||
|
|
||
| Both solutions are shell independent, and work with both Powershell and Windows bash. | ||
| This project was transferred to me by [Javier Chávarri](https://github.com/jchavarri) after it was abandoned following the switch of [ahrefs](https://github.com/ahrefs) to Melange. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,17 @@ | ||
| { | ||
| "name": "bs-atdgen-generator-integration-test", | ||
| "name": "rescript-atdgen-generator-integration-test", | ||
| "version": "0.1.0", | ||
| "scripts": { | ||
| "build": "bsb -make-world", | ||
| "start": "bsb -make-world -w", | ||
| "clean": "bsb -clean-world" | ||
| "build": "rescript", | ||
| "start": "rescript build -w", | ||
| "clean": "rescript clean" | ||
| }, | ||
| "license": "MIT", | ||
| "devDependencies": { | ||
| "@jchavarri/bs-atdgen-generator": "0.0.9", | ||
| "bs-platform": "7.3.2" | ||
| "@jchavarri/bs-atdgen-generator": "0.1.0", | ||
| "rescript": "10.1.4" | ||
| }, | ||
| "dependencies": { | ||
| "@ahrefs/bs-atdgen-codec-runtime": "^2.0.1" | ||
| "@ahrefs/bs-atdgen-codec-runtime": "^2.2.0" | ||
| } | ||
| } |