-buildtool toolspec (EXPERIMENTAL!) | bnd
Description: In many projects, the workspace carries the files to build it with an external tool. Gradle is the most popular but it is also possible to use other tools. An advantage of the workspace is that there are no specific setups required, the workspace contains all the information needed to build. For example, the bnd command line can build it. Tools are generally used to provide additional tasks.

- # -buildtool toolspec (EXPERIMENTAL!)

  In many projects, the workspace carries the files to build it with an external tool. Gradle is the most popular but it is also possible to use other tools. An advantage of the workspace is that there are no specific setups required, the workspace contains all the information needed to build. For example, the bnd command line can build it. Tools are generally used to provide additional tasks.

  The setup files of the build tool therefore tend to be dead weight. Dead weight, that frequently needs overlapping properties with the bnd workspace. Since the tools tend get updated frequently, there are many software engineering advantages in installing the build tool before the project is being built. It also makes it easier to maintain many different workspace, they no longer need to be updated when a new release becomes available. Only the workspace `cnf/build.bnd` needs to be maintained.

  ## Github Actions

  TBD: a github action that will run the bnd command is foreseen

  ## -buildtool instruction

  The `-buildtool` instruction provides the information for the bnd command line tool to install a build tool template from the net. It has the following attributes:

  - `version` – If the `version` is an OSGi version, the key must be a tool name, for example `gradle`. The url used to download the template will then be constructed of a url to `https://github.com/bndtools/workspace.tool.${key}/archive/refs/tags/${version}.zip`

    If it is not a version, it can be:

    - `url` – The key is interpreted as a URL to a template zip file.
    - `file` – The key is interpreted to a file local to the root of the workspace

  - `*` – Any other attributes will be expanded in a properties file

  ## Template

  The template zip must contain a `tool.bnd` file. This file describes how the template should be installed. This file can be anywhere in the zip hierarchy, its parent directory is the root. Only files from the root will be copied.

  The `tool.bnd` file must contain a `-tool` instruction.

      -tool \
          .*;tool.bnd;skip=true, \
          gradle.properties;macro=true,\
          gradlew;exec=true, \
          *

  This is a normal instructions. The keys are matched against the file names relative from the root. The first matching instruction, provides the instructions how to process the file. The following attributes are available.

  - `skip=*` : Skip these files
  - `macro=*` : Process macros. The macros can use the workspace macros and any macros specified in the `tool.bnd` file.
  - `append=*` : Append the extra attributes of the `-buildtool` instruction to the matching files. This will happen in the format of bnd/properties files.
  - `exec=*` : Make the file executable for the owner

  The attributes must have a value, this value is ignored.

  ## Example

  We want to use Gradle 7.3 with bnd 6.1.0. We therefore add the following to the bnd workspace `cnf/build` file:

      -buildtool \
          gradle; version=7.3.0; \
          bnd_version = 6.1.0
          bnd_snapshot=https://bndtools.jfrog.io/bndtools/libs-snapshot-local

  To install the tool, you can execute the bnd command `buildtool`:

      $ bnd buildtool --force

  This will download the sources at `https://github.com/bndtools/workspace.tool.gradle/archive/refs/heads/7.3.0.zip`. The zip file looks something like:

      workspace.tool.gradle/
          tool.bnd
          gradle/
              wrapper/
                  gradle-wrapper.jar
                  gradle-wrapper.properties
          gradle.properties
          settings.gradle
          gradlew.bat
          gradlew
          .gitignore

  The `tool.bnd` looks like:

      -tool \
          .*;tool.bnd;skip=true, \
          gradle.properties;macro=true,\
          gradlew;exec=true, \
          *

  It should be clear that the `gradle.properties` is expanded. After the files are copied, it looks like:

      # Appended by tool manager at 2021-12-02T14:40:55.660843Z
      version = url
      bnd_version = 6.1.0
      bnd_snapshots = https://bndtools.jfrog.io/bndtools/libs-snapshot-local

  After the command has finished, the gradle command can be executed

      $ ./gradlew --parallel clean build