Ant and Maven
Last
time I have written about general rules of engagement for Java
developers if they want to make lives of packagers easier. Today I'll
focus on specifics of two main build systems in use today: Ant and
Maven, but more so on Maven for reasons I'll state in a while.
Ant
Ant is (or at least used to be) most widely deployed build system in
Java ecosystem. There are probably multiple reasons for it, but
generally it's because Ant is relatively simple. In *NIX world Ant is
equivalent of pure make (and build.xml of Makefile). build.xml is just
that: an XML, and it has additional extensions to simplify common tasks
(calling javac, javadoc, etc.).
So the question is:
I am starting a new java project. How can I use Ant properly to make life easier for you?
The most simple answer?
DON'T! It might seem harsh and ignorant
of bigger picture and it probably is. But I believe it's also true
that Ant is generally harder to package than Maven. Ant build.xml
files are almost always unique pieces of art in themselves and as such
can be a pain to package. I am always reminded of following quote when
I have to dig through some smart build.xml system:
Debugging is twice as hard as writing the code in the first
place. Therefore, if you write the code as cleverly as possible, you
are, by definition, not smart enough to debug it.
--Brian Kernighan
And I have a feeling some people try to be really clever when writing
their build.xml files. That said, I understand there are times when
using Ant is just too tempting so I'll include a few tips for it
anyway.
Use apache-ivy extension for dependencies
One of main problem with and is handling of various
dependencies. Usually, they are in some subdirectory of main tree,
some jars versioned, some not, some patched without any note about
it...in other words nightmare in itself. Apache-ivy extension helps
here because it works with dependency metadata that packagers can use
to figure out real build dependencies including versions. We can also
be sure that no dependencies are patched in one way or the other.
Ivy is nice for developers as well. It will make your source tarballs
much smaller (You do have source tarballs right?!) and your build.xml
nicer. I won't include any examples here because I believe that Ivy
documentation is indeed very good.
One lib/ to rule them all
In case you really don't want to use Ivy, make sure you place all your
dependencies in one directory in top level of your project (don't
scatter your dependencies, even if you are using multiple
sub-projects). This directory should ideally be called
lib/. It should contain your dependencies named
as
${name}-${version}.jar. Most of the time you should
include license files for every dependency you bundle, because you are
becoming distributors and for most licenses this means you have to
provide full text of the license. For licenses use identical name as
jar filenames, but use ".license" suffix. All in all, make it easy to
figure out your build dependencies and play with them.
Don't be too clever
I can't stress this enough. Try to keep your build.xml files to the
bare minimum. Understanding ten 30 KiB big build.xml files with
multiple-phase build and tests spread through 10 directories is no
fun. Please think of poor packager when you write your build.xml
files. I don't mind having grey hair that much, but I'd rather if it
came later rather than sooner.
Maven
And now we are coming to my favourite part. Maven is a build and
project management tool that has extensive plugin support able to do
almost anything developer might ask for. And all that while providing
formal project structure, so that once you learn how Maven works in
one project you can re-use your knowledge in other projects.
Maven goodies
Maven provides several good things for packagers such as providing
clear dependencies and preventing simple patched dependencies from
sneaking in. Most important advantage for packagers coming with Maven
is the fact that
problems are the same in all projects. Once
you understand how certain Maven plugin works, you will know what to
expect and what to look for. But Maven is nice not just for packagers,
but also for developers.
Declarative instead of descriptive
You don't tell Maven:
Add jar A, jar B to the classpath, then use this properies
file to set-up test resources. Then compile tests (Have you compiled
sources yet?) and then ... and run them with X
Instead you place test files and resources into appropriate
directories and Maven will take care of everything. You just need to
specify your test dependencies in nice and tidy pom.xml.
Project metadata in one place
With Maven you have all project information in one place:
- Developer contact information
- Homepage
- SCM URLs
- Mailinglists
- Issue tracker URL
- Project reports/site generation
- Dependencies
- Ability modify behaviour according to architecture, OS or other property
Need I say more? Fill it out, keep it up-to-date and we will all be happy.
Great integration with other tools
Ecosystem around Maven has been growing in past years and now you will
find good support for handling your pom.xml files in any major java
IDE. But that is just the tip of the iceberg. There are Maven plugins
adding all kinds of additional tool support. Running checkstyle on
your code, helping with licensing, integration with gpg, ssh, jflex
and making releases. There are plugins for that and more.
Support for Ant
If you are in process of migrating your build system from Ant to
Maven, you can do it in phases. For parts of your builds you can
easily run Ant with maven-ant-plugin. Good example of such migration
in progress is checkstyle. In version 5.2 they introduced Maven build
system while preserving their old layout and running Ant for tests.
Maven messier side
A.K.A What you need to be aware of. It's generally quite hard to do
something bad in Maven, because it won't let you do that easily. That
said, there are plugins that can make it hard for us to package your
software.
maven-dependency-plugin:copy-dependencies
This specific goal can potentially cause problems because it allows to
copy classes from dependencies into resulting jar files. As I wrote
last time, this is unacceptable because it creates possible licensing,
security and maintenance nightmares. If you need even just one class
from another project, rather than copying it, add it as a dependency
into pom.xml
maven-shade-plugin
Shade plugin is a very shady plugin (pun intended). It can be used to
weave depdencies inside your jars while changing their package names
and doing all kinds of modifications in the process. I'll give you a small test now :-)
Let's say you have jar file with following contents:
META-INF/
META-INF/MANIFEST.MF
META-INF/maven/
META-INF/maven/org.packager/
META-INF/maven/org.packager/Pack/
META-INF/maven/org.packager/Pack/pom.properties
META-INF/maven/org.packager/Pack/pom.xml
org/
org/packager/
org/packager/signature/
org/packager/signature/SignatureReader.class
org/packager/signature/SignatureVisitor.class
org/packager/signature/SignatureWriter.class
org/packager/Pack.class
Can you tell, from looking at jar contents where is
org.packager.signature subpackage coming from? Take your time, think
about it. Nothing? Well here's a hint:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<configuration>
<relocations>
<relocation>
<pattern>org.objectweb.asm</pattern>
<shadedPattern>org.packager</shadedPattern>
</relocation>
</relocations>
</configuration>
</plugin>
I believe this demonstrates why usage of shade plugin is evil (in 99%
of cases at least). This is especially problematic if the shaded
packages are part of public API of your project, because we won't be
able to simply fix this in one package, but it will cascade up the
dependency chain.
maven-bundle-plugin
Bundle is one of the more controversial plugins, because it can be
used both for good and bad :-) One of the most important good use
cases for bundle plugin is generating OSGI bundles. Every project can
easily make their jar files OSGI compatible by doing something like
this:
...
<packaging>bundle</packaging>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
</plugin>
</plugins>
</build>
...
Easy right? Now to the darker side of bundle plugin. I have another
example to test your skills. This one should be easier than shade
plugin:
META-INF/MANIFEST.MF
META-INF/
META-INF/maven/
META-INF/maven/org.packager/
META-INF/maven/org.packager/Pack/
META-INF/maven/org.packager/Pack/pom.properties
META-INF/maven/org.packager/Pack/pom.xml
org/
org/objectweb/
org/objectweb/asm/
org/objectweb/asm/signature/
org/objectweb/asm/signature/SignatureReader.class
org/objectweb/asm/signature/SignatureVisitor.class
org/objectweb/asm/signature/SignatureWriter.class
org/packager/
org/packager/Pack.class
Problem is the same as with shade plugin (bundling of dependencies),
but at least here it's more visible in the contents of the jar and it
will not poison API of the jar. Just for the record, this is how it
was created:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
<Export-Package>org.objectweb.asm.signature</Export-Package>
</instructions>
</configuration>
</plugin>
Summary
Today I wrote about:
- Ant and why you shouldn't use it (that much)
- Ant and how to use it if you have to
- Maven and why it rocks for packagers and developers
- Maven and its plugins and why they suck for packagers sometimes
There are a lot more things that can cause problems, but these are the
most obvious and easily fixed. I'll try to gather more information
about things we (packagers) can do to help you (developers) a bit
more and perhaps include one final part for this guide.
