Introducing LuPNT¶

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¶

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>.