Installation

Use this chapter to get the SDK onto the machine, confirm headers and libraries are discoverable, and prove that a tiny program can link against the installed package.

The SDK provides libraries (Runtime, Builder, Adapter) that you link into your application, plus a command-line tool (tdse) for benchmarking and profiling.

Once the verification step succeeds, continue directly to Hands-On Tutorial. That chapter is the shortest trustworthy first run.

For a first customer-style evaluation, keep the goal narrow:

1. prove the shipped package is intact
2. prove headers and libraries are discoverable from a downstream consumer
3. prove one tiny program links and runs before you move on to Builder or host integration

When this chapter is complete, you should be ready to start the hands-on tutorial without changing tools, package paths, or library names.

System Requirements

Every SDK user needs a compiler and CMake to build against the SDK libraries.

• Windows: Windows 10 or later, 64-bit. MSVC 2019 or later.
• Linux: x86_64 GNU/Linux, glibc-based (tested on Ubuntu 24.04). GCC 10+ or Clang 14+.
• CMake: 3.21 or later. On Linux, pkg-config is also supported.
• Disk space: ~200 MB.

Prebuilt SDK packages include all third-party dependencies. You do not need to install SuiteSparse, OpenBLAS, LAPACK, or CUDA runtime libraries separately through your system package manager.

This chapter assumes a shipped closed-source RC evaluation package rather than source access to TDSE itself.

Package Contents

Linux

tdse-sdk/
├── bin/
│   ├── tdse                         (benchmark and profiling CLI)
│   └── tdse_plugin_doctor          (plugin diagnostics)
├── include/
│   ├── tdse/
│   │   ├── tdse.h                   (Runtime C API)
│   │   ├── tdse.hpp                 (Runtime C++ wrapper)
│   │   └── ...
│   ├── tdse_builder.h               (Builder C API)
│   ├── tdse_builder.hpp
│   ├── tdse_perf.h                  (backend selection)
│   ├── tdse_adapter_circuit.h
│   └── tdse_adapter_circuit/
│       ├── common.h
│       ├── compile.h
│       ├── compute.h
│       └── ...
├── lib/
│   ├── libtdse.so                   (Runtime, always shared)
│   ├── libtdse_builder.so           (Builder, .a for static builds)
│   ├── libtdse_adapter_circuit.so   (Adapter Circuit, .a for static builds)
│   ├── plugins/
│   │   └── sim/
│   │       ├── libtdse_sim_cpu_dense.so
│   │       ├── libtdse_sim_cpu_sparse.so
│   │       ├── libtdse_sim_cuda.so
│   │       └── plugin_manifest.json
│   ├── tdse/third_party/            (bundled: SuiteSparse, OpenBLAS, CUDA runtime)
│   ├── cmake/tdse/                  (CMake package)
│   └── pkgconfig/tdse.pc            (pkg-config)
└── share/tdse/
    ├── profiler/
    ├── third_party_notices/
    ├── tdse_sdk_variant.json
    └── tdse_runtimecore_variant.json

Third-party shared libraries (SuiteSparse, OpenBLAS, CUDA runtime) are bundled under lib/tdse/third_party/ so the SDK is self-contained.

Windows

tdse-sdk/
├── bin/
│   ├── tdse.exe                     (benchmark and profiling CLI)
│   ├── tdse_plugin_doctor.exe       (plugin diagnostics)
│   ├── tdse.dll                     (Runtime)
│   └── *.dll                        (third-party dependencies)
├── include/
│   ├── tdse/
│   │   ├── tdse.h                   (Runtime C API)
│   │   ├── tdse.hpp                 (Runtime C++ wrapper)
│   │   └── ...
│   ├── tdse_builder.h               (Builder C API)
│   ├── tdse_builder.hpp
│   ├── tdse_perf.h                  (backend selection)
│   ├── tdse_adapter_circuit.h
│   └── tdse_adapter_circuit/
│       ├── common.h
│       ├── compile.h
│       ├── compute.h
│       └── ...
├── lib/
│   ├── tdse.lib                     (Runtime import library)
│   ├── tdse_builder.lib             (Builder import library)
│   ├── tdse_adapter_circuit.lib     (Adapter Circuit)
│   ├── plugins/
│   │   └── sim/
│   │       ├── tdse_sim_cpu_dense.dll
│   │       ├── tdse_sim_cpu_sparse.dll
│   │       ├── tdse_sim_cuda.dll
│   │       └── plugin_manifest.json
│   ├── cmake/tdse/                  (CMake package)
│   └── pkgconfig/tdse.pc            (pkg-config)
└── share/tdse/
    ├── profiler/
    ├── third_party_notices/
    ├── tdse_sdk_variant.json
    └── tdse_runtimecore_variant.json

