 |
Bayeux
3.4.1
Core Foundation library for SuperNEMO
|
|
Bayeux
3.4.1
Core Foundation library for SuperNEMO
|
This walkthrough is intended to get you up and running with Bayeux as fast as possible. It therefore adopts a specific layout of where working copies of sources, builds of these sources and installs of the builds. You do not have to follow this layout, but we recommend it as a fast and convenient way to organise things. We welcome constructive comments, criticisms and suggestions for improvement, and these should be directed to the Bayeux/SuperNEMO Software Working Group.
To install the Bayeux stack, you first need the following:
In addition to the tools used to build Bayeux, the following libraries are needed to support its functionality:
You can reuse any existing installations of these libraries on your system to build Bayeux against. For the easiest and most robust installation, we recommend using the Cadfael Software Development Kit. This is based on the Linuxbrew cross UNIX platform package manager and provides a robust installation of the dependencies. It also provides the needed build tools listed earlier. To install Cadfael and the requisite software packages, see the dedicated installtion guide.
We expect the Bayeux stack to compile and run on most modern BSD or Linux based systems provided the listed Required Software is installed. Note however that this list is a work in progress, and sections below will highlight where problems may occur with missing software, and how to report and resolve these issues.
Bayeux is developed using the Subversion repository hosted by LPC Caen. Whilst you need a full account to commit to the repository, we will be using the provided read-only access.
To work with the software, we recommend using the following layout of code in directories:
where the BxSoftware is the arbitrary name of a directory that can be located where you wish, though it must be on a filesystem with the required free space.
If you already have a workspace setup, then you can skip to the following section. Otherwise to create it, open a terminal, and choose a directory for your software workspace. For clarity in this guide, because absolute paths are needed in certain cases, we will use the dummy directory /Users/ben, but you should choose your own location (${HOME}/Software, /usr/local...). The first step is to create the directory hierarchy:
With the directories in place, we can checkout the code. This is done via the svn command line client, and we be using a "sparse checkout" pattern. Whilst this requires a few more steps upfront, it provides a very stable and well organised working copy.
Note that in the following, we demonstrate how create a checkout by the fastest and easiest means possible. This means that you end up with:
If you already have a developer's account at LPC Caen, then the following instructions will also work, simply remove the --username and --no-auth-cache arguments from the svn commands.
At this point, you may see a warning about certificates:
Simply press t or p to accept the certificate. The process will then continue by asking for the password for visitor, for which you should enter anonymous (If you have accessed the LPC repository before, you may not see either the certificate check or password prompt).
The revision number you see will vary depending on the current state of development. If you now list the contents of the lpc-caen.svn directory it will be empty apart from a .svn directory. We now checkout the parts we need, specifically the Bayeux project.
As above, the revision number will depend on the current state of development. Each LPC project is organised using the standard Subversion directory layout of trunk for the mainline of development, branches for feature implementation and bug fixes, and tags for releases.
An ls of the above directories will show that, again, they are empty. However, if you use Subversion's list command, e.g.
you will get a listing of the contents in the upstream repository. This is what we mean by a "sparse checkout". Such a working copy allows you to query the repository for what is available, and then choose the parts you want to checkout. For example, you can get a list of the current tags of Bayeux by doing
Tags are always named using the standard MAJOR.MINOR.PATCH convention with an optional additional -STATUSN flag to indicate development lines.
With the workspace in place, we can checkout the required development lines of Bayeux. The version of Bayeux to which this documentation refers is 3.4.1. To check this tags out from scratch we do
The basic source code working copy is now in place. For more details on using Subversion, we recommend the Subversion Red Bean Guide.
Bayeux uses the CMake tool for driving the configure, build and install of its core library and applications. To ensure we don't mix up core source files with those generated by the build, we create a separate directory in which to configure and build under builds first:
The naming of the build directory is arbitrary, but it's useful to give them a name related to the build task.
We now run cmake in the build directory to configure the build. Here, we've used the CMAKE_INSTALL_PREFIX variable to specify where to install the build products.
Further options may be passed to CMake either via -D<OPTION>={ON|OFF} arguments on the command line or through the CMake curses/GUI interfaces to configure optional parts of Bayeux:
BAYEUX_ENABLE_TESTING : build the collection of testing programs (default: OFF),BAYEUX_WITH_DOCS : build and install the documentation (build with Doxygen, default: ON)BAYEUX_WITH_DOCS_OCD : build and install Object Configuration Description (OCD) documentation (default: ON, only if Bayeux_BUILD_DOCS is set).BAYEUX_WITH_GEANT4_MODULE : build the Bayeux/mctools Geant4 plugin library and associated tools (default: ON),BAYEUX_WITH_DEVELOPER_TOOLS : build and install utilities for developers (helper scripts and tools, default: ON)The exact output of the configuration step will depend on the OS you are running on, the compiler detected and the exact CMake version (later versions are more verbose). The important thing to check is that you see the last three lines
which indicate a successful configuration. By default, CMake generates a Makefile describing the build of Bayeux, so to run the build we just run make:
You should select the integer passed to -j based on the number of cores your system has, e.g. 4 for a quad core system. With parallel builds the exact output will vary, but a successful build will generally be indicated by the last lines being:
After a successful build, you can install Bayeux to the location you passed to CMAKE_INSTALL_PREFIX with
This will install everything required into a POSIX style hierarchy under the install prefix:
Note that the exact name of the lib directory will depend on the specifics of your platform.
If the Bayeux_ENABLE_TESTING configure option has been set, you can run unit tests for Bayeux by "building" the test target:
This will run all available testing programs and will report their success or failure. If all tests are successful, it will print these last lines:
which indicates that no errors occured.
You do not require any environment setup to use the installed applications, though you may, at your preference, prepend the ̀installs/bayeux-3.4.1/bin path to your UNIXPATH`. From a sh shell, this may write:
Once you have installed Cadfael successfully, you can safely remove the build directory to save disk space.
TODO
Whilst this walkthrough guide should cover most uses cases, we cannot guarantee that problems will not be encountered. If you do experience issues with any of the steps, please contact us, in the first instance email your issue to:
TODO Setup :
Please attach as much information as possible (operating system and version, compiler and version, CMake version etc) to assist in diagnosing the issue.
To checkout the trunk of Bayeux, we use the same procedure as for checking out a release and just change the path slightly:
This trunk version can be configured, built and tested using CMake just as described in the installation guide above. It is not recommended to install trunk builds due to the ongoing development cycle.
Other than the unit tests, Bayeux's builtin programs can be run directly from the build directory. All products of the build are output into a BuildProducts subdirectory of the main build directory. BuildProducts contains a directory hierarchy matching that of the final install prefix, by default:
Programs under the bin subdirectory may be run directly as required for testing or using.
1.8.15