diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index d27bcbbbf..a81df2b7f 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -42,6 +42,7 @@ if (DOXYGEN_FOUND AND SPHINX_FOUND) src/result.rst src/type_traits.rst src/ToString.rst + src/examples.rst ) diff --git a/docs/src/consuming.rst b/docs/src/consuming.rst index c3c25f60f..cce1521cb 100644 --- a/docs/src/consuming.rst +++ b/docs/src/consuming.rst @@ -3,16 +3,18 @@ Consuming slsDetectorPackage Depending on how you want to build your integration with slsDetectorPackage there are a few different ways to -consume the package. +consume our package. The recommended way is to use one of the +CMake approaches. -CMake with submodule in your project +CMake: slsDetectorPackage as submodule in your project --------------------------------------- If you are using CMake to build your integration and want to build everything -in one go we support adding slsDetectorPackage as a subfolder in your cmake project. -a minimal example would be. +in one go, we support adding slsDetectorPackage as a subfolder in your cmake project. + +A minimal CMakeLists.txt could look like this: .. code-block:: cmake @@ -27,15 +29,46 @@ a minimal example would be. #Link towards slsDetectorShared target_link_libraries(example slsDetectorShared) -An example that also uses git submodules is available in our github repo +A fully working example can be found at: https://github.com/slsdetectorgroup/cmake-subfolder-example +CMake: find_package(slsDetectorPackage) +------------------------------------------ + +If you have compiled and installed slsDetectorPackage we also support +find_package in CMake. If installed in a system wide location no path +should be needed, otherwise specify cmake prefix path. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.12) + project(myintegration) + + find_package(slsDetectorPackage 5.0 REQUIRED) + add_executable(example main.cpp) + target_link_libraries(example slsDetectorShared) + + +Then assuming the slsDetectorPackage is installed in /path/to/sls/install +you should be able to configure and build your project in this way. + +.. code-block:: bash + + cmake ../path/to/your/source -DCMAKE_PREFIX_PATH=/path/to/sls/install + make + + +A minimal example is available at: https://github.com/slsdetectorgroup/minimal-cmake + No tools minimal approach ----------------------------- -.. code-block:: c++ +While not recommended it is still possible to specify the include and library paths +manually when invoking g++. This can sometimes be handy for a quick try. + +.. code-block:: cpp #include "Detector.h" #include @@ -54,7 +87,8 @@ No tools minimal approach auto mac = det.getSourceUDPMAC()[module]; std::cout << "Mac addr of module "<< module << " is " << mac.str() << '\n'; - }⏎ + } + .. code-block:: bash diff --git a/docs/src/dependencies.rst b/docs/src/dependencies.rst index 2d9b76204..703a30799 100644 --- a/docs/src/dependencies.rst +++ b/docs/src/dependencies.rst @@ -13,7 +13,7 @@ To use the basic building blocks, meaning sls_detector_get/put and the shared libraries these are needed: * Linux, preferably recent kernel (currently no cross platform support) - * CMake > 3.9 + * CMake > 3.12 * C++11 compatible compiler. (We test with gcc and clang) * ZeroMQ version 4 @@ -24,7 +24,7 @@ GUI The GUI is currently using Qt4 but watch out for an upgrade to 5. * Qt 4.8 - * Qwt 6 + * Qwt 6.1 ----------------------- Python bindings diff --git a/docs/src/examples.rst b/docs/src/examples.rst new file mode 100644 index 000000000..eded0122a --- /dev/null +++ b/docs/src/examples.rst @@ -0,0 +1,115 @@ + + + +Examples +=========== + +Setup +------------ + +The examples here assume that you have compiled and installed slsDetectorPackage +to ~/sls/install and that the option for SLS_USE_SIMULATOR was enabled. This also builds +the virtual detector servers that we will be using for testing. + +We also add ~/sls/detector/install/bin to the path for convenience. + +Compile examples +------------------- + +The source code of the examples is available at: +https://github.com/slsdetectorgroup/api-examples + + +.. code-block:: bash + + git clone https://github.com/slsdetectorgroup/api-examples.git + mkdir build && cd build + cmake ../api-examples -DCMAKE_PREFIX_PATH=~/sls/detector/install + make + +Below follows a short description of what is included in the examples. + + +Running a config file [e1] +----------------------------- + + +.. code-block:: cpp + + #include "Detector.h" + ... + sls::Detector det; + det.loadConfig("path/to/config/file.config"); + + + +To configure the connection between PC and detector the easiest +is to run a config file. For this example we first launch a virtual Jungfrau server and +then set up the detector. + +**Launch a virtual detector server** + +.. code-block:: bash + + jungfrauDetectorServer_virtual + +This launches a virtual Jungfrau detector server. As default is uses port 1952 and 1953 +for communication over TCP. Most commands go on 1952 and only stop and status on 1953. + +**Run example to configure** + +.. code-block:: bash + + ./e1-config one_det_no_receiver.config + - 12:01:06.371 INFO: Shared memory deleted /slsDetectorPackage_multi_0_sls_0 + - 12:01:06.371 INFO: Shared memory deleted /slsDetectorPackage_multi_0 + - 12:01:06.372 INFO: Shared memory created /slsDetectorPackage_multi_0 + - 12:01:06.376 INFO: Loading configuration file: one_det_no_receiver.config + - 12:01:06.376 INFO: Adding detector localhost + - 12:01:06.377 INFO: Shared memory created /slsDetectorPackage_multi_0_sls_0 + - 12:01:06.377 INFO: Checking Detector Version Compatibility + - 12:01:06.378 INFO: Detector connecting - updating! + hostname [localhost] + + + Jungfrau detector with 1 modules configured + + +Using the return type sls::Result [e2] +----------------------------------------- + +Since many our detectors have multiple modules we cannot return +a single value when reading from the Detector. Hostname, Ip and also +for example exposure time can differ between modules. + +Therefore we return Result which is a thin wrapper around +std::vector. + +.. code-block:: cpp + + sls::Result res1{1, 1, 1}; + std::cout << "res1: " << res1 << '\n'; + res1.squash(); + res1.squash(-1); + + + +Setting exposure time [e3] +----------------------------------------- + +For setting times, like exposure time, period, delay etc. +we use std::chrono::duration. + +Example 3 shows how to set and read exposure time as well +as converting to floating point. + +.. code-block:: cpp + + #include "Detector.h" + #include + ... + std::chrono::microseconds t0{500}; + det.setExptime(t0); + + + diff --git a/docs/src/index.rst b/docs/src/index.rst index 63a3162ac..0bc7826e8 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -6,6 +6,11 @@ Welcome to slsDetectorPackage's documentation! ============================================== +.. note :: + + This is the documentation for the latest development version of slsDetectorPackage + For documentation on current and previous releases visit the official page: https://www.psi.ch/en/detectors/documentation + .. toctree:: :maxdepth: 1 :caption: Installation: @@ -21,6 +26,7 @@ Welcome to slsDetectorPackage's documentation! detector result receiver + examples .. toctree:: :caption: Python API diff --git a/docs/src/installation.rst b/docs/src/installation.rst index 4a363e182..1c22971ae 100644 --- a/docs/src/installation.rst +++ b/docs/src/installation.rst @@ -2,4 +2,24 @@ Installation ============================================== -get the source etc. \ No newline at end of file +Build from source using CMake +--------------------------------- + +.. note :: + + The default branch of our git repository is developer. It contains the + latest development version. It is expected to compile and work but + features might be added or tweaked. In some cases the API might also change + without being communicated. If absolute stability of the API is needed please + use one of the release versions. + +.. code-block:: bash + + git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git + mkdir build && cd build + cmake ../slsDetectorPackage -DCMAKE_INSTALL_PREFIX=/your/install/path + make -j12 + make install + + + diff --git a/docs/src/pydetector.rst b/docs/src/pydetector.rst index c9cf612e3..e6dba269b 100644 --- a/docs/src/pydetector.rst +++ b/docs/src/pydetector.rst @@ -1,9 +1,9 @@ Detector ===================================================== -.. py:currentmodule:: sls_detector +.. py:currentmodule:: slsdet -.. autoclass:: ExperimentalDetector +.. autoclass:: Detector :members: :undoc-members: :show-inheritance: \ No newline at end of file diff --git a/slsDetectorServers/jungfrauDetectorServer/CMakeLists.txt b/slsDetectorServers/jungfrauDetectorServer/CMakeLists.txt index 9b96b51a0..0215225ee 100644 --- a/slsDetectorServers/jungfrauDetectorServer/CMakeLists.txt +++ b/slsDetectorServers/jungfrauDetectorServer/CMakeLists.txt @@ -14,15 +14,12 @@ add_executable(jungfrauDetectorServer_virtual ../slsDetectorServer/src/communication_funcs_UDP.c ) -include_directories( +target_include_directories(jungfrauDetectorServer_virtual + PRIVATE ${CMAKE_CURRENT_SOURCE_DIR} ../slsDetectorServer/include ../../slsSupportLib/include ) -target_include_directories(jungfrauDetectorServer_virtual - PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} -) - target_compile_definitions(jungfrauDetectorServer_virtual PUBLIC JUNGFRAUD VIRTUAL STOP_SERVER ) @@ -36,5 +33,6 @@ set_target_properties(jungfrauDetectorServer_virtual PROPERTIES ) install(TARGETS jungfrauDetectorServer_virtual - RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} -) + EXPORT "${TARGETS_EXPORT_NAME}" + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} +) \ No newline at end of file