diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 8c6eda7..a1faa2a 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -34,6 +34,8 @@ nav: url: "/manual/bndeditor.html" - name: The JAR Viewer url: "/manual/jareditor.html" + - name: Bundle Graph + url: "/manual/bundlegraph.html" - name: Project Templates url: "/manual/templates.html" - title: null diff --git a/_manual/about.md b/_manual/about.md index a0ea992..e0ff425 100644 --- a/_manual/about.md +++ b/_manual/about.md @@ -1,6 +1,7 @@ --- title: Introduction description: An overview of the Bndtools manual +layout: prev-next-collection --- Bndtools is an Eclipse Plugin based on [bnd][1] with the goal to make programming for OSGi easier than in diff --git a/_manual/bndeditor.md b/_manual/bndeditor.md index c9634b6..63a81cd 100644 --- a/_manual/bndeditor.md +++ b/_manual/bndeditor.md @@ -1,6 +1,7 @@ --- title: Bnd Editor description: The Bnd properties editor for bnd files +layout: prev-next-collection --- The bnd editor provides a number of tabs with graphic editors. The following tabs are available: diff --git a/_manual/bundlegraph.md b/_manual/bundlegraph.md new file mode 100644 index 0000000..b7b09a6 --- /dev/null +++ b/_manual/bundlegraph.md @@ -0,0 +1,110 @@ +--- +title: Bundle Graph +description: Visualises the dependency graph of OSGi bundles +layout: prev-next-collection +since: 7.3.0 +--- + + +![Bundle Graph View](/images/bundle-graph.png){: style="width:100%" class="view"} + +The **Bundle Graph** view gives you an interactive, visual picture of how OSGi bundles depend on each other. Instead of reading lists of requirements and capabilities, you can see the relationships between bundles at a glance and quickly understand the impact of adding or removing a bundle from your runtime. + +## Opening the View + +Open the view via **Window › Show View › Other…** and search for *Graph*. Once open, you can populate it by dragging any of the following onto the *Available bundles* list: + +* A project from the Bndtools Explorer / Package Explorer +* A repository (or individual bundles) from the [Repositories View](/manual/repositories-view.html) +* A `.bndrun` file from the workspace + +## Interface Overview + +The view is split into three areas: + +| Area | Purpose | +|---|---| +| **Available bundles** (left panel) | Lists every bundle that was dragged into the view. Use the *Filter* field at the top to narrow down the list by name. | +| **Selected input bundles** (right panel) | The bundles you specifically want to centre the graph on. Move bundles here with the **Add >** button or by double-clicking. | +| **Graph canvas** (bottom) | An interactive diagram showing the bundles and their dependency edges. | + +### Toolbar Buttons + +The toolbar at the top right of the view provides quick access to common actions: + +* **New Graph** – clears the view and starts a fresh graph. +* **Refresh** – re-renders the graph using the current settings. +* **Layout** – switches between available automatic layout algorithms. +* **Minimise / Maximise** – standard Eclipse view controls. + +## Controls + +### Mode + +The **Mode** drop-down (bottom-left of the view) controls which bundles are included in the graph: + +| Mode | Description | +|---|---| +| **Selected + dependencies** | Shows the selected input bundles together with all bundles they (transitively) depend on. | +| **Selected + dependants** | Shows the selected input bundles together with all bundles that (transitively) depend on them. | +| **Selected + both** | Combines both directions – ideal for understanding the full neighbourhood of a bundle. | + +### Auto-render + +When **Auto-render** is checked, the graph is automatically redrawn whenever the selection or settings change. Uncheck it if you want to batch-configure the view before rendering (useful for large graphs), then click **Render** to draw the result. + +### Zoom + +Use the **–** and **+** buttons to zoom the canvas in and out, or choose a fixed percentage from the drop-down between them. The zoom level is shown as a percentage (e.g. *100%*). + +### Dependencies Filter + +The **Dependencies** drop-down lets you choose which kinds of dependency edges to display: + +| Option | Description | +|---|---| +| **All (mandatory + optional)** | Draws both solid (mandatory) and dashed (optional) edges. | +| **Mandatory only** | Hides optional dependency edges to reduce visual noise. | +| **Optional only** | Shows only optional dependency edges. | + +### Graph Interactions + +* **Pan** – click and drag on the canvas background to pan around. +* **Select** – click on a node to highlight it and its direct neighbours. +* **Add / Remove** – use the **Add >**, **< Remove**, **Add deps**, and **Add dependants** buttons to refine which bundles are in the *Selected input bundles* panel without leaving the view. +* **Remove from available** – select one or more bundles in the *Available bundles* list and click **Remove** to remove them from the pool entirely. + +## Reading the Graph + +* Each **node** (rectangle) represents one bundle. Its label shows the *Bundle Symbolic Name* and version. +* **Solid arrows** indicate a *mandatory* dependency (the source bundle requires a package or capability that the target bundle provides and that dependency is not optional). +* **Dashed arrows** indicate an *optional* dependency. +* The **selected input bundle(s)** are highlighted with a distinct border so they are easy to spot even in large graphs. + +## Use Cases + +### Understanding the transitive footprint of a bundle + +Select a bundle in *Available bundles* and click **Add >** to move it to *Selected input bundles*. With mode set to **Selected + dependencies**, the graph shows you every bundle that will be pulled in at runtime — helping you judge whether a dependency is too heavy before you commit to it. + +### Finding out which bundles depend on a given bundle + +Move the bundle of interest to *Selected input bundles* and switch mode to **Selected + dependants**. The graph shows every bundle that (transitively) relies on the chosen bundle, which is invaluable when you plan to update or replace it. + +### Investigating a failed resolution + +After a failed Resolve in the [bnd / bndrun editor](/manual/bndeditor.html#run), drag the `.bndrun` file into the view. The graph lets you trace dependency chains visually and spot which bundle is the root cause of the missing requirement. + +### Comparing dependency chains across two bundles + +Drag both bundles into the view, add them both to *Selected input bundles*, and choose **Selected + both**. The graph highlights shared sub-graphs and makes diverging dependency paths immediately apparent. + +### Reducing optional dependencies + +Set the **Dependencies** filter to **Optional only** to see which optional wiring is active in your runtime. You can then decide which optional bundles are worth including and which can be left out to keep the runtime lean. + +## More Information + +* [Resolving Dependencies](https://bnd.bndtools.org/chapters/250-resolving.html) – background on OSGi requirements and capabilities. +* [Resolution View](/manual/resolution-view.html) – a complementary view that shows requirements and capabilities in list form. +* [Repositories View](/manual/repositories-view.html) – browse and manage the repositories that supply bundles to the graph. diff --git a/_manual/jareditor.md b/_manual/jareditor.md index 8d75ad1..84e5fef 100644 --- a/_manual/jareditor.md +++ b/_manual/jareditor.md @@ -1,6 +1,7 @@ --- title: JAR Viewer description: Shows the content of a JAR file with extra attention for OSGi information +layout: prev-next-collection --- Double clicking a JAR or ZIP file wil open the Bndtools JAR Editor. It will display the JAR file's content with the following tabs: diff --git a/_manual/packageexplorer.md b/_manual/packageexplorer.md index 507fa5d..dcac757 100644 --- a/_manual/packageexplorer.md +++ b/_manual/packageexplorer.md @@ -1,6 +1,7 @@ --- title: Bndtools Explorer description: An overview of the Bndtools Explorer +layout: prev-next-collection --- The Bndtools Package Explorer is an extension of the [Eclipse Package Explorer][1]. The explorer provides an overview of the projects and their contents. It is extended with a search bar for projects and some extra filters. You an make simple searches or use the [bnd globbing](https://bnd.bndtools.org/chapters/820-instructions.html#glob). That is, you can wildcards (`example*bar`) but also multiple searches in one, for example, `foo|bar` to find multiple projects. diff --git a/_manual/repositories-view.md b/_manual/repositories-view.md index 79471be..2f0f8c7 100644 --- a/_manual/repositories-view.md +++ b/_manual/repositories-view.md @@ -2,6 +2,7 @@ title: Repositories View description: Shows the repositories and their contents author: Neil Bartlett +layout: prev-next-collection --- diff --git a/_manual/resolution-view.md b/_manual/resolution-view.md index 06d648f..819123e 100644 --- a/_manual/resolution-view.md +++ b/_manual/resolution-view.md @@ -2,6 +2,7 @@ title: Resolution View description: Provides insight into the requirements and capabilities of the selected bundle since: 7.1.0 +layout: prev-next-collection --- ![](/images/resolution-view.png) diff --git a/_manual/templates-osgi-service.md b/_manual/templates-osgi-service.md index a98b177..17297dc 100644 --- a/_manual/templates-osgi-service.md +++ b/_manual/templates-osgi-service.md @@ -2,6 +2,7 @@ title: Java OSGi Service description: Bndtools Template to create an OSGi service consisting of bundles for api, impl, consumer since: 7.1.0 +layout: prev-next-collection --- ## Java OSGi Service (api, impl, consumer) diff --git a/_manual/templates.md b/_manual/templates.md index feb5120..caae86f 100644 --- a/_manual/templates.md +++ b/_manual/templates.md @@ -1,6 +1,7 @@ --- title: Project Templates description: Get started faster with Bnd Project templates. +layout: prev-next-collection --- The Bndtools supports wizard-based creation of various elements required for OSGi development. There are templates for Bnd-Workspaces, Projects , Components, .bnd and .bndrun files and even for creating services consisting of multiple bundles. diff --git a/images/bundle-graph.png b/images/bundle-graph.png new file mode 100644 index 0000000..de23af8 Binary files /dev/null and b/images/bundle-graph.png differ diff --git a/index.md b/index.md index 7259be1..e167add 100644 --- a/index.md +++ b/index.md @@ -116,6 +116,18 @@
+
+
+

Bundle Graph

+

The Bundle Graph view gives you an interactive, visual picture of how OSGi bundles depend on each other based on their MANIFEST's Imports and Exports. This helps with understanding dependency chains or + debugging a failed resolution.

+
+
+ +
+
+
+

Dynamic Debugging