You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/development.md
+38-14Lines changed: 38 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,7 +39,7 @@ Modules with **\[\<AutoOpen\>\]** does not require `open` to use.
39
39
40
40
- OCaml 4.08 or higher
41
41
-[js_of_ocaml](https://github.com/ocsigen/js_of_ocaml) should be installed to your opam switch.
42
-
- The latest [gen_js_api](https://github.com/LexiFi/gen_js_api) is already present in `test/lib/gen_js_api` as a git submodule. Run `git submodule update --init --recursive`.
42
+
- The latest [gen_js_api](https://github.com/LexiFi/gen_js_api) is already present in `test/jsoo/lib/gen_js_api` as a git submodule. Run `git submodule update --init --recursive`.
43
43
44
44
- Node 14.0 or higher
45
45
-[yarn](https://yarnpkg.com/) is required.
@@ -56,17 +56,41 @@ The resulting `dist/ts2ocaml.js` is then ready to run through `node`.
56
56
57
57
## Testing
58
58
59
-
`dotnet fake build -t Test` builds the tool (as described above) and then performs the followings:
60
-
- Test the tool with the following packages:
59
+
`dotnet fake build -t Test` builds the tool and then performs the followings:
60
+
61
+
### Test the tool for [`js_of_ocaml` target](js_of_ocaml.md)
62
+
63
+
- Generate bindings for the following packages:
61
64
- TypeScript standard libraries (`node_modules/typescript/lib/lib.*.d.ts`)
62
-
-`typescript` (binding for TypeScript compiler API)
63
-
-`react`
64
-
-`scheduler/tracing`
65
-
-`csstype`
66
-
-`prop-types`
67
-
-`react-modal`
68
-
-`yargs`
69
-
-`yargs-parser`
70
-
- The output files will be placed into `output/`
71
-
- Copy the resulting OCaml bindings to `test/src/`
72
-
- Perform `dune build` in `test/`
65
+
-`typescript` with the `full` preset (involving a lot of inheritance)
66
+
-`react` with the `full` preset (depending on both `full` packages and `safe` packages)
67
+
-`scheduler/tracing` (`safe`)
68
+
-`csstype` (`full`)
69
+
-`prop-types` (`safe`)
70
+
-`react-modal` with the `full` preset (depending on a `full` package)
71
+
-`yargs` with the `safe` preset (depending on a `safe` package)
72
+
-`yargs-parser` (`safe`)
73
+
- The bindings will be placed into `output/test_jsoo/`
74
+
- Copy the bindings to `test/jsoo/src/`
75
+
- Perform `dune build` in `test/jsoo/`
76
+
77
+
> Tests for other targets will be added here
78
+
79
+
## Publishing
80
+
81
+
`dotnet fake build -t Publish` builds the tool, runs the tests, and then performs the followings:
82
+
83
+
### Prepare for publishing the standard library for [`js_of_ocaml` target](js_of_ocaml.md) to the `jsoo-stdlib` branch
84
+
85
+
- Copy `ts2ocaml_*.mli` from `output/test_jsoo/` to `dist_jsoo/src/`
86
+
- Copy `ts2ocaml_*.ml` from `test/jsoo/_build/default/src/` to `dist_jsoo/src/`
87
+
- Set the correct `version` in `dist_jsoo/dune-project`
88
+
- Perform `dune build` in `dist_jsoo/` to generate `.opam` file and check if it compiles
89
+
90
+
GitHub Action `publish.yml` is configured to push the `dist_jsoo` directory to the `jsoo-stdlib` branch.
91
+
92
+
### Prepare for publishing the tool to NPM
93
+
94
+
- Set the correct `version` in `package.json`
95
+
96
+
GitHub Action `publish.yml` is configured to publish `ts2ocaml` to NPM.
`ts2ocaml` is a powerful tool, but there are so many options and also some caverts.
9
+
10
+
Therefore, we first provide a walkthrough to use this tool for your project.
11
+
12
+
The documentation for the `ts2ocaml` command and its options comes after the walkthrough, starting with the [Usage](#usage) setion.
13
+
14
+
## Requirements
15
+
16
+
`ts2ocaml` for `js_of_ocaml` generates `.mli` files, which should then be processed with [`LexiFi/gen_js_api`](https://github.com/LexiFi/gen_js_api).
17
+
18
+
You should use the latest `gen_js_api` as `ts2ocaml` uses the latest features of `gen_js_api`.
19
+
As of Oct 2021, most of the required features have not been present in the latest version in opam.
20
+
So you would have to either do
21
+
22
+
*`opam pin add gen_js_api https://github.com/LexiFi/gen_js_api`**(recommended)**, or
23
+
*`git submodule`[their repository](https://github.com/LexiFi/gen_js_api) to the `lib` directory of your OCaml project.
24
+
- Note that if you use `gen_js_api` via a submodule, it might conflict with [`ts2ocaml-jsoo-stdlib`](#using-ts2ocaml-jsoo-stdlib-package) which is installed via `ocaml pin add`.
25
+
- Therefore, this would work only if you are going to do [`ts2ocaml jsoo --create-minimal-lib`](#using---create-minimal-lib--create-minimal-stdlib).
26
+
27
+
## Adding the standard library
28
+
29
+
Any bindings to JS packages, not limited to the ones generated by `ts2ocaml`, need a standard library to compile and run, which mainly consists of the bindings to JS and DOM APIs.
30
+
31
+
Actually, `ts2ocaml` is so powerful that it is capable of generating the standard library for itself.
32
+
33
+
However, the resulting code is rather big (~20MB in `.ml`, ~40MB in `.cma`), so letting users to generate it themselves and add it to their project is not really a good option. Most users would want to use an OPAM package instead.
34
+
35
+
Also, we understand not everyone wants to install such a big library, especially when they already have their preferred bindings for JS and DOM APIs. Such users would only want a minimal standard library.
36
+
37
+
To fulfill both needs, we've made two ways to add the standard library.
38
+
39
+
### Using `ts2ocaml-jsoo-stdlib` package
40
+
41
+
This package contains the full bindings for JS, DOM, and Web Worker API, generated with the [`full` preset](#choosing-a-preset).
42
+
43
+
As described in [Requirements](#requirements), `ts2ocaml` needs the latest `gen_js_api`, which is still not present in OPAM repository.
44
+
So, `ts2ocaml-jsoo-stdlib` is currently **not in OPAM repository**.
45
+
46
+
To install it to your OPAM switch, we recommend you to use [`opam pin`](https://opam.ocaml.org/doc/Usage.html#opam-pin).
47
+
48
+
The standard library for `ts2ocaml` version `X.Y.Z` is available as the `jsoo-stdlib-vX.Y.Z` tag in this repository.
49
+
Check the version of `ts2ocaml` with `ts2ocaml --version` and do the following:
### Using [`--create-minimal-lib`](#--create-minimal-stdlib)
61
+
62
+
`ts2ocaml jsoo --create-minimal-lib` generates a minimal standard library for `ts2ocaml`.
63
+
64
+
It only contains the following definitions:
65
+
* `-'tags intf` type, which is used for [tag-based subtyping](#feature-tag).
66
+
* TypeScript-specific primitive types, such as `any`, `never`, `unknown`, etc.
67
+
* Utility types for handling TypeScript's union types and intersection types.
68
+
69
+
You can safely add it to your project, and even modify it for your needs.
70
+
71
+
Note that you have to modify the bindings generated by `ts2ocaml` to make it work with the minimal standard library.
72
+
* Remove the `open Ts2ocaml` statements and then add `open Ts2ocaml_min` (or your own name if you renamed it).
73
+
* All the JS, DOM, and Web Worker types are left unknown. You have to replace them with the types from your binding by hand.
74
+
- We recommend using [`--preset=minimal`](#choosing-a-preset) when generating bindings, which disables all the features irrelevant to the bindings not from `ts2ocaml`.
9
75
10
76
## Choosing a preset
11
77
@@ -31,24 +97,79 @@ See [`--preset`](#--preset) for the options which will be set by each preset.
31
97
> **Hint:** if a package `foo` depends only on `bar` and `bar` depends on many other packages,
32
98
> it's safe to use `--preset=safe` to `foo` and `--preset=full` to `bar`, but not vice versa.
33
99
34
-
## Using the generated bindings in your project
100
+
## Generating and using the bindings
35
101
36
-
`ts2ocaml` for `js_of_ocaml` generates `.mli` files, which should then be processed with [LexiFi/gen_js_api](https://github.com/LexiFi/gen_js_api).
102
+
Once you figure out which preset (and some additional options if any) to use, you are now ready to run `ts2ocaml`.
37
103
38
-
You should use the latest `gen_js_api` as `ts2ocaml` uses the latest features of `gen_js_api`.
39
-
As of Oct 2021, most of the required features have not been present in the latest version in opam.
40
-
So you would have to `git submodule` their repository (`https://github.com/LexiFi/gen_js_api`) to the `lib` directory of your OCaml project.
A binding (`typescript.mli` in this example) and a JS stub file `stub.js` will be generated in the `src` directory.
43
109
44
-
TODO
110
+
Modify your `dune` file to include them in your project.
111
+
112
+
* Use `(js_of_ocaml (javascript_files stub.js))` to include the stub JS to the executable.
113
+
* Add a rule to run `gen_js_api` on the generated `.mli` file.
114
+
115
+
The resulting `dune` will look like below:
116
+
117
+
```lisp
118
+
(executable
119
+
(name your_app)
120
+
(libraries gen_js_api ts2ocaml-jsoo-stdlib)
121
+
(link_flags -no-check-prims)
122
+
(preprocess (pps gen_js_api.ppx))
123
+
(modes js)
124
+
(js_of_ocaml
125
+
(javascript_files stub.js)))
126
+
127
+
(rule
128
+
(targets typescript.ml)
129
+
(deps typescript.mli)
130
+
(action (run %{bin:gen_js_api} %{deps})))
131
+
132
+
(rule
133
+
(targets main.js)
134
+
(deps main.bc.js)
135
+
(action (run cp %{deps} %{targets})))
136
+
137
+
(alias
138
+
(name DEFAULT)
139
+
(deps main.js main.html))
140
+
```
141
+
142
+
> **Note:** if you are using `ts2ocaml-jsoo-stdlib`, don't forget to set [`--profile=release`](https://dune.readthedocs.io/en/latest/dune-files.html?highlight=profile#profile) when running dune!
143
+
> There is no dead code elimination without that option, so it would result in a 40MB+ JavaScript executable.
144
+
145
+
Each binding has an `Export` module which corresponds to the package's default export (`export default ..` or `export = ..` in TypeScript).
When multiple input files are given, `ts2ocaml` will merge it to one source file.
168
+
169
+
`ts2ocaml` will *not* resolve imports and exports between input files, so it can result in a broken binding.
170
+
171
+
We recommend you to **create one binding for each `.d.ts`**. It works in most of the cases, and it is easy to fix when the binding is broken.
172
+
52
173
> See also [the common options](common_options.md).
53
174
54
175
# General Options
@@ -73,8 +194,6 @@ Create `ts2ocaml_min.mli`, which is the minimal standard library for ts2ocaml *w
73
194
* DOM API (`Ts2ocaml_dom`), or
74
195
* web worker API (`Ts2ocaml_webworker`).
75
196
76
-
This option is helpful if you have an existing binding for these APIs, and don't want to use ones from the full `Ts2ocaml`[standard library](#standard-library).
77
-
78
197
When this option is used, ts2ocaml requires no input files. So most of the other options will be ignored.
0 commit comments