Skip to main content

Prerequisites

The following is a list of prerequisites required to start developing on Oasis Core:

  • Linux (if you are not on Linux, you will need to either set up a VM with the proper environment or, if Docker is available for your platform, use the provided Docker image which does this for you, see below).

  • System packages:

    NOTE: On Ubuntu/Debian systems, compiling mbedtls crate when building the oasis-core-runtime binary requires having the gcc-multilib package installed.

    On Fedora 29+, you can install all the above with:

    sudo dnf install bubblewrap gcc gcc-c++ clang-devel protobuf-compiler make cmake openssl-devel libseccomp-devel pkg-config

    On Ubuntu 18.10+ (18.04 LTS provides overly-old bubblewrap), you can install all the above with:

    sudo apt install bubblewrap gcc g++ gcc-multilib libclang-dev protobuf-compiler make cmake libssl-dev libseccomp-dev pkg-config
  • Go (at least version 1.18.3).

    If your distribution provides a new-enough version of Go, just use that.

    Please note that if you want to compile Oasis Core v22.1.9 or earlier, then go 1.19 is not supported yet; you need to use 1.18.x.

    Otherwise:

    • install the Go version provided by your distribution,

    • ensure $GOPATH/bin is in your PATH,

    • install the desired version of Go, e.g. 1.18.3, with:

      go install golang.org/dl/go1.18.3@latest
      go1.18.3 download
    • instruct the build system to use this particular version of Go by setting the OASIS_GO environment variable in your ~/.bashrc:

      export OASIS_GO=go1.18.3
  • Rust.

    We follow Rust upstream's recommendation on using rustup to install and manage Rust versions.

    NOTE: rustup cannot be installed alongside a distribution packaged Rust version. You will need to remove it (if it's present) before you can start using rustup.

    Install it by running:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

    NOTE: If you want to avoid directly executing a shell script fetched the internet, you can also download rustup-init executable for your platform and run it manually.

    This will run rustup-init which will download and install the latest stable version of Rust on your system.

  • Fortanix Rust EDP utilities.

    Make sure a nightly version of the Rust toolchain is installed:

    rustup install nightly

    Then install the Fortanix Rust EDP utilities by running:

    cargo +nightly install --git https://github.com/fortanix/rust-sgx --rev 998c34d158a69dd1af33f22587e8ae1c26ca6a27 fortanix-sgx-tools
    cargo +nightly install --git https://github.com/fortanix/rust-sgx --rev 998c34d158a69dd1af33f22587e8ae1c26ca6a27 sgxs-tools

    NOTE: These utilities must be compiled with a nightly version of the Rust toolchain since they use the #![feature] macro.

  • Oasis Core's Rust toolchain version with Fortanix SGX target.

    The version of the Rust toolchain we use in Oasis Core is specified in the rust-toolchain.toml file.

    The rustup-installed versions of cargo, rustc and other tools will automatically detect this file and use the appropriate version of the Rust toolchain when invoked from the Oasis core git checkout directory.

    To install the appropriate version of the Rust toolchain, make sure you are in an Oasis Core git checkout directory and run:

    rustup show

    This will automatically install the appropriate Rust toolchain (if not present) and output something similar to:

    ...

    active toolchain
    ----------------

    nightly-2022-08-22-x86_64-unknown-linux-gnu (overridden by '/code/rust-toolchain.toml')
    rustc 1.65.0-nightly (c0941dfb5 2022-08-21)
  • (OPTIONAL) gofumpt and goimports.

    Required if you plan to change any of the Go code in order for automated code formatting (make fmt) to work.

    Download and install it with:

    ${OASIS_GO:-go} install mvdan.cc/gofumpt@v0.3.1
    ${OASIS_GO:-go} install golang.org/x/tools/cmd/goimports@v0.1.11
  • (OPTIONAL) golangci-lint.

    Required if you plan to change any of the Go code in order for automated code linting (make lint) to work.

    Download and install it with:

    curl -sSfL \
    https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh \
    | sh -s -- -b $(${OASIS_GO:-go} env GOPATH)/bin v1.41.1
  • (OPTIONAL) protoc-gen-go.

    Download and install it with:

    ${OASIS_GO:-go} install google.golang.org/protobuf/cmd/protoc-gen-go@v1.21.0

    NOTE: If you didn't/can't add $GOPATH/bin to your PATH, you can install protoc-gen-go to /usr/local/bin (which is in $PATH) with:

    sudo GOBIN=/usr/local/bin ${OASIS_GO:-go} install google.golang.org/protobuf/cmd/protoc-gen-go@v1.21.0

    NOTE: The repository has the most up-to-date files generated by protoc-gen-go committed for convenience. Installing protoc-gen-go is only required if you are a developer making changes to protobuf definitions used by Go.

  • (OPTIONAL) jemalloc (version 5.2.1, built with 'je_' jemalloc-prefix)

    Alternatively set OASIS_BADGER_NO_JEMALLOC="1" environment variable when building oasis-node code, to build BadgerDB without jemalloc support.

    Download and install jemalloc with:

    JEMALLOC_VERSION=5.2.1
    JEMALLOC_CHECKSUM=34330e5ce276099e2e8950d9335db5a875689a4c6a56751ef3b1d8c537f887f6
    JEMALLOC_GITHUB=https://github.com/jemalloc/jemalloc/releases/download/
    pushd $(mktemp -d)
    wget \
    -O jemalloc.tar.bz2 \
    "${JEMALLOC_GITHUB}/${JEMALLOC_VERSION}/jemalloc-${JEMALLOC_VERSION}.tar.bz2"
    # Ensure checksum matches.
    echo "${JEMALLOC_CHECKSUM} jemalloc.tar.bz2" | sha256sum -c
    tar -xf jemalloc.tar.bz2
    cd jemalloc-${JEMALLOC_VERSION}
    # Ensure reproducible jemalloc build.
    # https://reproducible-builds.org/docs/build-path/
    EXTRA_CXXFLAGS=-ffile-prefix-map=$(pwd -L)=. \
    EXTRA_CFLAGS=-ffile-prefix-map=$(pwd -L)=. \
    ./configure \
    --with-jemalloc-prefix='je_' \
    --with-malloc-conf='background_thread:true,metadata_thp:auto'
    make
    sudo make install
    popd

    NOTE: jemalloc needs to be installed to the (default) /usr/local prefix (i.e. you can't use ./configure --prefix=$HOME/.local ...) because upstream authors hardcode its path.

In the following instructions, the top-level directory is the directory where the code has been checked out.

Using the Development Docker Image

If for some reason you don't want or can't install the specified prerequisites on the host system, you can use our development Docker image. This requires that you have a recent version of Docker installed.

Oasis development environment with all the dependencies preinstalled is available in the oasisprotocol/oasis-core-dev:master image. To run a container, do the following in the top-level directory:

make docker-shell

If you are curious, this target will internally run the following command:

docker run -t -i \
--name oasis-core \
--security-opt apparmor:unconfined \
--security-opt seccomp=unconfined \
-v $(pwd):/code \
-w /code \
oasisprotocol/oasis-core-dev:master \
bash

All the following commands can then be used from inside the container. See the Docker documentation for detailed instructions on working with Docker containers.