Build and Install

To build libosdp you need a C compiler and CMake 3.14 or newer. The build produces a static library (libosdpstatic.a) and a shared library (libosdp.so / .dylib / .dll). See examples/ for how to consume them from your application.

This project supports two build systems: CMake (recommended) and a thin Make-based "lean" build for cross-compile-only situations.

Setting Up the Build Environment ​

At a minimum you need a C compiler, CMake 3.14 or newer, and Git (to clone the repository with its submodules). The optional packages below unlock extra features: OpenSSL or MbedTLS for a hardened Secure Channel backend, Python 3 for the bindings and test suite, and Doxygen for the API documentation.

Linux (Debian / Ubuntu) ​

sudo apt install build-essential cmake git
# optional:
sudo apt install libssl-dev libmbedtls-dev python3 python3-pip doxygen

Linux (Fedora / RHEL) ​

sudo dnf install gcc gcc-c++ cmake git
# optional:
sudo dnf install openssl-devel mbedtls-devel python3 python3-pip doxygen

macOS ​

Install the Command Line Tools (which provide Clang) and CMake:

xcode-select --install
brew install cmake
# optional:
brew install openssl@3 mbedtls doxygen python

Windows ​

Install Visual Studio Build Tools (the "Desktop development with C++" workload provides MSVC), plus CMake and Git for Windows. For the optional OpenSSL / MbedTLS dependencies, the simplest path is vcpkg — see Using vcpkg below, which is also the recommended way to consume LibOSDP on Windows.

git clone https://github.com/osdp-dev/libosdp --recurse-submodules
cd libosdp

CMake Build ​

cmake -B build
cmake --build build --parallel

To install to a prefix:

cmake --build build --target install
# or:
cmake --install build --prefix /usr/local

The install lays down:

${prefix}/lib(64)/libosdp.so*           # shared library + soname symlinks
${prefix}/lib(64)/libosdpstatic.a       # static library
${prefix}/include/libosdp/osdp.h        # C API
${prefix}/include/libosdp/osdp.hpp      # C++ wrapper
${prefix}/include/libosdp/osdp_export.h # visibility macros
${prefix}/lib(64)/pkgconfig/libosdp.pc  # pkg-config metadata
${prefix}/lib(64)/cmake/libosdp/        # CMake package config (find_package)

To build only one variant, set OPT_BUILD_SHARED=OFF or OPT_BUILD_STATIC=OFF. At least one must remain enabled.

cmake -B build -DOPT_BUILD_SHARED=OFF   # static-only
cmake -B build -DOPT_BUILD_STATIC=OFF   # shared-only

Make Build ​

The Make build is a stripped-down alternative for cross-compile or embedded scenarios where pulling in CMake is undesirable. It builds the static library only.

./configure.sh
make
make install        # installs libosdp.a, headers, libosdp.pc
make check          # runs unit tests

See ./configure.sh --help for all flags.

Crypto Backend Selection ​

LibOSDP's Secure Channel needs an AES implementation. Three backends are supported; the default auto mode probes for OpenSSL, then MbedTLS, and falls back to the bundled TinyAES if neither is found (with a warning, since TinyAES is not hardened to the same degree as OpenSSL/MbedTLS).

Running the Test Suite ​

The full release-style test suite (PyTest + unit tests for both build systems) is wrapped in:

./scripts/run_tests.sh

For just the C unit tests under CMake:

cmake --build build --target check  # convenience wrapper
ctest --test-dir build               # native CTest entry point (also works in IDEs)

For the lean Make build:

make check

Compile-time Configuration Options ​

LibOSDP can be configured by passing -DOPT_XXX=ON/OFF flags to CMake. The same options are exposed by configure.sh flags for the lean build.

Tip: The --packet-trace and --data-trace options are explained in the debugging guide, including how to inspect the captured .pcap files.

Add LibOSDP to Your CMake Project ​

find_package (recommended) ​

Build and install LibOSDP, then in your project's CMakeLists.txt:

find_package(libosdp CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE libosdp::libosdp)

libosdp::libosdp is an alias that resolves to the shared library when both variants were installed, falling back to the static library when only static was built. If you specifically want one or the other, use libosdp::osdp (shared) or libosdp::osdpstatic (static) directly.

The package config carries the crypto backend dependency through find_dependency(), so a static-link consumer of an OpenSSL-built LibOSDP automatically picks up OpenSSL::Crypto without further setup.

add_subdirectory ​

You can also embed LibOSDP directly in your build:

add_subdirectory(third_party/libosdp)
target_link_libraries(my_app PRIVATE libosdp::libosdp)

The same libosdp::libosdp / libosdp::osdp / libosdp::osdpstatic aliases are defined in the build tree, so consumer code is identical whether LibOSDP is installed or vendored.

FetchContent ​

include(FetchContent)
FetchContent_Declare(libosdp
    GIT_REPOSITORY https://github.com/osdp-dev/libosdp.git
    GIT_TAG        v3.2.0  # update to latest release
)
FetchContent_MakeAvailable(libosdp)
target_link_libraries(my_app PRIVATE libosdp::libosdp)

Using pkg-config ​

LibOSDP installs a libosdp.pc file alongside the library. With pkg-config on your PKG_CONFIG_PATH:

gcc my_app.c $(pkg-config --cflags --libs libosdp) -o my_app

The Cflags adds -I${includedir}/libosdp, so #include <osdp.h> works as written. For static linking, pkg-config --static adds the crypto backend (-lcrypto or -lmbedcrypto) declared via Requires.private.

Using vcpkg ​

A port for LibOSDP is available in vcpkg upstream. Follow the getting started guide to set up vcpkg, then:

mkdir osdp_app && cd osdp_app
vcpkg new --application
vcpkg add port libosdp

Build with the vcpkg toolchain file:

cmake -DCMAKE_TOOLCHAIN_FILE="%VCPKG_ROOT%\scripts\buildsystems\vcpkg.cmake" -B build .
cmake --build build

Note: vcpkg is the recommended method to consume LibOSDP on Windows.