Eclipse Launcher Framework. This tutorial describes how the define custom launcher for additional programs. Level of this tutorial: Advanced

Learn more in the Learning Portal. Check out our
Eclipse Plugin Development Online Training High Priority

1. Eclipse Launching Framework

The Eclipse IDE supports launching of other programs. Launching in this context is defined as running or debugging a program from within the Eclipse IDE.

A launcher is a set of Java classes in an Eclipse plug-in that performs launching.

The framework uses types launch configuration types to determine which configuration is created.

The following framework plug-ins are responsible for handling launch configurations:

  • org.eclipse.debug.core plug-in responsible for of creating and persisting launch configurations on behalf of the configuration type

  • org.eclipse.debug.ui provides the base functionality to display and change an existing launch configuration

2. Using launch configurations as a user

The easiest way to create a launch configuration is using the Run Configuration…​ dialog. This dialog can be accessed in several ways.

  • By typing Run Configurations…​ in the Quick Access

  • By holding Ctrl while pressing the green launch button.

    run exc

  • By using the drop down menu of the green launch button

    run exc

    and clicking on Run Configurations…​ in the menu.

In the Run Configuration…​ you can choose between different launch configuration types:

run configurations

How to create new launch configurations is described within the picture above.

2.1. Export a launch configuration

Those launch configurations can also be exported to a *.launch file. You can reach the export wizard via export command in the file menu or by typing Export (Launch Configuration) in the Quick Access.

export launch configuration

When pressing Next you can choose, which launch configuration you want to export. You can also define a location to store the *.launch file.

launch configuration export wizard

