KAR file documentation contains incomplete example with `zip`

[dilyanpalauzov]

https://karaf.apache.org/manual/latest/kar contains:

As a KAR file is a simple zip file, you can create the KAR file by hand.

For instance, the following Unix commands create a very simple KAR file:

~$ mkdir repository
~$ cp /path/to/features.xml repository/features.xml
~$ cp /path/to/my.jar repository/my/project/my/1.0.0/my-1.0.0.jar
~$ zip -r my.kar repository
updating: repository/ (stored 0%)
  adding: repository/my/project/my/1.0.0/my-1.0.0.jar (deflated 0%)

When I try the above example I see also a line adding: repository/feature.xml (deflated 53%). This line is missing from the output above.

[jbonofre]

The example is not necessarily "complete", but it should use ... to mention that eventually other files can be included in kar archive.

[dilyanpalauzov]

I think the example should be complete: demonstrate that the .kar file must contain at least two files (an .xml and a .jar). It can and should be spelled with words, what and where other files can be included. Currently https://karaf.apache.org/manual/latest/kar states:

A KAR file contains a repository folder containing:

• a set of features XML files
• the artifacts following the Maven directory structure (groupId/artifactId/version/artifactId-version.type).

and https://karaf.apache.org/manual/latest/karaf-maven-plugin.html#_code_karaf_create_kar_code opposes:

There are two important directories in a kar:

• repository/ contains a Maven structured repository of artifacts to be copied into the Karaf repository. The features descriptor and all the bundles mentioned in it are installed in this directory.
• resources/ contains other resources to be copied over the Karaf installation.

Everything in target/classes is copied into the kar.

So there are on two places different descriptions on what makes sense to put in a .kar file. The one says XML files and jar files unded repository, the other says resources/ directory and .jar files under repository/. There should be a definition on one place, which combines the above explanations.

The first citation does not suggest that JSON can be used instead of XML, but https://karaf.apache.org/manual/latest/#_features_repositories_2 does so. Can the .kar file include JSON instead of XML descriptions for features?

My understanding is that .class files included from target/classes are irrelevant and the only way to create a .kar file, including particular .java files is to create two maven-modules: one creating a .jar file and the other creating a .kar file with that .jar file.

Is there a way to put in

<features xmlns="http://karaf.apache.org/xmlns/features/v1.6.0" name="a.b.c.d-${project.version}">
        <feature name="A" description="a" version="1.2.3">
                <bundle start-level="80">mvn:a.b.c/a.b.d/${project.version}</bundle>
        </feature>
</features>

used as input to org.apache.maven.plugins:karaf-maven-plugin something different from mvn: as path, e.g. a relative path ../../target/a.b.d-${project.version}.jar? I am asking, as for me, to put a .java file in a .kar file, it seems the only possible way is to put in one maven module the .java file in a .jar file as .class, and in another maven module to put the .jar file in the .kar file. But for the second step to work, the .jar file needs to be installed. However I do not need to install the .jar file (and the .kar file), all I need is to mvn package these files, and for this relative paths would be useful as input to karaf-maven-plugin.

[jbonofre]

OK, fair, I will update the documentation.