Rippled build instructions

From Ripple Wiki
Jump to: navigation, search

Overview

We recommend you use yum to install rippled.

These are the instructions for building rippled from source and running unit tests. Binaries for rippled can be found in the rippled setup section.

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

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 rippled is stopped.

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

Please be aware that these tests may fail if rippled has not been built yet.

node-inspector

Node-inspector allows using a Chrome or Safari browser as a debugger.

Installation:

npm install node-inspector

Add to path.

Debugging:

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

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

Building

Build rippled:

scons

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 [test or module name]

Run the Javascript driven unit tests:

npm install
npm test

Please be aware that these tests may fail if rippled has not been built yet.

Running multiple instances

For each instance you wish 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

Whatever the platform, we recommend a minimum of 8Gb ram for building rippled.

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.57-all-dev
# apt-get install protobuf-compiler libprotobuf-dev
# apt-get install nodejs

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

Ubuntu (14.04 LTS)

We recommend following the linked instructions.

https://wiki.ripple.com/Ubuntu_build_instructions

Alternatively, as root, you may make a text file and add:

# add-apt-repository -y ppa:boost-latest/ppa ; sudo apt-get update ; apt-get -y upgrade ; 
# sudo apt-get -y install git scons ctags pkg-config protobuf-compiler libprotobuf-dev libssl-dev python-software-properties libboost1.57-all-dev nodejs; 
# git clone https://github.com/ripple/rippled.git ; cd rippled/ ; git checkout master ; scons ; ./build/rippled --unittest ; sudo apt-get install npm; npm install; npm test

Make sure to chmod +x the file name and remove the # sign (which is added for readability on the wiki page) before running.

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
echo "dev-libs/boost static-libs threads context" >> /etc/portage/package.use
echo "dev-libs/openssl static-libs" >> /etc/portage/package.use
echo "sys-libs/zlib static-libs" >> /etc/portage/package.use
echo "dev-libs/protobuf static-libs" >> /etc/portage/package.use
emerge -uN layman
layman -S
layman -a bitcoin
emerge -av rippled

Alternatively, if you're building from scratch:

  • Make sure you install boost with these USE flags: static-libs thread context
  • emerge -avu dev-libs/boost dev-libs/protobuf dev-util/scons

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

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.

Post Install

You may want to seed a new ripple gateway wallet when you are done, please see https://ripple.com/wiki/Setup_a_gateway_account