Skip to content

Commit e670853

Browse files
author
Christoph Läubrich
committed
Add docs for 5.0.0 release
1 parent 35cf4b5 commit e670853

2,418 files changed

Lines changed: 82386 additions & 10 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎doc/5.0.0/BndBuild.html‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
<!DOCTYPE html>
2+
3+
4+
<!--
5+
| Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/markdown/BndBuild.md at 2025-08-29
6+
| Rendered using Apache Maven Fluido Skin 2.0.1
7+
-->
8+
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
9+
<head>
10+
<meta charset="UTF-8" />
11+
<meta name="viewport" content="width=device-width, initial-scale=1" />
12+
<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
13+
<title>BND Workspace Layout and Pomless Builds – Tycho</title>
14+
<link rel="stylesheet" href="./css/apache-maven-fluido-2.0.1.min.css" />
15+
<link rel="stylesheet" href="./css/site.css" />
16+
<link rel="stylesheet" href="./css/print.css" media="print" />
17+
<script src="./js/apache-maven-fluido-2.0.1.min.js"></script>
18+
<style>.github-fork-ribbon:before { background-color: gray; }</style>
19+
</head>
20+
<body>
21+
<a class="github-fork-ribbon right-top" href="https://github.com/eclipse-tycho/tycho" data-ribbon="Fork me on GitHub">Fork me on GitHub</a>
22+
<div class="container-fluid container-fluid-top">
23+
<header>
24+
<div id="banner">
25+
<div class="pull-left"></div>
26+
<div class="pull-right"></div>
27+
<div class="clear"><hr/></div>
28+
</div>
29+
30+
<div id="breadcrumbs">
31+
<ul class="breadcrumb">
32+
<li id="publishDate">Last Published: 2025-08-29<span class="divider">|</span>
33+
</li>
34+
<li id="projectVersion">Version: 5.0.0</li>
35+
</ul>
36+
</div>
37+
</header>
38+
<div class="row-fluid">
39+
<header id="leftColumn" class="span2">
40+
<nav class="well sidebar-nav">
41+
<ul class="nav nav-list">
42+
<li class="nav-header">Using Tycho</li>
43+
<li><a href="index.html">Overview</a></li>
44+
<li><a href="StructuredBuild.html">Structured Build Layout and Pomless Builds</a></li>
45+
<li class="active"><a><span class="icon-chevron-down"></span>BND Workspace and Pomless Builds</a>
46+
<ul class="nav nav-list">
47+
<li><a href="tycho-bnd-plugin/plugin-info.html">Tycho BND Plugin</a></li>
48+
</ul></li>
49+
<li><a href="PackagingTypes.html"><span class="icon-chevron-down"></span>Packaging Types</a>
50+
<ul class="nav nav-list">
51+
<li><a href="tycho-packaging-plugin/plugin-info.html">Tycho Packaging Plugin</a></li>
52+
</ul></li>
53+
<li><a href="TargetPlatform.html"><span class="icon-chevron-down"></span>Target Platform</a>
54+
<ul class="nav nav-list">
55+
<li><a href="target-platform-configuration/plugin-info.html">Target Platform Configuration Plugin</a></li>
56+
<li><a href="tycho-extras/target-platform-validation-plugin/plugin-info.html">Target Platform Validation Plugin</a></li>
57+
<li><a href="tycho-extras/tycho-version-bump-plugin/update-target-mojo.html">Update Target Platform Mojo</a></li>
58+
</ul></li>
59+
<li><a href="TestingBundles.html"><span class="icon-chevron-down"></span>Testing Bundles</a>
60+
<ul class="nav nav-list">
61+
<li><a href="tycho-surefire-plugin/plugin-info.html">Tycho Surefire Plugin</a></li>
62+
</ul></li>
63+
<li><a href="TychoCiFriendly.html">Tycho CI Friendly Versions</a></li>
64+
<li><a href="Category.html"><span class="icon-chevron-down"></span>Creating update sites using category.xml</a>
65+
<ul class="nav nav-list">
66+
<li><a href="tycho-p2-repository-plugin/plugin-info.html">Tycho P2 Repository Plugin</a></li>
67+
</ul></li>
68+
<li><a><span class="icon-chevron-down"></span>Properties</a>
69+
<ul class="nav nav-list">
70+
<li><a href="BuildProperties.html">Build Properties</a></li>
71+
<li><a href="SystemProperties.html">System Properties</a></li>
72+
<li><a href="TychoProperties.html">Tycho Properties</a></li>
73+
</ul></li>
74+
<li class="nav-header">Other Tycho Plugins</li>
75+
<li><a href="tycho-baseline-plugin/plugin-info.html">Baseline Plugin</a></li>
76+
<li><a href="tycho-compiler-plugin/plugin-info.html">Compiler Plugin</a></li>
77+
<li><a href="tycho-ds-plugin/plugin-info.html">Declarative Services Plugin</a></li>
78+
<li><a href="tycho-extras/tycho-document-bundle-plugin/plugin-info.html">Document Bundle Plugin</a></li>
79+
<li><a href="tycho-eclipse-plugin/plugin-info.html">Eclipse Plugin</a></li>
80+
<li><a href="tycho-gpg-plugin/plugin-info.html">GPG Signature Plugin</a></li>
81+
<li><a href="tycho-p2-director-plugin/plugin-info.html">P2 Director Plugin</a></li>
82+
<li><a href="tycho-p2-plugin/plugin-info.html">P2 Metadata Plugin</a></li>
83+
<li><a href="tycho-p2-publisher-plugin/plugin-info.html">P2 Publisher Plugin</a></li>
84+
<li><a href="tycho-extras/tycho-p2-extras-plugin/plugin-info.html">P2 Extras Plugin</a></li>
85+
<li><a href="tycho-apitools-plugin/plugin-info.html">PDE API Tools Plugin</a></li>
86+
<li><a href="tycho-source-plugin/plugin-info.html">Source Plugin</a></li>
87+
<li><a href="tycho-versions-plugin/plugin-info.html">Versions Plugin</a></li>
88+
<li><a href="tycho-cleancode-plugin/plugin-info.html">CleanCode Plugin</a></li>
89+
<li class="nav-header">Project Documentation</li>
90+
<li><a href="project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
91+
</ul>
92+
</nav>
93+
<div class="well sidebar-nav">
94+
<div id="poweredBy">
95+
<div class="clear"></div>
96+
<div class="clear"></div>
97+
<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
98+
</div>
99+
</div>
100+
</header>
101+
<main id="bodyColumn" class="span10">
102+
<section><a id="BND_Workspace_Layout_and_Pomless_Builds"></a>
103+
<h1>BND Workspace Layout and Pomless Builds</h1>
104+
<p>Tycho supports building projects that use the <a href="https://bndtools.org/concepts.html" class="externalLink">BND Workspace Layout</a>.</p><section><a id="BND_Workspace_Layout"></a>
105+
<h2>BND Workspace Layout</h2>
106+
<p>A BND Workspace layout build layout usually has the following structure:</p>
107+
<ul>
108+
109+
<li><code>root folder</code> - this usually is the root of your project repository
110+
<ul>
111+
112+
<li><code>cnf</code> - configuration folder for general setup
113+
<ul>
114+
115+
<li><code>build.bnd</code> - main configuration file</li>
116+
<li><code>ext</code> - additional configuration (optional)</li>
117+
</ul></li>
118+
<li><code>bundle1</code> - A bundle project
119+
<ul>
120+
121+
<li><code>bnd.bnd</code> - project configuration file</li>
122+
</ul></li>
123+
<li><code>bundle2</code> - Another bundle project
124+
<ul>
125+
126+
<li><code>bnd.bnd</code> - project configuration file</li>
127+
<li><code>myapp.bndrun</code> - a .bndrun file which can be used to export an executable .jar as part of the build</li>
128+
</ul></li>
129+
<li><code>...</code></li>
130+
</ul></li>
131+
</ul>
132+
<p>Any folder that does not match the layout is ignored.</p></section><section><a id="Pomless_Builds"></a>
133+
<h2>Pomless Builds</h2>
134+
<p>Given the above layout, Tycho now has a good knowledge about what your build artifacts are.
135+
In contrast to a traditional maven build where each module has to contain a <code>pom.xml</code> 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 <code>pom.xml</code>), there are only a few steps to consider:</p>
136+
<ul>
137+
138+
<li>Add a folder called <code>.mvn</code> to the root</li>
139+
<li>Inside the <code>.mvn</code> folder place a file called <code>extensions.xml</code> with the following content:</li>
140+
</ul>
141+
142+
<pre class="prettyprint linenums"><code class="language-xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
143+
&lt;extensions&gt;
144+
&lt;extension&gt;
145+
&lt;groupId&gt;org.eclipse.tycho&lt;/groupId&gt;
146+
&lt;artifactId&gt;tycho-build&lt;/artifactId&gt;
147+
&lt;version&gt;${tycho-version}&lt;/version&gt;
148+
&lt;/extension&gt;
149+
&lt;/extensions&gt;
150+
</code></pre>
151+
<ul>
152+
153+
<li>create a file called <code>maven.config</code> in the <code>.mvn</code> folder with the following content (adjust the Tycho version accordingly to the <a href="https://github.com/eclipse-tycho/tycho/releases" class="externalLink">latest release</a>!):</li>
154+
</ul>
155+
156+
<pre class="prettyprint linenums"><code class="language-properties">-Dtycho-version=4.0.11
157+
</code></pre>
158+
<ul>
159+
160+
<li>You can now run your build with <code>mvn clean verify</code>.</li>
161+
</ul>
162+
<p>You can check more details in a <a href="https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-workspace" class="externalLink">demo project</a>.</p><section><a id="Configure_the_pomless_build"></a>
163+
<h3>Configure the pomless build</h3>
164+
<p>If you want to further configure the build can be done in these ways:</p>
165+
<ol style="list-style-type: decimal;">
166+
167+
<li>You can specify additional global properties in the <code>.mvn/maven.config</code>.</li>
168+
<li>You can define properties per project properties in the <code>bnd.bnd</code> file <code>pom.model.property.&lt;some property&gt;: true</code>, see <a href="https://github.com/eclipse-tycho/tycho/wiki/Tycho-Pomless#overwrite-group-and-artifact-ids" class="externalLink">the wiki</a> for more details.</li>
169+
<li>You can place a <code>pom.xml</code> in your <code>cnf</code> 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.</li>
170+
</ol><section><a id="Create_executable_jar"></a>
171+
<h4>Create executable jar</h4>
172+
<p>Tycho can also create an executable <code>.jar</code> file of your application based on a <code>.bndrun</code> file containing <code>-runbundles</code>, which you can then deploy and start.</p>
173+
<p>Just add the following line to your <code>.mvn/maven.config</code> file or pass it on the maven commandline:</p>
174+
175+
<pre><code class="nohighlight nocode">-Dbndrun.exports=mydemo.app
176+
</code></pre>
177+
<p>This automatically searches all your bundles for a file named <code>mydemo.app.bndrun</code>.</p>
178+
<p>If you have a bundle <code>myappbundle</code> which contains <code>mydemo.app.bndrun</code>, then the build would create an executable jar at the following location:</p>
179+
<p><code>/myappbundle/target/executable/mydemo.app.bndrun.jar</code></p>
180+
<p>Your build output will look like this:</p>
181+
182+
<pre><code class="nohighlight nocode">[INFO] --- tycho-bnd:4.0.11:run (build) @ myappbundle ---
183+
[INFO] Exporting mydemo.app.bndrun ...
184+
[INFO] Exported to .../myappbundle/target/executable/tycho.demo.app.jar
185+
</code></pre></section></section></section><section><a id="Mixed_Builds"></a>
186+
<h2>Mixed Builds</h2>
187+
<p>You can even combine a BND Workspace and PDE bundles in a build, see <a href="https://github.com/eclipse-tycho/tycho/tree/master/demo/bnd-pde-workspace" class="externalLink">demo</a>.</p></section><section><a id="Troubleshooting"></a>
188+
<h2>Troubleshooting</h2>
189+
<p>Note: All properties in <code>.mvn/maven.config</code> can also be supplied via command line, for example to use a different tycho version use the following command line argument:</p>
190+
<p><code>mvn clean install -Dtycho-version=5.0.0</code></p>
191+
<p>This uses the snapshot build which is useful if you build tycho yourself on your local machine and want to test that build.</p><section><a id="polyglot.dump.pom"></a>
192+
<h3>polyglot.dump.pom</h3>
193+
<p>E.g., <code>-Dpolyglot.dump.pom=pom-gen.xml</code> specifies that the generated pom.xml files which tycho polyglot creates is called <code>pom-gen.xml</code>.
194+
This might be needed if you have name clashes with existing files in your build.</p></section><section><a id="tycho.pomless.aggregator.names"></a>
195+
<h3>tycho.pomless.aggregator.names</h3>
196+
<p>The command line argument <code>-Dtycho.pomless.aggregator.names=_dummydisabled_</code> is for handling a rare edge case:
197+
In case you have your bnd workspace in a subfolder named <code>bundles</code>, <code>plugins</code>, <code>tests</code>,<code>features</code>, <code>sites</code>,<code>products</code>, or <code>releng</code> then tycho can have problems.
198+
The reason is that those names are kind of &#x2018;magic&#x2019; names reserved for special usecases.
199+
<code>-Dtycho.pomless.aggregator.names=_dummydisabled_</code> is a workaround to instruct Tycho to ignore those names. You can choose any word like <code>_dummydisabled_</code>, but just make sure you do not have a folder with that name.</p></section></section><section><a id="Links"></a>
200+
<h2>Links</h2>
201+
<ul>
202+
203+
<li><a href="https://bnd.discourse.group/t/building-bnd-workspaces-with-pomless-maven-via-eclipse-tycho/" class="externalLink">Building bnd workspaces with Tycho</a></li>
204+
<li><a href="https://vogella.com/blog/getting-started-with-osgi-declarative-services-2024/" class="externalLink">Getting Started with OSGi Declarative Services</a></li>
205+
</ul></section></section> </main>
206+
</div>
207+
</div>
208+
<hr/>
209+
<footer>
210+
<div class="container-fluid">
211+
<div class="row-fluid">
212+
<p>© 2008–2025
213+
<a href="https://www.eclipse.org/">Eclipse Foundation</a>
214+
</p>
215+
</div>
216+
</div>
217+
</footer>
218+
</body>
219+
</html>

0 commit comments

Comments
 (0)