Run Configurations Tutorial

This step-by-step guide shows how to register and implement a simple run configuration. Run configurations are used to run internal and external processes from within IntelliJ Platform based products.

The full implementation is available in the code samples.

Pre-Requirements

Create an empty plugin project. See the Creating a Plugin Gradle Project section for details.

Implement a ConfigurationType

Implement ConfigurationType:

final class DemoRunConfigurationType extends ConfigurationTypeBase {

  static final String ID = "DemoRunConfiguration";

  DemoRunConfigurationType() {
    super(ID, "Demo", "Demo run configuration type",
        NotNullLazyValue.createValue(() -> AllIcons.Nodes.Console));
    addFactory(new DemoConfigurationFactory(this));
  }

}

Register the ConfigurationType

<extensions defaultExtensionNs="com.intellij">
  <configurationType
      implementation="org.jetbrains.sdk.runConfiguration.DemoRunConfigurationType"/>
</extensions>

Implement a ConfigurationFactory

Implement a new ConfigurationFactory through which custom run configurations will be created.

public class DemoConfigurationFactory extends ConfigurationFactory {

  protected DemoConfigurationFactory(ConfigurationType type) {
    super(type);
  }

  @Override
  public @NotNull String getId() {
    return DemoRunConfigurationType.ID;
  }

  @NotNull
  @Override
  public RunConfiguration createTemplateConfiguration(
      @NotNull Project project) {
    return new DemoRunConfiguration(project, this, "Demo");
  }

  @Nullable
  @Override
  public Class<? extends BaseState> getOptionsClass() {
    return DemoRunConfigurationOptions.class;
  }

}

Implement corresponding configuration options class extending RunConfigurationOptions to store settings.

public class DemoRunConfigurationOptions extends RunConfigurationOptions {

  private final StoredProperty<String> myScriptName =
      string("").provideDelegate(this, "scriptName");

  public String getScriptName() {
    return myScriptName.getValue(this);
  }

  public void setScriptName(String scriptName) {
    myScriptName.setValue(this, scriptName);
  }

}

Implement a RunConfiguration

To make your changes visible from the UI, implement a new run configuration.

public class DemoRunConfiguration extends RunConfigurationBase<DemoRunConfigurationOptions> {

  protected DemoRunConfiguration(Project project,
                                 ConfigurationFactory factory,
                                 String name) {
    super(project, factory, name);
  }

  @NotNull
  @Override
  protected DemoRunConfigurationOptions getOptions() {
    return (DemoRunConfigurationOptions) super.getOptions();
  }

  public String getScriptName() {
    return getOptions().getScriptName();
  }

  public void setScriptName(String scriptName) {
    getOptions().setScriptName(scriptName);
  }

  @NotNull
  @Override
  public SettingsEditor<? extends RunConfiguration> getConfigurationEditor() {
    return new DemoSettingsEditor();
  }

  @Nullable
  @Override
  public RunProfileState getState(@NotNull Executor executor,
                                  @NotNull ExecutionEnvironment environment) {
    return new CommandLineState(environment) {
      @NotNull
      @Override
      protected ProcessHandler startProcess() throws ExecutionException {
        GeneralCommandLine commandLine =
            new GeneralCommandLine(getOptions().getScriptName());
        OSProcessHandler processHandler = ProcessHandlerFactory.getInstance()
            .createColoredProcessHandler(commandLine);
        ProcessTerminatedListener.attach(processHandler);
        return processHandler;
      }
    };
  }

}

Implement the SettingsEditor

public class DemoSettingsEditor extends SettingsEditor<DemoRunConfiguration> {

  private final JPanel myPanel;
  private final TextFieldWithBrowseButton scriptPathField;

  public DemoSettingsEditor() {
    scriptPathField = new TextFieldWithBrowseButton();
    scriptPathField.addBrowseFolderListener("Select Script File", null, null,
        FileChooserDescriptorFactory.createSingleFileDescriptor());
    myPanel = FormBuilder.createFormBuilder()
        .addLabeledComponent("Script file", scriptPathField)
        .getPanel();
  }

  @Override
  protected void resetEditorFrom(DemoRunConfiguration demoRunConfiguration) {
    scriptPathField.setText(demoRunConfiguration.getScriptName());
  }

  @Override
  protected void applyEditorTo(@NotNull DemoRunConfiguration demoRunConfiguration) {
    demoRunConfiguration.setScriptName(scriptPathField.getText());
  }

  @NotNull
  @Override
  protected JComponent createEditor() {
    return myPanel;
  }

}

Compile and Run the Plugin

Execute the plugin.
Go to Run | Edit Configurations..., click to Add button (+ icon), and select Demo.
In the Script file field provide the path to an example script (e.g. displaying "Hello world" message).
Click the Apply button and close the dialog.
In the run toolbar select created configuration and click the run button.

The script should be executed and its result should be displayed in the console.

Last modified: 08 April 2024