Skip to content

Latest commit

 

History

History
351 lines (288 loc) · 10.3 KB

Build-system-support.adoc

File metadata and controls

351 lines (288 loc) · 10.3 KB

Build system support

The BuckleScript compilation model is similar to OCaml native compiler. If b.ml depends on a.ml, you have to compile a.ml and a.mli first.

Note

The technical reason is that BuckleScript will generate intermediate files with the extension .cmj which are later used for cross module inlining, arity inference and other information.

BuckleScript build system: bsb

BuckleScript proivdes a native build tool on top of Google’s ninja-build. It is designed for a 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 and the schema is available. It is strongly recommended to check out the schema after you finish reading the tutorials below.

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

settings.json
{
    "json.schemas": [
        {
            "fileMatch": [
                "bsconfig.json"
            ],
            "url" : "file:///path/to/bucklescript/docs/docson/build-schema.json" // (1)
        }
    ],
    // ....
}

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:

bsconfig.json
{
  "name": "test", // package name, required (1)
  "sources": "src" // (2)
}

  1. It is an extension to JSON with comment support

  2. Here we did not list files, so all .ml, .mli, .re, .rei will be considered as source files

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

The directory layout (after building) would be

.
├── lib
│   ├── bs
│   │   ├── src
│   │   └── test
│   ├── js
│   │   ├── src
│   │   └── test
│   ├── amdjs // (1)
│   │   ├── src
│   │   └── test
│   ├── goog  // (2)
│   │   ├── src
│   │   └── test
│   └── ocaml
├── scripts
├── src
└── test

  1. Will generate amdjs modules if flags are turned on

  2. Will generate goog modules if flags are turned on

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

Watch mode
bsb // (1)
bsb -w // (2)

  1. Do the plain build

  2. Do the plain build and watch

Build with other BuckleScript dependencies

List your dependency in bs-dependencies and install it via npm install as below:

bsconfig.json
{
    "name": "bs-string",
    "version": "0.1.3",
    "bs-dependencies": [
        "bs-mocha" // (1)
    ],
    "sources": [
       .. .
    ],
    "generate-merlin" : false // (2)
}

  1. Yet another BuckleScript dependency

  2. If true (default) bsb will generate merlin file for you

package.json
{
 "dependencies": {
    "bs-mocha": "0.1.5"
    },
  ...
}

After your npm install,

bsb -clean-world // (1)
bsb -make-world // (2)
bsb -w // (3)

  1. Clean the binary artifact of current build and your dependency

  2. Build dependencies and lib itself

  3. Start watching the project and whenever your changes are made, bsb will rebuild incrementally

You can also streamline the three commands as below:

bsb -clean-world -make-world -w

Mark your directory as dev only

Note sometimes, you have directories which are just tests that you don’t need your dependency to build. In that case you can mark it as dev only:

bsconfig.json
{
        "sources" : {
                "dir" : "test",
                "type" : "dev" // (1)
        }
}

  1. directory test is in dev mode, it will not be built when used as a dependency

A real world example of using bsb

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

bsconfig.json
{
  "name": "bucklescript-tea",
  "version": "0.1.3",
  "sources": [
   "src",   // (1)
    {
      "dir": "test",
      "type": "dev" // (2)
    }
  ]
}

  1. Source directory, by default it will export all units of this directory to users.

  2. Dev directory, which will only be useful for developers of this project.

package.json
{
  "name": "bucklescript-tea",
  "version": "0.1.3",
  "description": "TEA for Bucklescript",
  "scripts": {
    "build": "bsb",
    "watch": "bsb -w",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "peerDependencies": {
    "bs-platform": "^1.4.2" // (1)
  }
}

  1. Here we list bs-platform as a peer dependency so that different repos shares the same compiler.

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

bsconfig.json
{
    "name" : "bucklescript-have-tea",
    "sources" :  "src",
    "bs-dependencies": [
      "bucklescript-tea"
    ]
}
package.json
{
    "name" : "bucklescript-have-tea",
    "version" : "0.1.0",
    "dependencies" : { "bucklescript-tea" : "^0.1.2" }, // (1)
    "peerDependencies" : { "bs-platform" : "^1.4.2" } //(2)
}

  1. List bucklescript-tea as dependency

  2. List bs-platform as peer dependency

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

npm install // (1)
npm install bs-platform (2)
./node_modules/.bin/bsb -clean-world -make-world -w (3)

  1. Install the dependencies

  2. Install peer dependencies

  3. On Windows, it would be .\node_modules\.bin\bsb -clean-world -make-world -w

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

{
  ... ,
  "package-specs" : ["amdjs", "commonjs"],
  ...
}

Rerun the command

bsb -clean-world -make-world

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

Build using Make

Warning

bsb is the officially recommended build system. This section is included here only for people who are curious about how the build works.

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

Here is a simple Makefile to get started:

Makefile
OCAMLC=bsc.exe # (1)
OCAMLDEP=bsdep.exe # (2)
SOURCE_LIST := src_a src_b
SOURCE_MLI  = $(addsuffix .mli, $(SOURCE_LIST))
SOURCE_ML   = $(addsuffix .ml, $(SOURCE_LIST))
TARGETS := $(addsuffix .cmj, $(SOURCE_LIST))
INCLUDES=
all: $(TARGETS)
.mli:.cmi
        $(OCAMLC) $(INCLUDES) $(COMPFLAGS)  -c $<
.ml:.cmj:
        $(OCAMLC) $(INCLUDES) $(COMPFLAGS)  -c $<
-include .depend
depend:
        $(OCAMLDEP) $(INCLUDES) $(SOURCE_ML) $(SOURCE_MLI) > .depend

  1. bsc.exe is the BuckleScript compiler

  2. ocamldep executable is part of the OCaml compiler installation

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

However in practice, people used to a file watch service, such as watchman for example, will need the JSON configuration:

build.json
[
    "trigger", ".", {
        "name": "build",
        "expression": ["pcre", "(\\.(ml|mll|mly|mli|sh|sh)$|Makefile)"], // (1)
        "command": ["./build.sh"],
        "append_files" : true
    }
]

  1. whenever such files changed, it will trigger command field to be run

build.sh
make -r -j8 all (1)
make depend // (2)

  1. build

  2. update the dependency

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