The exported Eclipse Application Launch Configuration.launch file looks like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<launchConfiguration type="org.eclipse.pde.ui.RuntimeWorkbench">
    <booleanAttribute key="append.args" value="true"/>
    <booleanAttribute key="askclear" value="true"/>
    <booleanAttribute key="automaticAdd" value="true"/>
    <booleanAttribute key="automaticValidate" value="false"/>
    <stringAttribute key="bootstrap" value=""/>
    <stringAttribute key="checked" value="[NONE]"/>
    <booleanAttribute key="clearConfig" value="false"/>
    <booleanAttribute key="clearws" value="false"/>
    <booleanAttribute key="clearwslog" value="false"/>
    <stringAttribute key="configLocation" value="${workspace_loc}/.metadata/.plugins/org.eclipse.pde.core/Eclipse_Application_Launch_Configuration"/>
    <booleanAttribute key="default" value="false"/>
    <setAttribute key="deselected_workspace_bundles"/>
    <booleanAttribute key="includeOptional" value="true"/>
    <stringAttribute key="location" value="${workspace_loc}/../runtime-EclipseApplication"/>
    <booleanAttribute key="org.eclipse.debug.core.ATTR_FORCE_SYSTEM_CONSOLE_ENCODING" value="false"/>
    <booleanAttribute key="org.eclipse.jdt.launching.ATTR_ATTR_USE_ARGFILE" value="false"/>
    <booleanAttribute key="org.eclipse.jdt.launching.ATTR_SHOW_CODEDETAILS_IN_EXCEPTION_MESSAGES" value="true"/>
    <booleanAttribute key="org.eclipse.jdt.launching.ATTR_USE_START_ON_FIRST_THREAD" value="true"/>
    <stringAttribute key="org.eclipse.jdt.launching.JRE_CONTAINER" value="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8"/>
    <stringAttribute key="org.eclipse.jdt.launching.PROGRAM_ARGUMENTS" value="-os ${target.os} -ws ${target.ws} -arch ${target.arch} -nl ${target.nl} -consoleLog"/>
    <stringAttribute key="org.eclipse.jdt.launching.SOURCE_PATH_PROVIDER" value="org.eclipse.pde.ui.workbenchClasspathProvider"/>
    <stringAttribute key="org.eclipse.jdt.launching.VM_ARGUMENTS" value="-Xms40m -Xmx512m"/>
    <stringAttribute key="pde.version" value="3.3"/>
    <stringAttribute key="product" value="org.eclipse.sdk.ide"/>
    <setAttribute key="selected_target_bundles">
        <setEntry value="com.google.gson@default:default"/>
        <setEntry value="com.google.guava@default:default"/>
        <setEntry value="com.ibm.icu@default:default"/>
        <setEntry value="com.jcraft.jsch@default:default"/>
        <setEntry value="de.jcup.asciidoctoreditor.css@default:default"/>
        <setEntry value="de.jcup.asciidoctoreditor.libs@default:default"/>
        <setEntry value="de.jcup.asciidoctoreditor@default:default"/>
        <setEntry value="javax.annotation@default:default"/>
        <setEntry value="javax.inject@default:default"/>
        <setEntry value="org.apache.ant@default:default"/>
        <setEntry value="org.apache.batik.constants@default:default"/>
        <setEntry value="org.apache.batik.css@default:default"/>
        <setEntry value="org.apache.batik.i18n@default:default"/>
        <setEntry value="org.apache.batik.util@default:default"/>
        <setEntry value="org.apache.commons.compress@default:default"/>
        <setEntry value="org.apache.commons.jxpath@default:default"/>
        <setEntry value="org.apache.commons.logging@default:default"/>
        <setEntry value="org.apache.felix.gogo.command@default:default"/>
        <setEntry value="org.apache.felix.gogo.runtime@default:default"/>
        <setEntry value="org.apache.felix.gogo.shell@default:default"/>
        <setEntry value="org.apache.felix.scr@1:true"/>
        <setEntry value="org.apache.httpcomponents.httpclient@default:default"/>
        <setEntry value="org.apache.httpcomponents.httpcore@default:default"/>
        <setEntry value="org.apache.lucene.core@default:default"/>
        <setEntry value="org.apache.xerces@default:default"/>
        <setEntry value="org.apache.xml.resolver@default:default"/>
        <setEntry value="org.apache.xmlgraphics@default:default"/>
        <setEntry value="org.eclipse.ant.core@default:default"/>
        <setEntry value="org.eclipse.ant.launching@default:default"/>
        <setEntry value="org.eclipse.ant.ui@default:default"/>
        <setEntry value="org.eclipse.compare.core@default:default"/>
        <setEntry value="org.eclipse.compare@default:default"/>
        <setEntry value="org.eclipse.core.commands@default:default"/>
        <setEntry value="org.eclipse.core.contenttype@default:default"/>
        <setEntry value="org.eclipse.core.databinding.beans@default:default"/>
        <setEntry value="org.eclipse.core.databinding.observable@default:default"/>
        <setEntry value="org.eclipse.core.databinding.property@default:default"/>
        <setEntry value="org.eclipse.core.databinding@default:default"/>
        <setEntry value="org.eclipse.core.expressions@default:default"/>
        <setEntry value="org.eclipse.core.externaltools@default:default"/>
        <setEntry value="org.eclipse.core.filebuffers@default:default"/>
        <setEntry value="org.eclipse.core.filesystem.linux.x86_64@default:false"/>
        <setEntry value="org.eclipse.core.filesystem@default:default"/>
        <setEntry value="org.eclipse.core.jobs@default:default"/>
        <setEntry value="org.eclipse.core.net@default:default"/>
        <setEntry value="org.eclipse.core.resources@default:default"/>
        <setEntry value="org.eclipse.core.runtime@default:true"/>
        <setEntry value="org.eclipse.core.variables@default:default"/>
        <setEntry value="org.eclipse.debug.core@default:default"/>
        <setEntry value="org.eclipse.debug.ui@default:default"/>
        <setEntry value="org.eclipse.e4.core.commands@default:default"/>
        <setEntry value="org.eclipse.e4.core.contexts@default:default"/>
        <setEntry value="org.eclipse.e4.core.di.annotations@default:default"/>
        <setEntry value="org.eclipse.e4.core.di.extensions.supplier@default:default"/>
        <setEntry value="org.eclipse.e4.core.di.extensions@default:default"/>
        <setEntry value="org.eclipse.e4.core.di@default:default"/>
        <setEntry value="org.eclipse.e4.core.services@default:default"/>
        <setEntry value="org.eclipse.e4.emf.xpath@default:default"/>
        <setEntry value="org.eclipse.e4.tools.compat@default:default"/>
        <setEntry value="org.eclipse.e4.tools.emf.editor3x@default:default"/>
        <setEntry value="org.eclipse.e4.tools.emf.ui@default:default"/>
        <setEntry value="org.eclipse.e4.tools.jdt.templates@default:default"/>
        <setEntry value="org.eclipse.e4.tools.services@default:default"/>
        <setEntry value="org.eclipse.e4.tools@default:default"/>
        <setEntry value="org.eclipse.e4.ui.bindings@default:default"/>
        <setEntry value="org.eclipse.e4.ui.css.core@default:default"/>
        <setEntry value="org.eclipse.e4.ui.css.swt.theme@default:default"/>
        <setEntry value="org.eclipse.e4.ui.css.swt@default:default"/>
        <setEntry value="org.eclipse.e4.ui.di@default:default"/>
        <setEntry value="org.eclipse.e4.ui.dialogs@default:default"/>
        <setEntry value="org.eclipse.e4.ui.model.workbench@default:default"/>
        <setEntry value="org.eclipse.e4.ui.services@default:default"/>
        <setEntry value="org.eclipse.e4.ui.swt.gtk@default:false"/>
        <setEntry value="org.eclipse.e4.ui.widgets@default:default"/>
        <setEntry value="org.eclipse.e4.ui.workbench.addons.swt@default:default"/>
        <setEntry value="org.eclipse.e4.ui.workbench.renderers.swt@default:default"/>
        <setEntry value="org.eclipse.e4.ui.workbench.swt@default:default"/>
        <setEntry value="org.eclipse.e4.ui.workbench3@default:default"/>
        <setEntry value="org.eclipse.e4.ui.workbench@default:default"/>
        <setEntry value="org.eclipse.ecf.filetransfer@default:default"/>
        <setEntry value="org.eclipse.ecf.identity@default:default"/>
        <setEntry value="org.eclipse.ecf.provider.filetransfer.ssl@default:false"/>
        <setEntry value="org.eclipse.ecf.provider.filetransfer@default:default"/>
        <setEntry value="org.eclipse.ecf.ssl@default:false"/>
        <setEntry value="org.eclipse.ecf@default:default"/>
        <setEntry value="org.eclipse.egit.core@default:default"/>
        <setEntry value="org.eclipse.egit.doc@default:default"/>
        <setEntry value="org.eclipse.egit.ui@default:default"/>
        <setEntry value="org.eclipse.egit@default:default"/>
        <setEntry value="org.eclipse.emf.common@default:default"/>
        <setEntry value="org.eclipse.emf.databinding.edit@default:default"/>
        <setEntry value="org.eclipse.emf.databinding@default:default"/>
        <setEntry value="org.eclipse.emf.ecore.change@default:default"/>
        <setEntry value="org.eclipse.emf.ecore.edit@default:default"/>
        <setEntry value="org.eclipse.emf.ecore.xmi@default:default"/>
        <setEntry value="org.eclipse.emf.ecore@default:default"/>
        <setEntry value="org.eclipse.emf.edit@default:default"/>
        <setEntry value="org.eclipse.epp.mpc.core@default:default"/>
        <setEntry value="org.eclipse.epp.mpc.help.ui@default:default"/>
        <setEntry value="org.eclipse.epp.mpc.ui.css@default:default"/>
        <setEntry value="org.eclipse.epp.mpc.ui@default:default"/>
        <setEntry value="org.eclipse.equinox.app@default:default"/>
        <setEntry value="org.eclipse.equinox.bidi@default:default"/>
        <setEntry value="org.eclipse.equinox.common@2:true"/>
        <setEntry value="org.eclipse.equinox.concurrent@default:default"/>
        <setEntry value="org.eclipse.equinox.console@default:default"/>
        <setEntry value="org.eclipse.equinox.event@default:default"/>
        <setEntry value="org.eclipse.equinox.frameworkadmin.equinox@default:default"/>
        <setEntry value="org.eclipse.equinox.frameworkadmin@default:default"/>
        <setEntry value="org.eclipse.equinox.http.jetty@default:default"/>
        <setEntry value="org.eclipse.equinox.http.registry@default:default"/>
        <setEntry value="org.eclipse.equinox.http.servlet@default:default"/>
        <setEntry value="org.eclipse.equinox.jsp.jasper.registry@default:default"/>
        <setEntry value="org.eclipse.equinox.jsp.jasper@default:default"/>
        <setEntry value="org.eclipse.equinox.launcher.gtk.linux.x86_64@default:false"/>
        <setEntry value="org.eclipse.equinox.launcher@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.artifact.repository@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.console@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.core@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.director.app@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.director@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.directorywatcher@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.discovery.compatibility@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.discovery@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.engine@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.extensionlocation@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.garbagecollector@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.jarprocessor@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.metadata.repository@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.metadata@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.operations@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.publisher.eclipse@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.publisher@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.reconciler.dropins@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.repository.tools@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.repository@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.touchpoint.eclipse@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.touchpoint.natives@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.transport.ecf@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.ui.discovery@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.ui.importexport@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.ui.sdk.scheduler@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.ui.sdk@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.ui@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.updatechecker@default:default"/>
        <setEntry value="org.eclipse.equinox.p2.updatesite@default:default"/>
        <setEntry value="org.eclipse.equinox.preferences@default:default"/>
        <setEntry value="org.eclipse.equinox.registry@default:default"/>
        <setEntry value="org.eclipse.equinox.security.ui@default:default"/>
        <setEntry value="org.eclipse.equinox.security@default:default"/>
        <setEntry value="org.eclipse.equinox.simpleconfigurator.manipulator@default:default"/>
        <setEntry value="org.eclipse.equinox.simpleconfigurator@1:true"/>
        <setEntry value="org.eclipse.help.base@default:default"/>
        <setEntry value="org.eclipse.help.ui@default:default"/>
        <setEntry value="org.eclipse.help.webapp@default:default"/>
        <setEntry value="org.eclipse.help@default:default"/>
        <setEntry value="org.eclipse.jdt.apt.core@default:default"/>
        <setEntry value="org.eclipse.jdt.apt.pluggable.core@default:default"/>
        <setEntry value="org.eclipse.jdt.apt.ui@default:default"/>
        <setEntry value="org.eclipse.jdt.core.manipulation@default:default"/>
        <setEntry value="org.eclipse.jdt.core@default:default"/>
        <setEntry value="org.eclipse.jdt.debug.ui@default:default"/>
        <setEntry value="org.eclipse.jdt.debug@default:default"/>
        <setEntry value="org.eclipse.jdt.doc.isv@default:default"/>
        <setEntry value="org.eclipse.jdt.doc.user@default:default"/>
        <setEntry value="org.eclipse.jdt.junit.core@default:default"/>
        <setEntry value="org.eclipse.jdt.junit.runtime@default:default"/>
        <setEntry value="org.eclipse.jdt.junit4.runtime@default:default"/>
        <setEntry value="org.eclipse.jdt.junit5.runtime@default:default"/>
        <setEntry value="org.eclipse.jdt.junit@default:default"/>
        <setEntry value="org.eclipse.jdt.launching@default:default"/>
        <setEntry value="org.eclipse.jdt.ui@default:default"/>
        <setEntry value="org.eclipse.jdt@default:default"/>
        <setEntry value="org.eclipse.jetty.http@default:default"/>
        <setEntry value="org.eclipse.jetty.io@default:default"/>
        <setEntry value="org.eclipse.jetty.security@default:default"/>
        <setEntry value="org.eclipse.jetty.server@default:default"/>
        <setEntry value="org.eclipse.jetty.util@default:default"/>
        <setEntry value="org.eclipse.jface.databinding@default:default"/>
        <setEntry value="org.eclipse.jface.text@default:default"/>
        <setEntry value="org.eclipse.jface@default:default"/>
        <setEntry value="org.eclipse.jgit.archive@default:default"/>
        <setEntry value="org.eclipse.jgit@default:default"/>
        <setEntry value="org.eclipse.jsch.core@default:default"/>
        <setEntry value="org.eclipse.jsch.ui@default:default"/>
        <setEntry value="org.eclipse.ltk.core.refactoring@default:default"/>
        <setEntry value="org.eclipse.ltk.ui.refactoring@default:default"/>
        <setEntry value="org.eclipse.m2e.archetype.common@default:default"/>
        <setEntry value="org.eclipse.m2e.core.ui@default:default"/>
        <setEntry value="org.eclipse.m2e.core@default:default"/>
        <setEntry value="org.eclipse.m2e.jdt@default:default"/>
        <setEntry value="org.eclipse.m2e.maven.runtime@default:default"/>
        <setEntry value="org.eclipse.m2e.model.edit@default:default"/>
        <setEntry value="org.eclipse.m2e.workspace.cli@default:default"/>
        <setEntry value="org.eclipse.osgi.compatibility.state@default:false"/>
        <setEntry value="org.eclipse.osgi.services@default:default"/>
        <setEntry value="org.eclipse.osgi.util@default:default"/>
        <setEntry value="org.eclipse.osgi@-1:true"/>
        <setEntry value="org.eclipse.pde.api.tools.annotations@default:default"/>
        <setEntry value="org.eclipse.pde.api.tools.ui@default:default"/>
        <setEntry value="org.eclipse.pde.api.tools@default:default"/>
        <setEntry value="org.eclipse.pde.build@default:default"/>
        <setEntry value="org.eclipse.pde.core@default:default"/>
        <setEntry value="org.eclipse.pde.doc.user@default:default"/>
        <setEntry value="org.eclipse.pde.ds.annotations@default:default"/>
        <setEntry value="org.eclipse.pde.ds.core@default:default"/>
        <setEntry value="org.eclipse.pde.ds.ui@default:default"/>
        <setEntry value="org.eclipse.pde.genericeditor.extension@default:default"/>
        <setEntry value="org.eclipse.pde.junit.runtime@default:default"/>
        <setEntry value="org.eclipse.pde.launching@default:default"/>
        <setEntry value="org.eclipse.pde.runtime@default:default"/>
        <setEntry value="org.eclipse.pde.ua.core@default:default"/>
        <setEntry value="org.eclipse.pde.ua.ui@default:default"/>
        <setEntry value="org.eclipse.pde.ui.templates@default:default"/>
        <setEntry value="org.eclipse.pde.ui@default:default"/>
        <setEntry value="org.eclipse.pde@default:default"/>
        <setEntry value="org.eclipse.platform.doc.isv@default:default"/>
        <setEntry value="org.eclipse.platform.doc.user@default:default"/>
        <setEntry value="org.eclipse.platform@default:default"/>
        <setEntry value="org.eclipse.rcp@default:default"/>
        <setEntry value="org.eclipse.sdk@default:default"/>
        <setEntry value="org.eclipse.search@default:default"/>
        <setEntry value="org.eclipse.swt.gtk.linux.x86_64@default:false"/>
        <setEntry value="org.eclipse.swt@default:default"/>
        <setEntry value="org.eclipse.team.core@default:default"/>
        <setEntry value="org.eclipse.team.genericeditor.diff.extension@default:default"/>
        <setEntry value="org.eclipse.team.ui@default:default"/>
        <setEntry value="org.eclipse.text@default:default"/>
        <setEntry value="org.eclipse.tips.core@default:default"/>
        <setEntry value="org.eclipse.tips.ide@default:default"/>
        <setEntry value="org.eclipse.tips.json@default:default"/>
        <setEntry value="org.eclipse.tips.ui@default:default"/>
        <setEntry value="org.eclipse.tools.layout.spy@default:default"/>
        <setEntry value="org.eclipse.ui.browser@default:default"/>
        <setEntry value="org.eclipse.ui.cheatsheets@default:default"/>
        <setEntry value="org.eclipse.ui.console@default:default"/>
        <setEntry value="org.eclipse.ui.editors@default:default"/>
        <setEntry value="org.eclipse.ui.externaltools@default:default"/>
        <setEntry value="org.eclipse.ui.forms@default:default"/>
        <setEntry value="org.eclipse.ui.genericeditor@default:default"/>
        <setEntry value="org.eclipse.ui.ide.application@default:default"/>
        <setEntry value="org.eclipse.ui.ide@default:default"/>
        <setEntry value="org.eclipse.ui.intro.quicklinks@default:default"/>
        <setEntry value="org.eclipse.ui.intro.universal@default:default"/>
        <setEntry value="org.eclipse.ui.intro@default:default"/>
        <setEntry value="org.eclipse.ui.monitoring@default:default"/>
        <setEntry value="org.eclipse.ui.navigator.resources@default:default"/>
        <setEntry value="org.eclipse.ui.navigator@default:default"/>
        <setEntry value="org.eclipse.ui.net@default:default"/>
        <setEntry value="org.eclipse.ui.themes@default:default"/>
        <setEntry value="org.eclipse.ui.trace@default:default"/>
        <setEntry value="org.eclipse.ui.views.log@default:default"/>
        <setEntry value="org.eclipse.ui.views.properties.tabbed@default:default"/>
        <setEntry value="org.eclipse.ui.views@default:default"/>
        <setEntry value="org.eclipse.ui.workbench.texteditor@default:default"/>
        <setEntry value="org.eclipse.ui.workbench@default:default"/>
        <setEntry value="org.eclipse.ui@default:default"/>
        <setEntry value="org.eclipse.update.configurator@default:default"/>
        <setEntry value="org.eclipse.userstorage.oauth@default:default"/>
        <setEntry value="org.eclipse.userstorage.ui@default:default"/>
        <setEntry value="org.eclipse.userstorage@default:default"/>
        <setEntry value="org.eclipse.wst.common.core@default:default"/>
        <setEntry value="org.eclipse.wst.common.emf@default:default"/>
        <setEntry value="org.eclipse.wst.common.environment@default:default"/>
        <setEntry value="org.eclipse.wst.common.frameworks@default:default"/>
        <setEntry value="org.eclipse.wst.common.uriresolver@default:default"/>
        <setEntry value="org.eclipse.wst.sse.core@default:default"/>
        <setEntry value="org.eclipse.wst.xml.core@default:default"/>
        <setEntry value="org.hamcrest.core@default:default"/>
        <setEntry value="org.hamcrest@default:default"/>
        <setEntry value="org.junit@default:default"/>
        <setEntry value="org.objectweb.asm.tree@default:default"/>
        <setEntry value="org.objectweb.asm@default:default"/>
        <setEntry value="org.objenesis@default:default"/>
        <setEntry value="org.opentest4j@default:default"/>
        <setEntry value="org.sat4j.core@default:default"/>
        <setEntry value="org.sat4j.pb@default:default"/>
        <setEntry value="org.tukaani.xz@default:default"/>
    </setAttribute>
    <setAttribute key="selected_workspace_bundles"/>
    <booleanAttribute key="show_selected_only" value="false"/>
    <stringAttribute key="templateConfig" value="${target_home}/configuration/config.ini"/>
    <booleanAttribute key="tracing" value="false"/>
    <booleanAttribute key="useCustomFeatures" value="false"/>
    <booleanAttribute key="useDefaultConfig" value="true"/>
    <booleanAttribute key="useDefaultConfigArea" value="true"/>
    <booleanAttribute key="useProduct" value="true"/>
