Better explain the implications of -nouses instruction

[laeubi]

Because of issue

• Workspace template fails to read files from github in some Eclipse configurations #6431

I further analyzed the problem and found it to be a missing use clause:

• https://issues.apache.org/jira/browse/LOGGING-198

i then tried to fix the project (what uses maven-bundle plugin / bnd already!) but without success. It took me some time to realize, that with this commit all Apache commons projects effectively disable use clauses on their export package instructions.

The commit do not mentioned any rationale and I thought it would be good to make the project aware of the issue by linking the documentation that will obviously war that this is dangerous and maybe list cases where it should or should not be used but:

https://bnd.bndtools.org/instructions/nouses.html

only tells

Do not calculate the uses directive on package exports or on capabilities.

I find disabling this extremely dangerous and the doc should at least mention the implications of not using uses directives on packages (and capabilities)

[chrisrueger]

mention the implications of not using uses directives on packages (and capabilities)

Any suggestion on what to write there?

I had a look and found 2 places where this is used:

• bnd/biz.aQute.bndlib/src/aQute/bnd/osgi/Analyzer.java

  Line 2355 in c986676

  if (isTrue(getProperty(NOUSES)))

• bnd/biz.aQute.bndlib/src/aQute/bnd/component/DSAnnotations.java

  Line 301 in c986676

  if (!nouses) {

[laeubi]

The spec might be a good first source for derive some normative things:

Classes can depend on classes in other packages. For example, when they extend classes from another package, or these other classes appear in method signatures. It can therefore be said that a package uses other packages. These inter-package dependencies are modeled with the uses directive on the Export-Package header.

The most important part is this one here

Class space consistency can only be ensured if a bundle has only one exporter for each package.

So I hardly can imagine why one would want to disable this at all (and it seems only be either on or off...).

I had a look and found 2 places where this is used

This is where the flag is evaluated (I hope bnd nowhere uses the flag to disable this).

[chrisrueger]

Docu change is live https://bnd.bndtools.org/instructions/nouses.html