Rippled build instructions

From Ripple Wiki
Jump to: navigation, search

Contents

Overview

These are the instructions for building rippled and running unit tests. Binaries for rippled are not currently provided.

These instructions are provided as a guide. As anyone can edit this wiki, for security reasons alone, you should make sure you understand all commands and their implications.

rippled is build with a software construction tool named scons. The build process checks that key packages - OpenSSL and Boost - are up-to-date; you can also override compilation flag defaults, or set tags to control aspects of the build like debug mode.

See also:

External dependencies

Your system should have the following development libraries installed. Be sure to upgrade gcc to v4.8 or later because the codebase makes use of constructs only supported in the latest releases.

boost

The latest version of boost is typically required to build rippled. We suggest a separate installation of boost just for rippled, following the build instructions for boost provided at http://boost.org.

OpenSSL

OpenSSL is a security critical dependency for rippled. It is important that you have an up-to-date version of this library.

Under Linux, you can install a fresh version like this:

apt-get install libssl-dev

ctags (optional)

CTags allows editors, such as vim, to be able to jump to function definitions.

You can prevent scons' default use of ctags by explicitly specifying rippled as your build target:

scons build/rippled

node.js and npm (optional)

While not strictly necessary, having node.js will allow you to run the unit tests and help ensure your system is operating properly.

On some distributions, npm is included in the node.js package.

protocol buffers

Minimum version: 2.4.1

(needed just for compiling)

Other packages

  • scons
  • pkg-config
apt-get install pkg-config

Getting the Repository

Clone the repository:

git clone https://github.com/ripple/rippled.git

The repository is now in the rippled directory.

Move into the rippled directory:

cd rippled

Switch to the master branch:

git checkout master

Alternative, use the develop branch:

git checkout develop

Or use the release branch:

git checkout release

Internal dependencies

These elements should be brought into the Ripple development tree.

npm

npm is the node package manager. You will need nodejs installed on your system.

Ripple has the following npm dependencies and more:

ripple-lib
JavaScript library for rippled. Required for unit tests.
async
Higher-order functions and common patterns for asynchronous code
buster
Buster.JS JavaScript test framework

From the base of the source directory, install the node dependencies.

Install all of the rippled test suite node dependencies:

# npm install

This command installs the required packages in the current directory under: node_modules

The "should be installed with -g" should be a harmless warning.

Unit testing

Ensure you have a current version of Node.js.

To install NPM dependencies, run:

npm install

Configuration

Add node_modules/buster/bin to your path:

tcsh:

set path=( node_modules/buster/bin $path )

bash:

PATH=node_modules/buster/bin:$PATH

Create a test/config.js:

cp test/config-example.js test/config.js

Edit config.js as appropriate for your system.

Running CLI tests

The test runner will create a `tmp` folder in the root of the repository, with an auto-generated `ripple.cfg` file, and a folder for the db backend's disk storage. The configuration is generated from the `servers` object exported from `rippled/test/config.js`. There is an example configuration file at `rippled/test/config-example.js` you can copy to create this. You must specify a db backend (NodeBackEnd) to be able to run the tests.

Running a single test:

node test/module-test.js

Running all tests:

npm test

Or, if you have Buster.JS installed globally:

buster test

node-inspector

Node-inspector allows using a browser as a debugger.

Installation:

npm install node-inspector

Add to path.

Debugging:

inspector.js &
node --debug-brk --debug whatever.js 

Head to http://0.0.0.0:8080/debug?port=5858 to find your app nicely stopped on the first line.

Building

Build everything:

scons

Build only rippled:

scons build/rippled

Build quietly:

scons -Q

Clean out object files (equivalent to running `make clean`):

scons -c

Build with specified number of simultaneous jobs (ideal for multiprocessor systems):

scons -j jobs

On Linux, specify the number of jobs automatically:

setenv SCONSFLAGS "-j `grep -c processor /proc/cpuinfo`"