</launchConfiguration>

As you can see your launch configuration is stored in a XML format, which contains the specific settings of your custom launch configuration.

2.2. Import a launch configuration

The exported launch configuration can be imported as well. You can reach the import wizard via import command in the file menu or by typing Import (Launch Configuration) in the Quick Access.

import launch configuration

When pressing Next you can look for a *.launch file in your file system, and import it.

launch configuration import wizard

After we successfully imported a certain *.launch file, we can choose and run this launch configuration with the Run Configuration…​ dialog.

3. How a launch can be triggered

Three different ways to trigger a launch exist.

  • Pass a launch configuration to an ILaunchConfigurationDelegate, which runs the launch configuration

  • Use an ILaunchShortcut and determine with an IEditorPart how a launch should be done

  • Use an ILaunchShortcut and determine with an ISelection how a launch should be done

3.1. Creating a new launch configuration type

 The org.eclipse.debug.core plug-in provides the org.eclipse.debug.core.launchConfigurationTypes extension point. This allows to add a new launch configuration type. The extension point can be configured as follows.

<extension point="org.eclipse.debug.core.launchConfigurationTypes">
    <launchConfigurationType
        name="Example launch"
        delegate="com.example.ExampleLaunchConfigurationDelegate"
        modes="run, debug"
        id="com.example.launchConfigurationType">
    </launchConfigurationType>
