Skip to content

ide-pycharm.md

Latest commit

 

History

History
211 lines (147 loc) · 10.5 KB

ide-pycharm.md

File metadata and controls

211 lines (147 loc) · 10.5 KB

PyCharm Setup

Tips and configuration for developing with PyCharm. The committed .idea/ and .run/ files give you source roots, run/debug configurations, code style, file templates, and more out of the box — most setup is automatic when you open the project.

PyCharm Professional is required for debugging (remote debug server). Community edition works for editing and running the app, but cannot attach to the debug server.

Initial Setup

1. Build the project

Build first — the build populates _build/ with the Kit SDK, embedded Python interpreter, and all Omniverse extensions. It also generates .idea/lightspeed-kit.iml from .idea/lightspeed-kit.iml.template (via tools/utils/update_pycharm_sources.py) with:

  • Extension source roots — every directory under source/extensions/ for cross-extension imports
  • Build extra-paths — Kit kernel, extension cache, and pip bundle directories from _build/ (read from .vscode/settings.json python.analysis.extraPaths) grouped by container directory (extscache, extscore) so SDK imports (carb, pxr, omni.usd, etc.) resolve without manual interpreter-path configuration
  • Pip prebundle paths — discovered dynamically from deps/*.toml files that define [[dependency]] sections; the script reads each target field and finds the matching directories inside build extension directories so that third-party pip packages (pygit2, requests, py7zr, etc.) resolve correctly

The generated .iml is git-ignored; only the template is committed.

.\build.bat

2. Open the project

Open the repo root in PyCharm. The committed .idea/ files automatically configure:

  • Source roots — every extension in source/extensions/ plus all _build/ SDK paths are registered as source roots for import resolution (generated by the build via tools/utils/update_pycharm_sources.py)
  • Excluded directories — _build, _compiler, _repo, _testoutput, rtx-remix excluded from indexing
  • Search scopes — "Source Extensions" and "Python Extensions" for focused searching (.idea/scopes/)
  • File types — .kit files recognized as TOML for syntax highlighting (.idea/fileTypes.xml)
  • File templates — new Python files include the SPDX Apache-2.0 license header; new unit tests scaffold an AsyncTestCase class (.idea/fileTemplates/)
  • Ruff — linting enabled project-wide (.idea/misc.xml)
  • Encoding — UTF-8 default (.idea/encodings.xml)
  • Required plugins — PyCharm will prompt to install TOML and Shell Script plugins if missing ( .idea/externalDependencies.xml)
  • Module structure — project module mapping (.idea/modules.xml)

3. Set file template scheme to Project

The committed file templates (license header, unit test scaffold) only work when the template scheme is set to Project:

Settings (Ctrl+Alt+S) > Editor > File and Code Templates — set the Scheme dropdown (top of the page) to Project.

4. Configure the Python interpreter

Point PyCharm to Kit's embedded Python 3.10:

Settings (Ctrl+Alt+S) > Python > Interpreter > Add Interpreter > Add Local Interpreter — select the interpreter type and browse to:

_build\windows-x86_64\release\kit\python\python.exe

The build generates all SDK source roots in .idea/lightspeed-kit.iml (from the committed template), so no manual interpreter-path configuration is needed — all imports (carb, pxr, omni.*, py7zr, pygit2, requests, etc.) resolve out of the box.

5. Reload sources after a build

The build regenerates .idea/lightspeed-kit.iml from the template with updated source roots. PyCharm monitors this file and hot-reloads it — a restart is not required. To pick up the changes:

  • Alt-Tab away from PyCharm and back — PyCharm refreshes its virtual file system on window focus, which is usually enough.
  • If that doesn't work: click the Reload All from Disk toolbar button (or File > Reload All from Disk) to force PyCharm to re-read the .iml and update the project model.

Rebuild (.\build.bat) whenever you add new pip dependencies, update extension dependencies, or add/remove extensions so that _build/ and the .iml source roots stay in sync.

Run Configurations

The .run/ folder contains pre-configured run profiles organized into folders. They appear in PyCharm's run dropdown automatically:

Run

Configuration Type What it does Edition
Run Remix (Release) Shell Launches lightspeed.app.trex.bat (full app) Any
Run Remix (Dev) Shell Launches lightspeed.app.trex_dev.bat (dev app) Any

Debug

Configuration Type What it does Edition
Debug Remix (Release) Compound Starts debug server + launches full app with debugger Professional
Debug Remix (Dev) Compound Starts debug server + launches dev app with debugger Professional
Attach to Debugger Remote Debug Attaches to PyCharm's debug server on 127.0.0.1:33100 Professional

Debugging

  1. Select Debug Remix (Dev) or Debug Remix (Release) from the run dropdown.
  2. Click the Debug button (bug icon).
  3. Set breakpoints and debug normally — the app connects to PyCharm automatically.

These are compound configurations that start PyCharm's debug server (port 33100) and launch the app with omni.flux.debug.pycharm in one step.

For general debugging concepts, test debugging, and the debugpy-based alternative, see Debugging Guide.

Formatting & Linting

Run format_code.bat and lint_code.bat all from the terminal, or wire them as PyCharm external tools for hotkey integration:

Settings (Ctrl+Alt+S) > Tools > External Tools > + (Add):

Field Format Code Lint Code
Name Format Code Lint Code
Program $ProjectFileDir$\format_code.bat $ProjectFileDir$\lint_code.bat
Arguments (leave empty) all
Working directory $ProjectFileDir$ $ProjectFileDir$

Then assign keyboard shortcuts: Settings (Ctrl+Alt+S) > Keymap > External Tools — right-click the tool and assign a shortcut.

Project Structure

Excluded directories

The following directories are excluded from indexing (defined in .idea/lightspeed-kit.iml.template):

_build, _compiler, _repo, _testoutput, rtx-remix

If you need to exclude additional directories: Settings (Ctrl+Alt+S) > Project > Project Structure — select the folder and click Excluded.

Tip: Do not use an _* wildcard pattern to exclude — it will also exclude __init__.py files and break Python resolution.

Search scopes

Two shared scopes are pre-configured via .idea/scopes/ and available immediately:

  • Source Extensions — file:source/extensions//* — all files in project extensions
  • Python Extensions — file:source/extensions//*&&file:*.py — only Python files in extensions

Use them in Find in Files (Ctrl+Shift+F) by selecting the scope dropdown. To add custom scopes: Settings (Ctrl+Alt+S) > Appearance & Behavior > Scopes.

What's Committed

Summary of all shared configuration files in the repository:

.idea/ (project settings)

File Purpose
lightspeed-kit.iml.template Template for generated .iml (source roots, etc.)
modules.xml Module mapping
misc.xml Python SDK type, Ruff enabled
vcs.xml Git VCS mapping
encodings.xml UTF-8 default encoding
fileTypes.xml .kit → TOML file type association
externalDependencies.xml Required plugins (TOML, Shell Script)
fileTemplates/internal/Python Script.py SPDX Apache-2.0 license header for new Python files
fileTemplates/internal/Python Unit Test.py AsyncTestCase scaffold with license header
scopes/Source_Extensions.xml Search scope: all extension files
scopes/Python_Extensions.xml Search scope: Python extension files only
inspectionProfiles/profiles_settings.xml Inspection profile settings
.gitignore Excludes user-specific files (workspace, tasks, etc.)

.run/ (run configurations)

File Folder Purpose
Run Remix (Release).run.xml Run Launch full app
Run Remix (Dev).run.xml Run Launch dev app
Debug Remix (Release).run.xml Debug Debug full app (Professional)
Debug Remix (Dev).run.xml Debug Debug dev app (Professional)
Attach to Debugger.run.xml Debug Remote debug server connection (Professional)

Tips

Widescreen tool window layout

Enable Settings (Ctrl+Alt+S) > Appearance & Behavior > Appearance > Widescreen tool window layout to prevent the bottom tool window (terminal, run output, etc.) from spanning the full window width. With this option on, the left and right side panels (Project, Structure, etc.) extend to full height and the bottom pane only fills the space between them. This is especially useful on ultrawide or wide monitors where horizontal space is abundant.