module-dependencies

name	module-dependencies
description	How to manage module dependencies in IntelliJ codebase. Use when adding or modifying module dependencies in iml files.

Module Dependencies Management

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

Documentation

• Modularization Overview - Module organization principles:
  • Granularity of Modules
  • Modules in Project Sources
  • Modules at Runtime
  • Modules in Build Scripts
• 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:

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.