Skip to content

Latest commit

 

History

History
119 lines (92 loc) · 3.6 KB

Building.md

File metadata and controls

119 lines (92 loc) · 3.6 KB

Installation using Nix

If you want just to use moc, you can install the moc binary into your nix environment with

$ nix-env -i -f . -A moc

Development using Nix

To enter a shell with the necessary dependencies available, use

$ nix-shell

Within this shell you can run

  • make in src/ to build all binaries,
  • make moc in src/ to build just the moc binary,
  • make DUNE_OPTS=--watch moc to keep rebuilding as source files are changing
  • make in rts/ to build the Motoko runtime
  • make in test/ to run the test suite.

This invokes dune under the hood, which will, as a side effect, also create .merlin files for integration with Merlin, the Ocaml Language Server

Replicating CI locally

A good way to check that everything is fine, i.e. if this will pass CI, is to run

$ nix-build --no-out-link

Making releases

We make frequent releases, at least weekly. The steps to make a release (say, version 0.4.2) are:

  • Make sure that the top section of Changelog.md has a title like

     == 0.4.2 (2020-04-01)

    with today’s date.

  • Look at git log --first-parent 0.4.1..HEAD and check that everything relevant is mentioned in the changelog section, and possibly clean it up a bit, curating the information for the target audience.

  • git commit -a -m "Releasing 0.4.2"

  • Create a PR from this commit, and label it automerge-squash. Mergify will merge it into master without additional approval, within 2 or 3 minutes.

  • git switch master; git pull. The release commit should be your HEAD

  • git tag 0.4.2 -m "Motoko 0.4.2"

  • git branch -f release 0.4.2

  • git push origin release 0.4.2

The release branch should thus always reference the latest release commit.

Development without nix-shell

You can get a development environment without having to use nix-shell (although installing all required tools without nix is out of scope).

  • Use your system’s package manager to install ocaml (4.07) and opam
  • Install the packages: 
    opam install num vlq yojson menhir stdio js_of_ocaml js_of_ocaml-ppx ppx_inline_test atdgen wasm obelisk
  • Install into your PATH various command line tools used by, in particular, the test suite: 
    nix-env -i -f . -A wasmtime
nix-env -i -f . -A filecheck
nix-env -i -f . -A wabt
nix-env -i -f . -A drun
nix-env -i -f . -A ic-run
  • Building the Motoko runtime without nix is tricky. But you can run 
    nix-shell --run 'make -C rts'
    to get rts/mo-rts.wasm.
  • Add ./bin to your $PATH so that the testsuite will find the build products (see ./bin/wrapper.sh for details).

Profile the compiler

  1. Build with profiling within nix-shell (TODO: How to do with dune) 
    make -C src clean
make BUILD=p.native -C src moc
  2. Run moc as normal, e.g. 
    moc -g -c foo.mo -o foo.wasm
    this should dump a gmon.out file in the current directory.
  3. Create the report, e.g. using 
    gprof --graph src/moc
    (Note that you have to run this in the directory with gmon.out, but pass it the path to the binary.)

Updating Haskell Packages

When the .cabal file of a Haskell package is changed you need to make sure the corresponding .nix file (stored in nix/generated/) is kept in sync with it. These files are automatically generated; run

nix-shell nix/generate.nix

to update.

Don't worry if you forget to update the default.nix file, the CI job check-generated checks if these files are in sync and fail with a diff if they aren't.