Why Maven?

by Tim O'Brien

I continue to believe that Maven is the first choice for build systems despite the lack of quality documentation (which is a continued problem). Why? (Or specifically, why should an open souce project use Maven above other build systems?.....)

...open source projects benefit from having the most widely portable build possible. Widely portable builds reduce the inefficiencies associated with contributing to a project. In an open source project (such as Maven) there are two distinct groups: end-users and developers. When an end-user uses a project like Maven and decides to contribute a patch to Maven, they have to make the transition from using the output of a build to running a build. They have to first become a developer, and if it is difficult to learn how to build a project, this end-user has a disincentive to take the time to contribute to a project. In a widely portable project, an end-user doesn't have to follow a set or arcane build instructions to start becoming a developer, they can download the source, modify the source, build, and submit a contribution without asking someone to help them set up a build environment. When the cost of contributing source back to an open-source project is lower, you'll see an increase in source code contributions, especially casual contributions which can make the difference between a project's success and a project's failure. One side-effect of Maven's adoption across a wide group of open source projects is that it has made it easier for developers to contribute code to various open source projects.

In other words, even with Maven's problems (which will shortly be addressed, I promise), it still defines a common interface that many developers are familiar with. If you continue to use some custom procedural build system (even in your closed corporate environment) you are bucking the trend. The common interface, the ability to just "sit down in the driver's seat" and go, is more important than making sure that some highly opinionated software architect at a very large organization is happy with the "cleanliness" of the Maven repository or that someone feels that the Maven conventions can be bent to fit their own conventions.

Go ahead, adopt your own build process because you just *think* you know better, and have fun maintaining it. I know one thing about build systems, they are the last thing you need to be worrying about and your clients or employers rarely care to spend money on your clever, custom build system.


2007-11-04 10:10:17
Does using ant come under the category of "your clever, custom build system" in your opinion? I've watched a couple of open source projects move to maven and their effort expended on maven seems to be far in excess of the original ant build it was replacing. My experience of ant is that its pretty quick to set up and takes very little maintenance after that. Maven may be good for open source in that it allows others to get easily involved and you get a web-site with almost no effort as a bonus - but I don't believe you can sell maven on minimizing maintenance over something like ant.
Steve Loughran
2007-11-04 10:19:10
Given that documentation is one of the easiest things to contribute back (no need to worry about the patches breaking things), surely the quality of the documentation is a metric of community participation. In which case...
Tim O'Brien
2007-11-04 10:29:14
@Niall (P?), Not necessarily, when used properly, you can have an Ant build that is very maintainable. Using antlibs to define common tasks, using Ivy, these are things Ant has done in response to Maven. Nothing precludes anyone from building a great build system in Ant. But, I don't see antlibs in most Ant builds. I don't think antlibs have caught on, but this has more to do with the fact that people not keeping up to date with the tool. If the majority of Ant projects were created by people using antlibs and Ivy, I'd have another opinion entirely.

Niall, on a related note, I'm editing/modifying a text on Maven right now to remove all negative references to Ant and Make. Maven zealots have this awful tendency to point fingers at Ant and tell people that Ant is offensive. I like Ant, I use both Ant and Maven. I prefer Maven, but when I need Ant, I need it. I'm definitely not opposed to the well-written Ant build.

I do believe that a properly maintained Maven build is easier to maintain than the equivalent Ant build. The problem you've seen has more to do with Maven documentation being a terrible and misleading minefield of incompleteness and lies. (Hopefully that will be addressed in the medium-term.)

Tim O'Brien
2007-11-04 10:44:38
@Steve, if anyone else is reading this, Steve Loughran is the author of Ant in Action a well written book from Manning. I'd trust any build system written by him Ant or otherwise.

Fun, a criticism about project documentation. Good one. Documentation is a problem throughout open source projects, it has less to do with build systems and more to do with culture. Maven has awful project documentation. The reasons for this are many. I have a few theories. First, APT is an awful format to write documentation in and it is the encouraged format in Maven (that needs to change). Second, open source projects generally have fairly awful documentation this is due more to lack of attention than anything else. Third, you can't motivate individuals to write good documentation that has no perspective. There's a reason why the books I write for O'Reilly use "we" and "I", good technical documentation usually has some perspective associated with it. But, you often see documentation for some odd Commons component that has mixed tense and mixed perspective.

The other issue with documentation that spans all open source projects is that documentation is frequently not viewed as a primary artifact. It should be, the ASF should be more liberal granting a doc-only committer access to people who show both an interested and an ability. I think that it is very rare to have a very well documented open source project - even the Spring Framework, Hibernate, and Ant manuals have some problems there.

