bndtools · Copilot · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
diff --git a/bndtools.core/bndtools.shared.bndrun b/bndtools.core/bndtools.shared.bndrun
@@ -47,6 +47,7 @@
 	bnd.identity;id='org.bndtools.headless.build.manager',\
 	bnd.identity;id='org.bndtools.headless.build.plugin.ant',\
 	bnd.identity;id='org.bndtools.headless.build.plugin.gradle',\
+	bnd.identity;id='org.bndtools.help',\
 	bnd.identity;id='org.bndtools.launch',\
 	bnd.identity;id='org.bndtools.remoteinstall',\
 	bnd.identity;id='org.bndtools.templates.template',\

diff --git a/bndtools.core/bndtools.shared.latest.bndrun b/bndtools.core/bndtools.shared.latest.bndrun
@@ -47,6 +47,7 @@
 	bnd.identity;id='org.bndtools.headless.build.manager',\
 	bnd.identity;id='org.bndtools.headless.build.plugin.ant',\
 	bnd.identity;id='org.bndtools.headless.build.plugin.gradle',\
+	bnd.identity;id='org.bndtools.help',\
 	bnd.identity;id='org.bndtools.launch',\
 	bnd.identity;id='org.bndtools.remoteinstall',\
 	bnd.identity;id='org.bndtools.templates.template',\

