Bugs

Bugs should be filed in our bug tracker. Questions and comments can be sent to the developer mailing list: ramcloud-dev(As of 2019/10/7 support for RAMCloud has ended)

Necessary Tools

To get a working toolchain on Debian (and probably Ubuntu), this used to be sufficient:

aptitude install build-essential git-core doxygen libboost1.42-all-dev libpcre3-dev protobuf-compiler libprotobuf-dev libcrypto++-dev libevent-dev

To get a working toolchain on SUSE Linux Enterprise or openSUSE perform the following steps:

zypper rm libevent-1_4-2 *boost*
zypper install mpfr-devel glibc-devel-32bit doxygen scons libzip-devel libbz2-devel pcre-devel *boost*1_44*
Install from sources: libevent-2.0.20-stable, protobuf-2.4.1, cryptopp560, gcc-4.4.6

Here are some toolchain installation commands that have worked for other members of the community on different systems:

OSCommand
Ubuntu 15.04 /
Debian 8.2 
apt-get install build-essential git-core doxygen=1.7.1 libpcre3-dev protobuf-compiler libprotobuf-dev libcrypto++-dev libevent-dev libboost-all-dev libgtest-dev libzookeeper-mt-dev zookeeper libssl-dev

Source Code

For Core Developers

For those with r+w access to the repository on GitHub, which currently hosts our git repository, clone from here for write access:

git clone git@github.com:PlatformLab/RAMCloud.git
cd RAMCloud
git submodule update --init --recursive
ln -s ../../hooks/pre-commit .git/hooks/pre-commit

(Notes: the git submodule update retrieves additional repos needed to build RAMCloud, such as gtest; the ln -s command arranges for various consistency checks to run during commits, such as ensuring the absence of carriage returns)

For Read-Only Access

Use the same instructions as above, except replace "git@github.com:PlatformLab/RAMCloud.git" with "https://github.com/PlatformLab/RAMCloud.git" in the git clone command. With this approach you don't need to have r+w access to the repository on GitHub, and you can't push commits to the repository. With read-only access, you can send us patches, or we can pull them from your repository.

Compiling

cd RAMCloud   
make -j12

Object files and executables will appear in the subdirectory obj.xxx, where xxx is your current branch (typically master). By default, RAMCloud compiles with debugging symbols, which slows the system down considerably.  If you want to make performance measurements, recompile without debugging symbols:

make clean
make -j12 DEBUG=no

CentOS Issues

This shouldn't be necessary any more on the Stanford cluster, as /etc/skel/.bashrc now includes the line. -Diego 2012-04-15

Update your LD_LIBRARY_PATH to include /usr/local/lib. If you do not do so, you'll get cryptic errors claiming libramcloud.so cannot be found. It can, but some of its dependencies in /usr/local/lib cannot. Do the following:

echo "export LD_LIBRARY_PATH=/usr/local/lib" >> ~/.bashrc
export LD_LIBRARY_PATH=/usr/local/lib                           [or log out and back  in]

Interesting Targets

Style Rules

We have a comprehensive style guide for how code should be formatted in RAMCloud. Actually, we don't quite follow what that style guide says, but we do keep a consistent style.

If you use GNU EMACS this configuration can help.

Commit Style Rules

Obviously, you can do anything you want on your own clones.

You can also do anything you want to your own branches on fiz, including rewriting their histories in any way. (If you're working with someone else on a branch on fiz, you might want to use stricter rules.)

An issue below roughly means a logically independent change to the code base.

For any pushes into the master branch on fiz:

Speed Up Build

Put the following lines in the file `private/MakefragPrivateTop`:

# Use ccache to speed up compilation by caching object
# files across compilations.
CCACHE := yes
# Use gold linker for faster linking.
LINKER := gold

Running Under Valgrind

Compiling unit test:

make VALGRIND=yes test 

Running unit test:  The 'master' part in 'obj.master' could be replaced your git branch name.

 valgrind --leak-check=yes obj.master/test 

Running system test with valgrind: Use 'scripts/cluster.py', which posts RAMCloud tasks into the server cluster, with '–valgrind'. Use '–valgrindArgs' to pass the options to valgrind:

  scripts/cluster.py --verbose --timeout=600 --valgrind --valgrindArgs='--leak-check=yes --leak-resolution=med --show-reachable=no --undef-value-errors=no' --client=RAM-462/ram462test

Running With Google's Sanitizers

There are currently three Sanitizers available in the build option: AddressSanitizer (ASan), ThreadSanitizer (TSan) and UndefinedBehaviorSanitizer (UBSan). They can be enabled with the SANITIZER symbol. Different Sanitizers are not consistent with each other, so there can be only one Sanitizer enabled at a time.

Building RAMCloud and unit tests with ASan: Similarly, replace 'address' with 'thread' or 'undefined' to enable TSan or UBSan respectively.

make SANITIZER=address tests

Running unit tests and system tests are the same as usual once RAMCloud and the respective test files are compiled with the Sanitizer.

For more information (e.g., the kinds of bugs each Sanitizer can find, bug report format, additional runtime options, etc.), see: https://github.com/google/sanitizers/wiki

Additional Sanity Checks

Before pushing to the master branch on fiz it is generally a good idea to make sure your changes haven't caused regressions in the recovery system.

./scripts/recovery.py
./systemtests/run.py