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 asisaacsim-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 insource/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.