BuckleScript User Manual

JavaScript is not just the browser language, it’s also the only existing cross platform language. It is truly everywhere: users don’t need to install binaries or use package managers to access software, just a link will work.

Another important factor is that the JavaScript VM is quite fast and keeps getting faster. The JavaScript platform is therefore increasingly capable of supporting large applications.

BuckleScript is mainly designed to solve the problems of large scale JavaScript programming:

While a strong type-system helps in countering these problems, at the same time we hope to avoid some of the problems faced in using other offline transpilation systems:

The standard npm package management tool can be used to install BuckleScript. If you don’t already have npm installed, follow the directions listed here. Once npm is installed, run the following command:

or install it globally

When working with OCaml we also recommend using opam package manager to install OCaml toolchains, available here. You will benefit from the existing OCaml ecosystem.

Once you have opam installed, ask opam to switch to using our version of the compiler:

Note that using this approach, user can also install other OCaml tools easily.

Now you should see a file called lib/js/src/main_entry.js generated as below:

User can also run watch mode see changes instantly while editing.

Now we want to create two modules, one file called fib.ml which exports fib function, the other module called main_entry.ml which will call fib.

If everything goes well, you should see the output as below:

BuckleScript build system has built in support for NPM packages, please checkout the section about the bsb for NPM support.

BuckleScript extends the OCaml compiler options with several flags to provide better experience for NPM users.

In general, you are expected to see two kinds of build artifacts, the generated JS files and meta data which your OCaml dependencies rely on.

Since CommonJS has no namespaces, to allow JS files live in different directories, we have a flag

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

If you follow the layout convention above, using an OCaml package is pretty straightforward:

Your command line would be like this:

Please visit https://github.com/bloomberg/bucklescript-addons for more examples.

This part is similar to traditional FFI, with syntax as described below:

Users need to declare types for foreign functions (JS functions for BuckleScript or C functions for native compiler) and provide customized attributes.

In JS, it is quite common to have a function take variadic arguments, BuckleScript support typing homogeneous variadic arguments. For example,

Contrary to the Phantom arguments, _[@bs.as] is introduced to attach the const data.

For example:

Output

It can also be used in combination with other attributes, for example:

Output

Input

Output

NodeJS has several file local variables: dirname, filename, module_, and require, their semantics are more like macros instead of functions.

BuckleScript provides built-in macro support for these variables:

High order functions are functions where the callback can be another function. For example, suppose JS has a map function as below:

A naive external type declaration would be as below:

Unfortunately, this is not completely correct. The issue is by reading the type 'a → 'b → 'c, it can be in several cases:

In OCaml, they all have the same type; however, f and g may be compiled into functions with different arities.

A naive compilation will compile f as below:

Its arity will be consistent but is 1 (returning another function); however, we expect its arity to be 2.

Bucklescript uses a more complex compilation strategy, compiling f as

No matter which strategy we use, existing typing rules cannot guarantee a function of type 'a → 'b → 'c will have arity 2.

To solve this problem introduced by OCaml’s curried calling convention, we support a special attribute [@bs] at the type level.

