Repository structure#

The source tree has two primary entry points: source/libraries for the independently packaged libraries and source/examples for programs that use their public APIs.

source/
|-- libraries/
|   |-- VERSION                    Shared version for every distribution
|   |-- build.sh, build.bat        Library build entry points
|   |-- system_requirements.toml   Required language and tool versions
|   |-- isaacsim/                  Core and domain library distributions
|   |-- isaacsim_usd_schemas/      USD schema distributions
|   |-- isaacsim_deprecated/       Temporary compatibility distribution
|   |-- cmake/                     Shared CMake package infrastructure
|   |-- testing/                   Cross-library test infrastructure
|   `-- tools/                     Version and package maintenance tools
`-- examples/
    |-- examples.py                Example discovery, build, run, and test CLI
    |-- libraries/                 Standalone examples for individual APIs
    `-- series/                    Related workflow and problem-domain examples

Find a library or example#

Use the library inventory to select a distribution. Each distribution page lists its release, dependencies, modules, and available API languages. Use the Example catalog to find a working program by language, API, or topic. Follow Tutorials when you want a guided explanation that connects one or more examples.

You do not need to understand the source layout when you consume packaged artifacts. Use these paths when you build a package locally, contribute to a library, or explore and add examples.

Inside source/libraries#

The repository uses two terms to describe the library layout:

  • A distribution is one independently installable and shippable package. Its CMake group, component, manifest, and native archive names use underscores, such as isaacsim_common; its authored Python project name uses the canonical hyphenated form, such as isaacsim-common. A distribution can provide a Python wheel, native runtime files, a native Software Development Kit (SDK), and documentation. All of these forms use the version in source/libraries/VERSION.

  • A module is one focused C, C++, or Python API owned by a distribution, such as isaacsim.common.logging. A distribution can contain multiple modules, and a module does not have an independent version.

Most distributions live below source/libraries/isaacsim and derive their names from the first two path components. For example, source/libraries/isaacsim/common registers the isaacsim_common CMake group and authors the isaacsim-common Python project. USD schema distributions live below source/libraries/isaacsim_usd_schemas. The compatibility distribution remains in source/libraries/isaacsim_deprecated while APIs migrate to the new architecture.

Every distribution follows this structure:

source/libraries/isaacsim/<distribution>/
|-- CMakeLists.txt             Registers the distribution and its modules
|-- pyproject.toml             Defines Python package metadata
|-- docs/                      Optional distribution-level documentation
`-- <module>/                  One focused public API

The distribution’s CMakeLists.txt lists its modules and registers dependencies on other distributions. Its pyproject.toml declares the Python distribution name, summary, build backend, and any Python package dependencies. Internal library requirements receive the shared version when the wheel metadata is generated, so individual pyproject.toml files do not repeat the version.

Inside a library module#

A module contains only the directories required by its implementation. A module that provides native and Python APIs can use the complete layout below; pure Python, header-only, and USD schema modules use the relevant subset.

<module>/
|-- CMakeLists.txt             Registers sources, APIs, and dependencies
|-- CHANGELOG.md               Records changes to the module's public APIs
|-- include/                   Installed public C and C++ headers
|-- src/                       C and C++ implementation and private headers
|-- bindings/python/           Optional nanobind definitions
|-- python/
|   |-- __init__.py            Public package facade
|   |-- impl/                  Python implementation and public API inventory
|   `-- py.typed               Inline typing marker
|-- tests/
|   |-- c/                     C API tests
|   |-- cpp/                   C++ API tests
|   `-- python/                Python tests
|-- resources/                 Optional registered runtime or test data
|-- abi/                       Optional stable C symbol baseline
`-- docs/                      Optional module overview and API references

The module’s CMakeLists.txt determines which files build and install; the presence of a directory alone has no build meaning. Public native headers stay under include/, implementation details stay under src/, and Python modules expose a typed leaf package from python/. Tests remain beside the module they cover and are separated by implementation language.

Module documentation begins at docs/index.rst. C and C++ references come from public-header comments, and Python references come from public docstrings and generated binding stubs. The standard optional reference pages are api_c.rst, api_cpp.rst, and api_python.rst.

The supported module forms are compiled, header-only, pure Python, compatibility Python, USD schema, and native with Python bindings. See the source/libraries/README.md file in a source checkout for the complete build contract and instructions for adding a module.

Inside source/examples#

Examples below libraries demonstrate one focused public API. Examples below series share a workflow or problem domain. A series can be a sequence with a meaningful execution order or a collection whose members can be used independently. Tutorials provide the explanation and learning order across these examples.

A focused example has the following structure:

source/examples/libraries/<distribution>/<topic>/<example>/<language>/
|-- example.toml              Declares how to discover, build, run, and test it
|-- README.md                 Explains what the example demonstrates
|-- main.py                   Python entry point, when applicable
|-- CMakeLists.txt            Native build definition, when applicable
`-- src/                      Native sources, when applicable

Every example contains an example.toml manifest. It defines the example ID, title, summary, public API identifiers (the manifest’s owners field), topics, build and run adapters, requirements, and optional test cases. A Python-only example normally uses build.adapter = "none" and names its script in run.path. A native example uses the CMake build adapter, declares its targets, and names the executable to run.

The requirements table records the system capabilities and direct Isaac Sim distributions that the example uses. Each distribution entry selects its python or native_sdk installed surface. The manifest does not contain a version because examples and libraries ship together from the value in source/libraries/VERSION.

A related group adds one series manifest above its examples:

source/examples/series/<series>/
|-- series.toml               Defines the kind, members, and levels
|-- README.md                 Introduces the shared workflow or domain
|-- <example-one>/
|   |-- example.toml
|   |-- README.md
|   `-- <entry-point>
`-- <example-two>/
    |-- example.toml
    |-- README.md
    `-- <entry-point>

Each series example remains independently runnable. The series.toml file sets kind = "sequence" or kind = "collection" and assigns each member a beginner, intermediate, or expert level. Only a sequence implies that its listed order is part of the workflow.

Use source/examples/example.sh on Linux or source\examples\example.bat on Windows. These launchers provide runner dependencies, including packaging, through Pixi. The runner discovers manifests, resolves stable IDs, selects the configured library environment, and applies the declared build, run, and test adapters.

Run source/examples/example.sh list from the repository root on Linux, or source\examples\example.bat list on Windows, to see every example and its stable ID.

See source/examples/README.md in a source checkout for the complete example.toml reference and runner commands.