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

For new libraries, use package name "net.nuke24." + library name.

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.

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

Name/link Latest version Type Domain Notes
TJFetcher Command-line utility Build automation Fetches files based on URN from /uri-res/N2R servers
JavaCommandrunner36 36.1.28 Command-line utility Build automation Simple utility for running processes. As of v36.1.28, Low-to-nonexistent support for scripting or pipelining multiple commands, because I couldn't figure out a good way to represent that as a String[]!
TScript34-P0010 Library Language Runtime Implementation Interfaces for some basic functional datatypes
LanguageUtil Library Language Implementation Data types and functions useful for implementing parsers and ASTs, most notably a SourceSpan class. Deprecated; use TJLanguageUtil39, instead.
TJLanguageUtil39 39.1.0 Library Language Implementation Data types and functions useful for implementing parsers and ASTs, most notably a SourceSpan class
TScript34-P0012-Lib01 0.0.6 Library Demo My attempt to publish a library using Maven