diff --git a/README.md b/README.md index a646d587a..27dcb2cd4 100755 --- a/README.md +++ b/README.md @@ -1,102 +1,239 @@ -### Note +## Dependencies -Please do not update to any xxxx.xx.xx.dev0 tags. They are not releases, but tags for internal usage. -Use only releases with tags such as x.x.x or x.x.x-rcx. + Before building from source make sure that you have the + [software wiki](https://slsdetectorgroup.github.io/devdoc/dependencies.html) + installed. If installing using conda, conda will manage the dependencies. + Avoid also installing packages with pip. -### Documentation -##### 5.0.0 - Latest Release -Detailed documentation on the latest release can be found in the [software wiki](https://slsdetectorgroup.github.io/devdoc/index.html) and on the [official site](https://www.psi.ch/en/detectors/software). +## Documentaion + Detailed documentation can be found in the + [software wiki](https://slsdetectorgroup.github.io/devdoc/index.html) and on + the [official site](https://www.psi.ch/en/detectors/software). -##### Older Releases -Documentation is found in the package. +## Installation + +### 1. Install binaries using conda +Conda is not only useful to manage python environments but can also +be used as a user space package manager. Dates in the tag (for eg. 2020.07.23.dev0) +are from the developer branch. Please use released tags for stability. + +We have three different packages available: +* **slsdetlib** shared libraries and command line utilities +* **slsdetgui** GUI +* **slsdet** Python bindings -### Binaries -Binaries for the slsDetectorPackage are available through conda. ``` -#Add conda channels +#Add channels for dependencies and our library conda config --add channels conda-forge conda config --add channels slsdetectorgroup conda config --set channel_priority strict -conda install slsdetlib #only shared lib and command line -conda install slsdet #python bindings (includes slsdetlib) -conda install slsdetgui #gui (includes qt4) - -#Install specific version -conda install slsdet=2020.03.02.dev0 #developer version from 3 March 2020 +#create and activate an environment with our library +#replace 6.1.1 with the required tag +conda create -n myenv slsdetlib=6.1.1 +conda activate myenv +#ready to use +sls_detector_get exptime +etc ... ``` -### Source code -One can also obtain the source code from this repository and compile. ``` -git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git +# List available versions +# lib and binaries +conda search slsdetlib +# python +conda search slsdet +# gui +conda search slsdetgui +``` + +### 2. Build from source + +##### 2.1 Download Source Code from github +``` +git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git --branch 7.0.0 +``` + +**Pybind for Python**
+* **v7.0.0+**: +pybind11 packaged into 'libs/pybind'. No longer a submodule. No need for "recursive" or "submodule update". + +* **Older versions**: + pybind11 is a submodule. Must be cloned using "recursive" and updated when switching between versions using the following commands. ``` -#### Dependencies +# clone using recursive to get pybind11 submodule +git clone --recursive https://github.com/slsdetectorgroup/slsDetectorPackage.git -Refer [this page](https://slsdetectorgroup.github.io/devdoc/dependencies.html) for dependencies. - - -#### Compilation - -Compiling can be done in two ways. Either with the convenience script -cmk.sh or directly with cmake for more control. - -**1. Compile using script cmk.sh**
- -These are mainly aimed at those not familiar with using ccmake and cmake. +# update submodule when switching between releases +cd slsDetectorPackage +git submodule update --init ``` - The binaries are generated in slsDetectorPackage/build/bin directory. - Usage: ./cmk.sh [-c] [-b] [-p] [e] [t] [r] [g] [s] [u] [i] [m] [n] [-h] [z] [-d ] [-l Install directory] [-k ] [-j ] - -[no option]: only make - -c: Clean - -b: Builds/Rebuilds CMake files normal mode - -p: Builds/Rebuilds Python API - -h: Builds/Rebuilds Cmake files with HDF5 package - -d: HDF5 Custom Directory - -k: CMake command - -l: Install directory - -t: Build/Rebuilds only text client - -r: Build/Rebuilds only receiver - -g: Build/Rebuilds only gui - -s: Simulator - -u: Chip Test Gui - -j: Number of threads to compile through - -e: Debug mode - -i: Builds tests - -m: Manuals - -n: Manuals without compiling doxygen (only rst) - -z: Moench zmq processor +##### 2.2 Build from source + + +###### Build using CMake + +``` +# outside slsDetecorPackage folder +mkdir build && cd build + +# configure & generate Makefiles using cmake +# by listing all your options (alternately use ccmake described below) +# cmake3 for some systems +cmake ../slsDetectorPackage -DCMAKE_INSTALL_PREFIX=/your/install/path + +# compiled to the build/bin directory +make -j12 #or whatever number of cores you are using to build + +# install headers and libs in /your/install/path directory +make install +``` + +Instead of the cmake command, one can use ccmake to get a list of options to configure and generate Makefiles at ease. + + +``` +# ccmake3 for some systems +ccmake .. + +# choose the options +# first press [c] - configure +# then press [g] - generate +``` + +|Example cmake options|Comment| +|---|---| +| -DSLS_USE_PYTHON=ON | Python | +| -DPython_FIND_VIRTUALENV=ONLY | Python from only the conda environment | +| -DZeroMQ_HINT=/usr/lib64 | Use system zmq instead | +| -DSLS_USE_GUI=ON | GUI | + + +###### Build using in-built cmk.sh script + +``` +The binaries are generated in slsDetectorPackage/build/bin directory. + +Usage: ./cmk.sh [-b] [-c] [-d ] [e] [g] [-h] [i] [-j ] +[-k ] [-l ] [m] [n] [-p] [-q ] +[r] [s] [t] [u] [z] +-[no option]: only make +-b: Builds/Rebuilds CMake files normal mode +-c: Clean +-d: HDF5 Custom Directory +-e: Debug mode +-g: Build/Rebuilds gui +-h: Builds/Rebuilds Cmake files with HDF5 package +-i: Builds tests +-j: Number of threads to compile through +-k: CMake command +-l: Install directory +-m: Manuals +-n: Manuals without compiling doxygen (only rst) +-p: Builds/Rebuilds Python API +-q: Zmq hint directory +-r: Build/Rebuilds only receiver +-s: Simulator +-t: Build/Rebuilds only text client +-u: Chip Test Gui +-z: Moench zmq processor - # get all options - ./cmk.sh -? +# display all options +./cmk.sh -? - # new build and compile in parallel: - ./cmk.sh -bj5 -``` - -**2. Compile without script**
-Use cmake to create out-of-source builds, by creating a build folder parallel to source directory. This would create a debug build with address sanitizers. -``` - $ mkdir build - $ cd build - $ cmake ../slsDetectorPackage -DCMAKE_BUILD_TYPE=Debug -DSLS_USE_SANITIZER=ON - $ make -j12 #or whatever number of threads wanted +# new build and compile in parallel (recommended basic option): +./cmk.sh -cbj5 + +# new build, python and compile in parallel: +./cmk.sh -cbpj5 + +#To use the system zmq (/usr/lib64) instead +./cmk.sh -cbj5 -q /usr/lib64 ``` -To install binaries using CMake +###### Build on old distributions + +If your linux distribution doesn't come with a C++11 compiler (gcc>4.8) then +it's possible to install a newer gcc using conda and build the slsDetectorPackage +using this compiler + ``` - git clone --recursive https://github.com/slsdetectorgroup/slsDetectorPackage.git - mkdir build && cd build - cmake ../slsDetectorPackage -DCMAKE_INSTALL_PREFIX=/your/install/path - make -j12 #or whatever number of cores you are using to build - make install +#Create an environment with the dependencies +conda create -n myenv gxx_linux-64 cmake zmq +conda activate myenv + +# outside slsDetecorPackage folder +mkdir build && cd build +cmake ../slsDetectorPackage -DCMAKE_PREFIX_PATH=$CONDA_PREFIX +make -j12 +``` + +###### Build slsDetectorGui (Qt5) + +1. Using pre-built binary on conda +``` +conda create -n myenv slsdetgui=7.0.0 +conda activate myenv +``` + +2. Using system installation on RHEL7 +``` +yum install qt5-qtbase-devel.x86_64 +yum install qt5-qtsvg-devel.x86_64 +``` + +3. Using conda +``` +#Add channels for dependencies and our library +conda config --add channels conda-forge +conda config --add channels slsdetectorgroup +conda config --set channel_priority strict + +# create environment to compile +# on rhel7 +conda create -n slsgui zeromq gxx_linux-64 gxx_linux-64 mesa-libgl-devel-cos6-x86_64 qt +# on fedora or newer systems +conda create -n slsgui zeromq qt + +# when using conda compilers, would also need libgl, but no need for it on fedora unless maybe using it with ROOT + +# activate environment +conda activate slsgui + +# compile with cmake outside slsDetecorPackage folder +mkdir build && cd build +cmake ../slsDetectorPackage -DSLS_USE_GUI=ON +make -j12 + +# or compile with cmk.sh +cd slsDetectorPackage +./cmk.sh -cbgj9 +``` + +###### Build documentation from package +The documentation for the slsDetectorPackage is build using a combination +of Doxygen, Sphinx and Breathe. The easiest way to install the dependencies +is to use conda + +``` +conda create -n myenv python sphinx_rtd_theme breathe +``` + +``` +# using cmake or ccmake to enable DSLS_BUILD_DOCS +# outside slsDetecorPackage folder +mkdir build && cd build +cmake ../slsDetectorPackage -DSLS_BUILD_DOCS=ON + +make docs # generate API docs and build Sphinx RST +make rst # rst only, saves time in case the API did not change ``` -### Support +## Support dhanya.thattil@psi.ch erik.frojdh@psi.ch \ No newline at end of file