Skip to content

Commit

Permalink
Rework site documentation
Browse files Browse the repository at this point in the history
* fix wording and typos
* enable syntax highlighting
* replace tabs in code blocks for unified layout
* upgrade skin (dependabot doesn't work for site.xml)
  • Loading branch information
Bananeweizen committed Dec 18, 2024
1 parent edb9113 commit 3048b7d
Show file tree
Hide file tree
Showing 11 changed files with 222 additions and 226 deletions.
41 changes: 19 additions & 22 deletions src/site/markdown/BndBuild.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# BND Workspace Layout and Pomless Builds

Tycho supports building projects that use the **BND Workspace Layout** as [described here](https://bndtools.org/concepts.html).
Tycho supports building projects that use the [BND Workspace Layout](https://bndtools.org/concepts.html).

## BND Workspace Layout
A BND Workspace layout build layout usually has the following structure:

- `root folder` - this usually is the root of your project repository (e.g. git)
- `root folder` - this usually is the root of your project repository
- `cnf` - configuration folder for general setup
- `build.bnd` - main configuration file
- `ext` - additional configuration (optional)
Expand All @@ -15,37 +15,34 @@ A BND Workspace layout build layout usually has the following structure:
- `bnd.bnd` - project configuration file
- `...`

any folder that do not match the layout is ignored.
Any folder that does not match the layout is ignored.

## Pomless Builds
Given the above layout, Tycho now has a good knowledge about what your build artifacts are.
In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most all from your supplied bnd configuration files, so everything is configured there and usually no additional maven configuration is required, therefore this build is completely pomless (no pom.xml), there are only a few steps to consider:
In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most all from your supplied bnd configuration files, so everything is configured there and usually no additional maven configuration is required, therefore this build is completely pomless (no `pom.xml`), there are only a few steps to consider:

1. Add a folder called `.mvn` to the root
2. Inside the `.mvn` folder place a file called `extensions.xml` with the following content:

```
- Add a folder called `.mvn` to the root
- Inside the `.mvn` folder place a file called `extensions.xml` with the following content:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<extensions>
<extension>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-build</artifactId>
<version>${tycho-version}</version>
</extension>
<extension>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-build</artifactId>
<version>${tycho-version}</version>
</extension>
</extensions>
```

3. create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):

- create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):
```properties
-Dtycho-version=4.10.0
```
-Dtycho-version=3.0.0
```
4. You can now run your build with `mvn clean verify`

A runnable demo can be found here:
https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-workspace
- You can now run your build with `mvn clean verify`.

You can check more details in a [demo project](https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-workspace).

## Mixed Builds

You can even combine a BND Workspace and PDE bundles in a build, a runnable demo can be found here:
https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-pde-workspace
You can even combine a BND Workspace and PDE bundles in a build, see [demo](https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-pde-workspace).
16 changes: 8 additions & 8 deletions src/site/markdown/BuildProperties.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

Tycho uses the `build.properties` file [as defined by PDE](https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.pde.doc.user/reference/pde_feature_generating_build.htm) to configure various aspects of the build.

Note that Tycho only supports a subset of keys defined by PDE.
Note that Tycho only supports a subset of keys defined by PDE.
If a key is not supported, this may be because:

* it's legacy/deprecated
* it doesn't fit into the maven project model or the way maven is generally expected to work
* there are other ways to achieve the desired configuration (e.g. using pom.xml)
* it's a missing feature

In additional to the PDE properties, Tycho supports property expressions like `${project.version}` in `build.properties` values.
These expressions are only used in a Tycho build, not when using the Eclipse IDE incremental build.
In additional to the PDE properties, Tycho supports property expressions like `${project.version}` in `build.properties` values.
These expressions are only used in a Tycho build, not when using the Eclipse IDE incremental build.

See the table below for which keys in `build.properties` defined by PDE are supported by Tycho or if not, whether there are alternatives when using Tycho.

Expand All @@ -21,7 +21,7 @@ Key | Value
--- | ---
bin.includes | supported
bin.excludes | supported
qualifier | not supported - use [Build Qualifer Mojo](tycho-packaging-plugin/build-qualifier-mojo.html) instead
qualifier | not supported - use [Build Qualifier Mojo](tycho-packaging-plugin/build-qualifier-mojo.html) instead
forceContextQualifier | supported
custom* | not supported

Expand All @@ -38,7 +38,7 @@ src.includes | supported
src.excludes | supported
jars.extra.classpath | only supported in the form `platform:/plugin/<Bundle-SymbolicName>[/path/to/nested/jar]`
jars.compile.order | supported
additional.bundles | supported (since Tycho 2.4.0)
additional.bundles | supported


## Compiler-specific properties
Expand All @@ -53,7 +53,7 @@ javacWarnings.library | not supported - use [compilerArgument](https://wiki.ecli
javacErrors.library | not supported - use [compilerArgument](https://wiki.eclipse.org/Tycho/FAQ#How_to_configure_warning.2Ferror_settings_of_the_OSGi_compiler.3F) instead.
javacDefaultEncoding.library | supported
javacCustomEncodings.library | not supported
javacProjectSettings | not supported. Use [useProjectSettings](tycho-compiler-plugin/compile-mojo.html#useProjectSettings) or [compilerArgs](tycho-compiler-plugin/compile-mojo.html#compilerArgs) instead.
javacProjectSettings | not supported. Use [useProjectSettings](tycho-compiler-plugin/compile-mojo.html#useProjectSettings) or [compilerArgs](tycho-compiler-plugin/compile-mojo.html#compilerArgs) instead.
compilerArg | not supported. Use [compilerArgs](tycho-compiler-plugin/compile-mojo.html#compilerArgs) instead
compilerAdapter | not supported. Use [compilerId](tycho-compiler-plugin/compile-mojo.html#compilerId) instead
compilerAdapter.useLog | not supported
Expand All @@ -66,8 +66,8 @@ Key | Value
--- | ---
root | supported
root.config | supported
root.folder | supported (since Tycho 0.27.0)
root.config.folder | supported (since Tycho 0.27.0)
root.folder | supported
root.config.folder | supported
root.permissions | supported
root.link | supported
generate.feature | not supported - use [Tycho Source Plugin](tycho-source-plugin/plugin-info.html) instead
Expand Down
28 changes: 14 additions & 14 deletions src/site/markdown/Category.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
# Category

A category.xml file can be used to define which content is placed into a p2 repository.
It can also specify how to display the content in the p2 installation dialog.
A `category.xml` file can be used to define which content is placed into a p2 repository.
It can also specify how to display the content in the p2 installation dialog.
For Tycho to use it, it must to be placed into the root of an project with the packaging type 'eclipse-repository'.

The 'category.xml' format was originally defined by the Eclipse PDE project.
The `category.xml` format was originally defined by the Eclipse PDE project.
There are extensions to the format only supported by p2 and Tycho.

The following listing is a simple category file listing only one feature and one plug-in.
The following snippet is a simple category file listing only one feature and one plug-in.


```
```xml
<?xml version="1.0" encoding="UTF-8"?>
<site>
<feature id="com.example.feature">
Expand All @@ -19,26 +18,27 @@ The following listing is a simple category file listing only one feature and one
<category-def name="com.example.category.update" label="Example update site"/>
</site>
```

The following is an example, demonstrating a complex category definition.

```
```xml
<?xml version="1.0" encoding="UTF-8"?>
<site>
<!-- Include features -->
<feature id="feature.id" version="1.4.100.v2009"/>
<!-- Since Tycho 1.1.0 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=407273#c18), features can declare platform-specific compatibility for multi-platform builds -->
<!-- Examples: https://github.com/mickaelistria/org.eclipse.simrel.build/blob/master/categories/category.xml#L581 -->
<feature id="linux.specific.feature.id" version="0.0.0" os="linux"/>

<!-- Directly include bundles, without a feature -->
<bundle id="bundle.id" version="1.3.1.v2023"/>

<!-- Directly include any iu -->
<iu id="unit.id"/>

<!-- Include all IUs matching an expression -->
<iu>
<query>
<query>
<expression type="match">
<![CDATA[
id == $0
Expand All @@ -47,21 +47,21 @@ The following is an example, demonstrating a complex category definition.
<param>another.unit.id</param>
</query>
</iu>

<!-- Categories -->
<feature id="feature.in.category">
<category name="category.id"/>
</feature>
<category-def name="category.id" label="Category Label">
<description>Details on the category</description>
</category-def>

<!-- example for a dynamic category -->
<category-def name="javax" label="Bundles starting with javax."/>
<iu>
<category name="javax"/>
<query>
<expression type="match">id ~= /javax.*/</expression>
<expression type="match">id ~= /javax.*/</expression>
</query>
</iu>
</site>
Expand Down
24 changes: 12 additions & 12 deletions src/site/markdown/PackagingTypes.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,20 @@
Tycho defines the following custom Maven packaging types targeted for Eclipse Plug-in development.

* `eclipse-plugin` corresponds to [Eclipse Plug-in and Plug-in Fragment projects](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Plug-in).
* `eclipse-test-plugin` is similar to `eclipse-plugin` but only contains Plugin Tests to be executed inside an OSGi runtime. There is a noticable difference between `eclipse-plugin` and `eclipse-test-plugin` with respect to the goal executed during `integration-test`. The former uses `tycho-surefire-plugin:integration-test` while the latter uses `tycho-surefire-plugin:test`.
* `eclipse-test-plugin` is similar to `eclipse-plugin` but only contains Plugin Tests to be executed inside an OSGi runtime. There is a notable difference between `eclipse-plugin` and `eclipse-test-plugin` with respect to the goal executed during `integration-test`. The former uses `tycho-surefire-plugin:integration-test` while the latter uses `tycho-surefire-plugin:test`.
* `eclipse-feature` corresponds to [Eclipse Feature projects](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Feature)
* `eclipse-repository` corresponds to projects containing a `category.xml` file, the support of [Eclipse Update Site projects]https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Update-Site) has been removed in latest Tycho versions
* `eclipse-repository` corresponds to projects containing a `category.xml` file, the support of [Eclipse Update Site projects](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Update-Site) has been removed in latest Tycho versions
* `eclipse-target-definition` corresponds to [Eclipse Target Platform](https://github.com/eclipse-pde/eclipse.pde/blob/master/docs/User_Guide.md#Target_Platform)
* `p2-installable-unit` corresponds to [Installable Units](https://github.com/eclipse-equinox/p2/blob/master/docs/Installable_Units.md)

The lifecycle bindings (i.e. which Maven plugins are executed in which Maven phase by default) are defined by `tycho-maven-plugin` in a [Maven extension](https://maven.apache.org/guides/mini/guide-using-extensions.html) therefore it needs to be loaded accordingly:

```
```xml
<plugin>
<groupId>org.apache.tycho</groupId>
<artifactId>tycho-maven-plugin</artifactId>
<version>${project.version}</version>
<extensions>true</extensions>
<groupId>org.apache.tycho</groupId>
<artifactId>tycho-maven-plugin</artifactId>
<version>${project.version}</version>
<extensions>true</extensions>
</plugin>
```

Expand All @@ -25,11 +25,11 @@ Only the `default` lifecycle has custom bindings, i.e. the [`clean` and `site` l

The according artifact handlers (i.e. the mapping from the packaging type to a specific extension) are provided by `p2-maven-plugin` in <https://github.com/eclipse-tycho/tycho/tree/master/p2-maven-plugin/src/main/java/org/eclipse/tycho/p2maven/repository>. When referencing one of the packaging types as Maven dependency it needs to be loaded with extensions as well:

```
```xml
<plugin>
<groupId>org.apache.tycho</groupId>
<artifactId>p2-maven-plugin</artifactId>
<version>${project.version}</version>
<extensions>true</extensions>
<groupId>org.apache.tycho</groupId>
<artifactId>p2-maven-plugin</artifactId>
<version>${project.version}</version>
<extensions>true</extensions>
</plugin>
```
109 changes: 53 additions & 56 deletions src/site/markdown/StructuredBuild.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Structured Build Layout and Pomless Builds

Tycho supports any layout of your build, but you can save you a lot of configuration work if you are using the so called **Structured Build Layout**.
Tycho supports any layout of your build, but you can save a lot of configuration effort if you use the so called **Structured Build Layout**.

## Structured Build Layout
A structured build layout usually has the following folder layout, even though you might not use all of the depending on your project:
A structured build layout usually has the following folders, even though you might not use all of them depending on your project:

- `root folder` - this usually contains your parent pom where you configure the plugins to use
- `bundles` (or `plugins`) - this contains your bundles that make up your application
Expand All @@ -23,71 +23,68 @@ A structured build layout usually has the following folder layout, even though y

## Pomless Builds
Given the above layout, Tycho now has a good knowledge about what your build artifacts are.
In contrast to a traditional maven build where each module has to contain a `pom.xml` file Tycho can derive most if not all from your existing data, that is the files you are created and using in our IDE,
there are only a few steps to consider:
In a traditional Maven build each module has to contain a `pom.xml` file.
Tycho however can derive most of the information from other already existing files, if your project follows the above structured build layout.

1. Add a folder called `.mvn` to the root
2. Inside the `.mvn` folder place a file called `extensions.xml` with the following content:

```
- Add a folder called `.mvn` to the root
- Inside the `.mvn` folder place a file called `extensions.xml` with the following content:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<extensions>
<extension>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-build</artifactId>
<version>${tycho-version}</version>
</extension>
<extension>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-build</artifactId>
<version>${tycho-version}</version>
</extension>
</extensions>
```

3. create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):

```
- Create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!):
```properties
-Dtycho-version=3.0.0
```

4. finally create a `pom.xml` with the following content in the root folder:

```
- Finally create a `pom.xml` with the following content in the root folder:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<groupId> ... your desired group id ...</groupId>
<artifactId>parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
<module>bundles</module>
<module>features</module>
<module>sites</module>
<module>products</module>
</modules>
<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-maven-plugin</artifactId>
<version>${tycho-version}</version>
<extensions>true</extensions>
</plugin>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>target-platform-configuration</artifactId>
<version>${tycho-version}</version>
<configuration>
<target>
<file>../../target-platform.target</file>
</target>
</configuration>
</plugin>
</plugins>
</build>
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<groupId> ... your desired group id ...</groupId>
<artifactId>parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>

<modules>
<module>bundles</module>
<module>features</module>
<module>sites</module>
<module>products</module>
</modules>

<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-maven-plugin</artifactId>
<version>${tycho-version}</version>
<extensions>true</extensions>
</plugin>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>target-platform-configuration</artifactId>
<version>${tycho-version}</version>
<configuration>
<target>
<file>../../target-platform.target</file>
</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
```

5. You can now run your build with `mvn clean verify`
- You can now run your build with `mvn verify`.
Loading

0 comments on commit 3048b7d

Please sign in to comment.