</extension>

The different modes are ILaunchManager.RUN_MODE, ILaunchManager.DEBUG_MODE and ILaunchManager.PROFILE_MODE. You can set one or more of these modes, as depicted in the code above. The delegate must be an implementation of the ILaunchConfigurationDelegate interface, which contains just one method. This method is responsible for the actual launch. The ILaunchConfiguration contains launching attributes, which can be read by using one the its getAttribute methods. Therefore we also specify an interface with key constants for the custom attributes:

public interface SampleLaunchConfigurationAttributes {

    public static final String CONSOLE_TEXT = "com.vogella.custom.launcher.console.text";
}

The LaunchConfigurationDelegate implementation, which works with this attribute may look like this:

public class SampleLaunchConfiguration extends LaunchConfigurationDelegate {

    @Override
    public void launch(ILaunchConfiguration configuration, String mode, ILaunch launch, IProgressMonitor monitor)
            throws CoreException {
        String attribute = configuration.getAttribute(VogellaLaunchConfigurationAttributes.CONSOLE_TEXT, "Simon says \"RUN!\"");
        System.out.println(attribute);
    }

}

Usually a ILaunchConfigurationDelegate is invoked by the UI of org.eclipse.debug.ui, which is covered in Launch Configuration UI.

3.2. Using the ILaunchShortcut for ISelections and IEditorParts

