Modern, header-only C++17 wrapper for siderust — a high-precision astronomical computation library written in Rust.
siderust-cpp provides idiomatic C++ types (RAII, exceptions, value semantics) on top of the C FFI layer generated by siderust-ffi and tempoch-ffi.
| Module | What you get |
|---|---|
Time (time.hpp) |
UTC, CivilTime, TT-default JulianDate / MJD / Period, plus explicit Time<scale::S> and TimeContext |
Coordinates (coordinates.hpp) |
Modular typed API (coordinates/{geodetic,spherical,cartesian,types}.hpp) plus selective alias headers under coordinates/types/{spherical,cartesian}/... |
Frames & Centers (frames.hpp, centers.hpp) |
Compile-time frame/center tags and transform capability traits |
Orbits (orbit.hpp) |
KeplerianOrbit, MeanMotionOrbit, ConicOrbit, PreparedOrbit, plus compatibility alias Orbit |
Bodies (bodies.hpp) |
Star (RAII, catalog + custom), Planet (8 planets), ProperMotion, planet orbit data |
Observatories (observatories.hpp) |
Named sites: Roque de los Muchachos, Paranal, Mauna Kea, La Silla |
Altitude (altitude.hpp) |
Sun / Moon / Star / ICRS altitude: instant, above/below threshold, crossings, culminations |
Azimuth (azimuth.hpp) |
Sun / Moon / Star / ICRS azimuth: instant, crossings, extrema, range windows |
Targets (trackable.hpp, target.hpp, body_target.hpp, star_target.hpp) |
Polymorphic tracking with Trackable, Target, BodyTarget, and StarTarget |
Lunar Phase (lunar_phase.hpp) |
Phase geometry/labels, principal phase events, illumination window search |
Ephemeris (ephemeris.hpp) |
VSOP87 Sun/Earth positions, ELP2000 Moon position |
#include <siderust/siderust.hpp>
#include <iostream>
int main() {
using namespace siderust;
auto obs = ROQUE_DE_LOS_MUCHACHOS;
auto mjd = MJD::from_utc({2026, 7, 15, 22, 0, 0});
Period win(mjd, mjd + qtty::Day(1.0));
std::cout << "Epoch: " << mjd << '\n';
std::cout << "Sun alt: " << sun::altitude_at(obs, mjd).to<qtty::Degree>() << '\n';
std::cout << "Sun az: " << sun::azimuth_at(obs, mjd) << '\n';
Target fixed(279.23473, 38.78369);
std::cout << "Target alt: " << fixed.altitude_at(obs, mjd).to<qtty::Degree>() << '\n';
auto nights = sun::below_threshold(obs, win, qtty::Degree(-18.0));
std::cout << "Astronomical-night periods in next 24h: " << nights.size() << "\n";
}Coordinate types, Geodetic, and qtty quantities support operator<< with
frame/center context and unit labels, for example:
auto jd = siderust::JulianDate::J2000();
auto mars = siderust::ephemeris::mars_heliocentric(jd);
auto mars_eq = mars.transform<siderust::centers::Geocentric,
siderust::frames::EquatorialMeanJ2000>(jd);
std::cout << jd << '\n'; // e.g. TT JD 2451545 d
std::cout << mars << '\n'; // Heliocentric EclipticMeanJ2000 (x=... au, ...)
std::cout << mars_eq.to_spherical() << '\n'; // Geocentric EquatorialMeanJ2000 (ra=... deg, ...)JulianDate / MJD print as TT JD … / TT MJD … via tempoch-cpp. Use
std::cout in examples and tests rather than manual .value() formatting unless
you need a raw scalar for computation.
# Clone with submodules
git clone --recurse-submodules <url>
cd siderust-cpp
# Build
mkdir build && cd build
cmake ..
cmake --build .
# Run example
./14_nutation_models_example
./15_orbit_models_example
# Run tests
ctest --output-on-failurePackages for Debian/Ubuntu (.deb) and RHEL/Fedora/openSUSE (.rpm) can be
built with CMake + CPack.
# Debian/Ubuntu
sudo apt-get install cmake ninja-build rpm
# RHEL/Fedora
sudo dnf install cmake ninja-build dpkggit clone --recurse-submodules <url>
cd siderust-cpp
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DSIDERUST_BUILD_DOCS=OFF
cmake --build build --parallel
# Install headers + cmake config to a staging prefix
cmake --install build --prefix build/staging
# Copy shared libraries into the staging tree
mkdir -p build/staging/lib
cp siderust/target/release/libsiderust_ffi.so \
tempoch-cpp/tempoch/tempoch-ffi/target/release/libtempoch_ffi.so \
tempoch-cpp/qtty-cpp/qtty/target/release/libqtty_ffi.so \
build/staging/lib/
# Generate .deb and .rpm in build/packages/
cd build
cpack --config CPackConfig.cmake -G "DEB;RPM" -B packages
ls packages/# Debian/Ubuntu
sudo dpkg -i packages/siderust-cpp-*.deb
# RHEL/Fedora/openSUSE
sudo rpm -i packages/siderust-cpp-*.rpmAfter installation, headers land in /usr/local/include/siderust/ and the
shared libraries in /usr/local/lib/. CMake consumers can then use:
find_package(siderust_cpp REQUIRED)
target_link_libraries(your_target PRIVATE siderust::siderust_cpp)A reference external-consumer fixture lives under
tests/installed-consumer/ and is exercised by
the ci-installed-consumer.yml workflow on every push.
siderust-cpp is header-only, but every binary must load three Rust FFI shared
libraries at runtime: libsiderust_ffi, libtempoch_ffi, and libqtty_ffi.
| Install layout | Linux / macOS | Windows (MSVC) |
|---|---|---|
System packages (.deb / .rpm into /usr or /usr/local) |
The dynamic linker finds libraries in standard lib/ paths after ldconfig or equivalent. No extra environment variables are usually required. |
Install siderust_ffi.dll, tempoch_ffi.dll, and qtty_ffi.dll under bin/ (or ensure that directory is on PATH). Link via the .dll.lib import libraries in lib/. |
Custom CMake prefix (cmake --install … --prefix /opt/foo) |
Either add /opt/foo/lib to LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS), or link your executable with an RPATH/@rpath that points at $ORIGIN/../lib relative to your binary. The installed-consumer CI smoke test uses the latter when built with CMAKE_PREFIX_PATH set to the staged prefix. |
Add the install bin/ directory to PATH, or copy the three DLLs next to your executable. find_package(siderust_cpp) sets IMPORTED_LOCATION (DLL) and IMPORTED_IMPLIB (.dll.lib) on siderust::siderust_ffi. |
In-tree build (add_subdirectory / local build/) |
CMake sets BUILD_RPATH on examples and tests to the Cargo target/release directories under the submodules. |
Same as custom prefix: DLLs live next to import libraries under each crate’s target/release/. |
find_package(siderust_cpp) defines imported targets siderust::siderust_cpp and
siderust::siderust_ffi so that linking resolves symbols; loading still
requires the platform loader to locate the .so/.dylib/.dll files using the
rules above.
Note: Pre-built
.deband.rpmpackages are automatically built by CI and attached to every GitHub Release.
The repository includes a root Dockerfile that installs all build dependencies
(CMake, Rust, Doxygen), then runs configure/build/tests/docs during image build.
# Clone with submodules
git clone --recurse-submodules <url>
cd siderust-cpp
# Build image (validates build + tests + docs)
docker build -t siderust-cpp:dev .
# Open an interactive shell in the container
docker run --rm -it -v "$PWD":/workspace -w /workspace siderust-cpp:devNote: docker build writes generated docs inside the image layer, not your host
filesystem.
To generate docs on the host, run the docs target in a bind-mounted container:
docker run --rm \
-u "$(id -u):$(id -g)" \
-v "$PWD":/workspace \
-w /workspace \
siderust-cpp:dev \
bash -lc 'cmake -S . -B build -G Ninja && cmake --build build --target docs'Generated HTML entry point on host:
build/docs/doxygen/html/index.html
Generated HTML entry point inside container:
/workspace/build/docs/doxygen/html/index.html
If Doxygen is installed, CMake exposes a docs target:
cmake -S . -B build
cmake --build build --target docsGenerated HTML entry point:
build/docs/doxygen/html/index.html
- C++17 compiler (GCC 8+, Clang 7+, MSVC 2019+)
- CMake 3.21+
- Rust toolchain (cargo) — Rust FFI libraries are built automatically
- Internet connection for Google Test (fetched automatically)
siderust-cpp/
├── CMakeLists.txt
├── docs/
│ ├── Doxyfile.in
│ └── mainpage.md
├── cmake/
│ └── siderust_cppConfig.cmake.in
├── include/siderust/
│ ├── siderust.hpp ← umbrella header
│ ├── ffi_core.hpp ← error handling, enums
│ ├── time.hpp ← UTC, CivilTime, TT-default encoded dates, explicit `Time<scale::S>`
│ ├── coordinates.hpp ← coordinate umbrella header
│ ├── coordinates/
│ │ ├── geodetic.hpp
│ │ ├── spherical.hpp
│ │ ├── cartesian.hpp
│ │ ├── types.hpp
│ │ └── conversions.hpp
│ ├── bodies.hpp ← Star, Planet, ProperMotion
│ ├── observatories.hpp ← named observatory locations
│ ├── altitude.hpp ← sun/moon/star altitude API
│ ├── azimuth.hpp ← azimuth queries and events
│ ├── lunar_phase.hpp ← moon phase geometry and events
│ ├── trackable.hpp ← polymorphic trackable interface
│ ├── target.hpp ← fixed ICRS target (RAII)
│ ├── body_target.hpp ← body enum trackable adapter
│ ├── star_target.hpp ← star trackable adapter
│ └── ephemeris.hpp ← VSOP87/ELP2000 positions
├── examples/demo.cpp
├── tests/
│ ├── main.cpp
│ ├── test_time.cpp
│ ├── test_observatories.cpp
│ ├── test_coordinates.cpp
│ ├── test_bodies.cpp
│ ├── test_altitude.cpp
│ └── test_ephemeris.cpp
├── siderust-ffi/ ← git submodule (contains `siderust` as nested submodule)
└── tempoch-cpp/qtty-cpp/ ← nested git submodule
- Default astronomy-facing code should use
JulianDate,MJD, andPeriod, all pinned to TT. - Civil construction is available directly through
JulianDate::from_utc(...)andMJD::from_utc(...). - Advanced mixed-scale work stays explicit with
Time<scale::S>and named aliases such asUT1JulianDate.
┌──────────────┐
│ C++ user │ #include <siderust/siderust.hpp>
│ code │
└──────┬───────┘
│ header-only (inline)
┌──────▼───────┐
│ siderust-cpp │ C++17 types, RAII, exceptions
│ (headers) │
└──────┬───────┘
│ extern "C" calls
┌──────▼───────┐ ┌──────────────┐
│ siderust-ffi │──│ tempoch-ffi │ C ABI (cbindgen-generated)
│ (.so/.dylib) │ │ (.so/.dylib) │
└──────┬───────┘ └──────┬───────┘
│ │
┌──────▼─────────────────▼──┐
│ siderust (Rust) │
│ coordinates · altitude │
│ bodies · ephemeris │
│ tempoch · affn · qtty │
└───────────────────────────┘
Same license as siderust. See LICENSE.