-library library ( ‘,’ library )* | bnd
Description: A library can provide additional named functionality to a workspace, a project, or a bndrun file. It does this by including a bnd file in the setup that originates from a bundle in the repositories. This included bnd file can refer and use any binary resources in this bundle. Bundles can contain multiple libraries.

- # -library library ( ',' library )*

  A library can provide additional named functionality to a workspace, a project, or a bndrun file. It does this by including a `bnd` file in the setup that originates from a bundle in the repositories. This included bnd file can refer and use any binary resources in this bundle. Bundles can contain multiple libraries.

  The `-library` instruction can apply a library extension from the repositories to a workspace or project. A library extension is a resource that is stored in one of the repositories. When the `-library` instruction is used, the corresponding resource will be expanded in the workspace’s cache and one or more files from this area are read as include files containing bnd properties.

      -library    ::=  library ( ',' library )*
      library     ::=  '-'? NAME ( ';' parameter ) *

  For example, the library `foo` is included in a resource in the repository. We can apply this library in the `build.bnd`, `bnd.bnd`, or `*.bndrun` file.

      -library  foo

  The following `parameter` attributes are architected:

  * `version` – The version range of the capability. If no version is specified, 0 is used. If a version is specified, then this is the lowest acceptable version. The runtime will select the highest matching version. The `version` can also be:

  - `file` – the library name is a path to a directory or JAR file. Since this lacks the ‘where’ of the library in the directory or JAR, this can be set with the `where` attribute in the same clause.
  - `include` – The name of the include file or directory, relative to the root directory of the library. If a directory is targeted, all `*.bnd` files will be read. The default include depends on where the library is included. In:
    - The workspace (`build.bnd`) – `workspace.bnd`
    - A project (`bnd.bnd`) – `project.bnd`
    - A bndrun spec (`*.bndrun`) – `bndrun.bnd`

  Some remarks:

  - If the library name starts with a `-`, there will be no error if the capability cannot be found.
  - You can include a library multiple times with different include files/directories
  - The `${.}` macro refers to the cached root directory of the library.

  ## Repositories & Ordering

  Since libraries are stored in repositories but can also provide new repositories it is important to understand the ordering.

  Only libraries included in the workspace can contribute repositories. The workspace will first read the `cnf/ext` directory bnd files and then `build.bnd`. Any repositories defined in these bnd files can be used for libraries. The workspace will include the libraries based on these repositories. However, after all libraries have been included, all plugins are reset and this will reset the repositories. Any repository plugins defined in a library will then become available.

  Projects and bndrun files can include libraries but they cannot define any new repositories.

  NOTE: what about standalone bndruns?

  ## Creating a library

  A library is stored in a bundle. A bundle can contain multiple libraries that are each described by a capability in the `bnd.library` name space. This capability looks like:

      Provide-Capability: \
          bnd.library; \
              bnd.library     = foo; \
              version         = 1.2.3; \
              path           = lib/foo

  The following attributes are defined for the `bnd.library` capabilities:

  - `bnd.library` – The name of the library. Names should be kept simple but the names are shared between all libraries.
  - `version` – The version of the library.
  - `path` – A path to a directory in the bundle. The contents of this directory are the root of the library. This root is copied to the workspace cache.

  The root of the library should contain the bnd files to be included. The defaults (`workspace.bnd`, `project.bnd`, and `bndrun.bnd`) should only be there if it makes sense to include the library in that type.