Third-party DLLs are placed in bin/ alongside the CLI executable — adding bin/ to your PATH makes everything discoverable.

Install the SDK

Linux

Extract the tarball and verify the package is intact:

mkdir -p /opt/tdse-sdk
tar -xf tdse-sdk-*-linux-x86_64.tar.gz -C /opt/tdse-sdk --strip-components=1
/opt/tdse-sdk/bin/tdse sdk version --json-out -

Expected output: a JSON line containing "status":"ok". If you see error while loading shared libraries, add the library directory:

export LD_LIBRARY_PATH=/opt/tdse-sdk/lib:$LD_LIBRARY_PATH

For convenience, add the CLI to your PATH:

export PATH="/opt/tdse-sdk/bin:$PATH"

Windows

Extract the zip archive to a directory of your choice, e.g. C:\tdse-sdk, then verify:

C:\tdse-sdk\bin\tdse sdk version --json-out -

For convenience, add bin\ to your PATH via System Properties → Environment Variables.

Set Up Your Project

CMake

Point CMAKE_PREFIX_PATH to the SDK root and link the targets your application needs:

find_package(tdse REQUIRED)
target_link_libraries(my_app PRIVATE tdse::tdse tdse::tdse_builder)

cmake -DCMAKE_PREFIX_PATH=/path/to/tdse-sdk ..

Available targets:

Target	What it provides
tdse::tdse	Runtime (step loop, lifecycle, diagnostics)
tdse::tdse_builder	Builder (pack creation)
tdse::tdse_adapter_circuit	Adapter (circuit domain)

If your application only needs the Runtime, use find_package(tdseRuntimeCore) which exports tdse::tdse alone.

pkg-config (Linux)

export PKG_CONFIG_PATH=/opt/tdse-sdk/lib/pkgconfig:$PKG_CONFIG_PATH
g++ -std=c++20 my_app.cpp $(pkg-config --cflags --libs tdse) -o my_app

Manual Flags

If you are not using CMake or pkg-config:

Linux:

g++ -std=c++20 my_app.cpp \
    -I/opt/tdse-sdk/include \
    -L/opt/tdse-sdk/lib \
    -ltdse_builder -ltdse -lm \
    -Wl,-rpath,/opt/tdse-sdk/lib \
    -o my_app

Windows:

cl my_app.c ^
  /I"C:\tdse-sdk\include" ^
  /link "C:\tdse-sdk\lib\tdse.lib" "C:\tdse-sdk\lib\tdse_builder.lib"

Verify Your Setup

Compile and run a minimal program to confirm your project can find headers and link against both Runtime and Builder.

// test_sdk.cpp
#include <tdse/tdse.h>
#include <tdse_builder.h>
#include <cstdio>

int main() {
    const char* v = tdse_version_string();
    if (!v) return 1;
    std::printf("TDSE %s\n", v);
    std::printf("builder status: %s\n", tdse_builder_status_message(0));
    return v ? 0 : 1;
}

Linux:

g++ -std=c++20 test_sdk.cpp \
    -I/opt/tdse-sdk/include \
    -L/opt/tdse-sdk/lib \
    -ltdse_builder -ltdse -lm \
    -Wl,-rpath,/opt/tdse-sdk/lib \
    -o test_sdk
./test_sdk

Windows:

cl test_sdk.cpp ^
  /I"C:\tdse-sdk\include" ^
  /link "C:\tdse-sdk\lib\tdse.lib" "C:\tdse-sdk\lib\tdse_builder.lib"
test_sdk.exe

Expected output: TDSE 1.0.0-rc1 (or your installed version).

Check Individual Components

Use these commands to confirm specific SDK components are present. They are not required for normal use — they help diagnose setup problems.

Headers:

# Linux
ls /opt/tdse-sdk/include/tdse/tdse.h
ls /opt/tdse-sdk/include/tdse_builder.h

rem Windows
dir "C:\tdse-sdk\include\tdse\tdse.h"
dir "C:\tdse-sdk\include\tdse_builder.h"

Libraries:

# Linux
ls /opt/tdse-sdk/lib/libtdse.so
ls /opt/tdse-sdk/lib/libtdse_builder.so

rem Windows
dir "C:\tdse-sdk\lib\tdse.lib"
dir "C:\tdse-sdk\lib\tdse_builder.lib"

Plugins (required for Adapter Circuit commands):

# Linux
ls /opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cpu_dense.so
ls /opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cpu_sparse.so
ls /opt/tdse-sdk/lib/plugins/sim/plugin_manifest.json
ls /opt/tdse-sdk/bin/tdse_plugin_doctor

