diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 1f7d8a9..49adf5f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -14,11 +14,11 @@ jobs: runs-on: ubuntu-latest steps: - name: Git Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Gradle Wrapper Validation - uses: gradle/wrapper-validation-action@v1 + uses: gradle/actions/wrapper-validation@v4 - name: Set up Java - uses: actions/setup-java@v2 + uses: actions/setup-java@v4 with: distribution: 'temurin' java-version: 17 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..00b7084 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,242 @@ +# AGENTS.md — AI Agent Guide for bndtools/workspace + +This file helps AI coding agents understand the structure, conventions, and workflows +of this repository so they can contribute effectively and accurately. + +--- + +## What This Repository Is + +This is the **official bnd/bndtools workspace template** for the [bnd tool](https://github.com/bndtools/bnd). +It serves as a starting point for OSGi bundle development using bnd and Gradle. + +When a developer creates a new bnd workspace (via Bndtools IDE, the bnd CLI, or manually), +this template provides the baseline structure including: +- Shared workspace build configuration (`cnf/build.bnd`) +- Pre-configured OSGi repositories (OSGi R7 API, enRoute, Maven Central) +- Bndtools project templates (`cnf/templates/`) +- Gradle build integration + +**Reference docs:** [https://bnd.bndtools.org](https://bnd.bndtools.org) + +--- + +## Repository Layout + +``` +workspace/ +├── .github/ +│ └── workflows/ +│ └── build.yml # CI: builds with Gradle on Ubuntu/Java 17 +├── cnf/ # Configuration directory (makes this a bnd workspace) +│ ├── build.bnd # Workspace-wide build properties and repository plugins +│ ├── central.maven # Maven Central repository index (GAV coordinates) +│ ├── local/ # LocalIndexedRepo for locally built bundles +│ ├── release/ # LocalIndexedRepo for released bundles +│ └── templates/ # Bndtools project/workspace templates +│ ├── index.xml # OSGi repository index for the templates bundle +│ ├── index.xml.sha # SHA-256 of index.xml (used by bnd for integrity checks) +│ └── org.bndtools.templates.osgi/ +│ └── org.bndtools.templates.osgi-.jar +├── gradle/ # Gradle wrapper files +├── build.gradle # Workspace-level Gradle build (customization point) +├── gradle.properties # bnd version and snapshot URL +├── gradlew / gradlew.bat # Gradle wrapper scripts +└── settings.gradle # Gradle settings with bnd workspace plugin +``` + +### The `cnf` Directory + +The `cnf` directory is the _magic_ directory that identifies a bnd workspace (analogous +to `.git` for Git). It must always contain `build.bnd`. + +**`cnf/build.bnd`** — Workspace-wide properties loaded by every project. Contains: +- Repository plugin declarations (`-plugin.*`) +- Shared headers (`Bundle-Vendor`, `Bundle-Copyright`, etc.) +- Global build settings (`-contract`, Git metadata macros) + +**`cnf/ext/`** — Extension files (`.bnd`) loaded alphabetically before `build.bnd`. +Used for plugin configurations. Files here should not be edited by end users; they +may be overridden by upstream updates. + +--- + +## Key Dependencies and Versions + +| Component | Version | Notes | +|---|---|---| +| bnd / Bndtools | 7.3.0 | Set in `gradle.properties` as `bnd_version` | +| Gradle plugin | `biz.aQute.bnd.workspace` | Applied in `settings.gradle` | +| OSGi R7 API (`org.osgi.enroute:osgi-api`) | 7.0.0 | OSGi Release 7 specification APIs | +| OSGi enRoute enterprise API | 7.0.0 | Enterprise Java APIs (JPA, JAX-RS, etc.) | +| OSGi R7 implementations (`impl-index`) | 7.0.0 | Reference implementations | +| Templates bundle | 7.3.0.202606021345 | `org.bndtools.templates.osgi` from Maven Central | + +**Latest stable bnd release:** 7.3.0 (released 2026-06-02) +Check [https://github.com/bndtools/bnd/releases](https://github.com/bndtools/bnd/releases) for updates. + +--- + +## OSGi Semantic Versioning + +This project follows **OSGi semantic versioning** which uses `MAJOR.MINOR.MICRO.QUALIFIER`: +- `MAJOR` — breaking API change +- `MINOR` — backward-compatible new functionality +- `MICRO` — backward-compatible bug fixes +- `QUALIFIER` — build metadata (e.g. timestamp `202606021345`, or `SNAPSHOT`) + +This is compatible with [semver.org](https://semver.org) with the qualifier extension. +Timestamp qualifiers (e.g., `7.0.0.201810191116`) are valid but opaque — prefer clean +`MAJOR.MINOR.MICRO` versions (e.g., `7.3.0`) when possible. + +--- + +## Build System + +### Prerequisites +- Java 17 (JDK) +- Internet access to Maven Central and OSGi repositories + +### Building + +```bash +./gradlew build +``` + +The Gradle build uses the `biz.aQute.bnd.workspace` plugin which delegates project +discovery and build orchestration to bndlib. + +### CI + +The `.github/workflows/build.yml` runs `./gradlew build` on every push and pull request +using Ubuntu + Java 17 (Temurin distribution). + +--- + +## Templates System + +The `cnf/templates/` directory contains an OSGi repository with Bndtools project templates. +These templates appear in Bndtools IDE when creating new projects. + +### Template Bundle: `org.bndtools.templates.osgi` + +- Source: Maven Central (`org.bndtools:org.bndtools.templates.osgi`) +- Current version: **7.3.0** (OSGi bundle version: `7.3.0.202606021345`) +- JAR location: `cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-7.3.0.jar` + +#### Available Templates (v7.3.0) + +**OSGi Standard Templates** (category `bbb/OSGi Standard Templates`): +| Template | Type | Description | +|---|---|---| +| Component Development | project | OSGi Declarative Services component | +| API Project | project | OSGi API bundle skeleton | +| Integration Testing | project | OSGi integration test project | +| Minimal Workspace | workspace | Bare-minimum bnd workspace | +| Felix 4+ | bndrun | Apache Felix launcher configuration | + +**OSGi enRoute** (category `ccc/OSGi enRoute`): +| Template | Type | Description | +|---|---|---| +| OSGi enRoute Base Launcher | bndrun | enRoute base launch configuration | +| OSGi enRoute Debug Launcher | bndrun | enRoute debug launch configuration | + +### Updating the Templates Bundle + +When a new version of `org.bndtools.templates.osgi` is released on Maven Central: + +1. Download the new JAR from `https://repo.maven.apache.org/maven2/org/bndtools/org.bndtools.templates.osgi//` +2. Place the JAR in `cnf/templates/org.bndtools.templates.osgi/` +3. Remove the old JAR from the same directory +4. Regenerate `cnf/templates/index.xml` using bnd CLI: + ```bash + java -jar biz.aQute.bnd.jar index --name "Templates" --directory cnf/templates/ \ + cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-.jar + ``` +5. Update the `url` attribute in the generated `index.xml` to include the subdirectory prefix: + `org.bndtools.templates.osgi/org.bndtools.templates.osgi-.jar` +6. Regenerate `cnf/templates/index.xml.sha`: + ```bash + sha256sum cnf/templates/index.xml | awk '{print $1}' > cnf/templates/index.xml.sha + ``` + +### The `index.xml` and `index.xml.sha` Files + +- **`index.xml`** — OSGi Repository XML index (namespace `http://www.osgi.org/xmlns/repository/v1.0.0`). + Declares all capabilities of the templates bundle so bndlib/Bndtools can resolve and display them. +- **`index.xml.sha`** — SHA-256 hex digest of `index.xml`. Bnd uses this for integrity verification. + Must be kept in sync with `index.xml` whenever it changes. + +--- + +## Repository Plugins (cnf/build.bnd) + +The workspace configures the following repositories via `-plugin.*` properties: + +| Plugin ID | Name | Type | Purpose | +|---|---|---|---| +| `-plugin.1.R7.API` | OSGi R7 API | BndPomRepository | OSGi R7 specification APIs from enRoute | +| `-plugin.2.Enterprise.API` | Enterprise Java APIs | BndPomRepository | JPA, JAX-RS, Servlet APIs | +| `-plugin.3.R7.Impl` | OSGi R7 Reference Implementations | BndPomRepository | Felix, Aries, etc. | +| `-plugin.4.Test` | Testing Bundles | BndPomRepository | JUnit OSGi bundles | +| `-plugin.5.Debug` | Debug Bundles | BndPomRepository | Gogo shell, Web Console | +| `-plugin.6.Central` | Maven Central | MavenBndRepository | General Maven artifacts | +| `-plugin.7.Local` | Local | LocalIndexedRepo | Locally built artifacts | +| `-plugin.8.Templates` | Templates | LocalIndexedRepo | Project templates | +| `-plugin.9.Release` | Release | LocalIndexedRepo | Released workspace bundles | + +All BndPomRepository plugins use `https://repo.maven.apache.org/maven2/` as the release URL. + +--- + +## Common Maintenance Tasks for Agents + +### Updating the bnd version + +1. Edit `gradle.properties` → change `bnd_version` +2. Run `./gradlew build` to verify + +### Updating GitHub Actions + +Action versions in `.github/workflows/build.yml` should be kept current: +- `actions/checkout` → use latest v4.x +- `actions/setup-java` → use latest v4.x +- `gradle/actions/wrapper-validation` → use latest v4.x + +### Updating OSGi enRoute repository versions + +The `cnf/build.bnd` pins OSGi enRoute BOMs at version `7.0.0` (OSGi R7, the latest major release). +Check [https://search.maven.org/search?q=g:org.osgi.enroute](https://search.maven.org/search?q=g:org.osgi.enroute) for newer releases. + +### Adding a project to the workspace + +In a bnd workspace, each top-level directory (other than `cnf`) is a project. +To add one manually, create `/bnd.bnd`. The project name should match +the `Bundle-SymbolicName` of the bundle it produces. + +--- + +## Bnd Documentation References + +| Topic | URL | +|---|---| +| Introduction | https://bnd.bndtools.org/chapters/110-introduction.html | +| Workspace & Projects tour | https://bnd.bndtools.org/chapters/123-tour-workspace.html | +| Build system | https://bnd.bndtools.org/chapters/150-build.html | +| OSGi versioning | https://bnd.bndtools.org/chapters/170-versioning.html | +| Baselining | https://bnd.bndtools.org/chapters/180-baselining.html | +| Repositories | https://bnd.bndtools.org/chapters/150-build.html | +| bnd plugins | https://bnd.bndtools.org/plugins/ | +| Template fragments | https://bnd.bndtools.org/chapters/620-template-fragments.html | + +--- + +## Security and Quality Notes + +- **No credentials or secrets** should ever be committed to this workspace template. + All repository URLs are public read-only endpoints. +- **Dependency versions** are pinned to stable releases. Snapshot dependencies + (`-SNAPSHOT`) should only be used during active development against unreleased bnd. +- **SHA checksums** (`index.xml.sha`, `osgi.content` in `index.xml`) must always be + updated when the files they reference change. +- The `cnf/cache/` directory is gitignored and must never be committed. diff --git a/cnf/templates/index.xml b/cnf/templates/index.xml index 4c76493..80568ec 100644 --- a/cnf/templates/index.xml +++ b/cnf/templates/index.xml @@ -1,96 +1,88 @@ - + + + + - + - + - + - + - - + + + - - - + + - + - - + - - - - - - - - - - - - - - - + + + + + - - - - - - - + + + + + + + - - - + + + - - - + + + - - - - + + + + + + - - - - + - + + diff --git a/cnf/templates/index.xml.sha b/cnf/templates/index.xml.sha index c363d86..d8aa9d7 100644 --- a/cnf/templates/index.xml.sha +++ b/cnf/templates/index.xml.sha @@ -1 +1 @@ -61275256eb23a6404cfbbb35fee55ecba044ba36319684fd106af299857d019e \ No newline at end of file +98c02cf5052100ee6fbf4afce895a27c10189cabf37d6404020abadf7c7ac05d diff --git a/cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-7.0.0.jar b/cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-7.0.0.jar deleted file mode 100644 index 792c596..0000000 Binary files a/cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-7.0.0.jar and /dev/null differ diff --git a/cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-7.3.0.jar b/cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-7.3.0.jar new file mode 100644 index 0000000..511061c Binary files /dev/null and b/cnf/templates/org.bndtools.templates.osgi/org.bndtools.templates.osgi-7.3.0.jar differ diff --git a/gradle.properties b/gradle.properties index a384f21..854ee98 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,2 +1,2 @@ -bnd_version=7.0.0-SNAPSHOT +bnd_version=7.3.0 bnd_snapshots=https://bndtools.jfrog.io/bndtools/libs-snapshot-local