Commit b5596665 authored by Lynn Garren's avatar Lynn Garren
Browse files

using a single README in markdown format - Ben Morgan

parent ae4a23b9
#-------------------------------------------------------------
# building CLHEP
#-------------------------------------------------------------
Cmake is now the only build option.
Please see INSTALL.cmake for directions.
#-------------------------------------------------------------
# about linking
#-------------------------------------------------------------
CLHEP builds libraries for each package in addition to a single CLHEP library.
This alllows you to link with only the necessary parts of CLHEP.
We provide a set of <package>-config scripts which gives the list of
libraries to link, in the correct order.
The script can be embedded in a makefile.
clhep-config --libs - link list of ALL CLHEP libraries
<package>-config --libs - link list of ONLY those libraries
needed to use <package>
#-------------------------------------------------------------
#-------------------------------------------------------------
# building CLHEP with cmake
#-------------------------------------------------------------
At this time, the cmake build system only supports building
CLHEP as a complete package, starting from the top level directory.
This package requires cmake 2.6 or later.
#-------------------------------------------------------------
# installing from a source code tar ball
#-------------------------------------------------------------
Unwind the source code tar ball in some relevant directory.
Determine where the files will be installed.
Create a build directory that is NOT in the source code directory tree.
Make sure cmake is in your path.
cd <build_directory>
cmake -DCMAKE_INSTALL_PREFIX=<install_dir> <source_code_dir>
(Note that files will be installed under /usr/local if you do not
specify a prefix.)
make
(Build temporary copies of libraries and executables.)
make test
(Run the tests.)
make install
(Copy libraries, headers, executables, etc. to relevant
subdirectories under <install_dir>.)
#-------------------------------------------------------------
# cmake options
#-------------------------------------------------------------
-DCMAKE_INSTALL_PREFIX=/install/path
-DCMAKE_BUILD_TYPE=Debug|Release|RelWithDebInfo|MinSizeRel
-DCLHEP_BUILD_DOCS=ON
-DCMAKE_C_COMPILER=...
-DCMAKE_CXX_COMPILER=...
-DCMAKE_CXX_FLAGS="list_of_flags"
-DCLHEP_BUILD_CXXSTD=ON (enable c++11 extensions and thread support)
-DCLHEP_BUILD_CXXSTD="-std=c++NN" (use specified c++ extension and thread support)
-DLIB_SUFFIX=64 (installs the libraries in a lib64 subdirectory)
IMPORTANT:
If you include -DCLHEP_BUILD_DOCS=ON, do not use "make -jN"
#-------------------------------------------------------------
# building documents
#-------------------------------------------------------------
Documents are not built or installed automatically.
If you wish to build and install the documents,
add -DCLHEP_BUILD_DOCS=ON to your cmake command.
Documents will then be built during the normal build.
You will need to have latex in your path.
#-------------------------------------------------------------
# building from git
#-------------------------------------------------------------
To work with the head:
git clone http://git.cern.ch/pub/CLHEP
To work with a tag:
git clone http://git.cern.ch/pub/CLHEP
Use "git tag" to see the available tags.
git co <tag>
Now continue with directions as if you unpacked a source code tarball.
#-------------------------------------------------------------
# building cmake
#-------------------------------------------------------------
cmake 2.6 or later is readily available for Linux,
although you may need to install it
download the cmake tar file from http://www.cmake.org/cmake/resources/software.html
You may find a usable binary distribution there.
If not, get the source code and proceed as below (for either MacOSX or Linux).
Unwind the source code tarball. This directory is <cmake_source_dir>.
Identify a separate build directory and a separate install directory:
<cmake_build_dir> and <cmake_install_dir>.
cd <cmake_build_dir>
<cmake_source_dir>/bootstrap --prefix=<cmake_install_dir>
make
make install
Add <cmake_install_dir>/bin to your path.
#-------------------------------------------------------------
Full information on CLHEP is available on the WEB:
http://cern.ch/clhep
#-------------------------------------------------------------
# about linking
#-------------------------------------------------------------
CLHEP builds libraries for each package in addition to a single CLHEP library.
This alllows you to link with only the necessary parts of CLHEP.
We provide a set of <package>-config scripts which gives the list of
libraries to link, in the correct order.
The script can be embedded in a makefile.
clhep-config --libs - link list of ALL CLHEP libraries
<package>-config --libs - link list of ONLY those libraries
needed to use <package>
#-------------------------------------------------------------
CLHEP C++ Class Library for High Energy Physics
===============================================
- [CLHEP Home Page](http://proj-clhep.web.cern.ch/proj-clhep/)
- [Git Repository] (http://git.cern.ch/pubweb/CLHEP.git)
- [Bug Reports and Feature Requests](https://its.cern.ch/jira/browse/CLHEP/)
Installing CLHEP
================
Prerequisites
-------------
- Linux/OS X/BSD/Windows OS
- C++11 compliant compiler (GCC >= 4.8, Clang >= 3.3, Intel >= 15, MSVC >= 19)
- If the Intel compiler is used with GCC compatibility, it should be configured
to use GCC 4.8 or higher
- [CMake](http://www.cmake.org) >= 3.2
Building CLHEP with CMake
-------------------------
At this time, the cmake build system only supports building CLHEP as a
complete package, starting from the top level directory. Note, however,
that individual package libraries will still be build.
Unwind the source code tar ball in some relevant directory. Determine a prefix
under which CLHEP should be installed. Create a build directory that is
NOT in the source code directory tree (i.e. the tree rooted where this README
resides).
```
$ cd <build_directory>
$ cmake -DCMAKE_INSTALL_PREFIX=<install_dir> <source_code_dir>
$ cmake --build . --config RelWithDebInfo
$ ctest
$ cmake --build . --target install
```
The above will configure the build, compile CLHEP libraries with optimization and
debugging symbols, run the test suite and finally install the CLHEP binaries and
headers under the chosen install prefix.
Additional CMake Options
------------------------
The following arguments may be passed to CMake at the configuration stage either
via the command line or the `cmake-gui` and `ccmake` interfaces.
- `-DCMAKE_INSTALL_PREFIX=/install/path`
- Change prefix under which to install CLHEP
- Defaults to `/usr/local` on UNIX platforms
- `-DCLHEP_BUILD_CXXSTD=-std=c++NM`
- Compile CLHEP against C++ Standard `NM`
- Defaults to `11`
- `NM` can be chosen from `11`, `1y` or `14`.
- `-DLIB_SUFFIX=<S>`
- installs the libraries in a `lib<S>` subdirectory of the
install prefix
- `-DCLHEP_BUILD_DOCS=ON`
- Build and install CLHEP documentation
- Requires [Doxygen](http://www.doxygen.org) and a LaTeX compiler
The compiler discovered and used by CMake to build CLHEP may be
selected either by setting the `CC` and `CXX` shell/environment variables
to point to the required compilers, or by the CMake variables
`CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER`. Note that you *should not*
change the discovered compiler after initial configuration. If you
require concurrent builds against different compilers, use separate
build directories for each compiler.
Building CLHEP from Git
-----------------------
To work with the head:
```
$ git clone http://git.cern.ch/pub/CLHEP
```
To work with a tag:
```
$ git clone http://git.cern.ch/pub/CLHEP
... Use "git tag" to see the available tags.
$ git co <tag>
```
Now continue with the build instructions as if you unpacked a source code tarball.
Building Projects using CLHEP
=============================
About Linking
-------------
CLHEP builds libraries for each package in addition to a single CLHEP library.
This alllows you to link with only the necessary parts of CLHEP.
We provide a set of <package>-config scripts which give the list of
libraries to link, in the correct order.
The script can be embedded in a makefile.
```
clhep-config --libs - link list of ALL CLHEP libraries
<package>-config --libs - link list of ONLY those libraries
needed to use <package>
```
Using CMake
-----------
If your project uses CMake as its buildtool, CLHEP installs a CMake
"Package Config" file that can be used by CMake's `find_package` command.
When found, this file will set up CMake imported targets for the CLHEP
libraries which may then be linked to. For example, to create an
executable that uses CLHEP headers and libraries, your CMake script
would do
```cmake
...
find_package(CLHEP REQUIRED)
add_executable(MyProgram MyProgram.cc)
target_link_libraries(MyProgram CLHEP::CLHEP)
```
Here `CLHEP::CLHEP` is the imported target for the full CLHEP shared library.
CMake will handle setting up header and library paths for you. The static
variant of the library may also be linked using the `CLHEP::CLHEPS` imported
target:
```cmake
...
find_package(CLHEP REQUIRED)
add_executable(MyProgram MyProgram.cc)
target_link_libraries(MyProgram CLHEP::CLHEPS)
```
Imported targets also exist for the CLHEP component libraries:
```cmake
...
target_link_libraries(MyProgram CLHEP::Vector CLHEP::Random)
```
You only need to list the components you need as CMake will resolve and
ensure linking on any additional components required by those you have selected.
Static variants, e.g. `CLHEP::VectorS`, also exist for the components.
If you installed CLHEP to a non-standard prefix, you may need to
add this location to the `CMAKE_PREFIX_PATH` in order for CMake to locate CLHEP.
This may be done either by passing `CMAKE_PREFIX_PATH` with the location as a
command line argument to `cmake` or by setting `CMAKE_PREFIX_PATH` in the
environment (as a PATH style variable).
Using `pkg-config`
------------------
If your project uses `pkg-config` to locate build dependencies, CLHEP installs
`.pc` files for both the full and component CLHEP libraries. The standard
`pkg-config` commands may be used to discover required compiler and liker
flags, for example
```
$ pkg-config --cflags --libs clhep
```
or for component libraries
```
$ pkg-config --cflags --libs clhep-vector clhep-random
```
If you installed CLHEP to a non-standard location, you may need to add the
directory holding the `.pc` files (`<CMAKE_INSTALL_PREFIX>/lib<LIB_SUFFIX>/pkgconfig`)
to the `PKG_CONFIG_PATH` environment variable.
#-------------------------------------------------------------
You MUST use cmake and nmake to build on a Windows machine.
Work in a DOS window.
You may also have success using the cmake and VC gui interfaces.
#-------------------------------------------------------------
# setup the compiler
#-------------------------------------------------------------
call "C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat"
#-------------------------------------------------------------
# building CLHEP
#-------------------------------------------------------------
Work from a separate build directory.
cmake -DCMAKE_INSTALL_PREFIX=C:\....
-G "NMake Makefiles"
-DCMAKE_BUILD_TYPE=RelWithDebInfo
C:\full\path\to\CLHEP
nmake
nmake test
nmake install
#-------------------------------------------------------------
# trouble reports
#-------------------------------------------------------------
Please report problems using the bug-tracker of the savannah portal at:
http://savannah.cern.ch/projects/clhep
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment