pylupnt

LuPNT

LuPNT is an open-source C++/Python library for Lunar Positioning, Navigation, and Timing (PNT) Research. This project is a product of the Stanford NAV Lab. If using this project in your own work please cite the following:

@inproceedings{IiyamaCasadesus2023,
  title = {LuPNT: Open-Souce Simulator for Lunar Positioning, Navigation, and Timing},
  author={Iiyama, Keidai and Casadesus Vila, Guillem and Gao, Grace},
  booktitle={Proceedings of the Institute of Navigation Gnss+ conference (ION Gnss+ 2023)},
  institution = {Stanford University},
  year = {2023},
  url = {https://github.com/Stanford-NavLab/LuPNT},
}

Features

• Modern CMake practices
• Clean separation of library and executable code
• Integrated test suite
• Continuous integration via GitHub Actions
• Code coverage via codecov
• Code formatting enforced by clang-format and cmake-format via Format.cmake
• Reproducible dependency management via CPM.cmake
• Installable target with automatic versioning information and header generation via PackageProject.cmake
• Automatic documentation and deployment with Doxygen and GitHub Pages
• Support for sanitizer tools, and more

Usage

To cleanly separate the library and subproject code, the outer CMakeList.txt only defines the library itself while the tests and other subprojects are self-contained in their own directories. During development it is usually convenient to build all subprojects at once.

Dependencies

LuPNT requires OpenMP library for multiprocessing and a data directory. The installation scripts for MacOS, Ubuntu, and Windows can be found under scripts. Note that the data directory can be place anywhere as long as its path is correctly set. Execute the scripts before building the library.

Build and run the examples

Use the following command to build and run the executable target.

cmake -S examples/cpp -B build/examples
cmake --build build/examples -j4
./build_examples/examples/<example-name> --help

Build and run test suite

Use the following commands from the project's root directory to run the test suite.

cmake -S test -B build/test
cmake --build build/test -j4
CTEST_OUTPUT_ON_FAILURE=1 cmake --build build/test --target test

# or simply call the executable:
./build/test/LuPNTTests

To collect code coverage information, run CMake with the -DENABLE_TEST_COVERAGE=1 option.

Run clang-format

Use the following commands from the project's root directory to check and fix C++ and CMake source style. This requires clang-format, cmake-format and pyyaml to be installed on the current system.

cmake -S test -B build/test

# view changes
cmake --build build/test --target format

# apply changes
cmake --build build/test --target fix-format

See Format.cmake for details. These dependencies can be easily installed using pip.

pip install clang-format==14.0.6 cmake_format==0.6.11 pyyaml

Build the documentation

The documentation is automatically built and published whenever a GitHub Release is created. To manually build documentation, call the following command.

cmake -S documentation -B build/doc
cmake --build build/doc --target GenerateDocs
# view the docs
open build/doc/doxygen/html/index.html

To build the documentation locally, you will need Doxygen, jinja2 and Pygments installed on your system.

Build everything at once

The project also includes an all directory that allows building all targets at the same time. This is useful during development, as it exposes all subprojects to your IDE and avoids redundant builds of the library.

cmake -S all -B build
cmake --build build -j4

# run tests
./build/test/LuPNTTests
# format code
cmake --build build --target fix-format
# run standalone
./build/standalone/LuPNT --help
# build docs
cmake --build build --target GenerateDocs

Additional tools

The test and standalone subprojects include the tools.cmake file which is used to import additional tools on-demand through CMake configuration arguments. The following are currently supported.

Sanitizers

Sanitizers can be enabled by configuring CMake with -DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'>.

Static Analyzers

Static Analyzers can be enabled by setting -DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck>, or a combination of those in quotation marks, separated by semicolons. By default, analyzers will automatically find configuration files such as .clang-format. Additional arguments can be passed to the analyzers by setting the CLANG_TIDY_ARGS, IWYU_ARGS or CPPCHECK_ARGS variables.

Ccache

Ccache can be enabled by configuring with -DUSE_CCACHE=<ON | OFF>.