How to correctly handle split packages between org.hamcrest and org.hamcrest.library version 1.3.0?

[merks]

I'm concerned about how to properly generate split package information for org.hamcrest and org.hamcrest.library versions 1.3.0:

Here is what the Orbit EBR versions look like:

[MANIFEST]

Ant-Version                             Apache Ant 1.8.1
Archiver-Version                        Plexus Archiver
Automatic-Module-Name                   org.hamcrest.core
Build-Jdk                               1.8.0_162
Built-By                                genie.orbit
Built-Date                              2012-07-09 19:49:34
Bundle-ManifestVersion                  2
Bundle-Name                             %bundleName
Bundle-SymbolicName                     org.hamcrest.core
Bundle-Vendor                           %bundleVendor
Bundle-Version                          1.3.0.v20180420-1519
Created-By                              Eclipse Bundle Recipe Maven Plug-in
Export-Package                          org.hamcrest.core;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.internal;version="1.3.0";x-internal:=true;uses:="org.hamcrest"
                                        org.hamcrest;version="1.3.0";core=split;mandatory:=core;uses:="org.hamcrest.core,org.hamcrest.internal"
Implementation-Title                    hamcrest-core
Implementation-Vendor                   hamcrest.org
Implementation-Version                  1.3
Manifest-Version                        1.0
Originally-Created-By                   1.6.0_33-b03 (Sun Microsystems Inc.)
Require-Capability                      osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.5))"

and this:

[MANIFEST]

Ant-Version                             Apache Ant 1.8.1
Archiver-Version                        Plexus Archiver
Automatic-Module-Name                   org.hamcrest.library
Build-Jdk                               1.8.0_162
Built-By                                genie.orbit
Built-Date                              2012-07-09 19:49:34
Bundle-ManifestVersion                  2
Bundle-Name                             %bundleName
Bundle-SymbolicName                     org.hamcrest.library
Bundle-Vendor                           %bundleVendor
Bundle-Version                          1.3.0.v20180524-2246
Created-By                              Eclipse Bundle Recipe Maven Plug-in
Export-Package                          org.hamcrest.beans;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.collection;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.number;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.object;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.text;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.xml;version="1.3.0";uses:="javax.xml.namespace,org.hamcrest,org.w3c.dom"
                                        org.hamcrest;library=split;version="1.3.0";mandatory:=library;uses:="javax.xml.namespace,org.hamcrest.collection,org.hamcrest.core,org.w3c.dom"
Implementation-Title                    hamcrest-library
Implementation-Vendor                   hamcrest.org
Implementation-Version                  1.3
Manifest-Version                        1.0
Originally-Created-By                   1.6.0_33-b03 (Sun Microsystems Inc.)
Require-Bundle                          org.hamcrest.core;bundle-version="1.3.0"
Require-Capability                      osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.5))"

While update the recipe to include org.hamcrest.libary, I changed it to this to produce the spit package directives:

<![CDATA[
Bundle-Name:            Bundle ${mvnGroupId} : ${mvnArtifactId}
version:                ${versionmask;===;${version_cleanup;${mvnVersion}}}
Bundle-SymbolicName:    org.${replacestring;${mvnArtifactId};-;.}
Bundle-Version:         ${version}.v20230801-0843
Eclipse-Wrapped-Bundle: ${mvnGroupId}:${mvnArtifactId}:${mvnVersion}
Import-Package:         *
Export-Package:         org.hamcrest;library=split;version="${version}";mandatory:=library,\
                        *.internal.*;x-internal:=true;version="${version}";-noimport:=true,\
                        *;version="${version}";-noimport:=true
-noextraheaders:        true
-removeheaders:         Private-Package
]]>

That generates this:

[MANIFEST]

Ant-Version                             Apache Ant 1.8.1
Built-By                                tom
Built-Date                              2012-07-09 19:49:34
Bundle-ManifestVersion                  2
Bundle-Name                             Bundle org.hamcrest : hamcrest-core
Bundle-SymbolicName                     org.hamcrest.core
Bundle-Version                          1.3.0.v20230801-0857
Created-By                              1.6.0_33-b03 (Sun Microsystems Inc.)
Eclipse-Wrapped-Bundle                  org.hamcrest:hamcrest-core:1.3
Export-Package                          org.hamcrest.core;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.internal;x-internal:=true;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest;library=split;version="1.3.0";mandatory:=library;uses:="org.hamcrest.core,org.hamcrest.internal"
Implementation-Title                    hamcrest-core
Implementation-Vendor                   hamcrest.org
Implementation-Version                  1.3
Import-Package                          org.hamcrest;version="[1.3,2)";library=split
Manifest-Version                        1.0
Originally-Created-By                   1.6.0_33-b03 (Sun Microsystems Inc.)
Require-Capability                      osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.5))"

and this:

[MANIFEST]