In some cases, one would rather create a default launch configuration from an ISelection or an IEditorPart, than manually configuring a launch configuration. With this approach it is up to the programmer to determine how a launch should be done according the current ISelection or IEditorPart. Such an ILaunchShortcut can be defined with the org.eclipse.debug.ui.launchShortcuts extension point.

<extension
    point="org.eclipse.debug.ui.launchShortcuts">
    <shortcut
        class="com.examole.launcher.LaunchShortcut"
        icon="icons/vogella.png"
        id="com.example.sample.shortcut"
        label="Sample Shortcut"
        modes="run, debug">
        <contextualLaunch>
            <enablement>
                <with
                    variable="selection">
                    <count
                        value="+">
                    </count>
                </with>
            </enablement>
        </contextualLaunch>
    </shortcut>
</extension>

The referenced LaunchShortcut class must implement ILaunchShortcut.

public class LaunchShortcut implements ILaunchShortcut {

    @Override
    public void launch(ISelection selection, String mode) {
        System.out.println("Selection: " + mode);
    }

    @Override
    public void launch(IEditorPart editor, String mode) {
        System.out.println("Editor: " + mode);
    }

}

After implementing this, you can run the Sample Shortcut from a editor’s popup menu or on a ISelection, such as a Java class file.

run as sample shortcut

