Frequently_Asked_Questions

Q: Is this repository (https://github.com/maven-nar/nar-maven-plugin) the official home of the NAR plugin?

A: Yes. @duns, the original author, donated the plugin (with Sonatype's approval) to the community, since he no longer has time to maintain it.

Q: Is the NAR project being actively maintained?

A: Yes, it is now. It was rather dormant for the past few years, but now has at least two active maintainers (@ctrueden and @dscho), with a few others participating in the development as well.

Q: Is the NAR project being actively developed?

A: NAR is a volunteer project; no one is paid to work on it full time. So development is driven by community contributions. This means you! If there is a bug or feature you want addressed, we encourage you to file a pull request with your patch. The maintainers are very happy to help you, if you take the first step.

The maintainers often write "patches welcome" in response to bug reports, a phrase which unfortunately has grown to have negative connotations. But in the case of this project, we truly mean it! The reality is that none of the NAR maintainers have time to actively investigate bug reports or improve the codebase on our own. We do what we can to maintain the NAR project, but we are not experts on the codebase. It is no less time consuming for us to attempt bug-fixes than for any other member of the NAR community to do so. Which means that when we say "patches very welcome" we really do mean it. We need all the contributions we can get!

Q: Why was the plugin renamed to nar-maven-plugin?

A: To comply with the permitted usages of the Maven trademark. According to the Apache Project Management Committee:

The pmc is permitting persons who develop plugins for maven to use the mark maven in their plugin name provided the name and its usage meets certain criteria, amongst which is the "___-maven-plugin" naming scheme.

The NAR plugin was previously named `maven-nar-plugin` because it was slated for adoption as an official Maven plugin, but that never happened. So the `artifactId` has been changed to `nar-maven-plugin`. (The `groupId` will need to change as well, but that is still pending.)

Q: Where is the official forum/list?

A: The maven-nar Google group.

Q: Where is the official issue tracker?

A: GitHub Issues. There was a category for NAR in the Sonatype JIRA, which was active until May 2013, but it has apparently been deleted, so we unfortunately cannot migrate those issues to GitHub. If you had filed an issue there which is still relevant to the latest master branch, please file a new GitHub issue for it. Thanks!

Q: Where are the official releases? Are they deployed to Central?

A: Yes, releases are deployed to Sonatype's OSS repository. Version 3.0.0 was released on December 6th, 2013. Version 3.1.0 was released on June 7th, 2014. Maven Central mirrors the Sonatype OSS repository, including the nar-maven-plugin.

Q: Is there a public Maven repository with release builds?

A: Yes, stable releases are now available on Central!

<plugin>
    <groupId>com.github.maven-nar</groupId>
    <artifactId>nar-maven-plugin</artifactId>
    <version>3.0.0</version>
</plugin>

The source for 3.0.0 is tagged on GitHub.

Q: Where can I find a working example of how to configure the NAR plugin?

A: Several open source projects make use of the NAR plugin:

1. DevZendo Cross-Platform FileSystem Access uses NAR. The POM is straightforward and may be a good first project to study for learning about NAR.
2. SLIM-curve uses NAR with some extra configuration, and may be a good second project to study for seeing a few more parameters in action.
3. ImageJ has a native launcher component which uses NAR. Search the pom.xml for "nar" to find the relevant blocks. It is not a simple "hello world" example (e.g., it uses OS-specific profiles), but it is a working real-world use case which successfully builds on a Jenkins server farm including Windows, OS X and Linux nodes.

We would gladly welcome any other working examples of the NAR plugin in use!

Q: How can I test the latest SNAPSHOTs?

A: To use the latest code on the master branch and/or topic branches: clone the code from GitHub, and build it using mvn install. This installs the JAR into your local Maven repository cache (typically at ~/.m2/repository/com/github/maven-nar/nar-maven-plugin/3.0.0-SNAPSHOT). Then add a reference to the plugin within your project's POM:

<plugin>
    <groupId>com.github.maven-nar</groupId>
    <artifactId>nar-maven-plugin</artifactId>
    <version>3.0.0-SNAPSHOT</version>
</plugin>

It will resolve the plugin from your local cache.

Note that this approach is recommended only for testing, not for production code, because anyone else building your code will then also need to build nar-maven-plugin beforehand as well.

Q: How can I test a specific integration test?

A: Call mvn -Prun-its -Dinvoker.test=<directory-name> where <directory-name> is something like it0003-jni.

Q: How can I debug integration tests with, say, Eclipse?

A: There are two good methods. Which one is better depends on the integration test/failures.

Importing the generated integration test projects directly

Once mvn -Prun-its was called from the command-line, the integration tests are actually available as fully valid Maven projects in target/it/it*/. Those projects can be easily imported into your IDE of choice.

Important note for Eclipse users: Eclipse's Maven support will only pick up the NAR plugin when it is installed (i.e. after mvn -DskipTests install has been called from NAR plugin's top-level directory, before that Eclipse will happily ignore any changes you make to the NAR plugin's source code), and then still only when the integration test's configuration has been updated via Maven>Update Project... (no need to force SNAPSHOT updates, though).

Using a remote debugger

First, run the integration test as specified above. Then, create a new file called invoker.properties in target/it/<it-name>/ that contains this line:

invoker.mavenOpts = -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=localhost:8000

Now, run the integration test again. The JVM launched to run the test should suspend and wait for your next steps.

The next steps are:

1. Fire up Eclipse (or whatever IDE with debugging capabilities you want to use).
2. Create a new Debug Configuration for Remote Debugging, attached to port 8000 and associated with the nar-maven-plugin project, which you imported previously with File>Import>Existing Maven Project (you did, didn't you?).
3. Add any desired breakpoints.
4. Finally, click the Debug button of said debug configuration.

Q: Why does the nar-package goal run before the (general) jar goal

A: The nar-package goal generates the nar.properties file which needs to be included in the general jar artifact.

Q: Why does the NAR plugin produce both a jar artifact and an attached -noarch.nar artifact. Could these two not be combined?

A: The jar artifact contains only java classes and gets added to the classpath. It needs no further processing. The -noarch.nar artifact contains include files and needs to be unpacked to be useful for the native compilers. It does not need to be added to the classpath. Combining the two artifacts would complicate matters.

Q: I use the NAR plugin to create a JNI type library. How do I load this library from my code?

A: The JNI library is strictly connected to the corresponding java code in the main artifact (jar file). Since the main artifact has a version number, we decided that the JNI library should have the same version number. If you add the subtag <narSystemPackage> to the <library> tag, the NAR plugin will generate a NarSystem class for you which will load the library. Assuming you specified com.mycompany.mypackage as narSystemPackage, then you need to add the following code to the class with the native methods:

import com.mycompany.mypackage.NarSystem

public class ... {

	...

	static {
		NarSystem.loadLibrary();
	}

	...

}

Q: How do I use the NAR plugin to create a JNI type library for multiple platforms (Windows, MacOSX and Linux)?

A: First of all, you have to generate the platform-dependent attached artifacts from each platform, which will be called .nar files for convenience from here. Jenkins is highly recommended in this case. Secondly, native-lib-loader should be specified as a <dependency> in your pom.xml file. Additionally, you need to specify which will be used to load the native libraries. In this case, NAR plugin going to use native-lib-loader instead of System.load() function. Because the native-lib-loader will be used to unpack and load the native libraries from the given .nar files. This requires the .nar files to be in the class path so that native-lib-loader can find the appropriate native library.