Good things come to those who wait. I always wanted to improve our Java Packaging documentation a little. When I started to contribute to Debian Java in 2012, I often struggled to find the right information and examples that would explain how I could package my own libraries or applications for Debian. After six years of trial and error and helpful advice on the debian-java mailing list, I figured it would be time to document this journey.
At DebConf 2018 in Hsinchu I began to work on updating the wiki documentation. The current status of this work will always be visible at:
My basic idea was to explain packaging by examples. I didn't assume that everyone was already familiar with the Java basics and more often than not people end up packaging Java software because it is part of their job or an application supports more than one programming language. Otherwise it is a book of seven seals.
The first thing to know is that Java compiles to bytecode, so that *.java source files become *.class files. Those files are usually packed together in a zip-based archive, et voila now we have *.jar files. To compile your source code into bytecode you need the Java Virtual Machine provided by OpenJDK. Learn what the CLASSPATH and a MANIFEST file is and you are good to go. This is what the Java Packaging 101 is all about.
If you grok the basics you will easily understand the next section: NoBuildSystem
Despite the fact that some upstream projects come without a proper build system, they are often very simple to compile. Instead of one or two source files, you just have to compile dozens in one single directory. We have a Java helper tool called....Javahelper that does exactly that for you. A good start is to read the docs at /usr/share/doc/javahelper/tutorial.txt.gz also replicated here.
Of course the Java world has invented the most powerful build systems in existence that are even able to bend light and can throw galaxies around. Let's welcome Ant, Maven and Gradle. Everything else is irrelevant but don't trust me.
If you can choose we recommend to either use Ant or Maven. Gradle is packaged for Debian but is more difficult to tame because every upstream project looks different. On the contrary Maven follows conventions and every project looks very similar.
Last but not least there is also a Java Packaging FAQ.
Shouldn't there be more examples and much more information? I'd love that. Please help us to improve the documentation. If you think there is currently something missing, please contact us at email@example.com or just update the documentation. It's a Wiki!