Dan is the founder of Rectangular Software, an independent UK software company that provides development services and builds its own mobile and web applications. Dan has over a decade of experience in the software industry, building a wide variety of systems including casino, poker and spread-betting platforms, mobile applications, e-commerce websites, and network security software. His other programming interests include artificial intelligence, particularly evolutionary computation, and functional programming in Haskell. He has authored, or contributed to, a number of open source Java projects. Dan has posted 34 posts at DZone. You can read more from them at their website. View Full User Profile

10 Tips for Publishing Open Source Java Libraries

07.30.2009
| 6861 views |
  • submit to reddit

One of the strengths of the Java ecosystem is the huge number of open source libraries that are available.  There are often several alternatives when you need a library that provides some specific functionality.  Some library authors make it easy to evaluate and use their libraries while others don’t.  Open source developers may not care whether their libraries are widely used but I suspect that many are at least partially motivated by the desire to see their projects succeed.  With that in mind, here’s a checklist of things to consider to give your open source Java library the best chance of widespread adoption.

1. Make the download link prominent.

If other people can’t figure out how to download your project, it’s not going to be very successful. I’m bemused by the number of open source projects that hide their download links some place obscure. Put it in a prominent location on the front page. Use the word “download” and use large, bold text so that it can’t be missed.

2. Be explicit about the licence.

Potential users will want to know whether your licensing is compatible with their project. Don’t make users have to download and unzip your software in order to find out which licence you use. Display this information prominently on the project’s home page (don’t leave it hidden away in some dark corner of SourceForge’s project pages).

3. Prefer Apache, BSD or LGPL rather than GPL.

Obviously you are free to release your library under any terms that you choose. It’s your work and you get to decide who uses it and how. That said, while the GPL may be a fine choice for end user applications, it doesn’t make much sense for libraries. If you pick a copyleft licence, such as the GPL, your library will be doomed to irrelevance.  Even the Free Software Foundation acknowledges this (albeit grudgingly), hence the existence of the LGPL.

The viral nature of the GPL effectively prevents commercial exploitation of your work.  This may be exactly what you want, but it also prevents your library from being used by open source projects that use a more permissive licence.  This is because they would have to abandon the non-copyleft licence and switch to your chosen licence. That isn’t going to happen.

4. Be conservative about adding dependencies.

Every third-party library that your library depends on is a potential source of pain for your users. They may already depend on a different version of the same library, which can lead to JAR Hell (such problems can be mitigated by using a tool such as Jar Jar Links to isolate dependencies). Injudicious dependencies can also greatly increase the size of your project and every project that uses it.  Don’t introduce a dependency unless it adds real value to your library.

5. Document dependencies.

Ideally you should bundle all dependent JARs with your distribution. This makes it much easier for users to get started. Regardless, you should document exactly which versions of which libraries your library requires. NoClassDefFoundError is not the most friendly way to communicate this information.

6. Avoid depending on a logging framework.

Depending on a particular logging framework will cause a world of pain for half of your users. Some people like to use Sun’s JDK logging classes to avoid an external dependency; and some people like to use Log4J because Sun’s JDK logging isn’t very good. SimpleLog is another alternative.

If you pick the “wrong” logging framework you force your users to make a difficult choice.  Either they maintain two separate logging mechanisms in their application, or they replace their preferred framework with the one you insisted that they use, or (more likely) they replace your library with something else.

For most small to medium sized libraries logging is not a necessity. Problems can be reported to the application code via exceptions and can be logged there.  Incidental informational logging can usually be omitted (unless you’ve written something like Hibernate, which really does need trace logging so that you can figure out what is going on).

7. If you really need logging, use an indirect dependency.

OK, so not all libraries can realistically avoid logging.  The solution is to use a logging adapter such as SLF4J.  This allows you to write log messages and your users to have the final say over which logging back-end gets used.

8. Make the Javadocs available online.

Some libraries only include API docs in the download or, worse still, don’t generate it at all.  If you’re going to have API documentation (and it’s not exactly much effort with Javadoc), put it on the website. Potential users can get a feel for an API by browsing its classes and methods.

