Skip to content

Instantly share code, notes, and snippets.

@Shadows-of-Fire
Last active September 25, 2023 03:01
Show Gist options
  • Save Shadows-of-Fire/3c7dd1bacdcddd9476b7b4eafb9f37a9 to your computer and use it in GitHub Desktop.
Save Shadows-of-Fire/3c7dd1bacdcddd9476b7b4eafb9f37a9 to your computer and use it in GitHub Desktop.
Eclipse Run Configuration Docs

Introduction to Eclipse Runs

Description

To launch programs within the Eclipse IDE, a configuration file known as a Run Configuration must be created, which instructs Eclipse to perform a particular action or series of actions, eventually starting the program.

Basic Information

Eclipse Run Configurations (.launch files) are XML files. Each file declares one element named launchConfiguration, which holds the data of the run config.

The launchConfiguration must declare a type attribute, where the type is any launchConfigurationType declared by Eclipse or an extension (such as Buildship).

That element then contains sub-elements in the Eclipse E-Attribute format (not to be confused with XML Attributes).
E-Attributes are described here.

Each launchConfiguration has its own unique schema, defining which E-Attributes make up the configuration.

Known Launch Configurations

Currently, we know of the following types:

  • org.eclipse.buildship.core.launch.runconfiguration
  • org.eclipse.buildship.core.launch.test.runconfiguration
  • org.eclipse.debug.core.groups.GroupLaunchConfigurationType
  • org.eclipse.jdt.launching.localJavaApplication
  • org.eclipse.jdt.launching.remoteJavaApplication
  • org.eclipse.jdt.launching.javaApplet
  • org.eclipse.jdt.junit.launchconfig

Each type has its own file later in this document providing additional details.

Eclipse E-Attribute

Description

E-Attributes are what eclipse uses to represent the parameters of a launch configuration. They are nothing more than a key->value mapping with a special XML syntax, and are represented in java as a TreeMap<String, Object>.

Each E-Attribute infers its Java type from its XML element name, and supplies a key XML attribute which will be used in the TreeMap. The location of the E-Attribute's value depends on the type.

The information in this documentd was sourced from here.

E-Attribute Types

Groups

E-Attributes can be grouped into two categories, depending on how their value is stored. The first category is Primitive E-Attributes, representing strings, booleans, and integers. Primitive types always store their value in the XML attribute value within their XML element.

The remaining types are Collection E-Attributes, composed of sets, maps, and lists. These types store their values in sub-elements, which are specific "collection entry" E-Attributes that can only be used within the relevant collection.

Type Names

The list of valid E-Attribute type names is as follows:

  • stringAttribute
  • intAttribute
  • booleanAttribute
  • setAttribute
    • setEntry
  • mapAttribute
    • mapEntry
  • listAttribute
    • listEntry

Syntax

Primitives

All primitive elements take the form

<type key="myKey" value="myValue"/>

Thus, the syntax for the three primitive is:

<stringAttribute key="myString" value="aStringValue"/>
<intAttribute key="myInt" value="100"/>
<booleanAttribute key="myBool" value="false"/>

The value of stringAttribute may be any string.
The value of intAttribute must be an integer.
The value of booleanAttribute must be true or false.

Sets

Sets are an element of type setAttribute made up of child elements, each with the type setEntry, and each specifying the value attribute. Sets do not permit duplicate elements. The value of a setEntry is not explicitly typed. The expected data is application-specific.

<setAttribute key="mySet">
    <setEntry value="first"/>
    <setEntry value="second"/>
</setAttribute>

Maps

Maps are an element of type mapAttribute made up of child elements of type mapEntry that specify the key and value attributes. Sets do not permit duplicate elements. The value of a setEntry is not explicitly typed. The expected data is application-specific.

<mapAttribute key="myMap">
    <mapEntry key="one" value="first"/>
    <mapEntry key="two" value="second"/>
</mapAttribute>

Lists

Lists are similar to sets, but with type listAttribute and with sub-elements of type listEntry. Lists retain their order and permit duplicates. The value of a listEntry is not explicitly typed. The expected data is application-specific.

<listAttribute key="myList">
    <listEntry value="first"/>
    <listEntry value="second"/>
</listAttribute>

Eclipse Native Launches

Description

This document covers the launchConfiguration types declared under the org.eclipse.jdt.launching package. The information found here was derived from IJavaLaunchConfigurationConstants.

The following types are covered:

  • org.eclipse.jdt.launching.localJavaApplication
    • Used when launching a Java Application (via main class) locally.
  • org.eclipse.jdt.launching.remoteJavaApplication
    • Used when connecting to a remote JVM via socket for remote debugging.
  • org.eclipse.jdt.launching.javaApplet
    • Used when launching a Java Applet in an applet viewer.

These types form the core set of basic launch configurations that are native to eclipse when working with java programs.
The sections below detail how to construct a launch configuration of each type.

Local Java Application

Description

This section details the E-Attributes relevant to the org.eclipse.jdt.launching.localJavaApplication launch configuration type.

Supported Keys

  • org.eclipse.jdt.launching.PROJECT_ATTR
    • E-Attribute type: stringAttribute
    • Usage: Declares the Eclipse Project Name associated with this launch configuration. Must match the name of a project in the current Eclipse workspace.
    • Required: True
  • org.eclipse.jdt.launching.MAIN_TYPE
    • E-Attribute type: stringAttribute
    • Usage: Declares the fully-qualified class name of the main class to launch when starting the application.
    • Required: True
  • org.eclipse.jdt.launching.MODULE_NAME
    • E-Attribute type: stringAttribute
    • Usage: The value is the module name for the main type to launch.
    • Required: False
    • Default Value: The value of org.eclipse.jdt.launching.PROJECT_ATTR.
    • Note: Not Verified, was not used in FG6 runs and may be unused or unnecessary. In testing, this uses the same value as org.eclipse.jdt.launching.PROJECT_ATTR.
  • org.eclipse.jdt.launching.PROGRAM_ARGUMENTS
    • E-Attribute type: stringAttribute
    • Usage: A string specifying all arguments that will be passed to the program as they would appear on the command line.
    • Required: False
    • Default Value: ""
  • org.eclipse.jdt.launching.VM_ARGUMENTS
    • E-Attribute type: stringAttribute
    • Usage: A string specifying all arguments that will be passed to the JVM as they would appear on the command line.
    • Required: False
    • Default Value: ""
  • org.eclipse.jdt.launching.WORKING_DIRECTORY
    • E-Attribute type: stringAttribute
    • Usage: A string specifying the working directory of the launch configuration. May be either an absolute file path, or use eclipse variables (or any combination thereof).
    • Required: False
    • Default Value: "${workspace_loc:ProjectName}" where ProjectName is the value specified in org.eclipse.jdt.launching.PROJECT_ATTR.
    • Note: FG6 specified the full file path, but it is also acceptable to specify "${workspace_loc:ProjectName}/run" instead. The forward slash works on windows.
  • org.eclipse.debug.core.environmentVariables
    • E-Attribute type: mapAttribute
    • Usage: A string->string map of environment variables that will be set when executing the configuration.
    • Required: False
    • Default Value: Empty map
    • Note: FG6 used this to set MCP_MAPPINGS and MOD_CLASSES.
  • org.eclipse.jdt.launching.STOP_IN_MAIN
    • E-Attribute type: booleanAttribute
    • Usage: If true, execution will stop in main when entered, awaiting a debugger command to continue execution.
    • Required: False
    • Default Value: "false"
  • org.eclipse.jdt.launching.JRE_CONTAINER
    • E-Attribute type: stringAttribute
    • Usage: Specifies the JRE to use when executing the application. Must be in some weirdly specific form that I do not know the specifics of.
    • Examples:
      • value="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/jdk-17.0.5.8-hotspot/"
    • Required: False
    • Default Value: Either the JVM of the Project, or the Workspace if the Project does not specify a JVM.
  • org.eclipse.jdt.launching.CLASSPATH
    • E-Attribute type: listAttribute
    • Usage: "An ordered list of strings which are mementos for runtime class path entries."
    • Required: False
    • Default Value: "A default classpath is generated by the classpath provider associated with this launch configuration."
    • Note: Format Unknown
  • org.eclipse.jdt.launching.MODULEPATH
    • E-Attribute type: listAttribute
    • Usage: "An ordered list of strings which are mementos for runtime module path entries."
    • Required: False
    • Default Value: "A default modulepath is generated by the dependency provider associated with this launch configuration."
    • Note: Format Unknown

