|
1 | 1 | --- |
2 | | -title: Bndtools Concepts |
3 | | -description: Introduction to the Basics |
4 | | -author: Neil Bartlett |
| 2 | +title: Bndtools Workspace Concepts |
| 3 | +description: Introduction to the basic bnd workspace model |
5 | 4 | --- |
6 | 5 |
|
7 | | -Repositories |
8 | | -============ |
| 6 | +Bndtools is an Eclipse plugin that used [bnd](bnd.html) under the hood to create [OSGi](https://www.osgi.org/) _bundles_. A bundle is a Java ARchive (JAR) that has a manifest with the OSGi metadata. Bndtools provides an IDE for developing these bundles with the least amount of work and maximum feedback. |
9 | 7 |
|
10 | | -Bndtools uses *repositories* to supply dependencies to be used at build-time and at runtime. See the [separate section on repositories](repositories.html). |
| 8 | +## Workflow |
11 | 9 |
|
12 | | -Plug-ins and Plug-in Paths |
13 | | -========================== |
| 10 | +Although Bndtools is flexible enough to support many different workflows it helps to understand the workflow we had in mind when we worked on bnd and Bndtools. The following picture outlines the archetypical parts: |
14 | 11 |
|
15 | | -Repositories and other kinds of plug-in can be added to the workspace by editing the `-plugin` entry in `cnf/build.bnd`. Plug-ins are specified by their class name, with additional configuration properties passed as follows: |
| 12 | + |
16 | 13 |
|
17 | | - -plugin: <classname>;<property>=<value>;<property>=<value>,\ |
18 | | - <classname>;<property>=<value>;<property>=<value> |
| 14 | +A core concept in OSGi is to create _components_ that only use (service) APIs. I.e. it is recommended to restrict the compilation (or build path) to dependencies that only carry an API, not an implementation. Since APIs are not sufficient to run the component, it is necessary to provide an _assembly_ that contains the components and dependencies that can provide the necessary implementations. In Bndtools this is a `bndrun` file although the `bnd` file can also act as such. |
19 | 15 |
|
20 | | -For example: |
| 16 | +Bndtools is accompanied with a Gradle build that uses the same bnd that runs inside Eclipse for continuous integration. |
21 | 17 |
|
22 | | - -plugin: org.example.Plugin1; \ |
23 | | - name=First; \ |
24 | | - location=http://www.example.com/, \ |
25 | | - org.example.Plugin2; \ |
26 | | - name=Second; \ |
27 | | - licence=ApacheV2 |
| 18 | +An assembly is then tested and when accepted deployed. Bndtools can take a `bndrun` file and turn it into an _executable JAR_. |
28 | 19 |
|
29 | | -Note that if a property value contains a comma then the whole value must be enclosed in single or double quotes, to prevent the comma being interpreted as a delimiter in the plug-in list. |
| 20 | +Since development is a continuous process, Bndtools also support _baselining_, a technique based on semantic versioning to get warned when changes in API are made that are not backward compatible. |
30 | 21 |
|
31 | | -If the plug-in class is not built into bnd/Bndtools then we must use the `path:` directive to specify the classpath for the plug-in, e.g.: |
| 22 | +## bnd |
32 | 23 |
|
33 | | - -plugin: org.example.MyPlugin; \ |
34 | | - path:="plugins/myplugin-1.0.jar,/usr/lib/foo.jar" |
| 24 | +Bndtools is a user friendly driver of the [bnd](http://bnd.bndtools.org) library. bnd provides an abstract workspace/project model that Bndtools uses to tell Eclipse what to build. Since bnd has been growing up in parallel with OSGi itself it understands OSGi extremely well. It is an invaluable assistent for OSGi developers. |
35 | 25 |
|
36 | | -Bundles and Bnd Files |
37 | | -===================== |
| 26 | +A unique aspect of bnd is that it is an _abstract_ build model. Because it is abstract, projects developed with Bndtools can also be built with Gradle without any extra effort. This is the perfect combination of a user friendly IDE and a solid continuous integration tool. |
38 | 27 |
|
39 | | -Bndtools follows the "generated manifest" approach to building OSGi bundles; this is in contrast to the "manifest first" approach used by some other tools. See the OSGi Community Wiki page on [Tooling Approaches](http://wiki.osgi.org/wiki/Tooling_Approaches) for an explanation of the difference between these approaches. |
| 28 | +### Workspace/Repositories/Project Model |
40 | 29 |
|
41 | | -Bndtools projects are based on standard Eclipse Java projects. After the Java code is compiled into classfiles, the Bndtools builder takes over and produces one or more OSGi bundles. It uses `.bnd` files to control the contents of the OSGi bundles that it generates. |
| 30 | +Bndtools uses the bnd _workspace_ model. A workspace is a directory on the file system that has the file `cnf/build.bnd`. All configuration of Bndtools is done through `bnd` files. A bnd file is an UTF-8 file using the venerable properties format. The `build.bnd` file is the _shared_ configuration. Any property defined in this file is shared between all projects. |
42 | 31 |
|
43 | | -The Project Settings File: bnd.bnd |
44 | | ----------------------------------- |
| 32 | +Other directories in the workspace directory are project directories if they contain a `bnd.bnd` file. In that case, the OSGi Bundle Symbolic Name is the name of that directory. |
45 | 33 |
|
46 | | -A Bndtools project always contains a file named `bnd.bnd`. This file contains project settings such as the Build Path, which defines the libraries that are visible to the project at build time: |
| 34 | +Any properties defined in `build.bnd` can be overridden in the per project `bnd.bnd` file. Bndtools contains an easy to use editor that provides syntax highlighting for these bnd files. |
47 | 35 |
|
48 | | - |
| 36 | +_All_ information to build a workspace (that is, all projects in the workspace) is stored in these `bnd` files. No other information influences the result. |
49 | 37 |
|
50 | | -Single-Bundle and Multiple-Bundle Projects |
51 | | ------------------------------------------- |
| 38 | +The following picture shows the inheritance structure of the different bndand bndrun files. |
52 | 39 |
|
53 | | -Bndtools projects either generate a single bundle or multiple bundles. In the single-bundle mode (which is the default) all the instructions defining that bundle are listed in the `bnd.bnd` file: in other words, the `bnd.bnd` file controls both the project settings *and* the instructions for generating a single bundle. |
| 40 | + |
54 | 41 |
|
55 | | -In the multiple-bundle mode, the `bnd.bnd` still contains project settings such as Build Path. However the instructions controlling the output of bundles is separated into several other `.bnd` files. These are known as "sub-bundles", and turning on multiple-bundles mode is known as enabling "sub-bundles": |
| 42 | +### Repositories |
56 | 43 |
|
57 | | - |
| 44 | +External dependencies (e.g. Maven Central) are handled through _repositories_. Repositories are setup in the `build.bnd` file as _plugins_. bnd supports an extensive range of repositories: |
58 | 45 |
|
59 | | -When sub-bundles mode is turned on, one bundle is generated for *each* other `.bnd` file in the top-level of the Bndtools project. Those `.bnd` files contain only the instructions required to define the contents of a bundle such as Private Packages, Export Packages, etc. |
| 46 | +* Workspace |
| 47 | +* OSGi Repositories |
| 48 | +* Local file system based |
| 49 | +* Eclipse P2 |
| 50 | +* Maven |
| 51 | + |
| 52 | +Repository plugins map the external world into a bundle world. A general concept in bnd is that the repositories define an exact set of dependencies and not support transitive dependencies. The reason that the for many very useful transitive dependencies are not supported is that they tend to make horrible OSGi systems. |
60 | 53 |
|
61 | | -Derived Bundle Symbolic Names |
62 | | ------------------------------ |
| 54 | +Each project can depend on the bundles that are coming from the repositories. These bundles are explicitly listed in the `bnd.bnd` projects files. |
63 | 55 |
|
64 | | -The bundle symbolic name (BSN) of a generated bundle is derived from the project name and -- if sub-bundles is enabled -- the name of the sub-bundle file. |
| 56 | + |
65 | 57 |
|
66 | | -In single-bundle mode, the BSN of the bundle will be equal to the name of the Bndtools project. So if the project name is `org.example` then the BSN of the bundle will be `org.example`: |
67 | 58 |
|
68 | | - Bundle-SymbolicName: org.example |
| 59 | +### Builders |
69 | 60 |
|
70 | | -In sub-bundles mode, the BSN of each bundle is equal the name of the project plus the name of the sub-bundle file excluding its `.bnd` extension. So if the project name is `org.example` and there is a sub-bundle file named `foo.bnd` the BSN will be `org.example.foo`: |
| 61 | +Bndtools will continuously build the bundles. Any change in the IDE, either a Java source file or a bnd file will automatically trigger a new build which will result in a new up to date JAR. |
| 62 | + |
| 63 | +In OSGi, a bundle's _manifest_ must list what packages are required in runtime. bnd calculates this manifest by analyzing the bytecodes and finding out what dependencies are used. It uses the metadata available in the dependencies to handle versioning so that the developer can mostly ignore these details. |
| 64 | + |
| 65 | +Any other metadata is also provided indirectly or explicitly in a bnd file. Each `bnd.bnd` file can set manifest headers for example. |
| 66 | + |
| 67 | +### Run Files |
| 68 | + |
| 69 | +Before you can run an OSGi framework it is necessary to create an _assembly_ of bundles to run. Bndtools provide unique support for this with the _bndrun_ files. Instead of listing bundles, the bndrun file contains _initial requirements_. The Bndtools editor makes it possible to use drag and drop to fill this list from the repositories and the workspace's projects. This support is based on the OSGi _resource_ model. Bndtools provides a resolver that then takes the initial requirements together with the framework and repositories and calculates a closure of bundles that can run together. This feature has no counterpart in any other tool. |
| 70 | + |
| 71 | +### Debugging |
| 72 | + |
| 73 | +Bndtools integrates the bnd launcher that is parameterized from the bndrun file. After running the resolver, the bndrun file editor shows a `Run` or `Debug` button that will launch the assembly. This launcher is completely integrated with the Eclipse debugging tools. |
| 74 | + |
| 75 | +### Testing |
| 76 | + |
| 77 | +Normal JUnit testing is clearly fully supported with Bndtools and will work as expected. However, Bndtools also supports _OSGi integration testing_. In this case, the `bnd.bnd` file defines a set of bundles (which can be assembled with the resolver) that provide the runtime for the test. Except for the menu entry, this kind of integration testing is then identical to normal JUnit testing. That is, the developer can select a test class or test method and execute the test while the results are displayed in the JUnit view. |
| 78 | + |
| 79 | +### Continuous Integration |
| 80 | + |
| 81 | +Although developers spend the far majority of their time in an IDE, the most important part of a professional development takes place in the _continuous integration_. Only when a workspace is build from scratch is it possible to verify that a build is _repeatable_. That is, a product that is generated on a developer's desktop cannot be trusted. |
| 82 | + |
| 83 | +For this reason, workspaces generally integrate a gradle build based on bnd. By using the same underlying abstract build model, it is virtually guaranteed that when Eclipse indicates that the workspace builds fine, it will also build on a remote server. |
| 84 | + |
| 85 | +### Releasing |
| 86 | + |
| 87 | +Bndtools provides an integrated release model. Although special tools are provided to release from the IDE it is highly recommended to only release from the continuous integration. bnd can release to most of its supported repositories. Maven is extensively supported, including signing. |
| 88 | + |
| 89 | +### Deploying |
| 90 | + |
| 91 | +Bndtools can export a bndrun file to an executable JAR. This is a JAR that can be executed in any Java VM. The JAR contains the framework and all required bundles. When it runs with the venerable `java -jar x.jar` command it will unpack itself and launch a framework. The continuous integration can build this executable JAR. |
| 92 | + |
| 93 | +### Baselining |
| 94 | + |
| 95 | +Once API is released to external repositories, Bndtools will track the version numbers and the binary compatibility of newer versions with the older versions. If the developer makes a change that is not compatible with the semantics of the versions then it will place an error on the place where the version is maintained and the offending code. For example, adding a method to an interface is not backward compatible and requires a n update to the version. In this case the new method will be marked as error until the corresponding version is updated. |
71 | 96 |
|
72 | | - Bundle-SymbolicName: org.example.foo |
73 | 97 |
|
74 | | -You should not attempt to override the generated BSN, e.g. by including a `Bundle-SymbolicName` head in the `.bnd` file, because Bndtools uses the association between project names and bundle names in order to find bundles when projects depend on them. |
75 | 98 |
|
0 commit comments