5.1. Building Iroha¶
In this guide we will learn how to install all dependencies, required to build Iroha and how to build it.
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 Getting Started page of this documentation.
5.1.1. Preparing the Environment¶
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.
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.
You don’t need Docker to run Iroha, it is just one of the possible choices.
First of all, you need to install
docker-compose. You can
read how to install it on the
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
--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.
After it, you need to run the development environment. Run the
Please make sure that Docker is running before executing the script.
macOS users could find a Docker icon in system tray, Linux user could use
systemctl start docker
After you execute this script, following things happen:
1. The script checks if you don’t have containers with Iroha already running. Successful completion finishes with the new container shell.
2. The script will download
hyperledger/iroha:develop-build image contains all development dependencies and is
based on top of
postgres image is required for starting
and running Iroha.
- Two containers are created and launched.
4. The user is attached to the interactive environment for development and
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 to Building Iroha section.
Iroha requires Boost of at least 1.65 version.
To install Boost libraries (
libboost-all-dev), use current release from Boost webpage. The only
dependencies are thread, system and filesystem, so use
./bootstrap.sh --with-libraries=thread,system,filesystem when you are building
220.127.116.11.2. Other Dependencies¶
To build Iroha, you need following packages:
Use this code to install dependencies on Debian-based Linux distro.
apt-get update; \ apt-get -y --no-install-recommends install \ build-essential automake libtool \ libssl-dev zlib1g-dev \ libc6-dbg golang \ git tar gzip ca-certificates \ wget curl file unzip \ python cmake
If you are willing to actively develop Iroha and to build shared libraries, please consider installing the latest release of CMake.
If you want to build it from scratch and actively develop it, please use this code to install all dependencies with Homebrew.
xcode-select --install brew install cmake boost postgres grpc autoconf automake libtool golang soci
To install the Homebrew itself please run
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/homebrew/install/master/install)"
All the listed commands are desinged for building 64-bit version of Iroha.
18.104.22.168.1. Chocolatey Package Manager¶
First of all you need chocolatey package manager installed. Please refer the guide for chocoloatey installation.
22.214.171.124.2. Build Toolset¶
Install CMake, Git, Microsoft compilers via chocolatey being in Administrative mode of command prompt:
choco install cmake git visualstudio2017-workload-vctools
Despite PostgreSQL is not a build dependency it is recommended to install Postgres now for the testing later.
choco install postgresql # Don't forget the password you set!
126.96.36.199.3. Vcpkg Dependency Manager¶
Although Vcpkg is aimed to control dependency hell among the C++ libraries, unfortunately, we cannot install its default version. The first problem is that Iroha dependency called SOCI is not able to work with the latest Boost. The second reason - Vcpkg does not provide Postgres related libraries for Debug build.
The solution is to use Vcpkg from a pull request (until it is merged):
git clone https://github.com/Microsoft/vcpkg.git --depth=1 cd vcpkg git fetch origin pull/6328/head:vcpkg_for_iroha git checkout vcpkg_for_iroha
Then follow Vcpkg installation guide:
# execute in Power shell .\bootstrap-vcpkg.bat .\vcpkg.exe integrate install
After the installation of vcpkg you will be provided with a CMake build parameter like
Save it somewhere for the later use.
188.8.131.52.4. Vcpkg Packages¶
Install C++ dependencies via vcpkg:
# Execute this from cmd.exe NOT from Power Shell vcpkg.exe install ^ protobuf:x64-windows ^ grpc:x64-windows ^ tbb:x64-windows ^ gtest:x64-windows ^ gflags:x64-windows ^ soci[boost,postgresql]:x64-windows ^ boost-filesystem:x64-windows ^ boost-system:x64-windows ^ boost-thread:x64-windows ^ boost-variant:x64-windows ^ boost-multiprecision:x64-windows ^ boost-bimap:x64-windows ^ boost-format:x64-windows ^ boost-circular-buffer:x64-windows ^ boost-assign:x64-windows ^ boost-uuid:x64-windows ^ boost-accumulators:x64-windows ^ boost-property-tree:x64-windows ^ boost-process:x64-windows
If you plan to build 32-bit version of Iroha -
you will need to install all the mentioned librares above
x86 term instead of
5.1.2. Build Process¶
184.108.40.206. Cloning the Repository¶
Clone the Iroha repository to the directory of your choice.
git clone -b master https://github.com/hyperledger/iroha cd iroha
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.
220.127.116.11. Building Iroha¶
Building on Windows differs from the main flow and the guide is here.
To build Iroha, use those commands
mkdir build; cd build; cmake ..; make -j$(nproc)
Alternatively, you can use these shorthand parameters (they are not documented though)
cmake -H. -Bbuild; cmake --build build -- -j$(nproc)
$(nproc) variable does not work. Check the number of
logical cores with
sysctl -n hw.ncpu and put it explicitly in the command
cmake --build build -- -j4
18.104.22.168. CMake Parameters¶
We use CMake to build 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
You can specify parameters at the cmake configuring stage (e.g cmake -DTESTING=ON).
22.214.171.124.1. Main Parameters¶
|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|
126.96.36.199.2. Packaging Specific Parameters¶
|ENABLE_LIBS_PACKAGING||ON/OFF||ON||Enables or disables all types of packaging|
|PACKAGE_ZIP||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|
188.8.131.52. Running Tests (optional)¶
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 following command in the
cd build ctest . --output-on-failure
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
184.108.40.206.1. Building Iroha on Windows¶
Configure the CMake project using configuration parameter acquired from vcpkg.
cmake -HC:\path\to\iroha -BC:\path\to\build ^ -DCMAKE_TOOLCHAIN_FILE=C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake ^ -G "Visual Studio 15 2017 Win64" -T host=x64
To build a 32-bit version of Iroha change
-G "Visual Studio 15 2017 Win64"
-G "Visual Studio 15 2017"
-T host=x64 indicates only the fact that 64-bit system is used as a host,
where Iroha is going to be compiled.
cmake --build C:\path\to\build --target irohad cmake --build C:\path\to\build --target iroha-cli
220.127.116.11.2. Running Iroha on Windows¶
Set the correct path and PostgreSQL password in
C:\path\to\irohad.exe ^ --config C:\path\to\iroha\example\config-win.sample ^ --genesis_block C:\path\to\iroha\example\genesis-win.block ^ --keypair_name C:\path\to\iroha\example\node0
As we stated before Windows build support is on experimental stage, that is why there no much details regarding the process. If you want to explore the maximum of Windows-related works around Iroha please take a look at these pull requests: 1, 2, 3.