Steve, my sarcastic reaction is to say that, documentation lags because Maven makes it easier to be productive and write more code.

David Dossot
2007-11-04 10:51:04
I suggest you have a look at the free e-book "Better Builds with Maven" ( http://www.devzuz.com/web/guest/products/resources#BBWM ), which is a well done in-depth reference guide of Maven.
Niall (P)
2007-11-04 11:03:35
Some Apache projects have moved to confluence for documentation at Apache - which facilitates user involvement. Not sure that it has improved things though. Out of interest, whats your opnion on the best documentation solution for open source projects?
Tim O'Brien
2007-11-04 11:24:58
@Niall, I don't know, it's been something I've wrestled with. I see Wiki out there, I remember the big struggle the Foundation had (I think in 2002) when there was a discussion (big fight) about whether or not to allow Wiki contributions.

In hindsight, Wiki has worked a bit, you see people contributing to it more so, but don't you still get the sense that a lot of projects lack good documentation? It could just be that open source is never going to attract the kind of people that obsess over good documentation. Over at Wicket I know they just had a discussion about standardizing on Javadoc. It seems odd, but it does provide one place for documentation contributions. I've always thought that Commons Math was really well documented.

BTW, by good documentation I mean the kind of documentation you can print out, that doesn't have a lot of fragments, that has good tone, that is really comprehensive and concise. Part of the problem is that publishers like O'Reilly, Apress, and Manning court the maintainers of open source projects and tend to distract from the project's documentation effort. I've always thought that the real documentation for something like Ant or Maven is the published book. You see projects like Spring and Hibernate succeeding not necessarily through the published book by from maintaining a DocBook format internally.

I think the solution is to make sure that every TLP has at least one committer who, by convention, only pays attention to documentation. They are not a core developer of features, they might make small code contributions, but, in general, they just pay attention to documentation. I just don't *ever* see anyone becoming an Apache member because of documentation contributions, I don't see anyone ever being asked to join the PMC of a TLP based on doc contributions. On the other hand, I think documentation is just as important as the code.

Ironic that the project with the best documentation is Apache Ant. I think that's got more to do with the fact that it has been around forever and it hasn't had any revolutionary change since 2000. There's a big difference between the Ant and the Maven communities, I think the Maven people tend to bite off more than they can chew sometimes and you end up with a Maven plugin that is code complete with almost no documentation.

For full disclosure's sake, the big project I'm working on uses Maven for 75% of the build and Ant for the remaining 25%, there were things that the project team just decided were complex enough not to want to migrate the whole thing to Ant. I was in favor of writing custom plugins where we could, but, in hindsight, it wouldn't have been the best use of time.

2007-11-04 12:57:27
I'm constantly amazed that people still persist with Maven. It's always been the build tool that is almost there, promising so much and yet not quite delivering, the nirvana of build tools always tantalizingly out of reach. Ant, on the other hand, has always been the build tool that just works.

Employers may not pay for you to develop a build system, but they also don't pay you to monkey around with Maven for weeks on end, trying (in the absence of documentation) to get it to do one thing that doesn't quite fit with how Maven thinks you should be doing it. You will you always end up calling out to Ant anyhow.

The main advantage that Maven has traditionally offered over Ant has been its dependency management. Unfortunately, dependency management in Maven is a royal PITA. Want to get Maven not to download a graph of dependencies that includes every single open source Java project in the know universe? Sorry.
Want to version control your dependencies locally? You're stone out of luck.
Since Ant now has Ivy, it has also a superior dependency management tool.

Some people continue plugging away with Maven, always believing that it's going to deliver at some point. Others just use Ant, and forget about the damn build system.

Terry Laurenzo
2007-11-04 13:05:25
It is precisely because I hate messing with build systems that I tend to shy away from Maven for anything but simple and isolated needs... not that I'm a big fan of Ant either. I know a big part of it is that you use what you are familiar with. I know, for example, that if its late at night before a deadline and I find out I need to remix part of a jar to weave it with an AOP processor (as one example) that I can make Ant do that (or whatever I need). I have no such confidence in Maven -- I know it has these capabilities, but the details of how to use them are shrouded.

The core measure of merit I use to determine when a build system is good is when, with one or two incantations, someone unacquainted with the project can 1) check out what they need to build, 2) build and run/debug locally, 3) build a package, and 4) update dependencies. In ant, this corresponds to having targets run, debug, dist, and update-depends. If I can do these things in Ant, I'm generally content to stay there, knowing that I'm going to be able to easily extend it when I need to.