The compiled binary will be found here:

build/rippled

By default rippled is compiled with debugging symbols included. This increases the size of the executable by an order of magnatude.

Unit Tests

Run the built-in unit tests:

build/rippled --unittest

Run a specific built-in unit test:

build/rippled --unittest -- --run_test=Utils

Run the Javascript driven unit tests:

npm install
npm test

Running multiple instances

For each instance you which to run:

Create a directory for the instance.

mkdir alpha ; cd alpha

Create a configuration file specifying where the server should listen at: rippled.cfg

Launch rippled as a local, stand alone server:

rippled -a &

Use rippled as a command line agent to send a command to a server:

rippled stop

OS specific instructions

Amazon Web Services

Ubuntu (12.04 LTS Precise Pangolin)

These instructions are a guide to the commands needed to set up rippled. You should understand the commands and the available options before executing them. Most of these commands should be executed as root.

Verify the version of Ubuntu:

$ cat /etc/issue
Ubuntu 12.04.1 LTS \n \l

Update the packages database:

# sudo apt-get update

Upgrade the system:

# sudo apt-get upgrade

get add-apt-repository via

# sudo apt-get install python-software-properties

Add a more recent node repository:

# sudo add-apt-repository ppa:chris-lea/node.js

If you have a smaller instance, you will want to create and enable swap space. Otherwise, your system may not have enough memory to compile rippled.

Create a swap file:

# dd if=/dev/zero of=/swap bs=1024 count=1M

Format the swap file:

# mkswap /swap

Enable the swap file:

# swapon /swap

Enable swap on boot:

# echo "/swap swap swap sw 0 0" >> /etc/fstab

To verify swap is enabled:

# swapon -s
Filename                      Type            Size    Used    Priority
/swap                         file            1048572 0       -1

Install various dependencies:

# apt-get install pkg-config git scons ctags
# apt-get install libboost1.55-all-dev
# apt-get install protobuf-compiler libprotobuf-dev
# apt-get install nodejs

Download the source code for rippled and compile it as normal.

CentOS

Using CentOS is not recommended. No recent version of BOOST is available for this platform.

Verify the version of CentOS you are using:

# cat /etc/issue
CentOS release 6.3 (Final)

Upgrade your packages:

# yum update

Install required dependencies:

# yum install gcc-c++ scons openssl ctags
# yum localinstall  http://kojipkgs.fedoraproject.org//packages/protobuf/2.3.0/7.el6/i686/protobuf-2.3.0-7.el6.i686.rpm
http://kojipkgs.fedoraproject.org//packages/protobuf/2.3.0/7.el6/i686/protobuf-compiler-2.3.0-7.el6.i686.rpm
http://kojipkgs.fedoraproject.org//packages/protobuf/2.3.0/7.el6/i686/protobuf-devel-2.3.0-7.el6.i686.rpm

Gentoo

Rippled is available from the bitcoin portage overlay.

echo "app-portage/layman git" >> /etc/portage/package.use
emerge -uN layman
layman -S
layman -a bitcoin
emerge -av rippled

Arch Linux

Build and install the AUR package:

Review the configuration file located at /etc/rippled/rippled.cfg and start the server:

# rippled --conf=/etc/rippled/rippled.cfg

Please note that the PKGBUILD files do not install initscripts or .service files for rippled, so you will be responsible for arranging for rippled to start at boot-time.

OSX

See OSX Build Instructions

Ubuntu LTS 12.04.1, 64-bit

See the Amazon instructions above.

FreeBSD

Install the following ports:

devel/boost-libs
devel/protobuf
devel/scons
security/openssl

Build rippled by running scons from the main directory. You may receive errors about exuberant-ctags not being found and warnings about symbols with names beginning with ILL_ being redefined. These can be ignored.

Windows

To build rippled on Windows platforms, follow the Visual Studio 2013 Build Instructions.

Personal tools
Namespaces

Variants
Actions
Navigation
Tools