byTypeFilternativedependencies maven plugin

:toc: macro

image:https://travis-ci.org/fmarot/nativedependencies-maven.svg?branch=master["Build Status", link="https://travis-ci.org/fmarot/nativedependencies-maven"] image:https://img.shields.io/maven-central/v/com.teamtter.mavennatives/nativedependencies-maven-plugin.svg["Latest Maven Central deployment", link="http://search.maven.org/#search%7Cga%7C1%7Ccom.teamtter.mavennatives"]

toc::[]

= What is nativedependencies-maven ?

== WARNING

Even if this plugin may be useful, you may have a look at the official dependency plugin which is much more maintained and becomes more flexible over time (eg https://issues.apache.org/jira/browse/MDEP-628 & https://blogs.apache.org/maven/entry/apache-maven-dependency-plugin-version2)

== Maven plugin (nativedependencies-maven-plugin)

This Maven plugin will unpack the native dependencies (usually .so files on Linux, DLLs on Windows) into a single folder.

Those "native" dependencies are recognized thanks to the https://books.sonatype.com/mvnref-book/reference/profiles-sect-tips-tricks.html#profiles-sect-platform-classifier[Maven classifier] which must start with the "natives-" prefix.

If those artifacts are .zip, .tgz, (.7z are not fully supported) or any other recognized format, their content will be transparently extracted (optionally in different subdirectories) in target/natives/ directory.

By default, in case of a multi module project, we will unpack all natives dependencies to the same dir (thus saving space and unzip time while allowing all interdependent projects to benefit from the presence of native libs)

== Exemples of libraries

Those libraries may be handled by this plugin:

TODO: add configuration exemple for each one

== How to use

=== Maven dependency

The plugin is available from Maven Central, just add the following snippet to your pom to use it:

[source,xml]

... com.teamtter.mavennatives nativedependencies-maven-plugin 1.0.6 ... ... ... ------------------------------------------- === Options [source,xml] ------------------------------------------- com.teamtter.mavennatives nativedependencies-maven-plugin 1.0.5 unpacknatives generate-resources copy false true false so,dll linux 64 linux windows win -------------------------------------------

=== Multi module Maven project

==== the old way

By default, as you can see commented above (parameter 'nativesTargetDir'), the default directory will be "${session.executionRootDirectory}/target/natives".

This means that in a multi-module configuration, you can have all you native dependencies extracted alongside the main pom in ./target/natives.

This allows you to have a single location where are stored all your native libs, as long as you always run maven related commands FROM THE ROOT DIRECTORY.

If you want to target a specific child module, you can use the --projects parameter: mvn install --projects my-child-module

==== the new way

But in the real world you sometimes run child-modules directly from their own directory. Then you would loose time unzipping the native dependencies each time in a different child. So we introduced the 'autoDetectDirUpInFilesystem' parameter. It will (try to) autodetect the root of your maven tree and always unzip in the target/native directory alongside your parent pom. Even when you run Maven from a child module.

WARNING: implementation is quite naive and handles only tree file structure like this:

[source,xml]

parent-module | |- pom.xml |- child module 1 | | | |- pom.xml | |--child parent module |- pom.xml | |- lowest child module | |- pom.xml


==== in any case

Variable ${nativesTargetDir} is created in the Maven properties pool and reference the location where natives are unpacked. It's usefull to configure the exec Maven plugin to configure PATH or LD_LIBRARY_PATH for exemple.

== Eclipse plugin (Eclipse M2E Extension)

WARNING: there was once an Eclipse extension but not actively used nor developped. It has been removed on 2021/07/16

In the future we could restore it, the goal would be to automatically unzip dependencies directly from the IDE and add the folder to the PATH when running Eclipse launchers.

=== How to use the Eclipse M2E extension

Point Eclipse to the following update site:

= Getting help

The http://maven.40175.n5.nabble.com/Maven-Users-f40176.html[Maven Users mailing list] may also be a good start.

Or you can always https://github.com/fmarot/nativedependencies-maven/issues[open an issue] directly on Github.

= About the project

This is a fork of the previously existing https://code.google.com/p/mavennatives/[Maven Native Dependencies] project which was at version 0.0.7.

The maven plugin has then been renamed to "nativedependencies-maven-plugin" to follow Apache Maven conventions and groupId changed to "com.teamtter.mavennatives".

Big thanks to the original writers of Maven Native Dependencies.

Reasons for forking original project:

  • add finer grain control over what natives dependencies will be unpacked.
  • familiarize myself with the dev of Maven plugins.
  • improve eclipse plugin (NOT done at the moment)
  • finally find a way to prevent each and every project using native libs to have to manually (god I hate this word!) configure the -Djava.library.path and LD_LIBRARY_PATH

Current features added to original plugin:

  • generate a variable containing location of the directory where natives are unpacked ( use ${nativesTargetDir} in you pom ).
  • use GitHub instead of the dead Google Code
  • more modern code using annotations
  • parameter to be able to skip the plugin execution (overridable through a variable)
  • add parameters to auto-detect platform and get only platform specific libs
  • transparently handle misc compression format (zip, tar, tgz, 7zip...) and single file not compressed deps (.dll, .so, .dylib...)
  • keep a cache of the signature for each compressed artifact to avoid uncompressing it again if it has not changed. #performance

= Compiling the code

Commited code is compiled by https://travis-ci.org/fmarot/nativedependencies-maven/builds/[Travis-CI]

Eclipse's Tycho seem to require Java 8.

= License

Apache License 2.0

Nativedependencies Maven

nativedependencies-maven-plugin is a Maven plugin helping you deal with native dependencies (be it .so, .dll...)

Nativedependencies Maven Info

⭐ Stars11
🔗 Source Codegithub.com
🕒 Last Updatea year ago
🕒 Created7 years ago
🐞 Open Issues15
➗ Star-Issue Ratio1
😎 Authorfmarot