README.textile

Target Platform Definition DSL and Generator

Introduction

Target Platform Definition DSL and Generator provides a DSL with an advanced editor and a generator taking this DSL as input and generating a .target file that PDE is able to read to provision a Target Platform.

The greatest thing about this tool is that it avoids you to manage the links to strict versions (e.g., 3.2.5.v20093493-sfoit-v-rrel) in .target files. It lets you define the bundles and features you want to use in your target platform and it handles the generation of the .target file with the most recent available version. It is possible to restrict the lookup within a version range.

Installation

The update site https://download.eclipse.org/cbi/updates/tpd/ provides access to all versions going forward. The old update site for the 3.0.0-SNAPSHOT version at https://download.eclipse.org/cbi/tpd/3.0.0-SNAPSHOT/ is obselete.

Requirements

• Java SE 8

• Eclipse 4.4+

• Xtext 2.11+

Basic usage

• Create a file with .tpd extension

• Once done, right-click on the file and select Create Target Definition File. You can also use the the keyboard shortcut Alt + R (⌥ Alt + R on Mac).

• To activate the target platform, you can either use the Set as Target Platform action which is available on right-clicking on a .tpd file, or use the Ctrl + R (⌘ Cmd + R on Mac) keybinding.

• You can also right-click on an opened file and choose Validate, it will look for any error and will also check if all repositories are available and if all specified installation unit are available within the repository (and respecting the version range if any).

Syntax

An empty file is a valid file.

Strings can be surrounded by either simple quotes ' or double quotes ".

An ID is a character sequence starting with an alpha (no space allowed).

Keywords can be escaped by prefixing them with ^.

You must start by defining the name of your target by specifying the header.

target "The name of my target"

Then you can optionally include other target platform files if you decided to split your target platform definition into several files. This will still lead to the generation of a single .target file.

include "base.tpd"
include "http://git.some.server.org/tree/tp/all.tpd"

You can define some options about what should be retrieved from the p2 repository. You can do that with the with keyword.

with source allEnvironments	

Available options are:

• requirements, whether this target must have all required IUs of the selected IUs available and included in the target to resolve successfully. If this option is true, the planner will be used to resolve otherwise the slicer is used. The planner can describe any missing requirements as errors.
• allEnvironments, whether this target should download and include environment (platform) specific units for all available platforms (vs. only the current target definition’s environment settings). Only supported by the slicer so requirements must not be used for this setting to be used.
• source, whether this location should download and include source bundles for the selected units if the associated source is available in the repository.
• configurePhase, whether this target should execute the configure phase after fetching the selected units.

source and configurePhase are not supported by PDE before 3.8. If you use a version of PDE older than 3.8, these options will simply be ignored.

You can define the environment of your target platform about what should be retrieved from the p2 repository. You can do that with the environment keyword. Content assist is your friend to find proper values.

environment linux gtk x86_64

Then, you define the locations of your p2 repositories. You can add as many locations as your want to your target. Location string must be URL, if your p2 repository is local, don’t forget to put a file:/ URL.

location "http://download.eclipse.org/releases/kepler/" 

A location may have an ID that can be written before or after the URI. This is useful if you want to apply some maven stuff (providing a password, a mirror…) for this repository (see #17 for examples).

location kepler "http://download.eclipse.org/releases/kepler/" 

Then, you may list the Installable Units (IUs) your want to include in your target. This can be bundles or Eclipse features (it may end with feature.group).

location "http://download.eclipse.org/releases/kepler/" {	
    org.eclipse.emf.sdk.feature.group
}

Don’t forget that you can escape a keyword by prefixing it with ^, e.g. if you need to reference a bundle name environment, write it like ^environment. The ^ will be automatically stripped during the generation.

If no version is specified, the most recent IUs will be selected in the repository. You can restrain the range of version to use by using the same syntax as in MANIFEST.MF files.

location "http://download.eclipse.org/releases/juno/" {
    // select the most recent version of EMF after 2.7.0
    org.eclipse.emf.sdk.feature.group 2.7.0
    // select the most recent eclipse.rcp feature within the given range 
    org.eclipse.rcp.feature.group [4.0.0,4.3.0)
}

Then, the most recent version of the given IU within this range will be selected.

You can use the special keyword lazy as version to state that you don’t want the generator to select the version to put in the .target file. Instead, it puts 0.0.0 which is interpreted by PDE during the resolution of the .target.

Call the generator from the command line

This project provide an Eclipse application that you can launch from the command line. The ID of the application is org.eclipse.cbi.targetplatform.tpd.converter and is provided by the plugin org.eclipse.cbi.targetplatform. You can use this app in shell scripts, ant or Maven build. If you prefer Maven, the following pom.xml snippet may help you to get started. It configures the tycho-eclipse-plugin to execute the mentioned application passing its application ID and the .tpd file (named like the containing maven artifact/project) :

[...]
  <artifactId>[artifact.id.of.the.target.definition.project]</artifactId>
  <packaging>eclipse-target-definition</packaging>
[...]
  <properties>
     <tycho.version>4.0.6</tycho.version>
   </properties>
[...]
  <build>
    <plugins>
[...]
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-eclipse-plugin</artifactId>
        <version>${tycho.version}</version>
        <executions>
          <execution>
            <goals>
              <goal>eclipse-run</goal>
            </goals>
            <phase>generate-resources</phase>
          </execution>
        </executions>
        <configuration>
          <addDefaultDependencies>true</addDefaultDependencies>
          <repositories>
            <repository>
              <id>e2024-03-mirror</id>
              <layout>p2</layout>
              <url>https://[url.to.eclipse.release.p2.repository.mirror]/</url>
            </repository>
            <repository>
              <id>cbi-targetplatform-dsl-mirror</id>
              <layout>p2</layout>
              <url>https://[url.to.cbi-targetplatform-dsl-3.0.0-release.p2.repository.mirror]</url>
            </repository>
          </repositories>
          <dependencies>
            <dependency>
              <artifactId>org.eclipse.cbi.targetplatform.feature</artifactId>
              <type>eclipse-feature</type>
            </dependency>
            <dependency>
              <artifactId>org.eclipse.equinox.p2.core.feature</artifactId>
              <type>eclipse-feature</type>
            </dependency>
          </dependencies>
          <applicationArgs>
            <applicationArg>-application</applicationArg>
            <applicationArg>org.eclipse.cbi.targetplatform.tpd.converter</applicationArg>
            <applicationArg>${project.artifactId}.tpd</applicationArg>
          </applicationArgs>
        </configuration>
      </plugin>
[...]
    </plugins>
  </build>
</project>

Build

Do a mvn clean package or mvn clean verify.

On macOS, you need to add -Ptarget-default to the command line due to the silly Maven profile activation policy.

Developing and Contributing

Contributions are always welcome! See CONTRIBUTING.md for details.

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/