Using -noimport with @Export annotation

GENERAL
7

Just found this discussion here after hanging around here and learning how stuff actually works.

And I discovered the prescious -noimport:=true

My initial reaction was like "Why is -noimport:=true not the default? Like perspective of @laeubi in Using -noimport with @Export annotation - #5 by laeubi

What about we promote the more prominently to use something like -noimport:=true on the Exports when “just” adding OSGi meta data?

-exportcontents: *;-noimport:=true

This would reflect the default-behavior which is expected by @laeubi , the github issue and myself somehow (throwing in a buzzword*: principle of least surprise*). Then the substitution use-case could be documented as an alternative.

Given that the default behavior won’t change (that is what I took from discussion and github) I would like to ask

  1. how we could do a better job of documenting it?
  2. and maybe give better advice to library authors who just want to add OSGi metadata, but do not have OSGi knowledge?

A real life example of the pain it causes is the origin github Issues with 2024-06 and gson library used by lsp4j v0.22 · Issue #3236 · eclipse-jdtls/eclipse.jdt.ls · GitHub

The problem, as you’ve noted, is that both gson bundles import just “com.google.gson.annotations” (implied >= 0.0.0) leaving the door open for resolution between different versions of the same library :neutral_face: gson 2.10.1 should import with a range of [2.10.1,2.11.0) and gson 2.11.0 should import with a range of [2.11.0,2.12.0) to be safe.

com.google.gson_2.10.1.jar
Import-Package = sun.misc;resolution:=optional,com.google.gson.annotations;version="[2.10.1,2.11.0)"

com.google.gson_2.11.0.jar
Import-Package = sun.misc;resolution:=optional,com.google.gson.annotations;version="[2.11.0,2.12.0)"

This problem resulted in multiple other github issues in different projects (gson, bnd, eclipse…) and seems to be a real-world issue only a few people are able to debug.
This makes me think “What could we do about it?”

I am willing to contribute documentation but not sure if and where to start. So feedback is welcome.

As a starting point

I see the following docs pages: