Rippled build instructions
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.
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.
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 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 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:
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.
Minimum version: 2.4.1
(needed just for compiling)
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:
Switch to the master branch:
git checkout master
Alternative, use the develop branch:
git checkout develop
Or use the release branch:
git checkout release
These elements should be brought into the Ripple development tree.
npm is the node package manager. You will need nodejs installed on your system.
Ripple has the following npm dependencies and more:
- Higher-order functions and common patterns for asynchronous code
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.
Ensure you have a current version of Node.js.
To install NPM dependencies, run:
Add node_modules/buster/bin to your path:
set 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:
Running all tests:
Or, if you have Buster.JS installed globally:
Node-inspector allows using a browser as a debugger.
npm install node-inspector
Add to path.
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.
Build only rippled:
Clean out object files (equivalent to running `make clean`):
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:
By default rippled is compiled with debugging symbols included. This increases the size of the executable by an order of magnatude.
Run the built-in unit tests:
Run a specific built-in unit test:
build/rippled --unittest -- --run_test=Utils
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:
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.
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
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
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.
Ubuntu LTS 12.04.1, 64-bit
See the Amazon instructions above.
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.
To build rippled on Windows platforms, follow the Visual Studio 2013 Build Instructions.