Update tutorial for Bndtools 7.1.0+ breaking changes

[Copilot]

The tutorial reflected outdated Bndtools behavior, causing confusion for users on version 7.1.0+. Updated to match current workspace structure, annotations, and UI behavior.

Workspace Structure

• Documented new cnf/ layout: cache/, ext/, build.bnd
• Explained purpose of each directory

Annotations

Updated all code examples from legacy aQute annotations to standard OSGi:

// Old (deprecated)
import aQute.bnd.annotation.component.Component;

// New (standard)
import org.osgi.service.component.annotations.Component;

Bundle Behavior

• Corrected documentation: bundles now include compiled classes by default
• Clarified explicit exports still required for inter-bundle visibility

Template Availability

• Added fallback guidance when Component Development template missing
• Documented «Empty» template as alternative path

Editor & Versioning

• Added instructions for accessing Bundle Editor UI (now requires right-click → "Open With")
• Documented package-info.java (Java 9+) vs packageinfo (pre-Java 9)
• Troubleshooting for OSGi annotation compilation errors

Framework Selection

• Added instructions for configuring Equinox as alternative to Felix
• Example: Add org.eclipse.platform:org.eclipse.osgi:3.23.200 to cnf/ext/central.mvn

Fixes #266

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Tutorial seems out of date</issue_title>
<issue_description>I am trying to go through the tutorial and I have encountered a couple of issues.

I am using:

Eclipse IDE for RCP and RAP Developers (includes Incubating components)

Version: 2025-09 (4.37.0)
Build id: 20250905-1456

With:

  Bndtools	7.1.0.REL-202411251545-g47e504d	bndtools.main.feature.feature.group	Bndtools
  Bndtools m2e	7.1.0.REL-202411251545-g47e504d	bndtools.m2e.feature.feature.group	Bndtools
  Bndtools PDE	7.1.0.REL-202411251545-g47e504d	bndtools.pde.feature.feature.group	Bndtools

The first screenshot of the cnf directory after having created the workspace does not match up:

The templates for a new Bnd OSGi Project are missing quite a few:

This step in the wizard didn't show:

5: In the following page you will see an overview of the folders that will be created for this new project.

It states:

However, the bundle is currently empty, because we have not defined any Java packages to include in the bundle. This is an important difference of Bndtools with respect to other tools: bundles are always empty until we explicitly add some content. You can verify this by double-clicking the bundle file and viewing its contents: it will only have a META-INF/MANIFEST.MF entry.

But that does not match what I see. For me it includes the Greeting.class even with an empty bnd.bnd file:

When I double click the bnd.bnd file it opens the source. I have to right-click and select Bnd Bundle Editor to get the editor UI. Not sure why, I'm sure this never used to be the case but I have updated Eclipse a couple of times recently.

Exporting the org.example.api package will generate the package-info.java file (different naming to the tutorial which calls it packageinfo.java which I guess is just because I chose Java 21).

The package-info.java will contain errors:

I'm guessing this is because the tutorial told us to create an empty project instead of an API project. OSGi R8 is present in the cnf/ext/build.mvn file though.

I haven't gotten any further because the create implementation project step says to choose the template Component Development which doesn't exist.</issue_description>

<agent_instructions>The issue #266 mentions that the tutorial in /tutorial.md is out of date. Please try to improve the tutorial with the information given in the comments. Also try to investigate in changes in the master branch of bnd (https://github.com/bndtools/bnd). Especially look at the upcoming bnd 7.2.0 release (see upcoming release notes https://github.com/bndtools/bnd/wiki/Changes-in-7.2.0 ). For this also look at the bnd docs (https://github.com/bndtools/bnd/tree/master/docs and https://bnd.bndtools.org/) which are based on bnd's master branch and might contain clues.

Create a PR with the proposed changes.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@chrisrueger Thanks @steinybot for the report. A PR for the docs improvements is highly appreciated. I guess you are referring to this tutorial https://bndtools.org/tutorial.html ?

Regarding the other problem:

I haven't figured out how to get the launch configuration to work.

The only execution env I can see is felix:

Can you try adding Equinox Framework e.g.

org.eclipse.platform:org.eclipse.osgi:3.23.200 (maven central)

to one of your repositories? (e.g. in your cnf/ext/central.mvn or wherever your repo is defined)

It should then show up in the OSGi Framework dropdown.</comment_new>

• Fixes Tutorial seems out of date #266

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.