editEdit on GitHub

Installation Guide

Exonum core and most other Exonum repositories use the Rust programming language and the corresponding toolchain. This document details how to setup development environment for contributing to these projects, testing them, and developing using Exonum.

Note

As of version 0.1, you need to compile the core locally for every application that depends on it. Cargo (the Rust package manager) takes care of most things, but you still need to have dependencies installed locally as described below for the core to compile.

In future releases, Exonum will become more modular and will work as a standalone application. See the roadmap for more details.

Dependencies

Exonum depends on the following third-party system libraries:

You can find instructions how to install them on the various environments below.

MacOS

Install the necessary libraries using Homebrew:

brew install libsodium leveldb pkg-config

Linux

For distributives with deb-based package managers (such as Debian or Ubuntu), use

apt-get install build-essential libsodium-dev \
    libleveldb-dev pkg-config

libsodium is contained in a third-party PPA, so you may need to add it with

add-apt-repository ppa:chris-lea/libsodium

Package names and installation methods may differ in other Linux distributives; use package manager tools to locate and install dependencies.

Windows

Workability is not guaranteed yet.

Rust Toolchain

Exonum repositories use the stable Rust toolchain that can be installed by using the rustup program:

curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable

The toolchain includes the Rust compiler (rustc) and several utilities, of which the most important one is Cargo, the Rust package manager.

Clippy

A separate nightly Rust toolchain is required if you want to run the clippy linter locally. Clippy is used in CI builds of Exonum and other repositories to detect common Rust anti-patterns. In general, clippy supports the latest nightly version of Rust. It can be installed with

rustup toolchain install <nightly-rust-version>

where <nightly-rust-version> is the nightly Rust version supported by clippy (e.g., nightly-2017-05-10 for clippy version 0.0.131). Consult the clippy installation guide for more details.

After installing nightly Rust, clippy checks can be run with

cargo +<nightly-rust-version> clippy

Rustfmt

rustfmt is used to perform automatic code formatting and code style checks in CI builds. Note that Exonum repositories pin the version of rustfmt in order to get consistent formatting.

You can install rustfmt locally with

cargo install rustfmt --vers <rustfmt-version> --force

where <rustfmt-version> is the supported version of the formatter. You may find the supported version in the Travis configuration of Exonum core repository.

After installing the formatter, its checks can be run with

cargo fmt --write-mode=diff

Consult the rustfmt readme for more details.

Compiling Exonum

You can verify that you installed dependencies and the Rust toolchain correctly by cloning the exonum repository and running its built-in unit test suite:

git clone https://github.com/exonum/exonum.git
cd exonum
cargo test --manifest-path exonum/Cargo.toml

You may also run the extended test suite located in the sandbox directory:

cargo test --manifest-path sandbox/Cargo.toml

Non-Rust Components

Light Client Library

The light client library uses a fairly standard JavaScript development toolchain: Node and npm, together with Mocha + Chai for testing (and Karma for browser testing), istanbul for measuring test coverage, and Babel for transpiling to ES5. Workability of the development environment is tested on Node 4+.

Note

The light client library itself can run both on Node and in browsers.

Developing with Exonum

The cryptocurrency tutorial provides a step-by-step guide on how to develop applications on top of the Exonum framework.