rem Windows
dir "C:\tdse-sdk\lib\plugins\sim\tdse_sim_cpu_dense.dll"
dir "C:\tdse-sdk\lib\plugins\sim\plugin_manifest.json"
dir "C:\tdse-sdk\bin\tdse_plugin_doctor.exe"

Inspect Installed Variant

The installed package manifests tell you which public targets and optional features are present. Read these before guessing whether a machine has sparse CPU, CUDA, full SDK headers, or only RuntimeCore.

Linux:

cat /opt/tdse-sdk/share/tdse/tdse_sdk_variant.json
cat /opt/tdse-sdk/share/tdse/tdse_runtimecore_variant.json

Windows:

type C:\tdse-sdk\share\tdse\tdse_sdk_variant.json
type C:\tdse-sdk\share\tdse\tdse_runtimecore_variant.json

Typical tdse_sdk_variant.json fields include:

• build_variant - package flavor such as full-feature
• package_profile - always sdk
• features - optional slices such as sparse_cpu and cuda
• recommended_adapter_targets - the target list used by -DTDSE_ADAPTER_TARGETS=AUTO
• exported_targets - the exact installed CMake targets

Typical tdse_runtimecore_variant.json fields include:

• build_variant - the RuntimeCore bundle flavor for this release
• package_profile - always runtimecore
• config_package - the installed CMake package name, typically tdseRuntimeCore
• exported_targets - the exact installed RuntimeCore CMake targets

Use these manifests when:

• a downstream consumer needs to choose between RuntimeCore and the full SDK
• a build system wants to enable sparse CPU or CUDA only when installed
• you need to confirm that AUTO target selection is doing what you expect

If you consume the SDK through CMake, the package_consumer_targets example described in Examples Guide demonstrates the intended out-of-tree install-tree flow. If you consume the full SDK through pkg-config, the feature slices are exposed through variables such as sparse_libs and cuda_libs.

Acceptance Ladder

Use this ladder when you need more confidence than "the files extracted correctly."

1. Basic link proof Run tdse sdk version --json-out - and compile the tiny program in this chapter. This proves the CLI, headers, and core libraries are discoverable.
2. Installed-package consumer proof Build one of the out-of-tree package-consumer examples against the installed SDK: package_consumer_targets for CMake or package_consumer_pkgconfig for pkg-config.
3. Runtime and plugin proof Run tdse_plugin_doctor against the installed manifest, then complete the Hands-On Tutorial path to prove Builder -> Runtime execution still works on this machine.

For Linux packaging and release-candidate validation, the broader install, package, and clean-host gates are summarized in Platform Notes.

If your next question is "can a downstream build consume this install tree cleanly?", stop here and run one package-consumer example before reading deeper SDK chapters. That is a better first PoC signal than jumping straight into advanced Runtime or Adapter details.

Compatibility Promises

These are the public compatibility rules you can rely on when integrating against the installed SDK:

• Pack format: Runtime accepts supported pack versions and reports incompatibility at create time through normal diagnostics and validation APIs.
• Public structs: most extensible Runtime, Builder, Adapter, and plugin-facing request/config/diagnostic structs use a struct_size field for forward-compatible growth. Intentionally frozen payloads are documented as exceptions.
• Plugin ABI: simulation plugins follow major/minor compatibility. Same major plus same or older minor is accepted by the host.
• Installed-package consumption: the shipped install tree is exercised through CMake/package-export and pkg-config smoke paths, not only through ad hoc same-machine linking.

Troubleshooting

Symptom	Likely cause	Fix
tdse/tdse.h: No such file or directory	Include path not set	Add -I<prefix>/include
libtdse.so: cannot open shared object file	Library path not set (Linux)	export LD_LIBRARY_PATH=<prefix>/lib
LNK1181: cannot open input file 'tdse.lib'	Linker path not set (Windows)	/LIBPATH:<prefix>\lib or use CMake
find_package(tdse) fails	CMake cannot locate the SDK	-DCMAKE_PREFIX_PATH=<prefix>
No simulation engine plugin loaded	Plugin artifact missing or manifest path wrong	Check <prefix>/lib/plugins/sim/ and plugin_manifest.json
tdse: command not found	CLI not on PATH	Add <prefix>/bin to PATH

In production deployments:

• point TDSE_PLUGIN_MANIFEST at <prefix>/lib/plugins/sim/plugin_manifest.json
• enable TDSE_PLUGIN_STRICT_MODE=1
• use tdse_plugin_doctor as the first support or field diagnostic command

Next Step

If the install and verification steps succeeded:

• go to Hands-On Tutorial for the first end-to-end Builder -> Runtime run
• then use Examples Guide to find the closest runnable reference for your real workflow