Compiling binaries

This chapter explains how to compile the various Brane components.

First, start by installing the required dependencies.

Then, if you are coming from the scientist- or software engineer-chapters, you are most likely interested in compiling the brane CLI tool.

If you are coming from the administrator-chapters, you are most likely interested in compiling the branectl CLI tool and the various instance images.

People who aim to either run the Brane IDE or automatically compile BraneScript in another fashion, should checkout the section on libbrane_cli and branec.

Dependencies

If you want to compile the framework yourself, you have to install additional dependencies to do so.

Various parts of the framework are compiled differently. Most notably:

  • Any binaries (brane, branectl, branec or libbrane_cli.so) are compiled using Rust's cargo; and
  • Any services (i.e., nodes) are compiled within a Docker environment.

Depending on which to install, you may need to install the dependencies for both of them.

Binaries - Rust and Cargo

To compile Rust code natively on your machine, you should install the language toolchain plus any other dependencies required for the project. An overview per supported OS can be found below:

Windows (brane, branec and libbrane_cli.so only)

  1. Install Rust and its tools using rustup (follow the instructions on the website).
  2. Install the Visual Studio Tools to install the required Windows compilers. Installing the Build Tools for Visual Studio should be sufficient.
  3. Install Perl (Strawberry Perl is fine) (follow the instructions on the website).

macOS

  1. Install Rust and its tools using rustup:
    # Same command as suggested by Rustup itself
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    
    Or, if you want a version that installs the default setup and that does not ask for confirmation:
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --profile default -y
    
  2. Install the Xcode Command-Line Tools, since that contains most of the compilers and other tools we need
    # Follow the prompt after this to install it (might take a while)
    xcode-select --install
    

info The main compilation script, make.py, is tested for Python 3.7 and higher. If you have an older Python version, you may have to upgrade it first. We recommend using some virtualized environment such as pyenv to avoid breaking your OS or other projects.

Ubuntu / Debian

  1. Install Rust and its tools using rustup:
    # Same command as suggested by Rustup itself
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    
    Or, if you want a version that installs the default setup and that does not ask for confirmation:
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --profile default -y
    
  2. Install the packages required by Brane's dependencies with apt:
    sudo apt-get update && sudo apt-get install -y \
        gcc g++ \
        cmake
    

Arch Linux

  1. Install Rust and its tools using rustup:
    # Same command as suggested by Rustup itself
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    
    Or, if you want a version that installs the default setup and that does not ask for confirmation:
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --profile default -y
    
  2. Install the packages from pacman required by Brane's dependencies
    sudo pacman -Syu \
        gcc g++ \
        cmake
    

Services - control, worker and proxy nodes

The services are build in Docker. As such, install it on your machine, and it should take care of the rest.

Simply follow the instructions on https://www.docker.com/get-started/ to get started.

Compilation

With the dependencies install, you can then compile the parts of the framework of your choosing.

For all of them, first clone the repository. Either download it from Github's interface (the green button in the top-right), or clone it using the command-line:

git clone https://github.com/epi-project/brane && cd brane

Then you can use the make.py script to install what you like:

  • To build the brane CLI tool, run:
    python3 make.py cli
    
  • To build the branectl CLI tool, run:
    python3 make.py ctl
    
  • To build the branec BraneScript compiler, run:
    python3 make.py cc
    
  • To build the libbrane_cli.so dynamic library, run:
    python3 make.py libbrane_cli
    
  • To build the servives for a control node, run:
    python3 make.py instance
    
  • To build the servives for a worker node, run:
    python3 make.py worker-instance
    
  • To build the servives for a proxy node, run:
    python3 make.py proxy-instance
    

drawing Note that compiling any of these will result in quite large build caches (order of GB's). Be sure to have at least 10 GB available on your device before you start compiling to make sure your OS keeps functioning.

For any of the binaries (brane, branectl and branec), you may make them available in your PATH by copying them to some system location, e.g.,

sudo cp ./target/release/brane /usr/local/bin/brane

to make them available system-wide.

Troubleshooting

This section lists some common issues that occur when compiling Brane.

  1. I'm running out of space on my machine. What to do?
    Both the build caches of Cargo and Docker tend to accumulate a lot of artefacts, most of which aren't used anymore. As such, it can save a lot of space to clear them.

    For Cargo, simply remove the target-directory:

    rm -rf ./target
    

    For Docker, you can clear the Buildx build cache:

    docker buildx prune -af
    

    drawing The above command clears all Buildx build cache, not just Brane's. Use with care.

    It can also sometimes help to prune old images or containers if you're building new versions often.

    Do note that running either will re-trigger a new, clean build, and therefore may take some time.

  2. Errors like ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? or unix:///var/run/docker.sock not found when building services
    This means that your Docker engine is most likely not running. On Windows and macOS, start it by starting the Docker Engine application. On Linux, run:

    sudo systemctl start docker
    
  3. Permission denied errors when building services (Linux)
    Running Docker containers may be a security risk because it can be used to edit any file on a system, permission or not. As such, you have to be added to the docker-group to run it without using sudo.

    If you are managing the machine you are running on, you can run:

    sudo usermod -aG docker "$USER"
    

    Don't forget to restart your terminal to apply the change, and then try again.