diff --git a/org.bndtools.help/.gitignore b/org.bndtools.help/.gitignore
@@ -0,0 +1,3 @@
+bin/
+bin_test/
+generated/
diff --git a/org.bndtools.help/.project b/org.bndtools.help/.project
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.bndtools.help</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>bndtools.core.bndbuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>bndtools.core.bndnature</nature>
+	</natures>
+</projectDescription>
diff --git a/org.bndtools.help/_plugin.xml b/org.bndtools.help/_plugin.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin>
+   <extension point="org.eclipse.help.toc">
+      <toc file="toc.xml" primary="true"/>
+   </extension>
+</plugin>
diff --git a/org.bndtools.help/bnd.bnd b/org.bndtools.help/bnd.bnd
@@ -0,0 +1,12 @@
+# Set javac settings from JDT prefs
+-include: ${workspace}/cnf/includes/bndtools.bnd
+
+Bundle-SymbolicName: ${p};singleton:=true
+Bundle-Name: Bndtools Help Documentation
+
+-resourceonly: true
+
+-includeresource: \
+	{plugin.xml=_plugin.xml},\
+	toc.xml=toc.xml,\
+	docs/=docs/
diff --git a/org.bndtools.help/docs/chapters/110-introduction.html b/org.bndtools.help/docs/chapters/110-introduction.html
@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Introduction</title>
+<link rel="stylesheet" href="../help.css">
+</head>
+<body>
+<h1>Introduction</h1>
+<p>bnd is the Swiss army knife of OSGi, it is used for creating and working with OSGi bundles. 
+Its primary goal is take the pain out of developing bundles.</p>
+<p><strong>bnd consists of two major parts</strong></p>
+<p>Its primary function is generating OSGi meta data by analyzing Java classes. There are plugins for popular tools like Eclipse, Maven and Gradle.</p>
+<p>The other part is a IDE/build tool independent model of a workspace with projects.</p>
+<h2 id="osgi-without-bnd">OSGi without bnd</h2>
+<p>With OSGi you are forced to provide additional metadata in the JAR's manifest to verify the consistency of your "class path". This metadata must be closely aligned with the class files in the bundle and the policies that a company has about versioning. Maintaining this metdata is an error prone chore because many aspects are redundant.</p>
+<h2 id="osgi-with-bnd">OSGi with bnd</h2>
+<p>bnd's raison d'etre is therefore to remove the chores and use the redundancy to create the manifest from the class files instead of maintaining it by hand. The core task is therefore to analyze the class files and find any dependencies. These dependencies are then merged with ''instructions'' supplied by the user. For example, adding a version to all imported packages from a specific library can be specified as:</p>
+<div class="highlight"><pre><span></span><code>Import-Package: com.library.*; version = 1.21
+</code></pre></div>
+
+<p>The OSGi manifest must explicitly mention a package, bnd allows the use of wildcards. bnd contains many more such conveniences. bnd roots are about 10 years old and bnd has therefore a large number of functions that remove such chores. These range from simplifying the use of OSGi Declarative Services, working with Spring and Blueprint, WAR and WAB files, version analysis, project dependencies, and much more.</p>
+<p>Over time bnd started to appear in many different incarnations. It is an an ant task, a command line utility, and a bundle for Eclipse. Other projects have used bndlib to create a maven plugin, bndtools and Sigil both Eclipse IDEs, and others. By keeping the core library small and uncoupled (bnd has no external connections except Java 5), it is easy to embed the functionality in other projects.</p>
+<h2 id="workflow">Workflow</h2>
+<p>Traditionally, JAR files were made with the JDK jar tool, the jar ant task, or the Maven packager. All these tools share the same concept. The developer creates a directory image of the jar by copying files to a directory; this directory is then jarred. This model can be called the ''push'' model. Obviously this method works well.</p>
+<p>bnd works differently, it uses the ''pull'' model. Instructions in the bnd file describe the contents of the desired JAR file without writing this structure to disk. The contents from the output can come from the class path or from anywhere in the file system. For example, the following instruction includes the designated packages in the JAR:</p>
+<p>Private-Package: com.example.*</p>
+<p>bnd can create a JAR from packages the sources, directories or other JAR files. You never have to copy files around, the instructions that Bnd receives are sufficient to retrieve the files from their original location, preprocessing or filtering when required.</p>
+<p>The Jar is constructed from 3 different arguments:</p>
+<div class="highlight"><pre><span></span><code>Export-Package
+Private-Package
+Include-Resource
+</code></pre></div>
+
+<p>Private-Package and Export-Package contain ''instructions''. Instructions are patterns + attributes and directives, looking like normal OSGi attributes and directives. For example:</p>
+<div class="highlight"><pre><span></span><code>Export-Package: com.acme.*;version=1.2
+</code></pre></div>
+
+<p>Each instruction is applied to each package on the classpath in the definition order. That is, if an earlier instruction matches, the later instruction never gets a chance to do its work. If an instruction matches its attributes and properties are applied to the packages. The difference between the Private-Package argument and the Export-Package arguments is that the export version selects the packages for export. If the packages overlap between the two, the export wins.</p>
+<p>An instruction can also be negative when it starts with a '!'. In that case the package is excluded from the selection. For example:</p>
+<div class="highlight"><pre><span></span><code>Export-Package: !com.acme.impl, com.acme.*;version=1.2
+</code></pre></div>
+
+<p>Note that the instructions are applied in order. If the ! instruction was at the end in the previous example, it would not have done its work because the com.acme.* would already have matched.</p>
+<p>The Include-Resource argument can be used to copy resources from the file system in the JAR. This is useful for licenses, images, etc. The instructions in the argument can be a directory, a file, or an inline JAR. The default JAR path is the the root for a directory or the filename for a file. The path can be overridden. Instructions that are enclosed in curly braces, like {license.txt}, are pre-processed, expanding any macros in the file.</p>
+<p>Once the JAR is created, the bnd program analyzes the classes and creates an import list with all the packages that are not contained in the jar but which are referred to. This import list is matched against the Import-Package instructions. Normally, the Import-Package argument is *; all referred packages will be imported. However, sometimes it is necessary to ignore an import or provide attributes on the import statement. For example, make the import optional or discard the import:</p>
+<div class="highlight"><pre><span></span><code>Import-Package: !com.acme.*, *;resolution:=optional
+</code></pre></div>
+
+<p>The arguments to bnd are normal given as a set of properties. Properties that begin with an upper case are copied to the manifest (possibly after processing). Lower case properties are used for macro variables but are not set as headers in the manifest.</p>
+<p>After the JAR is created, the bnd program will verify the result. This will check the resulting manifest in painstaking detail.</p>
+<p>The bnd program works on a higher level then traditional jarring; this might take some getting used to. However, it is much more elegant to think in packages than that it is to think in files. The fact that bnd understand the semantics of a bundle allows it to detect many errors and allows bundles to be created with almost no special information. </p>
+<p>bnd will not create an output file if none of the resources is newer than an existing output file.</p>
+<p>The program is available in several forms: command line, ant task, maven plugin, and an Eclipse plugin.</p>
+</body>
+</html>
diff --git a/org.bndtools.help/docs/chapters/120-install.html b/org.bndtools.help/docs/chapters/120-install.html
@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>How to install bnd</title>
+<link rel="stylesheet" href="../help.css">
+</head>
+<body>
+<h1>How to install bnd</h1>
+<p>bnd is not a single product, it is a library (bndlib) used in many different software build environments. It runs inside Maven, ant, gradle, Eclipse, sbt, and maybe one day in Intellij. To install bnd, you will have to install these tools. </p>
+<div>
+<ul class="property-index">
+
+<li><a href=""></a> </li>
+
+
+</ul>
+</div>
+
+<h2 id="command-line">Command Line</h2>
+<p>That said, there is also a command line version of bnd, providing an easy way to try out its many features. You can install bnd through <a href="https://formulae.brew.sh/formula/bnd">brew</a> on MacOS.</p>
+<p>You can also run bnd command as executable jar, which can be downloaded from <a href="https://bndtools.jfrog.io/bndtools/libs-snapshot/biz/aQute/bnd/biz.aQute.bnd/">JFrog</a>:</p>
+<div class="highlight"><pre><span></span><code><span class="c1"># Install bnd CLI</span>
+curl<span class="w"> </span>-Lk<span class="w"> </span>-o<span class="w"> </span>~/biz.aQute.bnd.jar<span class="w"> </span><span class="se">\</span>
+<span class="w">    </span>https://bndtools.jfrog.io/artifactory/update-latest/biz/aQute/bnd/biz.aQute.bnd/7.2.1/biz.aQute.bnd-7.2.1.jar
+
+<span class="c1"># create alias for easy use via &#39;bnd&#39;</span>
+<span class="nb">alias</span><span class="w"> </span><span class="nv">bnd</span><span class="o">=</span><span class="s1">&#39;java -jar ~/biz.aQute.bnd.jar&#39;</span>
+
+<span class="c1"># display bnd version to verify installation</span>
+bnd<span class="w"> </span>version
+
+<span class="c1"># Run commands</span>
+bnd<span class="w"> </span>&lt;command&gt;
+
+<span class="c1"># Example</span>
+bnd<span class="w"> </span><span class="nb">help</span>
+</code></pre></div>
+
+<h2 id="libraries">Libraries</h2>
+<p>The binaries are available on JFrog:</p>
+<ul>
+<li><a href="https://bndtools.jfrog.io/artifactory/update-latest/biz/aQute/bnd/biz.aQute.bnd/">Releases and Release Candidates (RC)</a></li>
+<li><a href="https://bndtools.jfrog.io/bndtools/libs-snapshot/biz/aQute/bnd/biz.aQute.bnd/">SNAPSHOT releases</a> (e.g. the latest from current master branch)</li>
+</ul>
+<p>If you are a maven user, you can find many versions in central. The coordinates are:</p>
+<div class="highlight"><pre><span></span><code>    &lt;dependency&gt;
+        &lt;groupId&gt;biz.aQute.bnd&lt;/groupId&gt;
+        &lt;artifactId&gt;biz.aQute.bndlib&lt;/artifactId&gt;
+        &lt;version&gt;7.1.0&lt;/version&gt;
+    &lt;/dependency&gt;
+</code></pre></div>
+
+<h2 id="source-code">Source Code</h2>
+<p>bnd is maintained at <a href="https://github.com/bndtools/bnd">github</a>. If you want to change the code, just clone it and modify it. In general we accept pull requests, and often even highly appreciate them.</p>
+<h2 id="manual">Manual</h2>
+<p>The manual is also on <a href="https://github.com/bndtools/bnd/tree/master/docs">github</a>. If you see an improvement, do not hesitate to clone the repo and create a pull request. Improvements are bug corrections but we also like short articles about how to do do something with bnd.</p>
+<h2 id="communication-settings">Communication Settings</h2>
+<p>If you're behind a firewall that requires proxies or you use repositories that require authentication see <a href="/instructions/connection_settings.html">-connection-settings</a>.</p>
+</body>
+</html>