Building Octez from source

Building Octez from source#

If you plan to contribute to the Octez codebase or if you want to build a version of Octez that is based on the most recent code, the way to go is to set up a complete development environment by cloning the repository and compiling the sources using the provided makefile.

Note that setting up a complete development environment requires a powerful machine, and the required resources are increasing in the long run. If you are using Octez for production, consider installing forms of prebuilt binaries, refer to Installing Octez.

You can either build all the executables, as illustrated below, or only a subset of the executables, as detailed in section Compile.

TL;DR: From a fresh Debian Bookworm x86_64, you typically want to select a source branch in the Octez repository, e.g.:

  REPO="tezos/tezos"
  BRANCH="latest-release"

and then do:

sudo apt-get install -y rsync git m4 build-essential patch unzip wget opam jq bc
# [install rust]
wget https://sh.rustup.rs/rustup-init.sh
chmod +x rustup-init.sh
./rustup-init.sh --profile minimal --default-toolchain 1.88.0 -y

git clone https://gitlab.com/"$REPO".git tezos
cd tezos
git checkout $BRANCH
# [init opam]
opam init --bare

make build-deps
# [compile sources]
eval $(opam env)
make release
# [optional setup]
# puts Octez binaries in PATH:
# export PATH=$PWD/_build/install/default/bin/:$PATH
# if using bash, enables autocompletion:
# source ./src/bin_client/bash-completion.sh
# removes Mainnet/testnet disclaimers:
# export TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y

Warning

If you rerun the procedure above in an already cloned repository, typically by restarting from git checkout $BRANCH after upgrading the sources to a new version of Octez, you should do a git fetch before, to ensure that the tags for the latest release are known to Git. Otherwise, the sources compile perfectly fine but Octez executables may report their version incorrectly (e.g. 21.2+dev instead of 22.0).

The following sections describe the individual steps above in more detail.

Note

Besides compiling the sources, it is recommended to also install Python and some related tools, which are needed, among others, to build the documentation and to use the Git pre-commit hook.

Install Rust#

Compiling Octez requires the Rust compiler (see recommended version in variable $recommended_rust_version in file scripts/version.sh) and the Cargo package manager to be installed. If you have rustup installed, it should work without any additional steps on your side. You can use rustup to install both. If you do not have rustup, please avoid installing it from Snapcraft; you can rather follow the simple installation process shown below:

wget https://sh.rustup.rs/rustup-init.sh
chmod +x rustup-init.sh
./rustup-init.sh --profile minimal --default-toolchain 1.88.0 -y

Once Rust is installed, note that your PATH environment variable (in .profile) may be updated and you will need to restart your session so that changes can be taken into account. Alternatively, you can do it manually without restarting your session:

. $HOME/.cargo/env

Note that the command line above assumes that rustup installed Cargo in $HOME/.cargo, but this may change depending on how you installed rustup. See the documentation of your rustup distribution if file .cargo does not exist in your home directory.

Install Zcash Parameters#

Octez binaries require the Zcash parameter files to run. Docker images come with those files, and the source distribution also includes those files. But if you compile from source and move Octez to another location (such as /usr/local/bin), the Octez binaries may prompt you to install the Zcash parameter files. The easiest way is to download and run this script:

wget https://raw.githubusercontent.com/zcash/zcash/713fc761dd9cf4c9087c37b078bdeab98697bad2/zcutil/fetch-params.sh
chmod +x fetch-params.sh
./fetch-params.sh

The node will try to find Zcash parameters in the following directories, in this order:

  1. $XDG_DATA_HOME/.local/share/zcash-params

  2. $XDG_DATA_DIRS/zcash-params (if $XDG_DATA_DIRS contains several paths separated by colons :, each path is considered)

  3. $OPAM_SWITCH_PREFIX/share/zcash-params

  4. ./_opam/share/zcash-params

  5. ~/.zcash-params

  6. ~/.local/share/zcash-params

  7. /usr/local/share/zcash-params

  8. /usr/share/zcash-params

If the node complains that it cannot find Zcash parameters, check that at least one of those directories contains both files sapling-spend.params and sapling-output.params. Here is where you should expect to find those files:

  • if you are compiling from source, parameters should be in _opam/share/zcash-params (you may need to run eval $(opam env) before running the node);

  • if you used fetch-params.sh, parameters should be in ~/.zcash-params.

Note

Some operating systems may not be covered by the list of directories above. If Zcash is located elsewhere on your system (typically, on MacOS X), you may try creating a symbolic link such as: ln -s ~/Library/Application\ Support/ZcashParams ~/.zcash-params.

Note that the script fetch-params.sh downloads a third file containing parameters for Sprout (currently called sprout-groth16.params), which is not loaded by Sapling and can be deleted to save a significant amount of space (this file is much bigger than the two other files).

Install DAL trusted setup#

Users running DAL in operator or observer profiles need to have a set of cryptographic parameters (known as an SRS) installed in order to run their DAL node. In particular, these are needed when executing the Octez test suite, which involves DAL nodes running in various profiles. However, for simplicity, on some test networks the initialization parameters are mocked-up and built-in.

The cryptographic parameters can be retrieved via the following script:

scripts/install_dal_trusted_setup.sh

Get the sources#

Octez git repository is hosted at GitLab. All development happens here. Do not use our GitHub mirror which we don’t use anymore and only mirrors what happens on GitLab.

Checkout the latest-release branch to use the latest release. Alternatively, you can checkout a specific version based on its tag.

Install Octez dependencies#

Install the OCaml compiler and the libraries that Octez depends on:

make build-deps

Alternatively, if you want to install extra development packages such as merlin, you may use the following command instead:

make build-dev-deps

Note

  • These commands create a local OPAM switch (_opam folder at the root of the repository) where the required version of OCaml and OCaml Octez dependencies are compiled and installed (this takes a while but it’s only done once).

  • Be sure to eval $(scripts/env.sh) when you cd into the repository in order to be sure to load this local environment.

  • As the opam hook would overwrite the effects of eval $(scripts/env.sh) the script will disable the opam hook temporarily.

  • OPAM is meant to handle correctly the OCaml libraries but it is not always able to handle all external C libraries we depend on. On most systems, it is able to suggest a call to the system package manager but it currently does not handle version checking.

  • As a last resort, removing the _opam folder (as part of a git clean -dxf for example) allows to restart in a fresh environment.

Compile#

Once the dependencies are installed we can update OPAM’s environment to refer to the new switch and compile the project to build all the executables:

eval $(opam env)
make release

Note

Instead of the simple make command above, you may use more restrictive targets in the makefile to build only some subset of the executables. For instance, you may exclude experimental executables using make release; furthermore exclude executables such as the EVM node using make octez; or even restrict to Layer 1 executables using make octez-layer1.

Lastly, you can also add the Octez binaries to your PATH variable, and after reading the Disclaimer a few hundred times you are allowed to disable it with TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y.

You may also activate Bash autocompletion by executing:

source ./src/bin_client/bash-completion.sh

Warning

Note that if your shell is zsh, you may need extra configuration to customize shell completion (refer to the zsh documentation).

Update#

For updating to a new version, you typically have to update the sources by doing git pull in the tezos/ directory and replay the compilation scenario starting from make build-deps. You may also use make clean (and rm -Rf _opam/ if needed) before that, for restarting compilation in a fresh state.