subsurface: the newest release tag is a 2020 pointer to the nightly channel

The newest tag is a 2020 pointer to the nightly channel

The release list is the first thing to read and it explains the project's shape. The newest tag dates from May 2020 and is not titled as a release at all: it says to check the nightly builds. The two before it, from September and August 2019, are titled as release builds. So the last thing anyone tagged as a release shipped more than six years ago, and the tag that supersedes it is a signpost. Meanwhile the default branch's last commit is dated two days before this writing, and the repository is not archived. The README compounds it by offering a more stable, more tested build from a page named for the current release, which is the page whose newest artefact is that 2020 tag. Anyone planning around a Subsurface release is planning around something that stopped being released in 2020.

Every open pull request gets five platform artefacts

This is the best thing in the README and it deserves to lead the contributor story. The project states that artefacts for Windows, macOS, Android, a Linux AppImage and an iOS simulator build are generated for every open pull request and linked in the pull request comments, and that you should use them to test a change and give feedback before it is merged. Five platforms including a simulator build, per pull request, is unusual for a desktop application and it means a reviewer does not have to build anything to try a change. The same set of platforms appears in the continuous integration badges at the top of the file, alongside a snap workflow, a matrix for Debian and Ubuntu, a named distribution and Qt combination for one distribution, and one for another distribution on a later Qt major.

Nightly builds ship through five channels, one of them an edge channel

The distribution story is a paragraph long and worth reading closely. Nightly builds are produced from the latest code for Windows, macOS, Android and a Linux AppImage, and the README is explicit that the Android build requires sideloading. They are downloadable from a page on the project's website and directly from a separate repository of nightly builds on the forge. The same builds are then posted to daily repositories on three Linux distribution build systems, and released into a package store channel named for the leading edge rather than stable. So a user has five routes to the same artefact, two of which require configuration or trust decisions: sideloading a signed mobile build, and installing from a channel that by name is not the one your distribution marks as current. The source is one command:

git clone https://github.com/Subsurface/subsurface.git

Forking and browsing the sources is described as the same operation.

Two build files at the root and a static analysis config from a retired service

The repository root carries a lowercase makefile and a CMake file side by side, so there are two build entry points and the README points detailed instructions at a separate install document rather than describing either. Two more root entries are worth naming because of what they are rather than what they do: a configuration file for an automated static analysis service whose hosting has ended, and one for an automated dependency update service. Both are inert now, and both sit beside a working continuous integration setup that runs eight platform workflows, so the repository mixes current automation with configuration for automation that no longer receives anything. There is also an editor configuration, a formatting configuration, a contributor code of conduct, a coding style document, a testing readme, and an instruction file for coding assistants, which is a fairly wide surface for a project whose product is a desktop application for dive logs.

The map needs OpenGL 2.1, with a Qt variable as the escape hatch

The system requirements section is short and has one hard floor. On the desktop, the integrated map feature needs a graphics driver with support for at least OpenGL 2.1, and a machine without it has to run the program in software renderer mode. The program attempts to detect that case on its own, and the documented manual fallback is a two step procedure: learn how to set persistent environment variables for your operating system, then set the variable the Qt quick backend reads to its software value. That is the right level of detail for a support answer, and it is worth noticing what it implies: the map is the one feature with a graphics requirement, so a diver on an old machine loses the map rather than the log.

Windows installers are cross-built, which the README states plainly

One line in the usage section is an honest admission: native builds on Windows are not really supported, and the official Windows installers are cross-built on Linux. That is a common arrangement for projects with a single build host, and it explains why the Windows workflow exists even though nobody develops there. It also means a Windows bug report is a question about a binary produced on another operating system, which is worth remembering before you file one. The same section covers the two ways to open a data file, as an argument or from a default set in the preferences, and the import path for dive computers, which goes through an external library, with a special selection for Bluetooth models and a download button once you have named the computer and where it is attached.

Device support lives in a submodule with its generated table committed beside it

The last thing worth reporting is how the project keeps track of what it supports. Dive computer support is delegated to an external library, and the repository holds that library as a submodule rather than a copy. The list of supported computers is a plain text file at the root, named in the README as the place to look, and beside it sits a generated HTML table of the same list, committed to the repository. So the authoritative artefact is the text file, the published one is generated from it, and the submodule underneath has its own release cadence. The root also carries a table of hardware descriptors and a directory named for one vendor's media framework, which is where importer support for that platform's tools lives. It is a lot of generated and vendored surface for a program whose core is a logbook, and all of it is versioned beside the logbook format itself.

Editorial conclusion

subsurface fits a diver or a developer who wants the upstream rather than a distribution package, and it is worth understanding how its releases work before you rely on one. Three things to know. The stable option the README recommends resolves to a tag from 2020, so the project in practice ships from a nightly channel across five distribution routes, one of which is a sideloaded mobile build and one an edge channel in a package store. The good news is the testing story: every open pull request gets downloadable artefacts for five platforms. The practical instruction is to treat the current-release page as a historical artefact and to test from the nightly channel, and to expect the working tree to be years ahead of the last tag.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. subsurface/subsurface on GitHub