Building and Developing Scilla

• Clone vcpkg to a separate location:

  $ git clone https://github.com/Microsoft/vcpkg.git /path/to/vcpkg
  $ cd /path/to/vcpkg && git checkout 2022.09.27 && ./bootstrap-vcpkg.sh
  $ cd /path/to/scilla
  $ export VCPKG_ROOT=/path/to/vcpkg
  $ export PKG_CONFIG_PATH="$(pwd)/vcpkg_installed/$(scripts/vcpkg_triplet.sh)/lib/pkgconfig:$PKG_CONFIG_PATH"
  

openSUSE

• Install bubblewrap from https://software.opensuse.org/package/bubblewrap by clicking on the Show experimental packages button and then performing the 1-click install from the Virtualization:containers project.

• Install ocaml from https://software.opensuse.org/package/ocaml by performing the 1-click install of the officially released package.

• Run:

sudo zypper install -y curl m4 opam2 pkg-config zlib-devel gmp-devel libffi-devel libopenssl-devel boost-devel

Ubuntu

On machines older than Ubuntu 20.04, CMake >=3.16 (which is a requirement) is not present. Run the script scripts/install_cmake_ubuntu.sh (without root) to install a new CMake into ~/.local/bin.

Required Ubuntu packages can be installed as below:

sudo add-apt-repository -y ppa:avsm/ppa
sudo apt-get update
sudo apt-get install -y curl build-essential m4 ocaml opam pkg-config zlib1g-dev libgmp-dev libffi-dev libssl-dev libboost-system-dev libboost-test-dev libpcre3-dev cmake autoconf patchelf

On systems strictly older than 18.04, the binary installation script can be used. In this case, the opam package used in the apt-get install command should be skipped.

macOS

The dependencies (listed in Brewfile) can be installed via Homebrew as follows. Run

brew bundle

from the project root.

Homebrew's openssl package is keg-only, which means it doesn't get symlinked into /usr/local directory, so in case of a non-default version of the package, you will need to set up PKG_CONFIG_PATH environment variable as Homebrew suggests. It should look like

export PKG_CONFIG_PATH="/usr/local/opt/openssl@_Version_/lib/pkgconfig:$PKG_CONFIG_PATH"

To run tests using Dune (dune exec tests/testsuite.exe), you may need to increase the maximum number of open file descriptors as Makefile's test target does:

ulimit -n 1024

After you have proceeded with installation if an error with regards to version file during make occurs, see here for the solution.

Nix and NixOS

There is a shell.nix for Nix users, so running the nix-shell should drop you into and isolated environment with all the necessary dependencies available.

Windows 10 Pro/Home Edition (Creators Update & later) via WSL

1. Enable Windows Subsystem for Linux (Choose Ubuntu 22.04 LTS)

2. Install required Ubuntu Packages

• OpenSSL ships with WSL so there is no further action needed.

sudo add-apt-repository -y ppa:avsm/ppa

sudo apt-get install -y curl build-essential m4 ocaml pkg-config zlib1g-dev libgmp-dev libffi-dev libssl-dev libboost-system-dev libpcre3-dev

3. Delete other ppa entries

sudo rm -rf /var/lib/apt/lists/*
sudo rm -rf /etc/apt/sources.list.d/*
sudo apt-get update

4. Re-install the packages (but this time with a --fix-missing flag)

sudo apt-get install -y curl build-essential m4 ocaml pkg-config zlib1g-dev libgmp-dev libffi-dev libssl-dev libboost-system-dev libpcre3-dev --fix-missing

5. Install opam 2.x

Since --disable-sandboxing is only available in opam 2.x & not opam 1.x, WSL users should not use apt-get for installing opam as it will install 1.x which won't work on WSL.

To install opam 2.x run the script below:

sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)

6. Initialize opam (with --disable-sandboxing flag)

Disabling sandboxing is required since WSL does not support Sandboxing (via bubblewrap) at this time.

To disable sandboxing, simply run:

opam init --disable-sandboxing --compiler=ocaml-base-compiler.4.12.0 --yes

7. Set up current shell to work with opam

eval $(opam env)

8. Install Scilla's dependencies

Go to directory where you unzipped the latest Scilla release

cd <path/to/unzipped/latest/scilla/release>

opam install ./scilla.opam --deps-only --with-test

then

opam switch create ./ --deps-only --with-test --yes ocaml-base-compiler.4.12.0

9. Build and install

make clean; make

Optionally, you can install Scilla into your opam switch

make install

This installation can be removed with

make uninstall

10. Test your installation by running

eval-runner -gaslimit 10000 -libdir src/stdlib tests/eval/good/let.scilexp

from the project root.

If the output is as below, then you are good to go 👍. No further action will be necessary. The binaries (eval-runner, scilla-checker, scilla-runner & type-checker) are all installed in your opam switch.

{ [a -> (Int32 42)],
  [y -> (Int32 42)],
  [f -> <closure>],
  [x -> (Int32 42)] }

If you just installed opam package manager

Initialize opam

opam init --compiler=ocaml-base-compiler.4.12.0 --yes

Note: the initializer will change your shell configuration to setup the environment opam needs to work. You can remove --yes from the above command to manually control that process.

Setup your current shell to work with opam

eval $(opam env)

Check that you have all system-level dependencies

If one of the following commands asks you to install a plugin respond with "Y".

opam pin add . --no-action --yes
opam depext
opam pin remove scilla

You should see something like

# Detecting depexts using vars: arch=x86_64, os=macos, os-distribution=homebrew, os-family=homebrew
# The following system packages are needed:
gcc
gmp
libffi
lzlib
pcre
pkg-config
# All required OS packages found.

Install Scilla dependencies using opam

cd PROJECT_DIR    # go inside your Scilla project directory
opam install ./scilla.opam --deps-only --with-test

The above commands can, alternatively, be run using the make target opamdep:

make opamdep

If you have opam package manager already installed

First of all, make sure you have all the system-level dependencies.

You can try installing the Scilla dependencies using the instructions above, but skipping the initialization step. If opam reports a dependency conflict, one way out might be creating yet another opam switch and managing your switches when doing Scilla- and non-Scilla- related hacking.

Another way is to use opam's feature called local switch. This is like a standard opam switch but instead of $HOME/.opam, it will reside in the project root directory in _opam subdirectory. This lets us to avoid dependency conflict and changing our switches back and forth when working on different projects. To create a local opam switch and install all the Scilla dependencies, cd into project root and execute:

opam switch create ./ --deps-only --with-test --yes ocaml-base-compiler.4.12.0

Now, whenever you are inside the project directory, opam will prefer the local switch to any globally installed switches, unless being told explicitly which one to use.

We should warn you that using external tools like a text editor with merlin support might be tricky in the presence of local switches. A common workaround is to have a global opam switch with OCaml developer tools installed and have your editor to refer to that switch instead of the local one.

Note: using git clean, extra care should be paid so that it won't delete _opam directory. We suggest using make clean command or keeping _opam directory like so:

git clean -dfX --exclude=\!_opam/**

Instead of local switches, you can install a global switch called scilla on your system as follows

opam switch create scilla ocaml-base-compiler.4.12.0

Now you will need to install scilla's dependencies with the following command:

export SCILLA_REPO_ROOT=/path/to/scilla
opam install ./scilla.opam --deps-only --with-test