uparser is a C/C++ and Fortran command line argument parser.
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 uparser 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 -b master https://github.com/issamsaid/uparser.git
If you wish to clone a specific release (here we use the 1.0 release as an example) you may add:
pushd uparser
git checkout tags/1.0
popd
The following table summarizes the different details about all the
releases of the uparser library:
| Release number (tag) | Date | Description |
|---|---|---|
| 1.0 | 11/01/2016 | The initial release of the uparser 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 -b develop https://github.com/issamsaid/uparser.git
The uparser project has multiple components, each in a subdirectory of the root directory (uparser):
- 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.
The project compilation framework is to be setup using the cmake utility. Depending on your operating system you may choose a specific cmake generator to build the project. As an example, if you wish to build uparser on Unix based operating systems you can use the following (the rest of the examples in this material are also intended to be used on Unix based systems):
pushd uparser
mkdir build
pushd build
cmake -G"Unix Makefiles" ../
popd
The current version of uparser had been tested on various Linux
distributions with the GNU, Cray and Intel compilers.
Nevertheless, if you face issues with other compilers you are kindly invited to report them.
Note that if you are using Cray compilers you have to specify where the
Fortran compiler is wrapped. For example if you are using ftn you have to add:
pushd uparser
mkdir build
pushd build
cmake -DCMAKE_Fortran_COMPILER=ftn -G"Unix Makefiles" ../
popd
uparser uses internally the urb_tree libraries ( a red-black trees generic libraries) in order to track and efficiently manipulate some internal data structures. It also relies on the googletest framework for unit testing. Those libraries are automatically downloaded, compiled and installed when building uparser. Alternatively you can set the path to those libraries if they are already installed on your system as follows:
export URB_TREE_DIR="YOUR_PATH_TO_URB_TREE"
export GTEST_DIR="YOUR_PATH_TO_GTEST"
To build the uparser C static library you can run the default Makefile target as follows:
pushd build
make uparser
popd
This Makefile target will build the static library libuparser.a from the C/C++
source files in the src
subdirectory.
Since this is the default target you can also build the static C library
as follows:
pushd build
make
popd
If you would like to build the Fortran interface additionally, you can do so as follows:
pushd build
make uparser_fortran
popd
This target will build another static library libuparser_fortran.a from the
Fortran source files present in the
fortran_interface subdirectory. Note that the Fortran interface is only
an additional layer based on the Fortran 2003 standard (ISO/IEC 1539-1:2004(E)),
which generates procedure and derived-type declarations and global variables that are interoperable with C. Therefor, if the C/C++ interface is not built this target will build it as well.
The library comes with a set of unit tests and performance tests to validate the new features. You can check the unit testing directory here. The testing framework is used to thoroughly test uparser in C/C++ (test/src) and Fortran (test/fortran). The C/C++ interface unit tests are based on top of the googletest Framework). To build all the unit tests, C/C++ and Fortran included, you can invoke the following target:
pushd build
make build_tests
popd
Alternatively make uparser_test will only build the test suit for the C/C++ interface, and make uparser_test_fortran will build the unit tests for the
Fortran interface.
Tests should be written for any new code, and changes should be verified to not
break existing tests before they are submitted for review.
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
In order to install the uparser project you can invoke the classic Makefile install target:
pushd build
make install
popd
This target mainly installs the uparser C/C++ static library in the lib subdirectory on the project root directory. If the Fortran static library, the unit tests binaries and the examples binaries are built, they will be installed
respectively in the lib, test/bin and examples/bin subdirectories.
We use Travis CI for the continuous integration of the uparser 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). (We still trying to find out a way to emulate GPUs on travis since it does not feature GPUs for the time being).
In order to use the uparser C/C++ link your code against libuparser.a
(by adding -luparser 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 -luparser_fortran -luparser).
To perform the unit tests you can run:
pushd test
./bin/uparser_test // for C/C++
./bin/uparser_test_fortran // for Fortran
popd
It is now up to you to read the documentation in order to use uparser to write your own codes for various purposes.
We believe that uparser can be used by scientific programmers very efficiently. We tend to extend the functionalities of the library. For this to do we need 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 us.
uparser is a free software licensed under BSD.
For bug report, feature requests or if you willing to contribute please feel free to contact Issam SAID by dropping a line to said.issam@gmail.com.