diff --git a/docs/_chapters/150-build.md b/docs/_chapters/150-build.md index 9e8731c7b4..078fa99f9f 100644 --- a/docs/_chapters/150-build.md +++ b/docs/_chapters/150-build.md @@ -22,7 +22,7 @@ of the workspace. They can have the following extensions: * `.pmvn` – An index file for a [Maven Bnd Repository](plugins/maven.html). The first lines can contain properties for this plugin in the format of `# key = value`, e.g. `# name = OSGi R8`. * `.pobr` – An OSGi Repository file in XML. -The `ext` directory is a convenient way to add add reusable components. See [template fragments](620-template-fragments.html] how they can be used to manage workspaces. When files change in this directory the workspace will be reloaded. +The `ext` directory is a convenient way to add add reusable components. See [template fragments](620-template-fragments.html) how they can be used to manage workspaces. When files change in this directory the workspace will be reloaded. To cache some intermediate files, bndlib will create a `cnf/cache/` directory, this file should not be under source control. E.g. in Git it should be defined in the `.gitignore` file. diff --git a/docs/_chapters/600-developer.md b/docs/_chapters/600-developer.md index 4829e1bc00..6634601456 100644 --- a/docs/_chapters/600-developer.md +++ b/docs/_chapters/600-developer.md @@ -4,7 +4,6 @@ layout: default --- - ## API It is quite easy to use bnd from Java, you only need to include biz.aQute.bndlib on your class path. This chapter shows you some samples of how to use bndlib. @@ -66,3 +65,9 @@ If no such resource is found, bnd will look in the -make instruction. This instr The first name part of the clause is matched against the unfound resource. All plugins are called sequentially until one returns non-null. The arguments on the -make clause are given as parameters to the make plugin. Normally all Make Plugins should verify the type field. bnd has a bnd and a copy Make Plugin. + + +## Workspace Template Fragments + +If, for example, you created a library for bnd and want to make it easy for the user to setup his functionality have a look at [template fragments](620-template-fragments.html). + diff --git a/docs/_chapters/620-template-fragments.md b/docs/_chapters/620-template-fragments.md index 766335bc89..577a881ca8 100644 --- a/docs/_chapters/620-template-fragments.md +++ b/docs/_chapters/620-template-fragments.md @@ -5,25 +5,33 @@ layout: default A good workspace setup makes all the difference in the development cycle. Since a workspace can contain many projects, creating new workspaces is relatively rare. However, a workspace tends -to consist of many aspects. There is the gradle setup, the OSGi release, maybe the maven -layout etc. Initially, we attempted to use a single GitHub repository as a template for new workspaces, but this approach quickly became complex. -Instead, we developed _fragment_ templates. Fragments model one aspect of a workspace and are maintained in Github -repositories. One repository can hold many fragments. +to consist of many aspects. There is the _gradle setup_, the _OSGi release_, maybe the _maven +layout_ etc. Initially, we attempted to use a single GitHub repository as a template for new workspaces, but this approach quickly became complex. For example, if someone created a [library][3] for bnd, to make it easy for the user to setup his functionality, the author of the library had to maintain a full workspace with gradle, etc. This put the burden on chasing the OSGi release, the gradle releases, on the people that were willing to spread the gospel around OSGi/bndtools. -The workspace is already prepared for this model of fragments. The [merged instructions][2] mean that + +## Template Fragments + +Instead, we developed _fragment_ templates. A fragment models one aspect of a workspace and is maintained in Github repository, but one repository can hold many fragments. Multiple template fragments can be combined by the end-user to enrich the workspace with various aspects. +During workspace creation there is a wizard where one can select template fragments via checkboxes. + + + +The [workspace](/chapters/123-tour-workspace.html) is already prepared for this model of fragments. The [merged instructions][2] mean that we can extend the properties and instructions from many different sources. However, the most important feature here is the `cnf/ext` folder. Any `bnd` or special fragment file placed in this folder will automatically be ready before the `build.bnd` file is read. For example, a fragment could contain the index for OSGi R8. See [build](150-build.html). +## Providing template fragments as a developer + There is a single master index for all template fragments hosted on - https://github.com/bndtools/workspace-templates/blob/master/index.bnd +[https://github.com/bndtools/workspace-templates/blob/master/index.bnd](https://github.com/bndtools/workspace-templates/blob/master/index.bnd) This index is open for any person or organization that maintains one or more fragment and seeks an easy way to make them available to bndtools users. All that is needed is to host the fragment somewhere and provide @@ -33,7 +41,7 @@ The format of the index file is like all Parameters. * `key` – The key is the identity of the fragment. It is either a URL or provides the following structure: - id ::= [organization ['/' repository [ '/' path ] ['#' git-ref ]] + `id ::= [organization ['/' repository [ '/' path ] ['#' git-ref ]]` The id is resolved against `bndtools/workspace-templates#master`. Therefore, in the `example` organization, the `example` is a valid id that resolves to `example/workspace-templates#master`. Since the ID has a path, @@ -46,7 +54,9 @@ The index has the following attributes for a clause: * `require` – A comma separated list of fragment ids. Do not forget to quote when multiple fragments are required * `tag` – A comma separated list of tags, quotes are needed when there are multiple. -For example: +## Example + +For example consider this `index.bnd`: -workspace-templates \ bndtools/workspace-templates/gradle; \ diff --git a/docs/_chapters/img/template-fragments.png b/docs/_chapters/img/template-fragments.png new file mode 100644 index 0000000000..e955ffdd93 Binary files /dev/null and b/docs/_chapters/img/template-fragments.png differ diff --git a/docs/_data/sidebar.yml b/docs/_data/sidebar.yml index 1124e51872..aff5f4837e 100644 --- a/docs/_data/sidebar.yml +++ b/docs/_data/sidebar.yml @@ -44,6 +44,7 @@ nav: - url: /chapters/395-generating-documentation.html - url: /chapters/400-commands.html - url: /chapters/600-developer.html + - url: /chapters/620-template-fragments.html - url: /chapters/650-windows.html - url: /chapters/700-tools.html - title: Reference Material