Use Existing OCaml Libraries
This section is reserved for advanced usages. Usually, you'd pick an OCaml/Reason library that's already configured to work with our higher-level build system
bsb
(aka has absconfig.json
). If not, you'd usually add absconfig.json
to it. But if you want to directly use an OCaml package that's not part of the npm workflow, or are building some quirky infra with BuckleScript, keep reading!
This guide is also a small walkthrough of how bsb
works under the hood.
Built in NPM support
Build an OCaml Library as a NPM Package
Note: this section might be slightly stale. If any of the steps aren't working, please file us an issue! Thanks.
We highly recommend you try this endeavour on a dependency-less library first. It'd avoid lots of trouble.
BuckleScript's compiler, bsc
, extends the OCaml compiler options with several flags to provide a better experience for NPM users.
In general, you are expected to see two kinds of build artifacts: the generated JS files and metadata that your OCaml dependencies rely on.
Since CommonJS has no namespaces, to allow JS files to live in different directories, we have a flag
SHbsc.exe -bs-package-name $npm_package_name -bs-package-output modulesystem:path/to/your/js/dir -c a.ml
By passing this flag, bsc.exe
will store your package_name
and relative path to package.json
in .cmj
files. It will also generate JS files in the directory you specified. You can, and are encouraged to, store JavaScript files in a hierarchical directory.
For the binary artifacts (Note that this is not necessary if you only want your libraries to be consumed by JS developers, and it has benefit since end users don’t need these binary data any more), the convention is to store all *.cm
data in a single directory package.json/lib/ocaml
and Javascript files in a hierachical directory like package.json/lib/js
.
Use an OCaml Library as a NPM Package
If you follow the layout convention above, using an OCaml package is pretty straightforward:
SHbsc.exe -I path/to/ocaml/package/installed -c a.ml
Together
Your command line would be like this:
SHbsc.exe -I path/to/ocaml/package1/installed -I path/to/ocaml/package2/installed -bs-package-name $npm_package_name -bs-package-output commonjs:path/to/lib/js/ -c a.ml
Examples
You can see a more elaborate bsc
setup like so:
SHbsb -init dummy-project
cd dummy-project
npm run build
cat lib/bs/build.ninja
The Ninja file, generated by bsb
, describes the exact steps needed to build a trivial project using bsc
.
Additionally, please consult https://github.com/chenglou/intro-to-reason-compilation, which covers the lowest-level Reason + BuckleScript compilation mechanisms.