[Workflow] Add isaacsim source install uv workflow

docs/source/setup/installation/include/src_clone_isaaclab.rst

@@ -24,7 +24,7 @@ We provide helper executables at the repository root — ``./isaaclab.sh`` (Linu
 
          ./isaaclab.sh --help
 
-         usage: isaaclab.sh [-h] [-i [INSTALL]] [-f] [-p ...] [-s ...] [-t ...] [-o ...] [-v] [-d] [-n ...] [-c [CONDA]] [-u [UV]]
+         usage: isaaclab.sh [-h] [-i [INSTALL]] [-f] [-p ...] [-s ...] [-t ...] [-o ...] [-v] [-d] [-n ...] [-c [CONDA]] [-u [UV]] [--isaacsim_source PATH]
 
          Isaac Lab CLI
 
@@ -55,6 +55,10 @@ We provide helper executables at the repository root — ``./isaaclab.sh`` (Linu
            -c [CONDA], --conda [CONDA]
                                  Create a new conda environment for Isaac Lab. Default name is 'env_isaaclab'.
            -u [UV], --uv [UV]    Create a new uv environment for Isaac Lab. Default name is 'env_isaaclab'.
+           --isaacsim_source PATH
+                                 Build Isaac Sim from the source checkout at PATH, package it as wheels, and link
+                                 them as '_isaac_sim_wheels' for 'uv run --extra isaacsim-local'.
+                                 Runs the normal incremental build on every invocation.
 
    .. tab-item:: :icon:`fa-brands fa-windows` Windows
       :sync: windows
@@ -63,7 +67,7 @@ We provide helper executables at the repository root — ``./isaaclab.sh`` (Linu
 
          isaaclab.bat --help
 
-         usage: isaaclab.bat [-h] [-i [INSTALL]] [-f] [-p ...] [-s ...] [-t ...] [-o ...] [-v] [-d] [-n ...] [-c [CONDA]] [-u [UV]]
+         usage: isaaclab.bat [-h] [-i [INSTALL]] [-f] [-p ...] [-s ...] [-t ...] [-o ...] [-v] [-d] [-n ...] [-c [CONDA]] [-u [UV]] [--isaacsim_source PATH]
 
          Isaac Lab CLI
 
@@ -94,3 +98,7 @@ We provide helper executables at the repository root — ``./isaaclab.sh`` (Linu
            -c [CONDA], --conda [CONDA]
                                  Create a new conda environment for Isaac Lab. Default name is 'env_isaaclab'.
            -u [UV], --uv [UV]    Create a new uv environment for Isaac Lab. Default name is 'env_isaaclab'.
+           --isaacsim_source PATH
+                                 Build Isaac Sim from the source checkout at PATH, package it as wheels, and link
+                                 them as '_isaac_sim_wheels' for 'uv run --extra isaacsim-local'.
+                                 Runs the normal incremental build on every invocation.

docs/source/setup/installation/index.rst

@@ -768,6 +768,27 @@ requires Ubuntu 22.04 or newer on Linux. For driver requirements, see the `techn
 On Windows, enable `long-path support
 <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later>`__
 before building.
+For the recommended ``uv`` workflow, clone the Isaac Sim source next to an Isaac Lab checkout and
+run the following command from the Isaac Lab root. It triggers an incremental Isaac Sim build, packages the
+build as wheels, and configures ``uv`` to use those wheels:
+
+.. code-block:: bash
+
+   git clone https://github.com/isaac-sim/IsaacSim.git ../IsaacSim
+   uv run isaaclab --isaacsim_source ../IsaacSim
+
+The command records the local wheel directory and exact source-build version in ``pyproject.toml``
+and refreshes ``uv.lock``. Those changes describe your machine; do not commit them. To return to
+published Isaac Sim packages, revert both files before committing. Then run Isaac Lab normally:
+
+.. code-block:: bash
+
+   uv run --extra isaacsim-local isaaclab train --rl_library rsl_rl \
+      --task Isaac-Cartpole-Direct physics=isaacsim_physx
+
+The platform instructions below are useful when debugging Isaac Sim manually. After a
+manual build, run the same ``--isaacsim_source`` command to package it and configure ``uv``.
+
 
 .. tab-set::
    :sync-group: installation-platform
@@ -814,8 +835,8 @@ before building.
          %ISAACSIM_PYTHON_EXE% -c "print('Isaac Sim configuration is now complete.')"
          %ISAACSIM_PYTHON_EXE% %ISAACSIM_PATH%\standalone_examples\api\isaacsim.core.experimental.api\add_cubes.py
 
-Return to the workspace containing the ``IsaacSim`` checkout, then clone Isaac Lab, link it to the
-source build, install, and verify:
+To use the legacy installer instead, return to the workspace containing the ``IsaacSim`` checkout,
+then clone Isaac Lab, link it to the source build, install, and verify:
 
 .. code-block:: text
 

pyproject.toml

@@ -160,6 +160,9 @@ rerun = [
 ]
 
 isaacsim = ["isaacsim[all,extscache]==6.0.1.0"]
+# Isaac Sim built from source (``isaaclab --isaacsim_source``). Source builds carry pre-release
+# local versions that sort below the published release, so the command pins this locally.
+isaacsim-local = ["isaacsim[all,extscache]>=6.0.1.0"]
 
 ov = ["ovphysx==0.5.9", "ovrtx>=0.4.0,<0.5.0", "ovstage==0.1.0.346039"]
 ovphysx = ["ovphysx==0.5.9", "ovstage==0.1.0.346039"]

skills/user/install-isaac-lab/reference.md

@@ -59,12 +59,25 @@ Read `docs/source/setup/installation/index.rst` "System requirements" from the c
 
 Run the docs-defined minimal verification command after every install, before larger tests. The command varies by route:
 
-- Automatic uv (`installation-method-uv`), legacy installer (`installation-legacy-installer`), managed Python env (`installation-method-python-env`), Isaac Lab wheel (`installation-method-wheel`), and Isaac Sim source build (`installation-method-source`) verify Isaac Lab via the tutorial script documented in the section's included verification snippet:
+- Automatic uv (`installation-method-uv`), legacy installer (`installation-legacy-installer`), managed Python env (`installation-method-python-env`), and Isaac Lab wheel (`installation-method-wheel`) verify Isaac Lab via the tutorial script documented in the section's included verification snippet:
 
 ```bash
 uv run python scripts/tutorials/00_sim/create_empty.py --viz kit
 ```
 
+- Isaac Sim source build (`installation-method-source`) runs the same script against the locally built Isaac Sim wheels:
+
+```bash
+uv run --extra isaacsim-local python scripts/tutorials/00_sim/create_empty.py --viz kit
+```
+
+  This only uses the local build when `pyproject.toml` carries both edits that
+  `uv run isaaclab --isaacsim_source <path>` writes: `find-links = ["_isaac_sim_wheels"]` under
+  `[tool.uv]`, and an `isaacsim-local` extra pinning the exact version from
+  `_isaac_sim_wheels/isaacsim-*.whl`. Without the pin, uv resolves the published wheels from
+  `pypi.nvidia.com` instead, because source builds carry pre-release local versions that sort below
+  the release.
+
 - Downloaded Isaac Sim package (`installation-method-binary`) uses the bundled-Python verification documented in the section (launch via `${ISAACSIM_PATH}/isaac-sim.sh`, then run the tutorial script from the checkout).
 - Docker (`installation-method-container`) runs the same tutorial verification inside the container as documented in `docs/source/features/docker_cloud.rst`.
 

source/isaaclab/changelog.d/uv-friendly-isaacsim-source-build.minor.rst

@@ -0,0 +1,13 @@
+Added
+^^^^^
+
+* Added the ``--isaacsim_source`` CLI option, which incrementally builds Isaac Sim from a source checkout,
+  packages the build as Python wheels, links them into the repository as ``_isaac_sim_wheels``,
+  points ``uv`` at that directory through ``find-links`` in ``pyproject.toml``, pins the
+  ``isaacsim-local`` extra to the version it built, and re-resolves Isaac Sim from those
+  wheels. Run Isaac Lab against the build with ``uv run --extra isaacsim-local``. The pin is
+  required because source builds carry pre-release local versions that sort below the published
+  release, so an unpinned extra resolves back to the released wheels on ``pypi.nvidia.com``.
+* Added a check to ``--isaacsim_source`` that rejects a stale Isaac Sim ``_build`` tree whose
+  packaged Kit kernel does not match the Python ABI its wheel is tagged for, instead of letting
+  Isaac Sim fail later with ``No module named 'carb._carb'``.

source/isaaclab/isaaclab/cli/__init__.py

@@ -17,6 +17,7 @@
 )
 from .commands.misc import (
     command_build_docs,
+    command_build_isaacsim,
     command_new,
     command_run_docker,
     command_run_isaacsim,
@@ -262,6 +263,15 @@ def cli() -> None:
         const="env_isaaclab",
         help="Create a new uv environment for Isaac Lab. Default name is 'env_isaaclab'.",
     )
+    parser.add_argument(
+        "--isaacsim_source",
+        metavar="PATH",
+        help=(
+            "Build Isaac Sim from the source checkout at PATH, package it as wheels, and link\n"
+            "them as '_isaac_sim_wheels' for 'uv run --extra isaacsim-local'.\n"
+            "Runs the normal incremental build on every invocation."
+        ),
+    )
 
     args = parser.parse_args()
 
@@ -277,6 +287,9 @@ def cli() -> None:
     elif args.uv:
         command_setup_uv(args.uv)
 
+    elif args.isaacsim_source:
+        command_build_isaacsim(args.isaacsim_source)
+
     elif args.vscode:
         command_vscode_settings()