Skip to content

Commit 2173dd0

Browse files
Copilotchrisrueger
Copilot
and
chrisrueger
committed
docs: Fix _plugins markdown files and add content
Add comprehensive documentation content to all docs/_plugins markdown files Used AI to generate content: Session: https://github.com/bndtools/bnd/tasks/12270171-75d5-41b4-9187-f7dc23f750be Signed-off-by: Christoph Rueger <chrisrueger@gmail.com> Co-Authored-By: chrisrueger <188422+chrisrueger@users.noreply.github.com>
1 parent 83a0618 commit 2173dd0

10 files changed

Lines changed: 682 additions & 49 deletions

File tree

‎docs/_plugins/ant.md‎

Lines changed: 68 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,72 @@
11
---
22
parent: Plugins
3-
layout: bnd
4-
---
5-
---
6-
title: Ant Workspace Plugin
73
layout: default
4+
title: Ant Workspace Plugin
85
summary: Ensures that when a new project is created it also has a build.xml for an ant build
9-
---
6+
---
7+
8+
This plugin automatically creates a `build.xml` file in newly created projects. This enables Ant-based builds within a bnd workspace.
9+
10+
## How It Works
11+
12+
When a new project is created in the workspace, the Ant plugin will:
13+
14+
1. Look for a custom template at `cnf/ant/project.xml` in the workspace
15+
2. If found, copy the custom template to the new project as `build.xml`
16+
3. If not found, use a default `build.xml` that imports the workspace build configuration
17+
18+
## Default Template
19+
20+
If no custom template is provided, the plugin uses a default build.xml template that:
21+
22+
```xml
23+
<?xml version='1.0' encoding='UTF-8'?>
24+
<project name='project' default='build'>
25+
<import file='../cnf/build.xml' />
26+
</project>
27+
```
28+
29+
This default template imports the workspace-level Ant configuration from `cnf/build.xml`, allowing individual projects to benefit from centralized build definitions.
30+
31+
## Customization
32+
33+
To use a custom Ant build template:
34+
35+
1. Create a file at `cnf/ant/project.xml` in your workspace
36+
2. This template will be copied to each new project's `build.xml` file
37+
3. You can use project-specific properties and targets as needed
38+
39+
## Usage in build.bnd
40+
41+
The Ant plugin is typically enabled automatically in bnd workspaces. If you need to explicitly enable it or configure it, add the following to your `cnf/build.bnd`:
42+
43+
```properties
44+
-plugin.Ant: \
45+
aQute.bnd.plugin.ant.AntPlugin
46+
```
47+
48+
When you create a new project in the workspace (either through the bnd CLI or IDE), the plugin will automatically generate the `build.xml` file for that project.
49+
50+
## Example Workspace Setup
51+
52+
To use a custom Ant template:
53+
54+
1. Create your custom template at `cnf/ant/project.xml`:
55+
56+
```xml
57+
<?xml version='1.0' encoding='UTF-8'?>
58+
<project name='${project.name}' default='build' basedir='.'>
59+
<property name='src' value='src'/>
60+
<property name='bin' value='bin'/>
61+
<import file='../cnf/build.xml' />
62+
63+
<target name='compile'>
64+
<javac srcdir='${src}' destdir='${bin}'/>
65+
</target>
66+
</project>
67+
```
68+
69+
2. When a new project is created, this template will be used instead of the default.
70+
71+
<hr />
72+
TODO Needs review - AI Generated content

‎docs/_plugins/blueprint.md‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
---
22
parent: Plugins
3-
layout: bnd
4-
---
5-
---
6-
title: Blueprint Plugin
73
layout: default
4+
title: Blueprint Plugin
85
summary: Analyzes JARs for blueprint files so that any class references are added to the imports
96
---

‎docs/_plugins/eclipse.md‎