Ant-Version                             Apache Ant 1.8.1
Built-By                                tom
Built-Date                              2012-07-09 19:49:34
Bundle-ManifestVersion                  2
Bundle-Name                             Bundle org.hamcrest : hamcrest-library
Bundle-SymbolicName                     org.hamcrest.library
Bundle-Version                          1.3.0.v20230801-0857
Created-By                              1.6.0_33-b03 (Sun Microsystems Inc.)
Eclipse-Wrapped-Bundle                  org.hamcrest:hamcrest-library:1.3
Export-Package                          org.hamcrest.beans;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.collection;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.number;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.object;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.text;version="1.3.0";uses:="org.hamcrest"
                                        org.hamcrest.xml;version="1.3.0";uses:="javax.xml.namespace,org.hamcrest,org.w3c.dom"
                                        org.hamcrest;library=split;version="1.3.0";mandatory:=library;uses:="javax.xml.namespace,org.hamcrest.collection,org.hamcrest.core,org.w3c.dom"
Implementation-Title                    hamcrest-library
Implementation-Vendor                   hamcrest.org
Implementation-Version                  1.3
Import-Package                          javax.xml.namespace
                                        javax.xml.xpath
                                        org.hamcrest.core;version="[1.3,2)"
                                        org.hamcrest;version="[1.3,2)";library=split
                                        org.w3c.dom
Manifest-Version                        1.0
Originally-Created-By                   1.6.0_33-b03 (Sun Microsystems Inc.)
Require-Capability                      osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.5))"

Can the fact that org.hamcrest now exports org.hamcrest;library=split;version="1.3.0";mandatory:=library;... with this "split" stuff and imports org.hamcrest;version="[1.3,2)";library=split calso with this split stuff cause any problems? Is this correct? Is there any semantic significance to the name 'libraryor could this just befoobar`? I had trouble finding information about this...

Similarly for org.hamcrest.library, which looks pretty much like before, but I avoided the use of the require bundle. I think that's correct, right?

I'm just concerned that I really don't understand this well and done know where to find good information about what's correct and about the implications. E.g., what happens if these directives were missing/overlooked?

@HannesWell Before I mess something up, your insights would be greatly appreciated!

[HannesWell]

Can the fact that org.hamcrest now exports org.hamcrest;library=split;version="1.3.0";mandatory:=library;... with this "split" stuff and imports org.hamcrest;version="[1.3,2)";library=split calso with this split stuff cause any problems? Is this correct? Is there any semantic significance to the name 'libraryor could this just befoobar`? I had trouble finding information about this...

With org.hamcrest;library=split you export the package org.hamcrest with an additional attribute library whose value is split.
Both the attribute name and its value can be chosen arbitrarily, but if you reference them in an Import-Package header they must match the specified names/values in the exports as specified in Attribute Matching. With the mandatory directive you enforce that an importer must specify the attribute with the given name and consequently the declared value.
The difference between an attribute (name=value) and a directive (name:=value) is specified in General Syntax Definitions and Common Header Syntax.

For the case of Export-Package and Import-Package this is specified in:

• https://docs.osgi.org/specification/osgi.core/8.0.0/framework.module.html#framework.module.exportpackage
• https://docs.osgi.org/specification/osgi.core/8.0.0/framework.module.html#framework.module.importpackage

The general Dependencies main section als contains a few words about attributes and directives:

• https://docs.osgi.org/specification/osgi.core/8.0.0/framework.module.html#framework.module.dependencies

In this case it makes IMHO more sense to have a mandatory split attribute and let each bundle use a corresponding value:

Bundle-SymbolicName   org.hamcrest.core
Export-Package        org.hamcrest;split=core;version="1.3.0";mandatory:=split

Bundle-SymbolicName   org.hamcrest.library
Export-Package        org.hamcrest;split=library;version="1.3.0";mandatory:=split

Then if one wants to import the org.hamcrest package from the core bundle one has to use:

Import-Package        org.hamcrest;split=core

If the package from the library bundle shall be used, one declares:

Import-Package        org.hamcrest;split=library

Since the split attribute is mandatory, one cannot just declare

Import-Package        org.hamcrest

In order to generate the suggested attributs/directive, you could probably use the following BND-instructions(have not tried it out), but the idea is to use the replacestring macro to extract the core/library suffix from the bundle-symbolic name

Export-Package:         org.hamcrest;split=${replacestring;${bsn};org\.hamcrest\.};version="${version}";mandatory:=split,\
                        *.internal.*;x-internal:=true;version="${version}";-noimport:=true,\
                        *;version="${version}";-noimport:=true

For PDE there is currently and open Issue and a pending PR to help the user to add mandatory attributes:

• Improve error message for Import-Package resulution failure due to missing mandatory attributes and provide a quick-fix eclipse-pde/eclipse.pde#578
• Quick-fix for Import-Package resolution failure due to missing mandatory attributes eclipse-pde/eclipse.pde#678

[merks]

That's super helpful! Thanks!!

Another annoying consideration here is that I want to produce a drop-in replacement for the EBR version so doing what makes more sense doesn't like up perfectly with doing it the same way as before. 😱

Most importantly, I don't want to mess up the org.hamcrest.core bundle because it's widely used. The org.hamcrest.library I think not nearly so much...

[HannesWell]

You are very welcome.

Another annoying consideration here is that I want to produce a drop-in replacement for the EBR version so doing what makes more sense doesn't like up perfectly with doing it the same way as before. 😱

Unterstand. Both ist technically fine, as long as exporter and importer match. So yes, you should probably Stick with the previous (suboptimal) descision.