Examples

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<launchConfiguration type="org.eclipse.jdt.launching.localJavaApplication">
  <stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="MyProjectName"/>
  <stringAttribute key="org.eclipse.jdt.launching.MODULE_NAME" value="MyProjectName"/>
  <stringAttribute key="org.eclipse.jdt.launching.MAIN_TYPE" value="dev.shadowsoffire.test.MyProjectName"/>
  <stringAttribute key="org.eclipse.jdt.launching.VM_ARGUMENTS" value="-Xmx512M"/>
  <stringAttribute key="org.eclipse.jdt.launching.PROGRAM_ARGUMENTS" value="--testArgument testArgValue"/>
  <stringAttribute key="org.eclipse.jdt.launching.WORKING_DIRECTORY" value="${workspace_loc:MyProjectName}/run"/>
  <mapAttribute key="org.eclipse.debug.core.environmentVariables">
    <mapEntry key="TEST_VAR" value="test_value"/>
  </mapAttribute>
</launchConfiguration>

Buildship Launches

Description

This document covers the launchConfiguration types declared under the org.eclipse.buildship package. They are provided by the buildship plugin. The information found here was derived from the following sources:

The following types are covered:

  • org.eclipse.buildship.core.launch.runconfiguration
  • org.eclipse.buildship.core.launch.test.runconfiguration

These types form the set of launch configurations necessary for interfacing with gradle.
The sections below detail how to construct a launch configuration of each type.

Gradle Task Launch

Description

This section details the E-Attributes relevant to the org.eclipse.buildship.core.launch.runconfiguration launch configuration type.

Supported Keys

  • tasks
    • E-Attribute type: listAttribute
    • Usage: Ordered list of gradle tasks that will be run by the launch configuration.
    • Required: True
    • Note: Task names must be fully-qualified names.
  • working_dir
    • E-Attribute type: stringAttribute
    • Usage: Declares the working directory for the gradle task(s) that will be run.
    • Required: False
    • Default Value: "" - Unsure where execution will begin when the empty string is passed.
    • Note: This value can use Eclipse Variables similar to how org.eclipse.jdt.launching.WORKING_DIRECTORY can use them.
  • gradle_distribution
    • E-Attribute type: stringAttribute
    • Usage: The gradle distribution to use. Can specify to use the local gradle wrapper via "GRADLE_DISTRIBUTION(WRAPPER)".
    • Required: False
    • Default Value: "GRADLE_DISTRIBUTION(WRAPPER)"
    • Note: Syntax for specifing specific gradle versions unknown.
  • offline_mode
    • E-Attribute type: booleanAttribute
    • Usage: Specifies if offline mode is enabled or not. Equivalent to passing --offline to gradle during task execution.
    • Required: False
    • Default Value: "false"
  • show_console_view
    • E-Attribute type: booleanAttribute
    • Usage: Specifies if the eclipse console will be shown when execution begins.
    • Required: False
    • Default Value: "true"
  • show_execution_view
    • E-Attribute type: booleanAttribute
    • Usage: Specifies if the eclipse Gradle Executions window will be shown when execution begins.
    • Required: False
    • Default Value: "true"
  • gradle_user_home
    • E-Attribute type: stringAttribute
    • Usage: Override for the gradle user home.
    • Required: False
    • Default Value: null
    • Note: This value may be able to use Eclipse Variables similar to how org.eclipse.jdt.launching.WORKING_DIRECTORY can use them. Requires testing.
  • java_home
    • E-Attribute type: stringAttribute
    • Usage: Override for the java home used by gradle.
    • Required: False
    • Default Value: null
    • Note: This value may be able to use Eclipse Variables similar to how org.eclipse.jdt.launching.WORKING_DIRECTORY can use them. Requires testing.
  • arguments
    • E-Attribute type: listAttribute
    • Usage: A list of strings specifying all arguments that will be passed to the program. One argument per entry.
    • Required: False
    • Default Value: Empty list
  • jvm_arguments
    • E-Attribute type: listAttribute
    • Usage: A string specifying all arguments that will be passed to the JVM. One argument per entry.
    • Required: False
    • Default Value: Empty list

Examples

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<launchConfiguration type="org.eclipse.buildship.core.launch.runconfiguration">
  <stringAttribute key="working_dir" value="${workspace_loc:MyProjectName}"/>
  <listAttribute key="tasks">
    <listEntry value=":clean"/>
    <listEntry value=":processResources"/>
  </listAttribute>
</launchConfiguration>

Launch Groups

Description

This document covers Launch Groups, which are launchConfigurations that have the type org.eclipse.debug.core.groups.GroupLaunchConfigurationType. These are launch configurations that execute multiple launches in sequence. The information in this section was derived from GroupLaunchConfigurationDelegate.

