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

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

⚠️ DO NOT manually edit .iml files via JetBrains MCP - The IDE's automatic converter runs concurrently and can interfere with edits.

When you need to fix missing dependencies:

1. Use the standard Edit tool (not mcp__jetbrains__replace_text_in_file) for .iml files
2. The converter will automatically update BUILD.bazel files
3. Verify compilation with ./bazel-build-all.cmd