Prepare Decoding

Tool to compute decoding quantities.

Quickstart

Install the Python module from PyPI

Most functionality is available through a Python module which can be installed with:

pip install asmc-preparedecoding

This Python module is currently available on Linux and macOS. We hope it will be available soon on Windows.

Examples for using the Python module can be found in the following Jupyter notebook:

• creating decoding quantities

Please note that you must install Jupyter in order to view the notebook, and then open it:

pip install jupyter
jupyter-notebook notebooks/CreatingDecodingQuantities.ipynb

Compiling the C++ library and executable

Get the source, together with the vcpkg and pybind11 submodules:

git clone --recurse-submodules https://github.com/PalamaraLab/PrepareDecoding.git
cd PrepareDecoding

The recommended way to install dependencies is via the vcpkg submodule. If you have checked out this submodule, the dependencies will be automatically installed when you run the CMake configuration step (below).

Several additional system dependencies should be obtained from your package manager prior to the CMake configuration step:

• Ubuntu/Debian:

  sudo apt install cmake

• CentOS/Fedora:

  sudo yum install cmake

• macOS:

  brew install libomp pkg-config automake autoconf autoconf-archive libtool cmake

Configuring and compiling the project

This project uses CMake.

Create a build directory:

mkdir build
cd build

Configure, and build the PrepareDecoding library and executable:

cmake ..
cmake --build . --parallel 4 --target prepare_decoding_lib
cmake --build . --parallel 4 --target prepare_decoding_exe

You can optionally build the and run the unit tests:

cmake --build . --parallel 4 --target unit_tests
ctest --output-on-failure

Extra tools for C++ developers

Coverage

Configure with coverage enabled, using g++ or clang++:

cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON
cmake --build . --parallel 2 --target unit_tests
ctest -j2 --output-on-failure
lcov --directory . --capture --output-file coverage.info
lcov --remove coverage.info '/usr/*' '*/vcpkg/*' '*/test/*' --output-file coverage.info
lcov --list coverage.info

Static analysis

This project is configured to work with clang tidy and cppcheck. Enable the relevant option and compile with clang++.

For clang tidy:

cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_CLANG_TIDY=ON
cmake --build . --parallel 2 --target prepare_decoding_lib prepare_decoding_exe

For cppcheck:

cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_CPPCHECK=ON
cmake --build . --parallel 2 --target prepare_decoding_lib prepare_decoding_exe

Sanitisers

This project is configured to work with various LLVM sanitisers. Enable the relevant option, compile with clang++, and run the unit tests.

cmake .. -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITISER_{{{SANITISER}}}=ON
cmake --build . --parallel 2 --target unit_tests
./test/unit_tests

where {{{SANITISER}}} is one of:

• ADDRESS
• LEAK
• UNDEFINED_BEHAVIOUR
• THREAD

For developers: making a release

• Bump the version number in setup.py, CMakeLists.txt, and vcpkg.json
• Update RELEASE_NOTES.md
• Update permalink to the notebook in PyPI_README.md
• Push changes and check that all GitHub workflows pass
• Tag the commit in Git using syntax vX.Y.Z
• Make a release on GitHub, which should trigger a new build that will upload Python wheels to PyPI

License

This project is currently released under the GNU General Public License Version 3.