add bndtools workspace template fragment

Update BndBuild.md

Apply suggestions from code review

Co-Authored-By: Ed Merks <[email protected]>
Co-Authored-By: Christoph Läubrich <[email protected]>
(cherry picked from commit ff5dbb6)

Author: 3 people

README.md

@@ -3,15 +3,15 @@
 
 [![Build Tycho](https://github.com/eclipse-tycho/tycho/actions/workflows/maven.yml/badge.svg)](https://github.com/eclipse-tycho/tycho/actions/workflows/maven.yml) [![Unit Test Results](https://github.com/eclipse-tycho/tycho/actions/workflows/check.yml/badge.svg)](https://github.com/eclipse-tycho/tycho/actions/workflows/check.yml) [![License check](https://github.com/eclipse-tycho/tycho/actions/workflows/licensecheck.yml/badge.svg)](https://github.com/eclipse-tycho/tycho/actions/workflows/licensecheck.yml)
 
-Tycho is a manifest-first way to build
+Tycho is an IDE-first way to build:
 
-  * Eclipse plug-ins/OSGi bundles
+  * Eclipse plug-ins / OSGi bundles
   * Features
   * Update sites/p2 repositories
   * RCP applications
-  
-with Maven.
+  * bnd workspaces
 
+with Maven.
 
 * 👔 Eclipse project entry: https://projects.eclipse.org/projects/technology.tycho
 * 🗒️ Documentation:

setup/bnd-templates/pomless/.mvn/README.md

@@ -0,0 +1,53 @@
+# Tycho Workspace template fragment for bndtools for pomless Maven build
+
+This is a [bndtools template fragment](https://bnd.bndtools.org/chapters/620-template-fragments.html) which you can use in a new or existing bndtools workspace, 
+to add a Maven build based on Eclipse Tycho for your bnd workspace.
+
+It creates a `.mvn` folder in your bnd workspace root, contain an `extensions.xml` and a `maven.config`.
+
+See documentation for the [Tycho BND Plugin](https://tycho.eclipseprojects.io/doc/main/BndBuild.html) for more information. 
+
+## Building your workspace
+
+```
+cd mybndworkspace
+mvn clean install
+```
+
+This is all you need to build your bnd workspace with Maven / Tycho.
+
+It will automatically consider all `bnd.bnd` files.
+
+
+## Optional configurator pom.xml
+
+While the default build is pomless, you can create a parent `pom.xml` in your `cnf` folder.
+It can be as simple as the following:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<groupId>com.example.mygroup</groupId>
+	<artifactId>parent</artifactId>
+	<version>1.0.0-SNAPSHOT</version>
+	<packaging>pom</packaging>
+</project>
+```
+
+This is useful if you want to add other maven plugins to your build, e.g., for code analysis or reporting.
+
+## Create executable jar based on .bndrun files
+
+Tycho can also create an executable `.jar` file of your application based on the `.bndrun` file containing `-runbundles`, which you can then deploy and start.
+
+Just add the following line to your `.mvn/maven.config` file or pass it on the maven commandline:
+
+```
+-Dbndrun.exports=mydemo.app
+```
+
+See [Create executable jar](https://tycho.eclipseprojects.io/doc/main/BndBuild.html#Create_executable_jar) for details.
+

setup/bnd-templates/pomless/.mvn/extensions.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<extensions>
+  <extension>
+    <groupId>org.eclipse.tycho</groupId>
+    <artifactId>tycho-build</artifactId>
+    <version>${tycho-version}</version>
+  </extension>
+</extensions>

setup/bnd-templates/pomless/.mvn/maven.config

@@ -0,0 +1 @@
+-Dtycho-version=4.0.11

src/site/markdown/BndBuild.md

@@ -13,6 +13,7 @@ A BND Workspace layout build layout usually has the following structure:
         - `bnd.bnd` - project configuration file
     - `bundle2` - Another bundle project
         - `bnd.bnd` - project configuration file
+        - `myapp.bndrun` - a .bndrun file which can be used to export an executable .jar as part of the build
     - `...`
 
 Any folder that does not match the layout is ignored.
@@ -51,6 +52,55 @@ If you want to further configure the build can be done in these ways:
 2. You can define properties per project properties in the `bnd.bnd` file `pom.model.property.<some property>: true`, see [the wiki](https://github.com/eclipse-tycho/tycho/wiki/Tycho-Pomless#overwrite-group-and-artifact-ids) for more details.
 3. You can place a `pom.xml` in your `cnf` folder this will then be used as a parent for the aggregator, here you can add additional mojos, profiles and so on. If you want to enable certain things only for some of the projects you can use properties as described in (2) to skip the execution of mojos not relevant for other projects.
 
+#### Create executable jar
+
+Tycho can also create an executable `.jar` file of your application based on a `.bndrun` file containing `-runbundles`, which you can then deploy and start.
+
+Just add the following line to your `.mvn/maven.config` file or pass it on the maven commandline:
+
+```
+-Dbndrun.exports=mydemo.app
+```
+
+This automatically searches all your bundles for a file named `mydemo.app.bndrun`.
+
+If you have a bundle `myappbundle` which contains `mydemo.app.bndrun`, then the build would create an executable jar at the following location:
+
+`/myappbundle/target/executable/mydemo.app.bndrun.jar`
+
+Your build output will look like this:
+
+```
+[INFO] --- tycho-bnd:4.0.11:run (build) @ myappbundle ---
+[INFO] Exporting mydemo.app.bndrun ...
+[INFO] Exported to .../myappbundle/target/executable/tycho.demo.app.jar
+```
+
+
 ## Mixed Builds
 
 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).
+
+
+## Troubleshooting
+
+Note: All properties in `.mvn/maven.config` can also be supplied via command line, for example to use a different tycho version use the following command line argument:
+
+`mvn clean install -Dtycho-version=5.0.0-SNAPSHOT`
+
+This uses the snapshot build which is useful if you build tycho yourself on your local machine and want to test that build.
+
+
+### polyglot.dump.pom
+
+E.g., `-Dpolyglot.dump.pom=pom-gen.xml` specifies that the generated pom.xml files which tycho polyglot creates is called `pom-gen.xml`. 
+This might be needed if you have name clashes with existing files in your build.
+
+
+### tycho.pomless.aggregator.names
+
+The command line argument `-Dtycho.pomless.aggregator.names=_dummydisabled_` is for handling a rare edge case: 
+In case you have your bnd workspace in a subfolder named `bundles`, `plugins`, `tests`,`features`, `sites`,`products`, or `releng` then tycho can have problems.
+The reason is that those names are kind of 'magic' names reserved for special usecases. 
+`-Dtycho.pomless.aggregator.names=_dummydisabled_` is a workaround to instruct Tycho to ignore those names. You can choose any word like `_dummydisabled_`, but just make sure you do not have a folder with that name.
+

src/site/site.xml

@@ -54,6 +54,11 @@
 	<custom>
 		<fluidoSkin>
 			<sourceLineNumbersEnabled>true</sourceLineNumbersEnabled>
+			<gitHub>
+                <projectId>eclipse-tycho/tycho</projectId>
+                <ribbonOrientation>right</ribbonOrientation>
+                <ribbonColor>gray</ribbonColor>
+            </gitHub>
 		</fluidoSkin>
 	</custom>
 </site>