Warning
The code base for this project is under heavy and recent development. Please expect nothing from it for the time being; there is not yet a version that we consider "stable".
Bugs
Bugs should be filed in our bug tracker. Questions and comments can be sent to the developer mailing list: ramcloud-dev.
Necessary Tools
- GNU Make (Anything reasonably recent)
- GNU g++ (>= 4.4.6)
- git (>= 1.6.0)
- Perl (Anything reasonably recent)
- For mergedeps.pl, which automatically inserts included headers in source files into the make dependencies.
- Python 2.6, epydoc
- Boost
- If you're having issues with Boost on Ubuntu, check boost ticket #3844.
- pcre
- Doxygen 1.7.2
- protocol buffers
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
Source Code
For Contributors
For read-only repository access:
git clone git://fiz.stanford.edu/git/ramcloud.git cd ramcloud git submodule update --init --recursive make logcabin ln -s ../../hooks/pre-commit .git/hooks/pre-commit
(Notes: the git submodule update
retrieves additional repos needed to build RAMCloud, such as gtest and logcabin
; the ln -s
command arranges for various consistency checks to run during commits, such as ensuring the absence of carriage returns)
Don't worry about having read-only access; it really shouldn't impede you. We'd prefer to pull changes from you or have you send patches (see git-format-patch). This lets us ensure that the fiz repo is generally in a working state and is making forward progress.
For Core Developers
For those with fiz accounts clone from here for write access:
git clone ssh://fiz.stanford.edu/git/ramcloud.git cd ramcloud git submodule update --init --recursive make logcabin ln -s ../../hooks/pre-commit .git/hooks/pre-commit
Compiling
cd ramcloud make
LogCabin
LogCabin is a distributed system that will provide a small amount of highly replicated, consistent storage. It will be used by the RAMCloud Coordinator mainly for fault tolerance.
More information about LogCabin can be found at: https://ramcloud.stanford.edu/wiki/display/logcabin/LogCabin.
For current users of RAMCloud who have just pulled the latest commits that link RAMCloud to LogCabin, or if the LogCabin submodule is updated at any point, run:
git submodule update --init --recursive make logcabin
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
make
- build the RAMCloud server and client software- Output
obj.master/client/client, obj.master/server/server
- Replace 'master' with the git local branch name you are on if it is not 'master'
- Output
make tests
- build and run RAMCloud unit tests (requires CppUnit)make check
- currently runs Google style checker against files in the src directory; subject to check as style evolves
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:
- No commit should include changes for multiple issues. (Each commit in the push should complete or work towards a single issue.)
- Pushes should complete any issues they start, but individual commits within a push do not need to complete an issue.
- All commit messages should be meaningful without looking at the diff. (By reading a commit message, you should get some idea of what was modified and what the intent was. If you can't fit this in one line, skip a line and then write more.)
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
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
recovery.py runs a small but complete recovery. See Running Recoveries with recovery.py for details on testing more complicated recoveries with this tool.
- run.py runs a variety of messed up failure scenarios that try to exercise the system. As the system is able to tolerate more scenarios they will be added to this test suite.