Bndtools Repositories

Using and configuring repositories.

Table of Contents

Bndtools uses repositories to supply dependencies to be used at build-time and at runtime. A repository is essentially a collection of bundles, optionally with some kind of index. It may be located anywhere: in the workspace; somewhere else on the local file system; or on a remote server.

Bndtools uses repositories in the following ways:

Repositories are implemented as bnd plug-ins, and can be configured by editing the Plugins sections of the workspace configuration file (Bndtools menu ยป Open main bnd config).

Since repositories are implemented as plug-ins, it is theoretically possible to support almost any kind of repository, by developing a new plug-in type; though of course it is more convenient to use an existing repository plug-in. Bnd and Bndtools support the following repository types out-of-the-box.

1 Indexed Repositories

Bndtools supports a collection of repositories based on an index file that reports the content of the repository along with the capabilities and requirements of each resource listed. There are multiple available formats for the index:

The advantage of using indexed repositories is that they can be used for automatic Resolution in the bndrun editor. There are two basic types of indexed repositories:

1.1 Fixed Index Repositories

This repository can use an index file which is located anywhere, so long as the location can be addressed in the form of a URL. For example the index can be located on the local filesystem and addressed via a file: URL, or it can be located on a remote HTTP(s) server. The locations of the actual resources -- i.e. JAR files -- is specified by URLs embedded in the index file itself, and so they can also be either local or remote. In the case of remote index and/or resources, a local cache is used to avoid repeated downloads and to enable offline builds.

A Fixed Index repository cannot be modified from within bnd or Bndtools.

The following properties are supported:

Name Description Required?
name Name for the repository. No.
locations Comma-separated list of index URLs. NB: surround this value with single-quotes if it contains more than one entry. No. Default: empty
cache Local cache directory for remote resources. No. Default: ${user.home}/.bnd/cache/

It is not necessary to specify the format of the index -- this will be auto-detected so long as the format is one of those supported by the plugin. The index file may optionally be compressed with gzip.

1.2 Local Indexed Repository

This repository maintains a local filesystem directory of bundles. The repository is editable from with bnd/Bndtools and the index file is regenerated automatically when bundles are deployed into it.

The following properties are supported:

Name Description Required?
name Name for the repository. No.
local The local filesystem directory. Yes.
type The type (format) of index to generate. See note 1 below. No. Default: R5
pretty Whether to generate the index in pretty- printed format. See note 2 below. No. Default: false
readonly Whether the repository should be read-only, i.e. disabled for editing from Bndtools. No. Default: false
mode Resolution mode: build, runtime or any. Controls the resolution phase in which this repository may be used. No. Default: any
locations Comma-separated list of additional index URLs. NB: surround this value with single-quotes if it contains more than one entry. No. Default: empty
cache Local cache directory for remote resources. No. Default: ${local}/.cache

Note 1: The index is generated by default in R5 format. To request alternative format(s), specify a list of format names separated by the "|" (pipe) character. For example, to generate both R5 and OBR formats specify type=R5|OBR.

Note 2: R5 indexes are generated by default with no whitespace/indenting and gzipped, and the default index file name is index.xml.gz. Turning on pretty-printing enables indented, uncompressed output into the file index.xml. This setting has no effect on OBR indexes, which are always indented/uncompressed and named repository.xml.

2 File Repository

This type of repository is based on a very simple file system directory structure. It is editable from within Bndtools. NB: it does not support indexing, so repositories of this type cannot participate in resolution of Run Requirements.

The following properties are supported:

Name Description Required?
name Name for the repository. No.
location The local filesystem directory. Yes.
readonly Whether the repository should be read-only, i.e. disabled for editing from Bndtools. No. Default: false

3 Aether (Maven) Repositories

This type of repository uses Eclipse Aether to work with Maven-style repositories. This includes the public Maven Central repository, and also repositories hosted by repository manager products such as Nexus from Sonatype or Artifactory from JFrog.

It can also optionally use an index that is provided by the remote repository manager. This feature requires that indexing is enabled and configured in the manager; for example, the Nexus OBR Plugin can be used for this purpose. When an index is provided, this repository type be used to resolve Run Requirements.

The following properties are supported:

Name Description Required?
name Name for the repository. No. Default: "AetherRepository"
url Main URL of the remote repository. Yes.
username Username for authentication with repository manager. No, but certain operations (e.g. deploy) may fail if the manager requires authentication.
password Password for authentication with repository manager. No.
indexUrl The URL of the index file generated by the repository manager. No. Default: main URL + -obr/.meta/obr.xml.
cache Local cache directory for remote resources. No. Default: ${user.home}/.bnd/cache/

3.1 Limitations

The functionality provided by Aether (and Maven in general) is quite limited. If an index is not available then the following limitations apply:

4 Maven Repositories (Old Style)

NB. The repository types in this section are deprecated. Please use the Aether Repository type instead. The following documentation is retained for reference purposes only.

4.1 Maven Local

This type of repository is used to access bundles in the Maven local repository, usually found in $HOME/.m2/repository. Note that this plug-in accesses the Maven repository directly and does not building with Maven.

Name Description Required?
name Name for the repository. No.
root The location of the Maven repository. No. Default: $HOME/.m2/repository

Note that if you use the Bundle Plugin for Maven then you can also use the OBR repository type, since the Bundle Plugin generates an OBR index file whenever maven install is executed. For example:

aQute.bnd.deployer.repository.FixedIndexedRepo;\
        locations='file:${user.home}/.m2/repository/repository.xml';\
        name='Maven Repo'

4.2 Maven Remote

This type of repository can be used to access bundles in a remote Maven repository, including Maven Central or any Nexus repository. NB: this repository type is not browseable; if you attempt to view the contents of the repository using the Repositories View in Bndtools, it will appear to be empty. However it will be possible to reference JARs from the repository in your -buildpath or -runbundles if the group ID and artefact ID is known.

For example to reference a JAR with group ID org.osgi and artefact ID osgi_R4_core, use the following syntax:

-buildpath: org.osgi+osgi_R4_core
Name Description Required?
repositories Comma-separated list of Maven repository URLs. NB: surround this value with single-quotes if it contains more than one entry. No. Default: empty