5.1. Building Iroha

In this guide we will learn how to install all dependencies, required to build Iroha and how to build it.

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 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

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.1. Docker

Note

You don’t need Docker to run Iroha, it is just one of the possible choices.

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.

After it, 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 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 and postgres images. hyperledger/iroha:develop-build image contains all development dependencies and is based on top of ubuntu:16.04. postgres image is required for starting and running Iroha.

  1. Two containers are created and launched.

4. 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 to Building Iroha section.

5.1.1.2. Linux

5.1.1.2.1. Boost

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 the project.

5.1.1.2.2. Other Dependencies

To build Iroha, you need following packages:

build-essential automake libtool libssl-dev zlib1g-dev libc6-dbg golang git tar gzip ca-certificates wget curl file unzip python cmake

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

Note

If you are willing to actively develop Iroha and to build shared libraries, please consider installing the latest release of CMake.

5.1.1.3. macOS

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

Hint

To install the Homebrew itself please run

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/homebrew/install/master/install)"

5.1.2. Build Process

5.1.2.1. Cloning the Repository

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.1.2.2. Building Iroha

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)

Note

On macOS $(nproc) variable does not work. Check the number of logical cores with sysctl -n hw.ncpu and put it explicitly in the command above, e.g. cmake --build build -- -j4

5.1.2.3. 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 cmake -L, cmake-gui, or ccmake.

Hint

You can specify parameters at the cmake configuring stage (e.g cmake -DTESTING=ON).

5.1.2.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

5.1.2.3.2. Packaging Specific Parameters

Parameter Possible values Default Description
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

5.1.2.4. 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 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