Project

The IntelliJ Platform stores the project configuration data in XML files. The list of those files depends on the chosen project format:

Project and workspace settings are stored in a number of XML files under the $project_home_directory$/.idea directory. Each XML file is responsible for its own set of settings and can be recognized by its name: projectCodeStyle.xml, encodings.xml, vcs.xml etc. As for the file-based format projects, .iml files describe modules.

For file-based format projects (legacy), the information core to the project itself (e.g., location of the component modules, compiler settings, etc.) is stored in the $project_name$.ipr file. The information about modules the project includes is stored in $module_name$.iml files. Module files are created for each module.

Note that direct access to project files isn't required to load or save settings. See Persisting State of Components for more information.

Working with Projects

To work with projects and project files, use the following classes and interfaces:

Other classes for working with the project model are located in the projectModel-api.openapi package. Basic API classes and interfaces for the concepts of Project, Module and Application are placed in the core-api.openapi package.

How to get a `Project` instance?

A Project instance is available in multiple contexts:

Context	API
Action	`AnActionEvent.getProject()` `DataContext.getData(CommonDataKeys.PROJECT)`
Editor	`Editor.getProject()`
Module	`Module.getProject()`
PSI	`PsiElement.getProject()`
Tests	`IdeaProjectTestFixture.getProject()`

It is also possible to retrieve projects in generic contexts:

Project from VirtualFile:
- ProjectLocator.guessProjectForFile(VirtualFile) - returns any project containing a given file.
- ProjectLocator.getProjectsForFile(VirtualFile) - returns the list of projects that a given file is a part of.
List of currently opened projects: ProjectManager.getOpenProjects()

Getting a List of Source Roots for All Modules in a Project

Use the ProjectRootManager.getContentSourceRoots() method. To clarify this, consider the following code snippet:

String projectName = project.getName();
VirtualFile[] vFiles = ProjectRootManager.getInstance(project)
    .getContentSourceRoots();
String sourceRootsList = Arrays.stream(vFiles)
    .map(VirtualFile::getUrl)
    .collect(Collectors.joining("\n"));
Messages.showInfoMessage("Source roots for the " + projectName +
    " plugin:\n" + sourceRootsList, "Project Properties");

Checking If a File Belongs to a Project

Use ProjectFileIndex to get this information:

ProjectFileIndex projectFileIndex =
    ProjectRootManager.getInstance(project).getFileIndex();

Getting the Content or Source Root to Which a File or Directory Belongs

Use the ProjectFileIndex.getContentRootForFile() and ProjectFileIndex.getSourceRootForFile() methods. For example:

VirtualFile moduleContentRoot = ProjectRootManager.getInstance(project)
    .getFileIndex().getContentRootForFile(virtualFileOrDirectory);
VirtualFile moduleSourceRoot = ProjectRootManager.getInstance(project)
    .getFileIndex().getSourceRootForFile(virtualFileOrDirectory);

Note that this method returns null if the file or directory does not belong to any source root of modules in the project.

The ProjectFileIndex interface implements a number of methods you can use to check whether the specified file belongs to the project library classes or library sources:

isLibraryClassFile(): Returns true if the specified virtualFile is a compiled class file.
isInLibraryClasses(): Returns true if the specified virtualFileOrDirectory belongs to library classes.
isInLibrarySource(): Returns true if the specified virtualFileOrDirectory belongs to library sources.

Getting the Project SDK

Note that by default, the project modules use the project SDK. Optionally, you can configure an individual SDK for each module. See SDK for more details.

Changing the Project Structure

Utility classes used for modifying the project structure can be found in the package projectModel-impl.openapi. Its roots subpackage contains instances and utilities intended for work with project and module source roots, including ModuleRootModificationUtil and ProjectRootUtil. Project structure changes need to be performed in write action.

Refer to the project_model code sample to learn how project structure modification can be implemented.

Receiving Notifications About Project Structure Changes

To receive notifications about changes in project structure (modules or libraries being added or removed, module dependencies being changed, and so on), use the message bus and the ProjectTopics.PROJECT_ROOTS topic:

project.getMessageBus().connect().subscribe(
    ProjectTopics.PROJECT_ROOTS,
    new ModuleRootListener() {
      @Override
      public void rootsChanged(@NotNull ModuleRootEvent event) {
        // action
      }
    });

If targeting 2019.3 or later, declarative registration is available as well.

The event only notifies that something has changed; if more details are needed about what changes have occurred, keep a copy of the state of the project structure model which is relevant, and to compare it with the state after the change.

Receiving Notification About Project Close/Open Events

Use ProjectManagerListener listener or project open activity.

Last modified: 18 November 2024