Preserve aggregate wheel compatibility APIs

Author: StafaH

source/isaaclab/isaaclab/__init__.py

@@ -131,3 +131,25 @@ def _expose_mujoco_usd_schemas():
     __version__ = importlib.metadata.version("isaaclab")
 except importlib.metadata.PackageNotFoundError:
     __version__ = "0.0.0"
+
+
+# TODO(myurasov-nv): bootstrap_kernel() is ported from the internal GitLab wheel builder
+# for backwards compatibility. It is not called currently, but may be needed if Isaac Sim
+# requires explicit kernel bootstrapping before use. Remove once confirmed unnecessary.
+def bootstrap_kernel():
+    """Import Isaac Sim so it can initialize its kernel when available."""
+    isaaclab_path = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))
+    if importlib.util.find_spec("isaacsim") is not None:
+        import isaacsim  # noqa: F401
+
+        if importlib.util.find_spec("carb") is not None:
+            import carb
+
+            carb.log_info(f"Isaac Lab path: {isaaclab_path}")
+
+
+def main():
+    """Run the ``isaaclab`` command through its compatibility dispatcher."""
+    from isaaclab.__main__ import main as _main
+
+    sys.exit(_main())

tools/wheel_builder/res/__main__.py source/isaaclab/isaaclab/__main__.pytools/wheel_builder/res/__main__.py renamed to source/isaaclab/isaaclab/__main__.py

@@ -11,6 +11,8 @@
 
 import tomllib
 
+from isaaclab.paths import ISAACLAB_ROOT
+
 VSCODE_SETTINGS_TEMPLATE = """
 {
     "editor.rulers": [120],
@@ -115,7 +117,7 @@ def _get_paths(base_path: str, mock_python_modules: bool = False) -> list[str]:
     for folder in ["exts", "extscache", "extsDeprecated", "extsUser"]:
         extensions_paths.extend(_get_paths(os.path.join(isaacsim_path, folder), mock_python_modules=True))
     # - isaaclab
-    isaaclab_path = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))
+    isaaclab_path = str(ISAACLAB_ROOT)
     for folder in ["source"]:
         extensions_paths.extend(_get_paths(os.path.join(isaaclab_path, folder), mock_python_modules=True))
 

source/isaaclab/isaaclab/app/app_launcher.py

@@ -33,10 +33,10 @@
 
 SimulationApp = getattr(isaacsim, "SimulationApp", None)
 
-from isaaclab._paths import ISAACLAB_ROOT
 from isaaclab.app.loading_screen import report_activity
 from isaaclab.app.logging_utils import apply_python_logging_level, resolve_python_logging_level
 from isaaclab.app.settings_manager import get_settings_manager, initialize_carb_settings
+from isaaclab.paths import ISAACLAB_ROOT
 from isaaclab.utils._device import set_cuda_device
 from isaaclab.utils.renderers import ISAAC_RTX_SHOW_ALL_PARTITIONS_BY_DEFAULT_SETTING
 

source/isaaclab/isaaclab/benchmark/microbenchmark.py

@@ -13,8 +13,8 @@
 from pathlib import Path
 from types import MappingProxyType
 
-from isaaclab._paths import ISAACLAB_ROOT
 from isaaclab.cli.utils import run_python_command
+from isaaclab.paths import ISAACLAB_ROOT
 
 
 @dataclass(frozen=True)

source/isaaclab/isaaclab/benchmark/recorders/record_version_info.py

@@ -8,9 +8,9 @@
 import subprocess
 import sys
 
-from isaaclab._paths import ISAACLAB_ROOT
 from isaaclab.benchmark.interfaces import MeasurementData, MeasurementDataRecorder
 from isaaclab.benchmark.measurements import DictMetadata, StringMetadata
+from isaaclab.paths import ISAACLAB_ROOT
 
 # Path to the source checkout or installed wheel resources.
 _REPO_ROOT = str(ISAACLAB_ROOT)

source/isaaclab/isaaclab/cli/utils.py

@@ -13,7 +13,7 @@
 from pathlib import Path
 from typing import IO, Any
 
-from isaaclab._paths import ISAACLAB_ROOT
+from isaaclab.paths import ISAACLAB_ROOT
 
 # Default path to look for Isaac Sim is _isaac_sim symlink.
 DEFAULT_ISAAC_SIM_PATH = ISAACLAB_ROOT / "_isaac_sim"

source/isaaclab/isaaclab/_paths.py source/isaaclab/isaaclab/paths.pysource/isaaclab/isaaclab/_paths.py renamed to source/isaaclab/isaaclab/paths.py

@@ -29,7 +29,7 @@
 
 from filelock import FileLock
 
-from isaaclab._paths import ISAACLAB_ROOT
+from isaaclab.paths import ISAACLAB_ROOT
 
 logger = logging.getLogger(__name__)
 

source/isaaclab/isaaclab/utils/assets.py

@@ -12,8 +12,10 @@
 
 import pytest
 
-import isaaclab._paths as paths
+import isaaclab
+import isaaclab.__main__ as package_main
 import isaaclab.cli as cli
+import isaaclab.paths as paths
 
 pytestmark = pytest.mark.unit
 
@@ -23,10 +25,30 @@ def test_resolves_partial_source_checkout_root(tmp_path):
     package_root = tmp_path / "source" / "isaaclab" / "isaaclab"
     package_root.mkdir(parents=True)
 
-    with mock.patch.object(paths, "__file__", str(package_root / "_paths.py")):
+    with mock.patch.object(paths, "__file__", str(package_root / "paths.py")):
         assert paths._resolve_isaaclab_root() == tmp_path
 
 
+def test_top_level_compatibility_api_is_preserved():
+    """The flattened package must retain the aggregate wheel's public shims."""
+    assert callable(isaaclab.bootstrap_kernel)
+    with mock.patch.object(package_main, "main", return_value=0) as main, pytest.raises(SystemExit, match="0"):
+        isaaclab.main()
+
+    main.assert_called_once_with()
+
+
+def test_legacy_vscode_option_uses_compatibility_dispatcher():
+    """The installed entry point must continue to recognize the legacy VS Code option."""
+    with (
+        mock.patch.object(sys, "argv", ["isaaclab", "--generate-vscode-settings"]),
+        mock.patch.object(package_main, "generate_vscode_settings") as generate,
+    ):
+        package_main.main()
+
+    generate.assert_called_once_with()
+
+
 @pytest.mark.parametrize(
     ("command", "runner"),
     [

source/isaaclab/test/cli/test_installed_workflow_entrypoints.py

@@ -81,7 +81,7 @@ def test_wheel_builder_drops_workspace_members(tmp_path):
 
 def test_wheel_console_delegates_to_the_full_isaaclab_cli():
     """The wheel console command must expose the same workflows as a source installation."""
-    module_path = _repo_root() / "tools" / "wheel_builder" / "res" / "__main__.py"
+    module_path = _repo_root() / "source" / "isaaclab" / "isaaclab" / "__main__.py"
     spec = util.spec_from_file_location("_isaaclab_wheel_main", module_path)
     assert spec is not None
     assert spec.loader is not None
@@ -94,6 +94,13 @@ def test_wheel_console_delegates_to_the_full_isaaclab_cli():
     cli.assert_called_once_with()
 
 
+def test_wheel_console_uses_compatibility_dispatcher(tmp_path):
+    """The generated console script must preserve legacy installed-wheel options."""
+    generated = _generate_wheel_pyproject(tmp_path)
+
+    assert generated["project"]["scripts"]["isaaclab"] == "isaaclab.__main__:main"
+
+
 def test_wheel_builder_includes_isaacsim_extra(tmp_path):
     """The ``isaacsim`` extra must ship in the generated wheel metadata."""
     generated = _generate_wheel_pyproject(tmp_path)