I know someone will point out that Maven is very extensible, but there is a dearth of information out there that gives much clue as to how to use Maven beyond the simple stuff. Maybe I'm not looking in the right place, or maybe I haven't looked recently enough... who knows.

Tim O'Brien
2007-11-04 13:44:44
@SamL, "The main advantage that Maven has traditionally offered over Ant has been its dependency management. Unfortunately, dependency management in Maven is a royal PITA. Want to get Maven not to download a graph of dependencies that includes every single open source Java project in the know universe? Sorry."

You ever used exclusions? I use them all the time, they are well documented. Have you read the documentation? Probably not.

"Employers may not pay for you to develop a build system, but they also don't pay you to monkey around with Maven for weeks on end, trying (in the absence of documentation) to get it to do one thing that doesn't quite fit with how Maven thinks you should be doing it. You will you always end up calling out to Ant anyhow."

Again, Sam, have you read the documentation about writing plugins? it is fairly easy to write a plugin.

Tim O'Brien
2007-11-04 13:56:42
@Terry, Maven documentation continues to suck, badly. I don't hold out *any* hope that the project documentation will improve any time soon, but I do think that there will be a solution forthcoming. From what you wrote, I think you'd be on the fence - if the documentation were comprehensive (in both breadth and depth), you'd probably opt for Maven? It is true, Maven can do all that you need it to do, but I know from experience the plugins you need are criminally underdocumented.
2007-11-04 15:02:01
I have, to my lasting regret, pored over what passes for documentation in Maven many times. The problem with exclusions is that it's a real missed opportunity. What you actually want to do is say "I'm using X in configuration Y, so give me the dependencies I need and nothing else". Instead, what you actually have to do is say "I'm using X" and then traverse the transitive closure of the dependency graph in order to determine everything that you want to exclude. I dunno, maybe this has changed since I gave up on Maven. I hope so, because it was a really obvious problem.

As for plugins, well that just proves my point. Why should I spend my employer's time learning how to write plugins for the build tool, when Ant just does what I need?

2007-11-05 04:57:38
Tim - you drop a couple of hints, "even with Maven’s problems (which will shortly be addressed, I promise)" and "I don't hold out *any* hope that the project documentation will improve any time soon, but I do think that there will be a solution forthcoming" - can you expand on what you're referring to? Do you have insider knowledge of something you can't discuss, or just high hopes? When and where should we be looking for these improvements, and what form will they take?

I am very interested in Maven's promise, and have rolled it out in a few projects, but have been frustrated with the day-to-day use and am considering going back to Ant, now that Ivy is an Apache project.

2007-11-05 07:21:54
Hopefully someone will document Plexus so anyone can use it. It seems to be a fantastic design.

Yet as you want to do anything real, like having sub-containers, you'll have wade thru the quite sloppy code.

Their faq even wonders why no one uses it. It's because there is no documentation and the code is a mess.

Terry Laurenzo
2007-11-05 07:58:05
@Tim, I would say that I am *not* on the fence right now, but I could be if a reasonable solution was presented. I recently described my feelings towards Java build tools as this: "I loathe Maven but I only hate Ant." There's a lot of room for improvement in the situation when the only choices are between two idealistic, my-way-or-the-highway weird little tools.

I can't believe I'm going to border on defending Make and the autotools for C/C++ development, but let me point out a couple of things that make me comfortable using them: 1. A few guys wrote a real good book on them and made it available for free. The book covers in good detail the basics of getting started and moves on to more advanced cases. 2. I know that for any autotools problem, there is the "right" way (ie. you have to know m4) and the "not so right but fast" way to get done what you need to do (ie. you add some stanzas to your Makefile.am to do some extra work at critical points).

Point 2 is a big one that I have not seen Maven2 address (although Maven1 did and I may just be ignorant about how to do it in Maven2). Maven1 had pre-goals and post-goals which could be extended with an ant-like language. I know plugins let you do similar things, but I don't want to go through the brain-damage of writing a plugin (and first grokking how to do that) just to try an experiment in the build (which in make or ant would probably be a couple of lines of code). To take it further, I want to decide whether I want to stay with the "just add something to the makefile" approach or take it to the next level and wrap it in a plugin.

And ditto to the comments on Maven2 transitive dependencies. Nice try, but no.

Tim O'Brien
2007-11-05 08:21:12
@Terry, there are some quirks with transitive dependencies that bug me, but nothing is a showstopper. I generally think that the ability to pull in transitive dependencies for things like hibernate and spring is a good thing. When I need an exclusion it does tend to work for me (but I'll admit that I've had to look at source many times to figure out what to do).