4. Launch Configuration UI

The org.eclipse.debug.ui plug-in provides a user interface for the launch configurations.

A popular example for java developers is the java launch configuration dialog.

sample java application launch config ui

Previously we created a launch configuration delegate and in order run it from the UI, we can use the org.eclipse.debug.ui.launchConfigurationTabGroups extension point.

<extension
    point="org.eclipse.debug.ui.launchConfigurationTabGroups">
    <launchConfigurationTabGroup
        class="com.example.VogellaTabGroup"
        id="com.example.launchConfigurationTabGroup"
        type="com.example.launchConfigurationType">
    </launchConfigurationTabGroup>
</extension>

Here we reference to the com.example.launchConfigurationType, which we previously created.

Before we implement the tab group, we define a custom AbstractLaunchConfigurationTab, which will be placed on the tab group.

public class SampleTab extends AbstractLaunchConfigurationTab {

    private Text text;

    @Override
    public void createControl(Composite parent) {

        Composite comp = new Group(parent, SWT.BORDER);
        setControl(comp);

        GridLayoutFactory.swtDefaults().numColumns(2).applyTo(comp);

        Label label = new Label(comp, SWT.NONE);
        label.setText("Console Text:");
        GridDataFactory.swtDefaults().applyTo(label);

        text = new Text(comp, SWT.BORDER);
        text.setMessage("Console Text");
        GridDataFactory.fillDefaults().grab(true, false).applyTo(text);
    }

