From ca219956fd9295e4aa2bccd61ace5694d1fe9f33 Mon Sep 17 00:00:00 2001 From: Michael Keppler Date: Wed, 18 Dec 2024 19:00:41 +0100 Subject: [PATCH] Rework site documentation * fix wording and typos * enable syntax highlighting * enable line numbers for code blocks * replace tabs in code blocks for unified layout * upgrade skin (dependabot doesn't work for site.xml) --- src/site/markdown/BndBuild.md | 41 ++++---- src/site/markdown/BuildProperties.md | 16 +-- src/site/markdown/Category.md | 28 ++--- src/site/markdown/PackagingTypes.md | 24 ++--- src/site/markdown/StructuredBuild.md | 111 ++++++++++---------- src/site/markdown/SystemProperties.md | 2 +- src/site/markdown/TargetPlatform.md | 22 ++-- src/site/markdown/TestingBundles.md | 141 +++++++++++++------------- src/site/markdown/TychoCiFriendly.md | 53 +++++----- src/site/markdown/TychoProperties.md | 2 +- src/site/site.xml | 13 ++- 11 files changed, 227 insertions(+), 226 deletions(-) diff --git a/src/site/markdown/BndBuild.md b/src/site/markdown/BndBuild.md index f3ee54d3df..586db40b4d 100644 --- a/src/site/markdown/BndBuild.md +++ b/src/site/markdown/BndBuild.md @@ -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) @@ -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 - - org.eclipse.tycho - tycho-build - ${tycho-version} - + + org.eclipse.tycho + tycho-build + ${tycho-version} + ``` -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.0.10 ``` --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 \ No newline at end of file +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). diff --git a/src/site/markdown/BuildProperties.md b/src/site/markdown/BuildProperties.md index 80e1f69ed4..169ee6571b 100644 --- a/src/site/markdown/BuildProperties.md +++ b/src/site/markdown/BuildProperties.md @@ -2,7 +2,7 @@ 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 @@ -10,8 +10,8 @@ If a key is not supported, this may be because: * 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. @@ -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 @@ -38,7 +38,7 @@ src.includes | supported src.excludes | supported jars.extra.classpath | only supported in the form `platform:/plugin/[/path/to/nested/jar]` jars.compile.order | supported -additional.bundles | supported (since Tycho 2.4.0) +additional.bundles | supported ## Compiler-specific properties @@ -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 @@ -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 diff --git a/src/site/markdown/Category.md b/src/site/markdown/Category.md index c8517dc96e..bfdca2d852 100644 --- a/src/site/markdown/Category.md +++ b/src/site/markdown/Category.md @@ -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 @@ -19,9 +18,10 @@ The following listing is a simple category file listing only one feature and one ``` + The following is an example, demonstrating a complex category definition. -``` +```xml @@ -29,16 +29,16 @@ The following is an example, demonstrating a complex category definition. - + - + - + - + another.unit.id - + @@ -55,13 +55,13 @@ The following is an example, demonstrating a complex category definition. Details on the category - + - id ~= /javax.*/ + id ~= /javax.*/ diff --git a/src/site/markdown/PackagingTypes.md b/src/site/markdown/PackagingTypes.md index 5265bf0cdd..331fd363ba 100644 --- a/src/site/markdown/PackagingTypes.md +++ b/src/site/markdown/PackagingTypes.md @@ -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 - org.apache.tycho - tycho-maven-plugin - ${project.version} - true + org.apache.tycho + tycho-maven-plugin + ${project.version} + true ``` @@ -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 . When referencing one of the packaging types as Maven dependency it needs to be loaded with extensions as well: -``` +```xml - org.apache.tycho - p2-maven-plugin - ${project.version} - true + org.apache.tycho + p2-maven-plugin + ${project.version} + true ``` \ No newline at end of file diff --git a/src/site/markdown/StructuredBuild.md b/src/site/markdown/StructuredBuild.md index dbd8a8b5f7..97975cd41a 100644 --- a/src/site/markdown/StructuredBuild.md +++ b/src/site/markdown/StructuredBuild.md @@ -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 @@ -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 - - org.eclipse.tycho - tycho-build - ${tycho-version} - + + org.eclipse.tycho + tycho-build + ${tycho-version} + ``` -3. create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!): - -``` --Dtycho-version=3.0.0 +- Create a file called `maven.config` in the `.mvn` folder with the following content (adjust the version accordingly!): +```properties +-Dtycho-version=4.0.10 ``` -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 - 4.0.0 - ... your desired group id ... - parent - 1.0.0-SNAPSHOT - pom - - - bundles - features - sites - products - - - - - - org.eclipse.tycho - tycho-maven-plugin - ${tycho-version} - true - - - org.eclipse.tycho - target-platform-configuration - ${tycho-version} - - - ../../target-platform.target - - - - - + 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"> + 4.0.0 + ... your desired group id ... + parent + 1.0.0-SNAPSHOT + pom + + + bundles + features + sites + products + + + + + + org.eclipse.tycho + tycho-maven-plugin + ${tycho-version} + true + + + org.eclipse.tycho + target-platform-configuration + ${tycho-version} + + + ../../target-platform.target + + + + + ``` -5. You can now run your build with `mvn clean verify` +- You can now run your build with `mvn verify`. diff --git a/src/site/markdown/SystemProperties.md b/src/site/markdown/SystemProperties.md index a739b6b8a3..97371ac5d8 100644 --- a/src/site/markdown/SystemProperties.md +++ b/src/site/markdown/SystemProperties.md @@ -34,7 +34,7 @@ These properties control the behavior of P2 used by Tycho Name | Value | Default | Documentation --- | --- | --- | --- eclipse.p2.mirrors | true / false | true | Each p2 site can define a list of artifact repository mirrors, this controls if P2 mirrors should be used. This is independent from configuring mirrors in the maven configuration to be used by Tycho! -eclipse.p2.maxDownloadAttempts | _any positive integer_ | 3 | Describes how often Tycho attempts to re-download an artifact from a p2 repository in case e.g. a bad mirror was used. One can think of this value as the maximum number of mirrors Tycho/p2 will check. +eclipse.p2.maxDownloadAttempts | _any positive integer_ | 3 | Describes how often Tycho attempts to re-download an artifact from a p2 repository in case e.g. a bad mirror was used. One can think of this value as the maximum number of mirrors Tycho/p2 will check. ### Tycho P2 Transport diff --git a/src/site/markdown/TargetPlatform.md b/src/site/markdown/TargetPlatform.md index def0bc8044..09ee96dd33 100644 --- a/src/site/markdown/TargetPlatform.md +++ b/src/site/markdown/TargetPlatform.md @@ -25,11 +25,11 @@ Each module can have its own target platform, although with the normal configura ### Simple target platform configuration -In order allow Tycho to resolve the project dependencies against anything from a specific p2 repository, add that repository in the `` section of the POM. +In order to allow Tycho to resolve the project dependencies against anything from a specific p2 repository, add that repository in the `` section of the POM. Example: -``` +```xml eclipse-indigo http://download.eclipse.org/releases/2023-12 @@ -37,7 +37,7 @@ Example: ``` -In terms of the target platform, this means that the entire content of the specified p2 repositories become part of the target platform. +In terms of the target platform, this means that the entire content of the specified p2 repositories becomes part of the target platform. Background: In a normal (i.e. non-Tycho) Maven project, one can configure Maven repositories which can be used by Maven to resolve the project dependencies. Tycho can use p2 repositories for resolving OSGi dependencies. @@ -45,11 +45,11 @@ The p2 repositories need to be marked with layout=p2. (The normal Maven dependen ### Target files -The PDE target definition file format (*.target) allows to select a subset of units (bundles, features, etc.). +The PDE target definition file format (`*.target`) allows to select a subset of units (bundles, features, etc.). In order to add the content of a target definition file (see "Content" tab of the Target Editor) to the target platform in the Tycho build, place the target file in a eclipse-target-definition module and configure it in the target-platform-configuration build plugin. Example: -``` +```xml org.eclipse.tycho target-platform-configuration @@ -91,9 +91,9 @@ In case multiple target platform configuration approaches are combined, the targ Apart from the explicitly configured content, the target platform also contains the following artifacts: -Other artifacts from the same reactor -Locally built artifacts in the local Maven repository -Finally, it is possible to remove artifacts again from the target platform through a filtering syntax. +* Other artifacts from the same reactor +* Locally built artifacts in the local Maven repository +* Finally, it is possible to remove artifacts again from the target platform through a filtering syntax. ### Locally built artifacts @@ -111,7 +111,7 @@ See https://ci.eclipse.org/tycho/job/tycho-sitedocs/lastSuccessfulBuild/artifact ### Dependency resolution troubleshooting -Run mvn with the flags -Dtycho.debug.resolver=true and -X to see debug output. +Run mvn with the flags `-Dtycho.debug.resolver=true` and `-X` to see debug output. This will debug @@ -124,12 +124,12 @@ This will debug To list all the available IUs in an Eclipse p2 repository, run: -``` +```shell java -jar plugins/org.eclipse.equinox.launcher_1.6.600.v20231106-1826.jar -debug -consolelog -application org.eclipse.equinox.p2.director -repository https://download.eclipse.org/releases/latest/ -list ``` Java is used (instead of the eclipse binary) so that the console output appears in the shell. -Make sure your shell is inside the Eclipse root directory +Make sure your shell is inside the Eclipse root directory. You will need to replace that version number for org.eclipse.equinox.launcher with the one found inside your Eclipse installation. You will need to replace the Eclipse repository with the one you want a list of. diff --git a/src/site/markdown/TestingBundles.md b/src/site/markdown/TestingBundles.md index b0ef2f713b..6cc07c4bd2 100644 --- a/src/site/markdown/TestingBundles.md +++ b/src/site/markdown/TestingBundles.md @@ -7,37 +7,38 @@ There are different ways to test bundles / plug-ins with Tycho: Using [maven-surefire-plugin](https://maven.apache.org/surefire/maven-surefire-plugin/) is the preferred way whenever you want to write a plain unit-test. This is a unit test that either: -* don't need a OSGi runtime -* use some kind of mocking technique for OSGi (e.g. [Apache Sling OSGi Mocks](https://sling.apache.org/documentation/development/osgi-mock.html)) +* doesn't need an OSGi runtime +* uses some kind of mocking technique for OSGi (e.g. [Apache Sling OSGi Mocks](https://sling.apache.org/documentation/development/osgi-mock.html)) * or starts an embedded OSGi Framework (e.g. [osgi-test-framework](https://github.com/laeubisoft/osgi-test-framework)). This requires: - setting up your project using a test-source folder (see below), alternatively using the [standard maven layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) -- an configured execution of the `maven-surefire-plugin:test` goal +- a configured execution of the `maven-surefire-plugin:test` goal - packaging `eclipse-plugin` is used A sample snippet looks like this: -``` + +```xml - ... - - ... - - org.apache.maven.plugins - maven-surefire-plugin - ${surefire-plugin-version} - - - execute-tests - - test - - - - - - + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd"> + ... + + ... + + org.apache.maven.plugins + maven-surefire-plugin + ${surefire-plugin-version} + + + execute-tests + + test + + + + + + ``` To execute the tests, one has to invoke maven with `mvn test`. @@ -58,80 +59,80 @@ There are two ways to use this: of the integration-test phase of your build. This approach is not recommended for new designs. 2. You use `eclipse-plugin` packaging and configure an additional execution of the `tycho-surefire-plugin:plugin-test` goal with either a test-source folder (see below), alternatively using the [standard maven layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html). - + A sample snippet looks like this: -``` +```xml - ... - - ... - - org.eclipse.tycho - tycho-surefire-plugin - ${tycho-version} - - - execute-integration-tests - - plugin-test - verify - - - - - - + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd"> + ... + + ... + + org.eclipse.tycho + tycho-surefire-plugin + ${tycho-version} + + + execute-integration-tests + + plugin-test + verify + + + + + + ``` To execute the tests, one must invoke maven with `mvn verify`, the following demo projects are provided as an example: - Project with a configured source folder as a standalone project similar to the discouraged `eclipse-test-plugin` packaging: https://github.com/eclipse-tycho/tycho/tree/master/demo/testing/tycho/standalone -- Project using maven standard layout having the tests in the same module: +- Project using maven standard layout having the tests in the same module: https://github.com/eclipse-tycho/tycho/tree/master/demo/testing/tycho/samemodule ## bnd-testing The [tycho-surefire-plugin](https://tycho.eclipseprojects.io/doc/master/tycho-surefire-plugin/plugin-info.html) has also support for [bnd-testing](https://bnd.bndtools.org/chapters/310-testing.html), -this is like `plugin-test` but uses the BND testing framework. There is currently no JDT/PDE equivalent but this integrates nicely with the [OSGi Testing Support](https://github.com/osgi/osgi-test) and allows to execute prebuild test-bundles. +this is like `plugin-test` but uses the BND testing framework. There is currently no JDT/PDE equivalent but this integrates nicely with the [OSGi Testing Support](https://github.com/osgi/osgi-test) and allows to execute pre-built test-bundles. A sample snippet looks like this: -``` +```xml - ... - - ... - - org.eclipse.tycho - tycho-surefire-plugin - ${tycho-version} - - - execute-integration-tests - - bnd-test - verify - - - - - - + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd"> + ... + + ... + + org.eclipse.tycho + tycho-surefire-plugin + ${tycho-version} + + + execute-integration-tests + + bnd-test + verify + + + + + + ``` To execute the tests, one has to invoke maven with `mvn verify`, the following demo projects are provided as an example: - Project with maven standard layout having the tests in the same module and using [OSGi JUnit5 annotations](https://github.com/osgi/osgi-test/blob/main/org.osgi.test.junit5/README.md) -to automatically inject services: +to automatically inject services: - https://github.com/eclipse-tycho/tycho/tree/master/demo/testing/bnd/osgi-test -## combining different approaches +## combining different approaches ## setup test source folders in eclipse diff --git a/src/site/markdown/TychoCiFriendly.md b/src/site/markdown/TychoCiFriendly.md index c1e9c86d4f..093acfa834 100644 --- a/src/site/markdown/TychoCiFriendly.md +++ b/src/site/markdown/TychoCiFriendly.md @@ -1,6 +1,7 @@ # Tycho CI Friendly Versions -Starting with Maven 3.8.5 Tycho now supports an enhanced form of the [Maven CI Friendly Versions](https://maven.apache.org/maven-ci-friendly.html) beside the standard properties names one could also use: +Starting with Maven 3.8.5 Tycho now supports an enhanced form of the [Maven CI Friendly Versions](https://maven.apache.org/maven-ci-friendly.html). +Besides the standard properties names one can also use: - releaseVersion - major @@ -8,29 +9,29 @@ Starting with Maven 3.8.5 Tycho now supports an enhanced form of the [Maven CI F - micro - qualifier -These uses the usual semantics that you can use them in a version string e.g. `${releaseVersion}${qualifier}` and pass them on the commandline. +These uses the usual semantics that you can use them in a version string e.g. `${releaseVersion}${qualifier}` and pass them on the command line. -Beside this, Tycho supports some useful default calculation for `qualifier` if you give a format on the commandline with `-Dtycho.buildqualifier.format=yyyyMMddHHmm` +Beside this, Tycho supports some useful default calculation for `qualifier` if you give a format on the command line with `-Dtycho.buildqualifier.format=yyyyMMddHHmm` (or [any other format supported](https://tycho.eclipseprojects.io/doc/latest/tycho-packaging-plugin/build-qualifier-mojo.html#format)). Tycho will also make the build qualifier available in your Maven model! Alternatively, if you want that your qualifier matches the one from maven you can specify `-DforceContextQualifier=abc` -That way you can configure your pom in the following way: +That way you can configure your POM in the following way: -``` +```xml - 4.0.0 - ... - ... - pom - ${releaseVersion}${qualifier} - - - 1.0.0 - -SNAPSHOT - ... - - ... + 4.0.0 + ... + ... + pom + ${releaseVersion}${qualifier} + + + 1.0.0 + -SNAPSHOT + ... + + ... ``` @@ -39,23 +40,23 @@ and your artifact will get the `1.0.0-` version when publis To use this new feature you need to enable the tycho-build extension with the `.mvn/extensions.xml` file in the root of your project directory: -``` +```xml - - org.eclipse.tycho - tycho-build - ${tycho-version} - - + + org.eclipse.tycho + tycho-build + ${tycho-version} + + ``` Please note that we use another new feature from Maven 3.8.5 here, where you can use properties from the file `.mvn/maven.config` in your `.mvn/extensions.xml` file, so if you put in this: -``` +```properties -Dtycho-version=4.0.0 # probably add more here .. ``` -You can now control your Tycho version for `.mvn/extensions.xml` and your `pom.xml` in one place and still override it on the commandline with `-Dtycho-version=...` +You can now control your Tycho version for `.mvn/extensions.xml` and your `pom.xml` in one place and still override it on the command line with `-Dtycho-version=...` diff --git a/src/site/markdown/TychoProperties.md b/src/site/markdown/TychoProperties.md index d838f1b0cf..1ef56b64ae 100644 --- a/src/site/markdown/TychoProperties.md +++ b/src/site/markdown/TychoProperties.md @@ -1,6 +1,6 @@ # Tycho Properties -Maven provides a set of properties like `project.version` or `project.basedir` that could be used within pom files e.g. to configure the plugins. +Maven provides a set of properties like `project.version` or `project.basedir` that can be used within POM files e.g. to configure the plugins. Tycho provides its own set of additional properties. diff --git a/src/site/site.xml b/src/site/site.xml index 6b0bc13256..b2f9727ea1 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -25,7 +25,7 @@ - + @@ -43,12 +43,17 @@ - - + + org.apache.maven.skins maven-fluido-skin - 2.0.0-M10 + 2.0.1 + + + true + +