You said: "I can't believe I'm going to border on defending Make and the autotools for C/C++ development, but let me point out a couple of things that make me comfortable using them: 1. A few guys wrote a real good book on them and made it available for free. The book covers in good detail the basics of getting started and moves on to more advanced cases."

Yep. Exactly, the problem is that no one has written a good basics book for Maven 2. You end up with snippets of docs written by core developers on the project which assume familiarity with often ill-defined concepts. So, there is a standard directory layout, but no real rigid definition in the documentation. It is difficult to point people at the "definitive" reference. (Hibernate and Spring have similar issues, especially when the docs don't dig into the details of an option.)

Don't feel bad defending autoconf, I'm not using it for Java projects, but it is great. Again, I dislike it when someone writes a book about technology X and feels the need to disparage technology Y. I sound like a broken record, but there are ways to extend a Maven build with some ant snippets, i do it all the time, but you might have just been exhausted by the process of finding the appropriate instructions.

Terry Laurenzo
2007-11-05 08:29:36
@Tim, sorry for the brief comment on the transitive dependencies. I was jumping on a call and just hit post. I've been annoyed with the include the whole world issue with Maven2, but I've been equally annoyed with trying to explain how configurations in ivy work. M2 is definitely a step up from M1, where the poms just got bigger and bigger as you tried to enumerate all dependencies.

I've just gotten extremely cranky w.r.t. build tools of late. I think I got infected by the Ruby community in that regard... :)

Corba the Geek
2007-11-05 10:01:32
There is a free eBook on Maven: "Better Builds with Maven" that helps fill the documentation void:


Are you including this in your inadequate documentation criticism?

Tim O'Brien
2007-11-05 10:21:43
@Corba the Geek, a little, it is a large book, but I think there are some problems with the construction. I wouldn't criticize any of the authors, I think everyone involved with that book is very talented, but it didn't read as a single, cohesive document.
Steve Loughran
2007-11-05 11:10:27
I think you are right, documentation is pretty bad for most OSS projects. The best I've seen : Ubuntu, because their project planning is the wiki. Next, much of the Ruby and Python stuff. Oh, and all of TeX/LaTeX.

Ant is all HTML based, and has a big index of all the tasks, with examples. But we could go back and look at lot more at the troubleshooting and getting started stuff. Ideally, the troubleshooting is something we could build in to the engine. So when we encounter a misspelt/misspelled attribute, we look for something similar and hint. Same for namespaces.

We've tried a wiki, but nobody has (yet) embraced it. I think you can adopt it, but then people lose the offline docs. Is that good or bad? As a laptop user, I think it is bad. But what we may need is a separation between reference content -that must be offine- and guides/essays, where offline is OK.

2007-11-05 17:09:21
The interface of maven is great. Repositories are really useful and clever. But the implementation lacks, is buggy, slow!!, and it's hard to enhance with custom tasks and needs.
Buildr is a great implementation of maven concepts, and it works. Fast.
It's just been approved as an Apache project as well.
Martin Gilday
2007-11-06 06:22:56
@Steve. With a wiki you can generate PDF/HTML static content to go with each release, as Struts2 does. This way if you are planning to be offline you can have a offline copy, or a fresh wiki when online.
Pether Sorling
2007-11-06 07:43:24
A lots of good documentation available, both


and on top of that loads of good articles.

2007-11-09 05:10:16

Can you explain me how to create new poll on this forum. Thanks :)
2007-11-11 13:14:14
> the lack of quality documentation

The free maven book is cool.

Ben Teese
2007-11-12 19:48:44
Having used Maven on and off for the last couple of years, I'd have to say it kind of reminds me of the 'Brilliant but Temperamental' app described in Kathy Sierra's blog entry 'Is your app an ass-kisser?':

"Can do amazing work, but the slightest thing can set him off. Difficult to keep happy. Pain in the ass, but worth it...until someone else comes along who can do what he does without all the 'issues'."

Whilst I don't know whether the 'someone else' that comes along will be buildr or something else, I do know that if/when somebody replicate the ease-of-use of rake and rubygems in the Java world, I'll be dropping Maven like a hot potato.
2007-11-18 10:05:55
Greetings to all.

Prompt the best online shop on sale of Books.
2008-06-15 04:44:33
Check out http://www.gradle.org. It's build files are in groovy, so you get all the power of a real language ('if', variables etc.), you can seamlessly call ant tasks, so you have all the power of ant, and it integrates with Ivy. But on top of this it adds features from Maven: plugins, multi-module support (but done in a much better way, e.g., you can define inter-project target dependencies) and conventions. building a simple jar is just one line: 'usePlugin("java")' - the plugin defines all targets, and using convention paths. Of course, you can redefine targets/paths if you need to.