Overview

In the Consulo, a project encapsulates all the source code, libraries, and build instructions into a single organizational unit. Everything done in the IDE is accomplished within the context of a project. A project defines some collections referred to as modules and libraries. Depending on the logical and functional requirements for the project, a single-module or a multi-module project is possible.

Working with Projects

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

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.

For directory-based format projects, the 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.

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

To work with projects and project files, use the following classes and interfaces: * Project * ProjectRootManager * ProjectManager * ProjectFileIndex

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.

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 the 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.

Checking Whether a File or Directory Is Related to the Project Libraries

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 a 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(ModuleRootEvent event) {
  }
});

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.