Here ('a → 'b → 'c [@bs]) will always be of arity 2, in general, 'a0 → 'a1 …​ 'aN → 'b0 [@bs] is the same as 'a0 → 'a1 …​ 'aN → 'b0 except the former’s arity is guaranteed to be N while the latter is unknown.

To produce a function of type 'a0 → .. 'aN → 'b0 [@bs], as follows:

A special case for arity of 0:

Note that this extension to the OCaml language is sound. If you add an attribute in one place but miss it in other place, the type checker will complain.

Another more complex example:

All JS objects of type 'a are lifted to type 'a Js.t to avoid conflict with OCaml’s native object system (we support both OCaml’s native object system and FFI to JS’s objects), ## is used in JS’s object method dispatch and field access, while # is used in OCaml’s object method dispatch.

OCaml supports object oriented style natively and provides structural type system. OCaml’s object system has different runtime semantics from JS object, but they share the same type system, all JS objects of type 'a is typed as 'a Js.t

OCaml provide two kinds of syntaxes to mode structural typing: < p1 : t1 > style and class type style, they are mostly the same except that the latter is more feature rich (support inheritance) but more verbose.

We introduced the extension bs.debugger, for example:

which will be compiled into:

We introduced bs.re for Javascript regex expression:

The compiler will infer f has type Js.Re.t and generate code as below

Below is a simple example for mocha library. For more examples, please visit https://github.com/bloomberg/bucklescript-addons

bsc.exe will build module Main and all its dependencies, when it finishes, it will run node main.js.

The same as above, but will not run node.

So that you can do

The compiler will sort the order of input files before starting compilation.

BuckleScript supports two compilation mode, script mode and package mode, in package mode, you have to provide package.json on top and set the options -bs-package-name, -bs-package-output. In script mode, such flags are not needed

The project name of your project, user is suggested to make it consistent with the name field in package.json

The format is module_system:oupt/path/relative/to/package.json Currently supported module systesms are: commonjs, amdjs and goog:<namespace>

For example, when you want to use the goog module system, you can do things like this:

For example:

It will generate x.js in lib/js as commonjs module, lib/goog as google module and lib/amdjs as amdjs module at the same time.

You would then need a bundler for the different module systems: webpack supports commonjs and amdjs while google closure compiler supports all.

Trigger the generation of TypeScript .d.ts files. bsc.exe has the ability to also emits .d.ts for better interaction with typescript. This is still experimental.

For more options, please see the documentation of bsc.exe -help.

Turn off warnings on FFI type declarations

For this flag, it will not create any intermediate file, which is useful for learning or troubleshooting.

If users don’t use any bs specific annotaions, user can explicitly turn it off. Another use case is that users can use -ppx explicitly as below:

Don’t print version header

In OCaml, the C FFI allows the user to define a custom data type and customize caml_compare, caml_hash behavior, etc. This is not available in our backend (since we have no C FFI).

In general, Users should only use physical equality as an optimization technique, but not rely on its correctness, since it is tightly coupled with the runtime.

Currently, BuckleScript assumes that the char range is 0-255. The user should be careful when they pass a JavaScript string to OCaml side. Note that we are working on a solution for this problem.

OCaml’s weak map is not available in BuckleScript. The weak pointer is replaced by a strict pointer.

OCaml has int, int32, nativeint and int64 types. - Both int32 and int64 in BuckleScript have the exact same semantics as OCaml. - int in BuckleScript is the same as int32 while in OCaml it’s platform dependent. - nativeint is treated as JavaScript float, except for division. For example, Nativeint.div a b will be translated into a /b | 0.

The Printf.print implementation in BuckleScript requires a newline (\n) to trigger the printing. This behavior is not consistent with the buffered behavior of native OCaml. The only potential problem we foresee is that if the program terminates with no newline character, the text will never be printed.

We do our best to mimic the native compiler, but we have no guarantee and there are differences.

BuckleScript uses the same algorithm as native OCaml but the output is different due to runtime representation of int/int64/int32 and float.

Marshall module is not supported yet.

Command line arguments are always empty, might be fixed in the near future. Sys.max_array_length and Sys.max_string_length will be the same as max_int, but it might be respected.

Because of the JavaScript environment limitation, Pervasives.stdin is not supported but both Pervasives.stdout and Pervasives.stderr are.

Evaluation rules are obvious. =~ respect semantics version, for example, the underlying engine

For BuckleScript users, nothing needs to be done (it is baked in the language level), for non BuckleScript users, we provide an external pre-processor, so it will work with other OCaml compilers too. Note that the bspp.ml is a stand alone file, so that it even works without compilation.

BuckleScript proivdes a native build tool on top of Google’s ninja-build, it is designed for fast feedback loop (typically 100ms feedback loop) and works cross platform.

bsb can be running in any subdirectory, it is a schema based build tool, the schema is available, it is strongly recommended to check out the schema after you finish reading the tutorials below.

If your editors support JSON schema validation and auto-completion like VSCode, below is a configuration to help you get auto-completion and validation for free:

The build system is installed as bsb.exe in bs-platform/bin/bsb.exe, due to a known issue in npm, we create a JS wrapper (which is accessible in .bin too), so the user can call either bsb(slightly higher latency but symlinked into .bin) or bsb.exe

Here is a minimal configuration:

The entry point is bsb, it will check if there is already build.ninja in the build directory, if not or need regenerated it will generate a file build.ninja and delegate the hard work to ninja.

The directory layout (after building) would be

We wrap bsb.exe as bsb so that it will work across different platform.

Below is a json configuration for the bucklescript-tea: the Elm artchitecture in BuckleScript

Now, we have a repo bucklescript-have-tea to depend on bucklescript-tea, its configurations are as below:

Suppose you are in bucklescript-have-tea top directory,

You can also change the package-specs to have another module format, for example, tweak your bsconfig.json:

Rerun the command

You will get both commonjs and amdjs support, in the end, we suggest you check out the schema and enjoy the build!

BuckleScript distribution has bsdep.exe which has the same interface as ocamldep

Here is a simple Makefile to get started:

In theory, people need run make depend && make all, make depend will calculate dependency while make all will do the job.

However, in practice, people used to use a file watch service, take watchman for example, you need json configure

Now in your working directory, type watchman -j < build.json and enjoy the lightning build speed.

The current design of BuckleScript follows several high level principles. While those principles might change in the future, there are enforced today and can explain certain technical limitations BuckleScript has.

Lambda Representation

As pictured in the diagram above, BuckleScript is primarily based on the Lambda representation of the OCaml compiler. While this representation is quite rich, some information is lost from the upstream representation. The patch to the OCaml compiler tries to enrich this representation in a non-intrusive way (see next section).

Minimal Patch to the OCaml compiler

BuckleScript requires patches to the OCaml compiler. One of the main reasons is to enrich the Lambda representation so that the generated code is as nice as possible. A design goal is to keep those patches minimal and useful for the OCaml compiler in general so that they can later be integrated.

BuckleScript preserves the soundness of the OCaml language. Assuming the FFI is correctly implemented, the type safety is preserved.

In order to make the JavaScript generated code as close as possible to the original OCaml core we thrive to introduce as few new symbols as possible.

As we clarified before, the internal representation should not be relied upon. We are working to provide a ppx extension as below:

So that it will a automatically provide constructing and destructing functions:

Below assume that you are working in jscomp directory, and that you’ve followed instructions from Minimal dependencies to build OCaml.

The build target is

So whenever you change files relevant to the build tool bsb.exe, try it and do some test, if it works, send a pull request!

Note that for most binaries in BuckleScript, we also have a release mode, which will pack all relevant files into a single file, this is important, since it will cut all our dev-dependencies, so the user does not need install those tools.

You can verify it by typing

But please don’t commit those changes in PR, it will cause painful merge conflicts

There is also a snapshot mode,

This will actually snapshot your changes into a single ml file and used in npm distribution. But please don’t commit those changes in PR, it will cause painful merge conflicts

BuckleScript runtime implementation is currently a mix of OCaml and JavaScript. (jscomp/runtime directory). The JavaScript code is defined in the .ml file using the bs.raw syntax extension.

The goal is to implement the runtime purely in OCaml and you can help contribute.

Each new PR should include appropriate testing.

Currently all tests are in jscomp/test directory and you should either add a new test file or modify an existing test which covers the part of the compiler you modified.

The specification is in jscomp/test/mt.ml

For example some simple tests would be like:

Suppose you have mocha installed, if not, try npm install mocha

mocha -R list jscomp/test/your_test_file.js

npm run cover

You’ll need Asciidoctor installed. Modify the section you want in site/docsource/, then run site/docsource/build.sh.

Js_of_ocaml is a popular compiler which compiles OCaml’s bytecode into JavaScript. It is the inspiration for this project, and has already been under development for several years and is ready for production. In comparison, BuckleScript, while moving fast, is still a very young project. BuckleScript’s motivation, like js_of_ocaml, is to unify the ubiquity of the JavaScript platform and the truly sophisticated type system of OCaml, however, there are some areas where we view things differently from js_of_ocaml. We describe below, some of these differences, and also refer readers to some of the original informal discussions.

Both projects are improving quickly, so this can change in the future!