Expose the Aegisub version to Lua as aegisub.version

[CoffeeFlux]

Scripts can currently only check aegisub.lua_automation_version, which has been 4 for years, so they have no way to check for changes that can't be detected by looking for a function, such as new optional arguments or new dialog control fields. This adds aegisub.version, a table with:

Field	Value
string	The full version string, e.g. "3.5.0" for a release or "9900-master-4e440a614" for a development build. For display and logging.
major, minor, patch	The version declared in meson.build (project(version: ...))
build	The build number, which increases with every commit to master; nil if unknown

Version numbers

The numbers come from meson's project version rather than from parsing the version string. That version is bumped when a release is being prepared (e.g. to 3.5.0 alongside the 3.5.0 beta), so it's always the latest release a build contains, or the one being prepared. That means:

• Every build gets numbers, not just tagged releases: development builds, tarballs, shallow clones and forks alike.
• Minimum-version checks are safe: a development build made after 3.5.0 has everything 3.5.0 has, and reports 3.5.0.

They're passed in as compile-time defines, so there's no string parsing.

Build number

This is the existing revision number from tools/version.sh: commits since the last SVN commit. It's only increasing along master; other branches and forks number their builds differently. So it's useful for gating on features added since the latest release in official builds, but scripts should prefer the version numbers or feature detection. It's nil when the number is unknown, which happens when building from a shallow clone. CI clones the full history and meson dist tarballs carry the generated header, so official builds always have it.

Docs and testing

automation/v4-docs/misc.txt documents the table. It recommends checking for the specific feature where possible, and notes that the version is for changes that can't be detected that way.

Tested on macOS with an autoload script that dumps the table: a development build reports string=9902-…-0e5bdd30c major=3 minor=5 patch=0 build=9902. Running tools/version.sh in a --depth 1 clone gives build number 0, which is exposed as nil.

🤖 Generated with Claude Code

[CoffeeFlux]

I need to fix up the actual values returned here, but we definitely need a richer way to fetch the version than just the automation API counter, unless we want to start bumping that any time we change anything. The motivation here in particular is wanting to add an API for DepCtrl to use, but needing a way to gate on it. I'm inclined to start by exposing less and seeing what's useful, so maybe the build number is the right place to start, along with the semver version set in meson?

[petzku]

While this does seem logical, is there a reason against scripts just checking for the specific features they expect to be present? e.g. petzku.Phantom checks if aegisub.gui exists before registering a macro that depends on it; Encode Clip similarly guards just the aegisub.gui.is_modified call.

EDIT: i somehow entirely glossed over this being mentioned in OP already, sorry. still, though: it's not clear to me what those cases are where you couldn't check for function existence (unless you're planning on significant backwards-compat breaks, i guess?)

[arch1t3cht]

I guess one case I can think of is where an API function that used to take three arguments is extended to take an optional fourth argument in a newer version, or if aegisub.dialog.display is extended to allow more fields in the dialog control table. Unless script authors explicitly relied on a fourth argument being a no-op before, this would be a backwards-compatible extension that's hard to detect without calling API functions.

Either way, exposing the version explicitly is just more idiomatic.

As for the specific API, the conclusion is that it looks good to me, but for future reference here's why I discarded some alternatives:

• Considering Aegisub's history with having multiple active forks, I thought about adding some extra free-form field where non-official versions of Aegisub could identify themselves, but the string already pretty much allows that, and any additional logic would just complicate things further. If it really becomes necessary, forks can always add extra keys to the table themselves. And the hope is to go back to a single upstream anyway.
• In the past I thought about adding some sort of subversioning to the lua API specifically (as opposed to the version of Aegisub as a whole). But exposing Aegisub's main version is probably a good idea anyway, at which point the Lua API version would not really bring too many additional benefits.

Regarding the code:

• The version string parsing should probably go into a version.h utility function? (Returning something like an std::optional<std::tuple<int, int, int>>)
• Most (I haven't checked in detail which) Lua API functions have documentation in automation/v4-docs. But there's also the Lua Reference on the website, and the two seem to diverge in some places. One day, those two sets of documentation should probably be compared and consolidated into one single source of truth, but that's a bigger project. But until then, it's probably best to at least add documentation for aegisub.version to the v4-docs.

[CoffeeFlux]

OK I've updated this to be a bit more useful. I'm not sure what the release flag would do so it has been dropped, and the version just threads the one set in Meson through.

[CoffeeFlux]

Needs a corresponding site update as well