The keys of a launch group each include an index number, represented in this document as N. The index is placed in the keys of the inner E-Attributes between the org.eclipse.debug.core.launchGroup. and the true key name. For clarity, the key names will be declared below as org.eclipse.debug.core.launchGroup.N.keyName where N is the index number.

A Launch Group specifies many entries, with the index numbers starting at zero. Grouped launches will be run in ascending order based on index number, but do not need to be declared in ascending order. However, it is illegal to have gaps between index numbers. If a launch group declares an entry with index 3, it must declare entries with indicies 0, 1, and 2.

Supported Keys

  • org.eclipse.debug.core.launchGroup.N.name
    • E-Attribute type: stringAttribute
    • Usage: Specifies the name of the launch configuration that will be run for this index.
    • Required: True
    • Note: The name of a launch configuration is generally its file name, omitting the .launch extension.
  • org.eclipse.debug.core.launchGroup.N.enabled
    • E-Attribute type: booleanAttribute
    • Usage: Specifies if the launch group entry at this index is enabled and should be run.
    • Required: True
    • Note: This value should default to "true", but the parser always attempts to read the value, which means the default is ignored.
  • org.eclipse.debug.core.launchGroup.N.adoptIfRunning
    • E-Attribute type: booleanAttribute
    • Usage: Specifies if the launch group entry should use a currently executing instance, if one exists.
    • Required: False
    • Default Value: "false"
  • org.eclipse.debug.core.launchGroup.N.mode
    • E-Attribute type: stringAttribute
    • Usage: The execution mode for the launch configuration at this index. One of "run", "debug", "profile", or "inherit". See here for reference.
      • "run" - Always execute the configuration without invoking the debugger or the profiler.
      • "debug" - Always execute the configuration with the debugger.
      • "profile" - Always execute the configuration with the profiler.
      • "inherit" - Execute the configuration in whatever mode was specified by the user when starting the Launch Group.
    • Required: True
    • Note: This value should default to "inherit", but the parser always attempts to read the value, which means the default is ignored.
  • org.eclipse.debug.core.launchGroup.N.action
    • E-Attribute type: stringAttribute
    • Usage: The name of the post-launch action to take after the configuration at this index has launched, but before the next index has launched. One of "NONE", "WAIT_FOR_TERMINATION", "DELAY", or "OUTPUT_REGEXP". See here for reference.
      • "NONE" - Perform no action.
      • "WAIT_FOR_TERMINATION" - The thread controlling the Launch Group will sleep until the current entry has completed execution.
      • "DELAY" - The thread controlling the Launch Group will sleep for a specified number of seconds.
      • "OUTPUT_REGEXP" - The thread controlling the Launch Group will await a response from the entry that matches the specified regular expression.
    • Required: False
    • Default Value: "NONE"
  • org.eclipse.debug.core.launchGroup.N.actionParam
    • The actionParam has a variable declaration depending on the value of org.eclipse.debug.core.launchGroup.N.action.
    • "NONE"
      • Ignored
    • "WAIT_FOR_TERMINATION"
      • Ignored
    • "DELAY"
      • E-Attribute type: intAttribute
      • Usage: Specifies the time, in seconds, that the DELAY action will sleep for.
      • Required: True
    • "OUTPUT_REGEXP"
      • E-Attribute type: stringAttribute
      • Usage: The regular expression that will be matched against the output of the launch group entry.
      • Required: True

Examples

Assume we have a launch configuration named Project_RunGradleTasks and another named Project_LaunchApplication.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<launchConfiguration type="org.eclipse.debug.core.groups.GroupLaunchConfigurationType">
  <stringAttribute key="org.eclipse.debug.core.launchGroup.0.name" value="Project_RunGradleTasks"/>
  <booleanAttribute key="org.eclipse.debug.core.launchGroup.0.enabled" value="true"/>
  <stringAttribute key="org.eclipse.debug.core.launchGroup.0.mode" value="run"/>
  <stringAttribute key="org.eclipse.debug.core.launchGroup.1.name" value="Project_LaunchApplication"/>
  <booleanAttribute key="org.eclipse.debug.core.launchGroup.1.enabled" value="true"/>
  <stringAttribute key="org.eclipse.debug.core.launchGroup.1.mode" value="inherit"/>
</launchConfiguration>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment