Skip to content

Installation

StarDS is a header-only C++ library with optional CLI tools and Python bindings. All of these are built from source with CMake.

Requirements

Component Requirement
C++ compiler C++20 (or newer)
CMake 3.10+ (3.14+ for Python bindings)
Python (bindings) 3.8+
NumPy (bindings) 1.20.0+
SWIG (bindings) 4.0+

Optional native dependencies (enable extra features):

  • zlib — GZIP compression (build flag STARDS_ENABLE_ZLIB)
  • LZ4 — fast compression codec (build flag STARDS_ENABLE_LZ4)
  • libcurl — HTTP remote access (build flag STARDS_ENABLE_CURL)
  • OpenSSL — S3 request signing (build flag STARDS_ENABLE_S3)

Clone the repository

git clone https://code.usgs.gov/astrogeology/stards.git
cd stards
git submodule update --init --recursive

Build the CLI tools

mkdir build && cd build
cmake .. \
  -DSTARDS_BUILD_TOOLS=ON \
  -DSTARDS_ENABLE_ZLIB=ON \
  -DSTARDS_ENABLE_LZ4=ON \
  -DSTARDS_ENABLE_CURL=ON \
  -DSTARDS_ENABLE_S3=ON

make -j$(nproc)

This builds stardsls and stards_translate.

CMake options

All options default to ON, so a plain cmake .. already builds the library, tools, and (where SWIG/Python are available) the bindings with every optional feature enabled. Pass -D<OPTION>=OFF to turn a feature off.

Option Default Effect
STARDS_BUILD_LIB=ON ON Build the header-only library target
STARDS_BUILD_TOOLS=ON ON Build the CLI tools (stardsls, stards_translate)
STARDS_BUILD_TESTS=ON ON Build the unit tests
STARDS_BUILD_PYTHON_BINDINGS=ON ON Build the Python bindings
STARDS_ENABLE_ZLIB=ON ON Enable GZIP compression
STARDS_ENABLE_LZ4=ON ON Enable LZ4 compression
STARDS_ENABLE_CURL=ON ON Enable HTTP remote access
STARDS_ENABLE_S3=ON ON Enable S3 cloud storage (requires CURL)

Build the Python bindings

mkdir build && cd build
cmake .. \
  -DSTARDS_BUILD_PYTHON_BINDINGS=ON \
  -DSTARDS_ENABLE_ZLIB=ON \
  -DSTARDS_ENABLE_LZ4=ON \
  -DSTARDS_ENABLE_CURL=ON \
  -DSTARDS_ENABLE_S3=ON

make -j$(nproc)
sudo make install

The bindings are importable as the pystards package once built and installed.

Use the header in your own C++ project

StarDS is header-only, so you only need the include path plus any optional libraries you want to link. Each optional feature is gated by a compile definition (ENABLE_ZLIB, ENABLE_LZ4, ENABLE_CURL, ENABLE_S3) — these are the -D preprocessor macros the header checks, and are distinct from the STARDS_ENABLE_* CMake build options used when building this repo's own targets:

# CMakeLists.txt
# In-tree checkout: StarDS/include. Installed: the header is at
# $PREFIX/include/stards/stards.h (use $PREFIX/include/stards, or find_package(STARDS)).
include_directories(/path/to/stards/StarDS/include)

find_package(ZLIB)
find_package(CURL)
find_package(OpenSSL)

if(ZLIB_FOUND)
    target_link_libraries(your_target PRIVATE ZLIB::ZLIB)
    target_compile_definitions(your_target PRIVATE ENABLE_ZLIB)
endif()

if(CURL_FOUND)
    target_link_libraries(your_target PRIVATE CURL::libcurl)
    target_compile_definitions(your_target PRIVATE ENABLE_CURL)
endif()

if(OPENSSL_FOUND)
    target_link_libraries(your_target PRIVATE OpenSSL::SSL OpenSSL::Crypto)
    target_compile_definitions(your_target PRIVATE ENABLE_S3)
endif()

Then include the single header:

#include "stards.h"
using namespace star;

int main() {
    auto store = StarDataset::create("data.stards");
    store->put("matrix", NDArray<double>::zeros({100, 100}));
    store->flush();
    return 0;
}

Next steps