Lines changed: 88 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,92 @@
11
---
22
parent: Plugins
3-
layout: bnd
4-
---
5-
---
6-
title: Eclipse Plugin
73
layout: default
4+
title: Eclipse Plugin
85
summary: Will add .project and .classpath files to newly created projects
9-
---
6+
---
7+
8+
This plugin automatically creates Eclipse project configuration files when a new project is created in the workspace. These files are essential for importing bnd projects into the Eclipse IDE.
9+
10+
## How It Works
11+
12+
When a new project is created, the Eclipse plugin will:
13+
14+
1. Create a `.project` file (Eclipse project descriptor)
15+
2. Create a `.classpath` file (Eclipse classpath configuration)
16+
17+
If either file already exists, the plugin will not overwrite it.
18+
19+
## Custom Templates
20+
21+
The plugin looks for custom templates in the workspace configuration:
22+
23+
- Custom `.project` template: `cnf/eclipse/project.tmpl`
24+
- Custom `.classpath` template: `cnf/eclipse/classpath.tmpl`
25+
26+
If custom templates exist, they will be used. Otherwise, default templates are used.
27+
28+
## Template Processing
29+
30+
Before writing the template files to disk, they are processed by the project's variable replacer. This allows you to use project variables within your custom templates.
31+
32+
For example, in your template, you can use:
33+
- `${project.name}` - the project name
34+
- `${basedir}` - the base directory
35+
- Any other project properties defined in the project's `bnd.bnd` file
36+
37+
## Initialization
38+
39+
The Eclipse plugin also runs during workspace initialization, ensuring that:
40+
- The workspace `cnf` project has the required `.project` and `.classpath` files
41+
- All existing projects in the workspace get updated Eclipse files if they're missing
42+
43+
## Usage in build.bnd
44+
45+
The Eclipse plugin is typically enabled automatically in bnd workspaces. If you need to explicitly enable it, add the following to your `cnf/build.bnd`:
46+
47+
```properties
48+
-plugin.Eclipse: \
49+
aQute.bnd.plugin.eclipse.EclipsePlugin
50+
```
51+
52+
## Example Workspace Setup
53+
54+
To create custom Eclipse templates:
55+
56+
1. Create a custom `.project` template at `cnf/eclipse/project.tmpl`:
57+
58+
```xml
59+
<?xml version="1.0" encoding="UTF-8"?>
60+
<projectDescription>
61+
<name>${project.name}</name>
62+
<comment>Custom Eclipse project for ${project.name}</comment>
63+
<projects>
64+
</projects>
65+
<buildSpec>
66+
<buildCommand>
67+
<name>org.eclipse.jdt.core.javabuilder</name>
68+
<arguments>
69+
</arguments>
70+
</buildCommand>
71+
</buildSpec>
72+
<natures>
73+
<nature>org.eclipse.jdt.core.javanature</nature>
74+
</natures>
75+
</projectDescription>
76+
```
77+
78+
2. Create a custom `.classpath` template at `cnf/eclipse/classpath.tmpl`:
79+
80+
```xml
81+
<?xml version="1.0" encoding="UTF-8"?>
82+
<classpath>
83+
<classpathentry kind="src" path="src"/>
84+
<classpathentry kind="output" path="bin"/>
85+
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
86+
</classpath>
87+
```
88+
89+
These templates will be used for all new projects created in the workspace.
90+
91+
<hr />
92+
TODO Needs review - AI Generated content

