Child pages
  • External Builder API and Plugins
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

Services and extensions in External Builder

The external builder process uses the standard Java services mechanism to support plugins. There are several service interfaces (e.g. BuilderService) which can be implemented in plugins to extend the builder functionality. An implementation of a service need to be registered by creating META-INF/services/<service-interface-fqn> file containing the qualified name of the implementation class. E.g. BuilderService's implementations are registered in META-INF/services/org.jetbrains.jps.incremental.BuilderService file. These files don't have extensions so you need to map corresponding patterns to text files in IDEA settings.

Registering a plugin for External Builder

Sources of a plugin for External Builder should be put in a separate module. By convention such module has name '...-jps-plugin' and its sources are placed under 'jps-plugin' directory in the main plugin directory. Use compileServer.plugin extension to add the plugin to classpath of external build process, the plugin jar should be named "<jps module name>.jar". 'Build' | 'Prepare Plugin Module for deployment' action will automatically pack 'jps-plugin' part to a separate jar accordingly.

Debugging a plugin for External Builder

Start IDEA with your plugin with the following VM option 


After that every time compilation is run in the test IDEA, the build process will wait for debugger connection at this port and only then proceed. In working copy of IDEA a "Remote" run configuration should be created and pointed it to this port. Specifying port "-1" will disable debugging mode.

Profiling external build process

The build process has built-in self-cpu-profiling capabilities. To enable them do the following:
1. Copy <idea-home>/lib/yjp-controller-api-redist.jar and <idea-home>/bin/yjpagent.* files to <idea-system-dir>/compile-server
2. In "Settings | Compiler | Additional compiler process VM options" field enter -Dprofiling.mode=true
3. Make sure automatic make is turned off
After this every build process run should result in a CPU snapshot stored in <user-home>/Snapshots directory. Snapshots are named like "ExternalBuild-{date}.snapshot".

Specifying -Dprofiling.mode=false will turn profiling off.
Please capture a couple of snapshots for the situations in which you believe the build should work much faster than it works.

Please create an issue in the issue tracker and attach generated *.snapshot files to it or upload them to and specify links in the issue. Please also provide details about the memory and other VM settings for the build process you were using.

Accessing External Build process' logs

The log file is located under the directory


There both "build-log.log" and "build-log.xml" files can be found. The build-log.xml is a log4j  configuration file, where the log level and desired logging categories can be adjusted. This file contains logging from all build sessions, including those from the auto-make. 

Accessing project model and configuration from External Build

The project model in External Build process is provided by JPS (JetBrains Project System). A project is represented by JpsProject, a module - by JpsModule and so on. If your compiler depends on something that isn't added to the model yet (e.g. some facet settings), you need to extend the JPS model (use JpsGwtModuleExtension as a reference implementation) and provide implementation of JpsModelSerializerExtension to load the configuration from project files.

Implementing builder

If your compiler isn't involved into compilation of an existing BuildTarget you need to create a new implementation of BuildTarget and BuildTargetType. Also register an implementation of BuildTargetScopeProvider extension on IDEA side to add required targets to the build scope.

The builder implementation should extend either TargetBuilder or ModuleLevelBuilder class and should be created using BuilderService extension.

  • No labels