    @Override
    public void setDefaults(ILaunchConfigurationWorkingCopy configuration) {
    }

    @Override
    public void initializeFrom(ILaunchConfiguration configuration) {
        try {
            String consoleText = configuration.getAttribute(VogellaLaunchConfigurationAttributes.CONSOLE_TEXT,
                    "Simon says \"RUN!\"");
            text.setText(consoleText);
        } catch (CoreException e) {
            // ignore here
        }
    }

    @Override
    public void performApply(ILaunchConfigurationWorkingCopy configuration) {
        // set the text value for the CONSOLE_TEXT key
        configuration.setAttribute(VogellaLaunchConfigurationAttributes.CONSOLE_TEXT, text.getText());
    }

    @Override
    public String getName() {
        return "Vogella sample launch tab";
    }

}

With this tab we can set our SampleLaunchConfigurationAttributes.CONSOLE_TEXT attribute to the ILaunchConfiguration.

In the com.example.SampleTabGroup, we can use existing AbstractLaunchConfigurationTab implementations, like the CommonTab, or the SampleTab from above.

public class SampleTabGroup extends AbstractLaunchConfigurationTabGroup {

    @Override
    public void createTabs(ILaunchConfigurationDialog dialog, String mode) {
        setTabs(new ILaunchConfigurationTab[] { new SampleTab() ,new CommonTab()});
    }

}

A specific icon for the launch configuration can be defined by using the org.eclipse.debug.ui.launchConfigurationTypeImages extension point.

<extension
        point="org.eclipse.debug.ui.launchConfigurationTypeImages">
    <launchConfigurationTypeImage
            id="com.example.ui.launch.launchconfigurationtypeimage"
            configTypeID="com.example.launchConfigurationType"
            icon="icons/full/obj16/vogella.png">
    </launchConfigurationTypeImage>
</extension>

The result will look similar to this:

vogella launch ui

5. Eclipse Launcher Framework resources

Blogpost about writing a custom launcher

IBM tutorial about the launcher framework

If you need more assistance we offer Online Training and Onsite training as well as consulting

See License for license information.