5. Building Iroha¶
In this guide we will learn how to install all dependencies, required to build Iroha and how to actually build it.
There will be 3 steps:
- Installing environment prerequisites
- Installing Iroha dependencies (will be performed automatically for Docker)
- Building Iroha
Note
You don’t need to build Iroha to start using it. Instead, you can download prepared Docker image from the Hub, this process explained in details in the Quick Start Guide page of this documentation.
5.1. Prerequisites¶
In order to successfully build Iroha, we need to configure the environment. There are several ways to do it and we will describe all of them.
Currently, we support Unix-like systems (we are basically targeting popular Linux distros and MacOS). If you happen to have Windows or you don’t want to spend time installing all dependencies you might want to consider using Docker environment. Also, Windows users might consider using WSL
Technically Iroha can be built under Windows natively in experimental mode. This guide covers that way too. All the stages related to native Windows build are separated from the main flow due to its significant differences.
Please choose your preferred platform below for a quick access:
Hint
Having troubles? Check FAQ section or communicate to us directly, in case you were stuck on something. We don’t expect this to happen, but some issues with an environment are possible.
5.1.1. Docker¶
First of all, you need to install docker
and docker-compose
. You can
read how to install it on the
Docker’s website
Note
Please, use the latest available docker daemon and docker-compose.
Then you should clone the Iroha repository to the directory of your choice:
git clone -b master https://github.com/hyperledger/iroha --depth=1
Hint
--depth=1
option allows us to download only latest commit and
save some time and bandwidth. If you want to get a full commit history, you
can omit this option.
When it is done, you need to run the development environment. Run the
scripts/run-iroha-dev.sh
script:
bash scripts/run-iroha-dev.sh
Hint
Please make sure that Docker is running before executing the script.
MacOS users could find a Docker icon in system tray, Linux users can use
systemctl start docker
After you execute this script, the following things will happen:
- The script will check whether you have containers with Iroha already running. Successful completion finishes with the new container shell.
- The script will download
hyperledger/iroha:develop-build
andpostgres
images.hyperledger/iroha:develop-build
image contains all development dependencies and is based on top ofubuntu:20.04
.postgres
image is required for starting and running Iroha. - Two containers are created and launched.
- The user is attached to the interactive environment for development and testing with
iroha
folder mounted from the host machine. Iroha folder is mounted to/opt/iroha
in Docker container.
Now your are ready to build Iroha! Please go directly to Building Iroha section.
5.1.2. Linux¶
To build Iroha, you will need the following packages:
build-essential
git
ca-certificates
tar
ninja-build
curl
unzip
cmake
Use this code to install environment dependencies on Debian-based Linux distro.
apt-get update; \
apt-get -y --no-install-recommends install \
build-essential ninja-build \
git ca-certificates tar curl unzip cmake
Note
If you are willing to actively develop Iroha and to build shared libraries, please consider installing the latest release of CMake.
Now you are ready to install Iroha dependencies.
5.1.3. MacOS¶
If you want to build Iroha from scratch and actively develop it, please use the following code to install all environment dependencies with Homebrew:
xcode-select --install
brew install cmake ninja git gcc@9
Hint
To install the Homebrew itself please run
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/homebrew/install/master/install)"
Now you are ready to install Iroha dependencies.
5.1.4. Windows¶
Note
All the listed commands are designed for building 64-bit version of Iroha.
5.1.4.1. Chocolatey Package Manager¶
First of all you need Chocolatey package manager installed. Please refer the guide for chocolatey installation.
5.1.4.2. Building the Toolset¶
Install CMake, Git, Microsoft compilers via chocolatey being in Administrative mode of command prompt:
choco install cmake git visualstudio2019-workload-vctools ninja
PostgreSQL is not a build dependency, but it is recommended to install it now for the testing later:
choco install postgresql # Don't forget the password you set!
Now you are ready to install Iroha dependencies.
5.2. Installing dependencies with Vcpkg Dependency Manager¶
Currently we use Vcpkg as a dependency manager for all platforms - Linux, Windows and MacOS. We use a fixed version of Vcpkg to ensure the patches we need will work.
That stable version can only be found inside the Iroha repository, so we will need to clone Iroha. The whole process is pretty similar for all platforms but the exact commands are slightly different.
5.2.1. Linux and MacOS¶
Run in terminal:
git clone https://github.com/hyperledger/iroha.git
iroha/vcpkg/build_iroha_deps.sh
vcpkg/vcpkg integrate install
After the installation of vcpkg you will be provided with a CMake build parameter like
-DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
.
Save it somewhere for later use and move to Building Iroha section.
5.2.2. Windows¶
Execute from Power Shell:
git clone https://github.com/hyperledger/iroha.git
powershell -ExecutionPolicy ByPass -File .\iroha\.packer\win\scripts\vcpkg.ps1 .\vcpkg .\iroha\vcpkg
After the installation of vcpkg you will be provided with a CMake build parameter like
-DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
.
Save it somewhere for later use and move to Building Iroha section.
Note
If you plan to build 32-bit version of Iroha -
you will need to install all the mentioned librares above
prefixed with x86
term instead of x64
.
5.3. Build Process¶
5.3.1. Cloning the Repository¶
This step is currently unnecessary since you have already cloned Iroha in the previous step. But if you want, you can clone the Iroha repository to the directory of your choice.
git clone -b master https://github.com/hyperledger/iroha
cd iroha
Hint
If you have installed the prerequisites with Docker, you don’t need
to clone Iroha again, because when you run run-iroha-dev.sh
it attaches
to Iroha source code folder. Feel free to edit source code files with your
host environment and build it within docker container.
5.3.2. Building Iroha¶
To build Iroha, use these commands:
cmake -H. -Bbuild -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Ninja"
cmake --build build --target irohad -- -j<number of threads>
Warning
If you want to use tests later, instead of building irohad target, you need to use this:
cmake -H. -Bbuild -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -G "Ninja"
cmake --build build --target all -- -j<number of threads>
Note
On Docker the path to a toolchain file is /opt/dependencies/scripts/buildsystems/vcpkg.cmake
. In other
environment please use the path you have got in previous steps.
Number of threads will be defined differently depending on the platform:
- On Linux: via
nproc
. - On MacOS: with
sysctl -n hw.ncpu
. - On Windows: use
echo %NUMBER_OF_PROCESSORS%
.
Note
When building on Windows do not execute this from the Power Shell. Better use x64 Native tools command prompt.
Now Iroha is built. Although, if you like, you can build it with additional parameters described below.
5.3.3. CMake Parameters¶
We use CMake to generate platform-dependent build files.
It has numerous flags for configuring the final build.
Note that besides the listed parameters cmake’s variables can be useful as well.
Also as long as this page can be deprecated (or just not complete) you can browse custom flags via cmake -L
, cmake-gui
, or ccmake
.
Hint
You can specify parameters at the cmake configuring stage (e.g cmake -DTESTING=ON).
5.3.3.1. Main Parameters¶
Parameter | Possible values | Default | Description |
---|---|---|---|
TESTING | ON/OFF | ON | Enables or disables build of the tests |
BENCHMARKING | OFF | Enables or disables build of the Google Benchmarks library | |
COVERAGE | OFF | Enables or disables lcov setting for code coverage generation | |
USE_LIBURSA | OFF | Enables usage of the HL Ursa cryptography instead of the standard one | |
USE_BURROW | OFF | Enables the HL Burrow EVM integration |
5.3.3.2. Packaging Specific Parameters¶
Parameter | Possible values | Default | Description |
---|---|---|---|
PACKAGE_ZIP | ON/OFF | OFF | Enables or disables zip packaging |
PACKAGE_TGZ | OFF | Enables or disables tar.gz packaging | |
PACKAGE_RPM | OFF | Enables or disables rpm packaging | |
PACKAGE_DEB | OFF | Enables or disables deb packaging |
5.3.4. Running Tests (optional)¶
First of all, please make sure you built Iroha correctly for the tests.
After building Iroha, it is a good idea to run tests to check the operability of the daemon. You can run tests with this code:
cmake --build build --target test
Alternatively, you can run the following command in the build
folder
cd build
ctest . --output-on-failure
Note
Some of the tests will fail without PostgreSQL storage running,
so if you are not using scripts/run-iroha-dev.sh
script please run Docker
container or create a local connection with following parameters:
docker run --name some-postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-p 5432:5432 \
-d postgres:9.5 \
-c 'max_prepared_transactions=100'