gns3-gui's readme defers its own installation to another site

The readme is a pointer, and the installation section is one line

The page opens with the project name and the words describing it as the interface repository, then the installation heading contains a single sentence sending you to a documentation site. What follows is three short sections: the software dependencies, how to change the interface, how to debug it, and where to report a security problem. That is a deliberate and, for a shipped desktop application, a defensible shape, because install instructions for a tool that runs on three operating systems age faster than anything else on a page. The one command the page does give you for developers is two lines long:

``` {.bash} cd scripts python build_pyqt.py ``` The dependency section is the part that earns its place: it names the interface toolkit and says whether to take it from the distribution or from the package index, and it is honest that the rest of the Python packages are installed by the installer rather than by hand.

Two release lines ship in parallel, with a patch between two alphas

The three most recent releases are two builds of a 3.1.0 alpha and one patch from the 2.2 line, and they are interleaved: an alpha in August, a maintenance release at the end of July, and another alpha in September. So the project is running a stable line and a pre-release line at once, which is what you would expect from an application with a large installed base and a rewrite in progress. The naming carries the distinction, since the pre-release builds are tagged with a letter suffix rather than a number. The readme does not explain the support policy for either line, so the practical question of which line to install is answered on the documentation site rather than here, and the repository's own release list is the only evidence of how the two relate.

One dependency is pinned to the last release for the oldest interpreter

The requirements file is seven lines and one of them carries a comment that explains itself better than most dependency files do. The schema validation library is pinned to an exact version for Python 3.9 with the note that this is the last release to support that interpreter, and it is given a range instead for 3.10 and above. So the oldest supported interpreter and one dependency's version range are a single decision, and anybody raising the floor has to come back and change that line. The rest of the file is short and modern: a resource measurement library, distribution detection, a dark theme package pinned exactly, a certificate store package for newer interpreters only, and the error reporting client with a range and a comment.

The error reporting client is in the mandatory list and labelled optional

One line in that file is an error reporting client with a version range and a comment that says optional dependency. It is not in an extra, not behind a marker and not conditional on a Python version, so anybody installing from this file installs it, and the comment describes an intention rather than the current arrangement. It is a small thing and it is the kind of thing that survives for years, because the file is correct as far as the installer is concerned and the comment is correct as far as the author's intent goes. The certificate store package beside it is the more consequential of the two choices, since it means the application trusts the certificate authorities the operating system trusts rather than carrying its own.

The container installs a virtual framebuffer and only the development requirements

The container exists to run the test suite and nothing else, and it says so in its first comment. It starts from the latest long term image, installs the interpreter, the interface toolkit and its extra modules, the development headers and a virtual framebuffer, copies both requirement files in, and then installs only the development one with the flag that permits writing into the system interpreter's site directory. So the runtime requirement file is present in the image and never installed from, presumably because the development file includes it. The final command runs the suite under the virtual framebuffer with verbose output, which is how a graphical interface gets tested on a machine with no screen. Two flags in that file are dated and one base image tag floats.

A root module exists to fake the frozen flag, and the desktop entry exists twice

Two root entries explain themselves only if you know the packaging conventions. One is a module whose name announces that it is faking a frozen interpreter state, which is how a Python application tells its own installer that it is running from a bundle rather than a source tree. The other is a desktop entry file at the root, while the packaging script installs a desktop entry from inside the resources directory under a shorter name. So the file that ends up in a user's applications menu is not the one sitting in the repository root, and both are maintained. There is also an application metadata file for software centres, four requirement files split by role and platform, a directory for the interface description files the build script compiles, and a security scanning configuration from a commercial service.

Two release channels and one security inbox

The badge row points at the build pipeline, at the package index using the project's older domain name for it, and at a vulnerability scanning service, which gives you the three things a reader usually wants: whether the tests pass, what version is published, and whether anyone has flagged a known issue in the dependencies. The security section then gives a single address and nothing else, and the repository carries a security policy file beside a licence file and a copying file, so the written policy exists for anyone who wants more than the address. That asymmetry is normal. A published inbox tells a reporter where to send something, and the policy file is what a security team reads before deciding whether to report at all.

Editorial conclusion

Work in this repository if you are changing the simulator's interface rather than installing it, because for anything else the documentation site is the source and this page is a signpost to it. Two things to know. The dependency file is doing more work than it looks: one entry is pinned to the last release supporting the oldest interpreter the project still supports, so the floor and the floor's dependencies are connected decisions. And the readme's silence about installation is not an oversight but a boundary, which means a change to how the application is installed probably belongs in another repository entirely. Read the changelog and the security policy before assuming either is current.

Frequently asked questions

Official sources

1. GNS3/gns3-gui on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases