Installation

The project does not currently provide pre-built binary releases. Users must build the project from source on their local system. The project is built as a Python package with native applications and extension modules written in C/C++.

The following instructions will help the user build and install the package into their local Python environment as a pip package. The package build system leverages scikit-build and CMake to compile native C/C++ elements and deploy them alongside pure Python modules in the final package.

Prerequisites

  • The project is currently tested for use on Linux x86-64 target systems.

  • See Third-Party Dependencies for a list of third-party libraries that must be installed on the local system in order to build the project. They can be managed using the system package manager (apt on Ubuntu, yum on CentOS, etc.) or with a C/C++ package management framework—the package maintainers at NASA develop and test using vcpkg. If using vcpkg, the dependencies will likely not be in a default system folder and so the following environment variables should be set to point the build system at the CMake toolchain file provided by your vcpkg install:

    #!/bin/bash
export SKBUILD_CONFIGURE_OPTIONS=" -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"

  • Python must be installed on the local system (3.7+), ideally inside a virtual environment.

  • We require pip>=22.3.1. To upgrade, you can run pip install --upgrade pip.

Obtaining source code

You can clone the repository from (TODO), or download the latest source code archive from (TODO).

Build and install

Navigate to the source code folder tree and run

pip install -v .

This will build the upsp package and install it in your Python environment. Several executable entrypoints will be available in your local Python environment bin folder after install.

To check successful install, you can run psp_process -h to display its application usage, and run python -c "import upsp.raycast; import pydoc; print(pydoc.render_doc(upsp.raycast.BVH))" to display the Python API usage statement for one of the upsp C/C++ Python extension modules.

Unit Tests

Unit tests for C/C++ modules are written with Google Test and are built as part of the packaging process.

  • After running pip install, you should have a local folder called _skbuild that caches the results of the build, for example, _skbuild/linux-x86_64-3.9/cmake-build

  • Navigate to cpp/test and then run ../../_skbuild/linux-x86_64-3.9/cmake-build/run_tests (Some unit tests rely on relative paths to test data located in cpp/test).