Skip to content

Commit

Permalink
Merge pull request #5927 from kwin/feature/clarify-properties-file-fo…
Browse files Browse the repository at this point in the history
…rmat

Clarify configuration file format
  • Loading branch information
pkriens authored Dec 7, 2023
2 parents 4d1c6b0 + c438559 commit 0a150ca
Show file tree
Hide file tree
Showing 3 changed files with 13 additions and 2 deletions.
12 changes: 11 additions & 1 deletion docs/_chapters/130-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ There is often a confusion of terminology, like, is a bundle a component? We are

In DS, the implementation class is called the _component_ and in this document we follow this lead. Therefore, in general a bundle consists of a number of components.

# The Workspace
## The Workspace

The bndlib _workspace_ is an encapsulation of a set of cohesive _projects_, where a project exports zero or more bundles via _repositories_. A repository provides access to set of bundles exported by some means, likely from other workspaces. A repository can be on the local file system or a remote system like Maven central.

Expand All @@ -60,3 +60,13 @@ Projects can depend on other projects in the workspace or import bundles from th
A workspace is a single directory, just like a git workspace it encompasses all its sub directories. Though the name of the workspace directory is free to choose, it is highly recommended to use a naming strategy. In practice you will create many different workspaces and having a naming strategy will significantly simplify the handling of these workspaces.

On the same root level in the workspace as the `cnf` directory, bndlib expects the projects. Yes, projects *must* reside in the root level. The reason is again, simplicity. We will later discuss how the bundle's symbolic name is derived from the project's directory name. Since projects can depend on each other, bndlib maintains a workspace repository of projects that it derives from the top level directories. Some people desperately want to use hierarchies of projects (often because that is how they used to work before). However, even people patching bndlib to make it hierarchical admit that the simple linear model is actually working quite well. The reason it works so well is that a workspace is not supposed to hold every single bundle that your organization produces. It is intended to be a cohesive set of between 10-20 up to a couple of hundred projects.

## Configuration

Bnd uses Java properties files (often with extension `.bnd`) for configuration purposes. Those usually contain [headers](800-headers.html) or [instructions](825-instructions-ref.html). The files are read with [`java.util.Properties.load(Reader)`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Properties.html#load(java.io.Reader)) with `UTF-8` encoding and therefore support either of the following key value separators

1. `=` (default separator)
2. `:` (separator also used in MANIFEST.MF files)
3. `<white space character>`

In general any `<white space>` characters directly preceding or succeeding the separator are stripped.
2 changes: 1 addition & 1 deletion docs/_chapters/790-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,4 @@ The following classes are used:
* **Macro** – General macro, applicable everywhere
* Maven, Ant, Gradle – Only applicable in the given tool


Usually the format of both headers and instructions follows the Java properties files specification outlined in [Concepts](130-concepts.html).
1 change: 1 addition & 0 deletions docs/_data/sidebar.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ nav:
- url: /chapters/700-tools.html
- title: Reference Material
subfolderitems:
- url: /chapters/790-reference.html
- url: /chapters/800-headers.html
- url: /chapters/820-instructions.html
- url: /chapters/825-instructions-ref.html
Expand Down

0 comments on commit 0a150ca

Please sign in to comment.