JetBrains/intellij-community / .agents/skills/module-dependencies
module-dependencies
VerifiedAdd or modify IntelliJ 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:
- 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.cmdafter 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 incommunity/.idea/modules.xml - inserts entries in the canonical order:
.imlbasename without the.imlsuffix, matchingorg.jetbrains.intellij.build.ModulesXml - removes trailing line breaks from the listed
.imlfiles when--fix-iml-eofis 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
Library Version Changes
Bump a library with the dashboard tool, not by hand: bun community/build/libraries-dashboard/libraries-dashboard.mjs bump <groupId:artifactId>=<version> --kind=wrapper. It rewrites the maven-id, the jar URLs and every <sha256sum>, and prints the follow-up commands.
The artifact list must match the POM
JPS resolves a repository library from its POM and requires the <verification> artifact set to equal the resolved jar set. Bazel downloads the listed URLs instead, so a mismatch passes every local Bazel build and fails the first JPS step on TeamCity ("Library 'x': not found expected artifacts"). Two rules follow:
- A transitive artifact in a library block stays at the version the POM of the main artifact declares. Do not align it with another wrapper by editing the version.
- To share one version across wrappers, exclude the dependency and add a module dependency on its wrapper.
community/libraries/mockk/jvm/intellij.libraries.mockk.jvm.imlexcludesbyte-buddy-agentand depends onintellij.libraries.byte.buddy.agent.
The bump command checks a multi-artifact library against the direct dependencies of the new POM and fails on a mismatch. After a manual edit of a library block, run the same check:
bun community/build/libraries-dashboard/libraries-dashboard.mjs check <groupId:artifactId>
The check reads one POM without its parents and compares direct dependencies only. To reproduce the JPS resolution that TeamCity runs before every build, run ./build/downloadLibraries.cmd. It needs Space credentials.
Version copies outside the JPS model
After you change the version of a repository library in an *.iml or in .idea/libraries/*.xml, run the Fleet generator in the monorepo checkout:
./fleet/build/generateProjectModel.cmd dump
The Fleet generator copies the JPS library versions into fleet/build/jps-library-mappings.tsv and both fleet/kmp.MODULE.bazel files. Its check mode fails on drift.
When the dump changes a kmp.MODULE.bazel, update both Bazel lockfiles:
./bazel.cmd mod deps --lockfile_mode=update
(cd community && ./bazel.cmd mod deps --lockfile_mode=update)
The kmp module extension records its artifact list in the MODULE.bazel.lock of each module, and CI runs Bazel with --lockfile_mode=error, so a stale lockfile fails the build. bun community/build/libraries-dashboard/libraries-dashboard.mjs bump prints these commands after a bump.
Some files outside the JPS model copy a library version, and the project structure tests check each copy:
community/platform/jps-bootstrap/pom.xmlcopies every library that jps-bootstrap uses (JpsBoostrapStructureTest).JetBrainsAnnotationsExternalLibraryResolver.VERSIONcopiesorg.jetbrains:annotations(IdeaUltimateProjectStructureTest).
The bump command rewrites these copies and reports a copy that still differs. After a manual version change, edit them by hand. Then run the tests that gate the Smoke Tests build:
./tests.cmd --module intellij.projectStructureTests --test 'com.intellij.ideaProjectStructure.fast.*'
These tests also check the Kotlin, Compose and LanguageTool version alignment and the unused project libraries.
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.
Test Access to internal Declarations
A Kotlin internal declaration is visible to a test only when the test module is a friend of the
production module.
The same module. A test source root of a module sees the internal declarations of the
production sources. Nothing to configure. The generator adds the production target to the
associates attribute of the _test_lib target.
A separate test module. Add the TestModuleProperties component to the test module .iml:
<component name="TestModuleProperties" production-module="intellij.platform.configurationStore.impl" />
Then run ./build/jpsModelToBazel.cmd. The generator moves the production module from deps to
associates, and the Kotlin compiler gets it as a friend path. For a complete example, see
community/notebooks/visualization/intellij.notebooks.visualization.tests.iml.
The component holds one module. A test module cannot be a friend of two production modules, and the friendship is not transitive.
Java. Java has no internal modifier. Put the test class in the same package as a
package-private declaration. For a member that carries @ApiStatus.Internal, add
@VisibleForTesting or @TestOnly, because the compiler makes no check here.
Important Notes
When you need to fix missing dependencies:
- Edit the
.imlwith the repo-approved edit tool. - Run
bun build/jps-module.mjs register <path-to-iml> --fix-iml-eoffor every changed module file. - Run
./build/jpsModelToBazel.cmdso generatedBUILD.bazelfiles match the.imlsource of truth. - Verify compilation or tests for the affected module.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |