module-dependencies

Module Dependencies Management

This document describes how to manage module dependencies when working with IntelliJ IDEA codebase.

Documentation

Modularization Overview - Module organization principles:
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:

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:

./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:

### 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):

### skip generation section `test module.name`

Example - Custom test target with preserved content:

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:

Edit the .iml with the repo-approved edit tool.
Run bun build/jps-module.mjs register <path-to-iml> --fix-iml-eof for every changed module file.
Run ./build/jpsModelToBazel.cmd so generated BUILD.bazel files match the .iml source of truth.
Verify compilation or tests for the affected module.