module-dependencies

# Module Dependencies Management This document describes how to manage module dependencies when working with IntelliJ IDEA codebase. ## Documentation - [Modularization Overview](../../../../docs/IntelliJ-Platform/4_man/Modularization/) - Module organization principles: - [Granularity of Modules](../../../../docs/IntelliJ-Platform/4_man/Modularization/0_Granularity-of-modules.md) - [Modules in Project Sources](../../../../docs/IntelliJ-Platform/4_man/Modularization/1_Modules-in-project-sources.md) - [Modules at Runtime](../../../../docs/IntelliJ-Platform/4_man/Modularization/2_Modules-at-runtime.md) - [Modules in Build Scripts](../../../../docs/IntelliJ-Platform/4_man/Modularization/3_Modules-in-build-scripts.md) - [Project Structure](../../../../docs/IntelliJ-Platform/4_man/Project-Structure/) - Naming conventions, Kotlin usage, dependencies ## Build System Overview The repository uses a hybrid build system: - **JPS (*.iml files)**: Source of truth for module dependencies - **Bazel (BUILD files)**: Auto-generated from *.iml files - **Generator**: run `build/jpsModelToBazel.cmd` after changing .iml files ## JPS Module Registration Helper When creating or editing a JPS module `.iml`, use the helper instead of hand-editing project module lists: ```bash bun build/jps-module.mjs register <path-to-iml> --fix-iml-eof ``` The helper: - registers the module in `.idea/modules.xml` - also registers `community/...` modules in `community/.idea/modules.xml` - inserts entries in the canonical order: `.iml` basename without the `.iml` suffix, matching `org.jetbrains.intellij.build.ModulesXml` - removes trailing line breaks from the listed `.iml` files when `--fix-iml-eof` is passed Use `bun build/jps-module.mjs check <path-to-iml> --fix-iml-eof` to verify without writing. ## Running the IML-to-Bazel Generator To manually run the converter that generates Bazel BUILD files from .iml files: ```bash ./build/jpsModelToBazel.cmd ``` This is useful when: - The automatic converter didn't run (e.g., .iml files were modified outside the IDE) - You need to regenerate BUILD files after git operations - Troubleshooting build system synchronization issues ## BUILD.bazel Auto-Generated Sections BUILD.bazel files have auto-generated sections marked with comments: ```starlark ### auto-generated section `build module.name` start ... generated content ... ### auto-generated section `build module.name` end ### auto-generated section `test module.name` start ... generated content ... ### auto-generated section `test module.name` end ``` **Key rules:** - Content **inside** auto-generated sections is overwritten by the generator - Content **outside** auto-generated sections is preserved during regeneration ### Skip Generation Marker To prevent auto-generation of a section (so you can provide custom content): ```starlark ### skip generation section `test module.name` ``` **Example - Custom test target with preserved content:** ```starlark load("@community//build:tests-options.bzl", "jps_test") # Custom test target (before auto-generated sections) jps_test( name = "my-tests_test", runtime_deps = [ ":my-tests_test_lib", "//:main_test_lib", ], ) ### skip generation section `test my.module.name` ### auto-generated section `build my.module.name` start ... (let generator handle the build section) ``` ## Content Modules and Wrapper Plugins Product layouts can include content modules directly. If production runtime already gets a dependency from a content module in the product layout, that content-module dependency can be enough and does not automatically require adding a wrapper plugin dependency to a production `.iml` or plugin descriptor. Test plugin resolution is different because tests often do not run with the full production product layout or flat classpath. If a test module loads a plugin whose dependencies include content modules owned by a wrapper plugin, add the wrapper plugin as a test/runtime dependency in the test module `.iml` instead of broadening the production module dependency. For example, a test that needs Problems View content modules may need `intellij.platform.problemView.plugin` as a runtime dependency even when the production module only depends on Problems View content modules. ## Important Notes When you need to fix missing dependencies: 1. Edit the `.iml` with the repo-approved edit tool. 2. Run `bun build/jps-module.mjs register <path-to-iml> --fix-iml-eof` for every changed module file. 3. Run `./build/jpsModelToBazel.cmd` so generated `BUILD.bazel` files match the `.iml` source of truth. 4. Verify compilation or tests for the affected module.