diff --git a/README.md b/README.md index ebd84e4d0..1ed43c4f3 100755 --- a/README.md +++ b/README.md @@ -1,24 +1,33 @@ ## Dependencies -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. +Before building from source make sure that you have the [dependencies](https://slsdetectorgroup.github.io/devdoc/dependencies.html) installed. If installing using conda, conda will manage the dependencies. Avoid also installing dependency packages with pip. ## Documentaion Detailed documentation including installation can be found in the [software wiki](https://slsdetectorgroup.github.io/devdoc/index.html). -Different releases can be found on the [official site](https://www.psi.ch/en/lxn/software-releases). +List of releases can be found on the [official site](https://www.psi.ch/en/lxn/software-releases). Firmware compatiblity can be found in [firmware page](https://github.com/slsdetectorgroup/slsDetectorFirmware) ## Installation -### 1. Install binaries using conda +The slsDetectorPackage provides core detector software implemented in C++, along with Python bindings packaged as the slsdet Python extension module. Choose the option that best fits your environment and use case. + +1. **Install pre-built binaries using conda (Recommended)**: Install pre-built binaries for the C++ client, receiver, GUI and the Python API (`slsdet`), simplifying setup across platforms. + +2. **Pip**: Install only the Python extension module, either by downloading the pre-built library from PyPI or by building the extension locally from source. Available only from v9.2.0 onwards. + +3. **Build from source**: Compile the entire package yourself, including both the C++ core and the Python bindings, for maximum control and customization. However, make sure that you have the dependencies installed. If installing using conda, conda will manage the dependencies. Avoid installing packages with pip and conda simultaneously. + +### 1. Install pre-built binaries using conda (Recommended) 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 +* **slsdetlib** Shared libraries and command line utilities * **slsdetgui** GUI * **slsdet** Python bindings +* **moenchzmq** Moench ``` #Add channels for dependencies and our library @@ -44,11 +53,26 @@ conda search slsdetlib conda search slsdet # gui conda search slsdetgui +# moench +conda search moenchzmq ``` -## 2. Build from source +## 2. Pip +The Python extension module `slsdet` can be installed using pip. This is available from v9.2.0 onwards. -### 2.1 Download Source Code from github +``` +#Install the Python extension module from PyPI +pip install slsdet + +# or install the python extension locally from source +git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git --branch 9.2.0 +cd slsDetectorPackage +pip install . +``` + +## 3. Build from source + +### 3.1. Download Source Code from github ``` git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git --branch 7.0.0 ``` @@ -56,10 +80,11 @@ git clone https://github.com/slsdetectorgroup/slsDetectorPackage.git --branch 7. > **Note:** For v6.x.x of slsDetectorPackage and older, refer [pybind11 notes on cloning](#Pybind-and-Zeromq). -### 2.2 Build from source +### 3.2. Build from source +One can either build using cmake or use the in-built cmk.sh script. -### Build using CMake +### 3.2.1. Build using CMake ``` # outside slsDetecorPackage folder @@ -99,7 +124,7 @@ ccmake .. > **Note:** For v7.x.x of slsDetectorPackage and older, refer [zeromq notes for cmake option to hint library location](#Pybind-and-Zeromq). -### Build using in-built cmk.sh script +### 3.2.2. Build using in-built cmk.sh script ``` The binaries are generated in slsDetectorPackage/build/bin directory. @@ -144,9 +169,9 @@ Usage: $0 [-b] [-c] [-d ] [-e] [-g] [-h] [-i] > **Note:** For v7.x.x of slsDetectorPackage and older, refer [zeromq notes for cmk script option to hint library location](#Pybind-and-Zeromq). -### Build on old distributions +### 3.3. Build on old distributions using conda -If your linux distribution doesn't come with a C++11 compiler (gcc>4.8) then +If your linux distribution doesn't come with a C++17 compiler (gcc>8) then it's possible to install a newer gcc using conda and build the slsDetectorPackage using this compiler @@ -164,7 +189,7 @@ make -j12 > **Note:** For v7.x.x of slsDetectorPackage and older, refer [zeromq notes for dependencies for conda](#Pybind-and-Zeromq). -### Build slsDetectorGui (Qt5) +### 3.4. Build slsDetectorGui (Qt5) 1. Using pre-built binary on conda ``` @@ -215,7 +240,7 @@ cd slsDetectorPackage > **Note:** For v7.x.x of slsDetectorPackage and older, refer [zeromq notes for dependencies for conda](#Pybind-and-Zeromq). -### Build documentation from package +### 3.5. 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 @@ -236,7 +261,7 @@ make rst # rst only, saves time in case the API did not change -## Pybind and Zeromq +## 4. Pybind and Zeromq ### Pybind11 for Python **v8.0.0+**: @@ -278,4 +303,5 @@ zeromq-devel must be installed and one can hint its location using ## Support dhanya.thattil@psi.ch - erik.frojdh@psi.ch \ No newline at end of file + erik.frojdh@psi.ch + alice.mazzoleni@psi.ch \ No newline at end of file diff --git a/docs/src/dataformat.rst b/docs/src/dataformat.rst index 39707a5b9..4d39b0078 100644 --- a/docs/src/dataformat.rst +++ b/docs/src/dataformat.rst @@ -1,3 +1,5 @@ +.. _data format: + Data Format ================================ diff --git a/docs/src/dependencies.rst b/docs/src/dependencies.rst index 344c41b24..a4b02f98e 100644 --- a/docs/src/dependencies.rst +++ b/docs/src/dependencies.rst @@ -14,7 +14,12 @@ the shared libraries these are needed: * Linux, preferably recent kernel (currently no cross platform support) * CMake >= 3.14 - * C++11 compatible compiler. (We test with gcc and clang) + * C++17 compatible compiler. (We test with gcc and clang) + +.. note :: + + For v9.x.x of slsDetectorPackage and older, C++11 compatible compiler. + ----------------------- Python bindings diff --git a/docs/src/fileformat.rst b/docs/src/fileformat.rst index f35498d0c..707e2f119 100644 --- a/docs/src/fileformat.rst +++ b/docs/src/fileformat.rst @@ -1,3 +1,5 @@ +.. _file format: + File format ================================ diff --git a/docs/src/index.rst b/docs/src/index.rst index 80cdcfee9..c51abdba0 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -33,7 +33,8 @@ Welcome to slsDetectorPackage's documentation! :maxdepth: 2 multidet - + quick_start_guide + .. toctree:: :caption: Python API :maxdepth: 2 @@ -50,7 +51,7 @@ Welcome to slsDetectorPackage's documentation! :maxdepth: 1 commandline - quick_start_guide + .. toctree:: :caption: Developer diff --git a/docs/src/installation.rst b/docs/src/installation.rst index 82128f9e5..1eaf6e5fa 100644 --- a/docs/src/installation.rst +++ b/docs/src/installation.rst @@ -220,7 +220,7 @@ Example cmake options Comment 3.3. Build on old distributions using conda ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If your linux distribution doesn't come with a C++11 compiler (gcc>4.8) then +If your linux distribution doesn't come with a C++17 compiler (gcc>8) then it's possible to install a newer gcc using conda and build the slsDetectorPackage using this compiler diff --git a/docs/src/quick_start_guide.rst b/docs/src/quick_start_guide.rst index 3e4efc943..b7842b8b9 100644 --- a/docs/src/quick_start_guide.rst +++ b/docs/src/quick_start_guide.rst @@ -19,14 +19,14 @@ For a Single Module slsReceiver # custom port 2012 - slsReceiver -t2012 + slsReceiver -p 2012 For Multiple Modules .. code-block:: bash - # slsMultiReceiver [starting port] [number of receivers] [print each frame header for debugging] - slsMultiReceiver 2012 2 0 + # slsMultiReceiver [-p: starting port, -n: number of receivers] + slsMultiReceiver -p 2012 -n 2 Client @@ -131,6 +131,27 @@ For Multiple Modules .. note :: The **hostname** and **detsize** command in a multi module system can affect the row and column values in the udp/zmq header. The modules are stacked row by row until they reach the y-axis limit set by detsize (if specified). Then, stacking continues in the next column and so on. + + + + +Data +----- + +Check out the :ref:`UDP header section` for details on output UDP header data format.` + +Check out the :ref:`Data format section` for details on output data format. + + +Receiver +--------- + +When using `slsReceiver`, `slsMultiReceiver` or `slsFrameSynchronizer`, check out the following sections: + + - :ref:`File format` + - :ref:`slsReceiver header format` + - :ref:`Master file attributes` + Gui ---- diff --git a/docs/src/slsreceiver.rst b/docs/src/slsreceiver.rst index 932c25a05..d0bceff0a 100644 --- a/docs/src/slsreceiver.rst +++ b/docs/src/slsreceiver.rst @@ -38,18 +38,41 @@ There are three main receiver types. How to start them is described :ref:`below< +----------------------+--------------------+-----------------------------------------+--------------------------------+ - - .. _Starting up the Receiver: Starting up the Receiver ------------------------- + +.. code-block:: bash + + Usage: slsReceiver Options: + -v, --version : Version. + -p, --port : TCP port to communicate with client for configuration. Non-zero and 16 bit. + -u, --uid : Set effective user id if receiver started with privileges. + + Usage: slsMultiReceiver Options: + -v, --version : Version. + -n, --num-receivers : Number of receivers. + -p, --port : TCP port to communicate with client for configuration. Non-zero and 16 bit. + -c, --callback : Enable dummy callbacks for debugging. Disabled by default. + -u, --uid : Set effective user id if receiver started with privileges. + + Usage: slsFrameSynchronizer Options: + -v, --version : Version. + -n, --num-receivers : Number of receivers. + -p, --port : TCP port to communicate with client for configuration. Non-zero and 16 bit. + -c, --print-headers : Print callback headers for debugging. Disabled by default. + -u, --uid : Set effective user id if receiver started with privileges. + + + + For a Single Module .. code-block:: bash slsReceiver # default port 1954 - slsReceiver -t2012 # custom port 2012 + slsReceiver -p 2012 # custom port 2012 For Multiple Modules @@ -59,13 +82,13 @@ For Multiple Modules # option 1 (one for each module) slsReceiver - slsReceiver -t1955 + slsReceiver -p 1955 # option 2 - slsMultiReceiver 2012 2 + slsMultiReceiver -p 2012 -n 2 # option 3 - slsFrameSynchronizer 2012 2 + slsFrameSynchronizer -p 2012 -n 2 diff --git a/slsReceiverSoftware/include/sls/Receiver.h b/slsReceiverSoftware/include/sls/Receiver.h index 0a3a83482..a9d9060db 100644 --- a/slsReceiverSoftware/include/sls/Receiver.h +++ b/slsReceiverSoftware/include/sls/Receiver.h @@ -18,7 +18,7 @@ class Receiver : private virtual slsDetectorDefs { * throws an exception in case of failure * @param port TCP/IP port number */ - Receiver(uint16_t port = 1954); + explicit Receiver(uint16_t port = 1954); ~Receiver(); diff --git a/slsReceiverSoftware/src/CommandLineOptions.cpp b/slsReceiverSoftware/src/CommandLineOptions.cpp index b2c67bd58..dbc0c72ae 100644 --- a/slsReceiverSoftware/src/CommandLineOptions.cpp +++ b/slsReceiverSoftware/src/CommandLineOptions.cpp @@ -240,7 +240,7 @@ void CommandLineOptions::handleAppSpecificOption(int opt, const char *optarg, case 't': LOG(sls::logWARNING) << "Deprecated option '-t' and '--rx_tcport'. Use " - "'p' or '--port' instead."; + "'--p' or '--port' instead."; base.port = parsePort(optarg); break; }