Should I bundle source and class files in the same JAR?

Question

Separate Jars

When creating JAR files, I've always kept the source separate and offered it as an optional extra.

eg:

• Foo.jar
• Foo-source.jar

It seems to be the obvious way to do things and is very common. Advantages being:

1. Keeps binary jar small
2. Source may not be open / public
3. Faster for classloader? (I've no idea, just guessing)

Single Jar

I've started to doubt whether these advantages are always worth it. I'm working on a tiny component that is open-source. None of the advantages I've listed above were problems in this project anyway:

1. Classes + source still trivially small (and will remain that way)
2. Source is open
3. Class loading speed of this jar is irrelevant

Keeping the source with the classes does however bring new advantages:

1. Single dependency
2. No issues of version mismatch between source and classes
3. Developers using this jar will always have the source to hand (to debug or inspect)

Those new advantages are really attractive to me. Yes, I could just zip source, classes and even javadoc into a zip file and let clients of my component decide which they want to use (like Google do with the guava libraries) but is it really worth it?

I know it goes against conventional software engineering logic a little, but I think the advantages of a single jar file out-weigh the alternatives.

Am I wrong? Is there a better way?

Answer 1

I prefer 'Separate Jars'.

Because binary class jar is for running on JVM, but source not. Source should be carefully maintained by your source control system(SVN). If source needs to release, zip it in separate jar. Many open source separates class jar and source one.

Answer 2

Yes, I could just zip source, classes and even javadoc into a zip file and let clients of my component decide which they want to use (like Google do with the guava libraries) but is it really worth it?

Of course it is worth it! It takes about 2 seconds to do it, or just a few minutes to change your build scripts.

This is the way that most people who distribute sources and binaries handle this problem.

EDIT

It is not your perspective you need to consider. You have to think of this from the perspective of the people deploying / using your software.

• They aren't going to use the source code on the deployment platform.
• Therefore putting the source code in the binary JAR is a waste of disc space, slows down deployment and slows down application startup.
• If they want to do something about it, they've got a problem. How do they rebuild the JAR file to get rid of the source code? How do they know what is safe to leave out?

From the deployer / user's perspectives, there are no positives, only negatives.

Finally, your point about people not being able to track source versus binary versions doesn't really hold water. Most people who would be interested in the source code are perfectly capable of doing this. Besides, there some simple things you can do to address the issue, like using JAR filenames that include your software's version number, or putting the version number into the manifest.

Answer 3

If you want others to test and inspect/improve your code then you can have your source with the binaries. If not, keep the source away from the jar.