‎docs/_plugins/git.md‎

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,69 @@
11
---
22
parent: Plugins
3-
layout: bnd
4-
---
5-
---
6-
title: Git Workspace Plugin
73
layout: default
4+
title: Git Workspace Plugin
85
summary: Ensures that certain directories have a gitignore
9-
---
6+
---
7+
8+
This plugin automatically creates `.gitignore` files in new projects to ensure that generated build artifacts are not committed to version control.
9+
10+
## How It Works
11+
12+
When a new project is created, the Git plugin will:
13+
14+
1. Create a `.gitignore` file in the project root that excludes common build directories
15+
2. Create `.gitignore` files in source directories to preserve empty directory structure in Git
16+
17+
## Default Ignore Patterns
18+
19+
The plugin automatically creates entries to ignore the following directories (though actual names can be customized via project properties):
20+
21+
- `generated/` - Directory for generated build artifacts (default: from `DEFAULT_PROP_TARGET_DIR`, usually "generated")
22+
- `bin/` - Compiled binary output (default: from `DEFAULT_PROP_BIN_DIR`, usually "bin")
23+
- `bin_test/` - Compiled test output (default: from `DEFAULT_PROP_TESTBIN_DIR`, usually "bin_test")
24+
25+
These patterns prevent accidental commits of compiled code and generated resources.
26+
27+
## Preserving Empty Directories
28+
29+
The plugin also creates minimal `.gitignore` files in source directories (as returned by the project's source path and test source configuration). These empty `.gitignore` files ensure that Git preserves the directory structure even if the directories are initially empty, which is important for bnd project initialization.
30+
31+
## Customization
32+
33+
You can customize the directory names that should be ignored by modifying the project properties:
34+
35+
- `DEFAULT_PROP_TARGET_DIR` - Directory for generated artifacts
36+
- `DEFAULT_PROP_BIN_DIR` - Directory for compiled output
37+
- `DEFAULT_PROP_TESTBIN_DIR` - Directory for compiled test output
38+
39+
These properties are defined in `aQute.bnd.osgi.Constants`.
40+
41+
## Usage in build.bnd
42+
43+
The Git plugin is typically enabled automatically in bnd workspaces. If you need to explicitly enable it, add the following to your `cnf/build.bnd`:
44+
45+
```properties
46+
-plugin.Git: \
47+
aQute.bnd.plugin.git.GitPlugin
48+
```
49+
50+
When you create a new project in the workspace, the plugin will automatically generate appropriate `.gitignore` files.
51+
52+
## Generated .gitignore
53+
54+
The plugin generates a root `.gitignore` in the project with entries similar to:
55+
56+
```
57+
/generated/
58+
/bin/
59+
/bin_test/
60+
```
61+
62+
And also creates empty `.gitignore` files in source directories to preserve the directory structure in Git. This ensures that:
63+
64+
1. Build artifacts are never committed
65+
2. Empty source directories are preserved in the repository
66+
3. New developers have a clean workspace ready for builds
67+
68+
<hr />
69+
TODO Needs review - AI Generated content

‎docs/_plugins/jpa.md‎

Lines changed: 71 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,75 @@
11
---
22
parent: Plugins
3-
layout: bnd
4-
---
5-
---
6-
title: Java Persistence Architecture Plugin
73
layout: default
4+
title: Java Persistence Architecture Plugin
85
summary: Analyses JPA persistence.xml files and adds any discovered class to the imported packages.
9-
---
6+
---
7+
8+
This plugin analyzes Java Persistence Architecture (JPA) configuration files and automatically adds discovered classes to the bundle's imported packages. This ensures that all JPA entities and related classes are properly included in the package imports.
9+
10+
## How It Works
11+
12+
The JPA plugin processes `persistence.xml` files found in the `META-INF` directory of JAR files during the build analysis phase. It:
13+
14+
1. Locates all `persistence.xml` resources in the `META-INF` directory
15+
2. Parses the JPA persistence configuration to identify entity classes and other related classes
16+
3. Automatically adds these classes to the bundle's package imports
17+
18+
## Processing Method
19+
20+
The plugin uses XSLT (XSL Transformations) to parse the XML configuration. This approach:
21+
22+
- Reliably extracts class references from the XML structure
23+
- Handles complex persistence configurations
24+
- Ensures consistent processing across different persistence.xml formats
25+
26+
## Imported Classes
27+
28+
The plugin discovers and imports:
29+
30+
- Entity classes defined in the persistence.xml
31+
- Entity listeners
32+
- Converter classes
33+
- Any other classes referenced in the persistence configuration
34+
35+
This automatic import discovery prevents the need to manually declare package imports for JPA-related classes, reducing configuration errors and improving build reliability.
36+
37+
## Integration
38+
39+
The JPA component integrates with bnd's analyzer plugin architecture, running automatically during the build analysis phase when JPA resources are detected. No additional configuration is required beyond including the plugin in your build configuration.
40+
41+
## Usage in build.bnd
42+
43+
The JPA plugin is typically enabled by default in bnd. If you need to explicitly enable or reference it, add the following to your `cnf/build.bnd`:
44+
45+
```properties
46+
-plugin.JPA: \
47+
aQute.lib.spring.JPAComponent
48+
```
49+
50+
The plugin runs automatically during the build analysis phase when processing bundles that contain JPA persistence.xml files.
51+
52+
## Example JPA Configuration
53+
54+
Suppose you have a bundle with the following `META-INF/persistence.xml`:
55+
56+
```xml
57+
<?xml version="1.0" encoding="UTF-8"?>
58+
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence" version="2.2">
59+
<persistence-unit name="default">
60+
<class>com.example.entity.User</class>
61+
<class>com.example.entity.Order</class>
62+
<class>com.example.listener.AuditListener</class>
63+
</persistence-unit>
64+
</persistence>
65+
```
66+
67+
The JPA plugin will automatically add the following packages to your bundle's imports:
68+
69+
- `com.example.entity`
70+
- `com.example.listener`
71+
72+
This ensures that all entity and listener classes are properly declared as package imports without manual configuration.
73+
74+
<hr />
75+
TODO Needs review - AI Generated content

0 commit comments

Comments
 (0)