9. Provide a minimal example.

In an ideal world your library will be accompanied by a beautiful user manual complete with step-by-step examples for all scenarios. In the real world all we want is a code snippet that shows how to get started with the library. Your online Javadocs can be intimidating if we don’t know which classes to start with.

10. Make the JAR files available in a Maven repository.

This one that I haven’t really followed through on properly for all of my projects yet, though I intend to. That’s because I don’t use Maven, but some people like to. These people will be more likely to use your library if you make the JAR file(s) available in a public Maven repository (such as Java.net’s). You don’t have to use Maven yourself to do this as there is a set of Ant tasks that you can use to publish artifacts.

From http://blog.uncommons.org/

Published at DZone with permission of its author, Dan Dyer.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Martin Spasovski replied on Thu, 2009/07/30 - 3:58am

From these points, I'd like to point out that No 2 & 3 (license stuff) are the first thing a developer looks for when he searches for a lib. And from creators point of view 4 & 5 (dependencies management) are required (without them don't even consider publishing it) and 8 & 10 are kindly reccomended :) it's easier to open a bookmarked api documentation, than to browse the local hard drive to extract it and to open it.

Nice article!

Erik Post replied on Thu, 2009/07/30 - 7:20am

How about dual (commercial/free) licensing? Any insights or experiences to share?

Mostly Harmless replied on Thu, 2009/07/30 - 9:58am

How do you think we hold up to your list??

 http://wiki.architecturerules.org/

I think we hit 7 of them or so right on the head, with one in progress (dependencies). I suppose the download links could be a little more prominent as well.

Thanks for looking at our page and providing any feedback.

 

Rogerio Liesenfeld replied on Thu, 2009/07/30 - 10:12am

Really great tips!

My open source project, JMockit, fortunately already satisfies all of them, except for number 10.

I also don't use Maven, but I agree that it is important to provide jmockit.jar in a Maven repository. I even tried to do this using Ant some time ago, but did not find good Ant tasks for that at the time. I will try again with the Maven Ant tasks you pointed to.

Thanks

Dan Dyer replied on Thu, 2009/07/30 - 11:21am in response to: Erik Post

I guess that works best (from a commercial perspective) if the open source licence is the GPL, otherwise there's little incentive for users to buy the commercial version.  But it still doesn't really serve developers who are using permissive licences for their projects. 

It's not just the GPL that makes things awkward for users of a library.  Any licence that places obligations on not only the direct users of the library, but also their users too (those that use the library that depends on the licensed library) will have similar problems.  For example, Terracotta's attribution licence seems reasonable in isolation, but if every library did that things would get messy.

 

 

Andy Jefferson replied on Thu, 2009/07/30 - 11:43am

> 7. If you really need logging, use an indirect dependency.


But if you add a dep to SLF4J or "Clogging" then you just added another dependency. Why not just abstract out an interface to logging for your app and then provide an implementation of that for log4j and JDK1.4 "Logger", and it uses the one it finds in the CLASSPATH, like we've done in DataNucleus for several years - hence no. hard. dependency. at. all.

Mladen Girazovski replied on Fri, 2009/07/31 - 3:30am

10. Make the JAR files available in a Maven repository.

This one that I haven’t really followed through on properly for all of my projects yet, though I intend to. That’s because I don’t use Maven, but some people like to. These people will be more likely to use your library if you make the JAR file(s) available in a public Maven repository (such as Java.net’s). You don’t have to use Maven yourself to do this as there is a set of Ant tasks that you can use to publish artifacts.

There is more people using the Maven Repos than just Maven users (Ivy, Buckminster can use Maven Repos as well, etc). When using Maven it will help to take care of point 1 (it can can be found in the maven repo) & 4 (dependencies will be resolved by Maven), Point 5 will be superflous and Point 8 & 9 can be addressed very simple as well.

Mohamed El-beltagy replied on Sat, 2009/08/01 - 4:04am

Great article. Thanks for the tips.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.