TOGoS's Java Libraries

Compared to publishing and using libraries in the Deno, Node/NPM, or PHP/Composer ecosystems, Java libraries are kinda hard. This document exists to help me remember what conventions I want to follow, what Java libraries I have already created, and how to use them.

Conventions

Package Name

For new libraries, use package name "net.nuke24." + library name, possibly with an additional level of "x" + year for 'experimental little thingies'.

Maven Group/Artifact

For the group ID, everything up to this project's name in the package name, and the project's name for the artifact ID.

At least this is what I did for Libertarian2511:

Versioning

Try not to introduce breaking changes between versions of a library. Make a new library, instead. Instead of 'MyCoolLib' version v2.0, create 'MyCoolLib2'. Keep the 2 as if it's a version number if you like, but put them in separate namespaces. E.g. every version of JavaCommandRunner36 is 36.something.

If a library relies on another library, e.g. to define some interfaces, its published form should not include the dependency.

When not too inconvenient, make libraries Maven-compatible. This means creating a pom.xml file. Even if you don't formally publish a package, you can manually install JAR files into your ~/.m2/repository.

Where To Put Experimental Little Thingies

Not sure this will last? Don't want to clutter up the list of Git repos? You can use the Scratch38 or TScript34 repositories/namespaces to store the thing.

Package name should then be net.nuke24.scratch38.s0123, net.nuke24.tscript34.p0123, where 0123 is the sub-project number.

Alternatively, use an "x" + year namespace, like net.nuke24.x2025.

Include Mechanism

Since it's Java, the most straightforward way to include a library is probably to publish a JAR file.

Maven can automate downloading dependencies, but it's not trivial to get that all working.

Some alternatives:

Include the JAR file in the dependent project's Git repo, either directly or by URN (so that Git doesn't try to track the whole thing), using TJFetcher to go get it.

Include the library's Git repo as a subtree of a parent project. A downside of this approach is that it should only be used to pull libraries into a top-level project that is not a library. Otherwise you could end up pulling the same library as a transitive dependency into a project multiple times, possibly getting conflicting versions of it.

Libraries