urb_tree stands for universal Red-Black tree, which is a generic C/C++ and Fortran implementation of Red-Black trees with, easy-to-use and fast traversal routines.
The following section is a step by step guide that will take you from fetching the source code from the repository branches to running your urb_tree first examples on your machine.
The project contains two git main branches: master and develop. The master branch only contains the major releases, and is intended to use the library as is. We recommend to clone from this branch if you would like to use the latest stable version. The releases are tagged on the master branch and each version has a major number and a minor number which are used as the tagging string (.e.g. the first release is tagged 1.0 on the master branch). Cloning the master branch and checking out the latest release can be done as follows:
git clone --recursive -b master https://github.com/issamsaid/urb_tree.git
Note that the --recursive option is added to include all the submodules used
by urb_tree to the cloned repository.
If you wish to clone a specific release (here we use the 1.0 release as
an example) you may add:
pushd urb_tree
git checkout tags/1.0
popd
The following table summarizes the different details about all the
releases of the urb_tree library:
| Release number (tag) | Date | Description |
|---|---|---|
| 1.0 | 08/18/2016 | The initial release of the urb_tree library |
On the other hand, the develop branch contains the latest builds and is intended to be used by the developers who are willing to contribute or improve the library. To get started, you can clone this branch as follows:
git clone --recursive -b develop https://github.com/issamsaid/urb_tree.git
The urb_tree project has multiple components, each in a subdirectory of the root directory (urb_tree). The src subdirectory is the C/C++ interface, the fortran_interface subdirectory is the Fortran interface, the test subdirectory contains the unit tests of the library, the doc subdirectory is where the documentation of the library is to be generated, and the examples includes a set of examples of how to use the library. The project can be compiled using the cmake utility as follows:
pushd urb_tree
mkdir build
pushd build
cmake -G"Unix Makefiles" ../
popd
The current version of the urb_tree library had been tested on various Linux workstations with the GNU and Intel compilers. Nevertheless, if you face issues with other compilers you are kindly invited to report them. To build the library you can run the default target which compiles the C/C++ interface only:
pushd build
make urb_tree
popd
This Makefile target will build the static library liburb_tree.a from the C/C++
source files in the src
subdirectory.
In order to install the libraries on the lib subdirectory you can run:
pushd build
make install
popd
You can also classically run the following in order to build only the C/C++ interface and install it:
pushd build
make all install
popd
The documentation of the library can be generated, in the doc subdirectory, with the help of doxygen by simply running:
pushd build
make doc
popd
It is now up to you to read the documentation and check the examples in order to use urb_tree to write your own codes for scientific purposes.
In order to use the urb_tree C/C++ link your code against liburb_tree.a
(by adding -lurb_tree to your linker options),
however if your code is based on Fortran the
latter should linked against both the C/C++ library and the Fortran interface (
with the help of the options -lurb_tree_fortran -lurb_tree).
If you want to work with the latest build, you are invited to fetch from the develop branch. The library comes with a set of unit tests and performance tests (on top of the googletest Framework) to validate the new features. You can check the unit testing directory here. The testing framework is used to thoroughly test urb_tree in C/C++ (test/src).
pushd build
make urb_tree_test
make install -C test // This is needed due to a cmake bug
popd
Tests should be written for any new code, and changes should be verified to not break existing tests before they are submitted for review. To perform the tests (which are automatically built when you compile the library) you can run:
pushd test
./bin/urb_tree_test // for C/C++
popd
Or simply:
pushd build
make test
popd
The library comes with an examples subdirectory which contains some C/C++ and Fortran samples. Those can be built and installed as follows:
pushd build
make urb_tree_examples
make install -C examples // This is needed due to a cmake bug
pupd
The examples binaries can be browsed in the test/bin subdirectory.
I use Travis CI for the continuous integration of the urb_tree library. The image on the top of the page is a link to the latest build of each branch. A build is launched after each pull request with respect to the Travis CI configuration file .travis.yml.
If you believe that urb_tree can be used in the scope of your work, and that it could be extended to fit your needs, feel free share your feedbacks and proposals of features and use cases. If you are willing to contribute please visit the contributors guide CONTRIBUTING, or feel free to contact me.
urb_tree is a free software licensed under BSD.
For bug report, feature requests or if you willing to contribute please feel free to contact me by dropping a line to said.issam@gmail.com.