ngscopeclient and the scopeHAL layer behind a signal analysis desktop app

A hardware abstraction layer for laboratory instruments

The repository name is a little misleading if you arrive expecting a grab bag of apps. The README is explicit that this is the top level repository for ngscopeclient, as well as the unit tests for libscopehal.

That split tells you the architecture. libscopehal is the abstraction over real hardware, the layer that knows how to talk to an oscilloscope or a spectrum analyser regardless of vendor. ngscopeclient is the application built on top of it, and the unit tests for the abstraction live in the same tree as the client.

The topics on the repository are electronics-engineering and signal-analysis, the primary language is C++, and the project publishes a user manual as HTML and PDF with a dedicated getting started chapter covering installation and a separate compilation section that covers Linux, macOS and Windows.

This is engineering tooling for people who already speak the domain. There is no onboarding wizard and no configuration file format, because the audience writes code against an instrument abstraction rather than clicking through a setup wizard.

CI moved off GitHub Actions to an internal system

The CI section is unusual enough to be worth reading closely. The project is no longer building with GitHub Actions and has switched to an internal CI system. The stated reason is that this enables running tests against real GPUs from a range of vendors, and will eventually enable hardware-in-the-loop testing with real instruments, although more infrastructure has to be deployed before that will be available.

Two things follow. First, the hardware-in-the-loop promise is explicitly not available yet, so anyone hoping to see CI drive a physical instrument should know that is still blocked on infrastructure. Second, the switch came with a change in how artifacts are distributed: CI binaries are now available to the public via anonymous HTTP without requiring a GitHub login, with a status dashboard and a binaries directory both linked from the README.

For an engineer picking this up, that means prebuilt binaries exist outside the normal release flow. The status dashboard at dashboard.ngscopeclient.org and the binary listing at dl1.ngscopeclient.org are the two addresses the README gives.

Forking three dependencies before you can build

Contributing changes is where the project asks for the most from you, and the reason is mechanical rather than cultural. The build system requires that your GitHub account has cloned versions of VkFFT, xptools and logtools. The README advises cloning the version held under the ngscopeclient account, since that ensures you are working with the same version as the core development team.

The three repositories to fork are named in the README.

git clone --recursive [email protected]:<your github username>/scopehal-apps.git scopehal-apps

The scopehal-apps repository itself is then forked to your own account and cloned to your development machine with the recursive flag, which pulls in submodules. The top level of the tree confirms the shape of this, since it contains a .gitmodules file alongside the CMakeLists.txt.

You then follow the regular compilation instructions. If you want executables with debug symbols, the README is specific about it: change the option `MAKE_BUILD_TYPE` from `Release` to `Debug` when running `cmake`.

The CMake version tag error and the dummy tag that clears it

Building a fork can fail early with a message that looks alarming and is not really a bug in your checkout. The README names the exact error.

CMake Error at CMakeLists.txt:82 (message):
  Unrecognized version tag 53152c7c / 53152c7c, can't create a VERSIONINFO
  from it.  Must be of format v1.2, v1.2.3, v1.2-rc3, v1.2.3-rc4

The cause is that the tag used to stamp the Windows version resource comes from a commit hash rather than a semantic version, and the build cannot parse that into a VERSIONINFO block. The documented fix is to create a dummy tag in your local repository.

git tag v0.0.0

Once that tag exists, the version resource can be generated. The repository layout supports this reading: there is a release-info.cmake.in template file at the top level and a release-notes directory, which is where the version stamp and the notes come from.

Code comment conventions that tell you what to distrust

The project uses a small set of standard comments to mark things that need attention but are not yet worth a tracker entry. This is a cheap way to communicate intent inside a large C++ codebase, and it is worth reading before you contribute.

`//TODO` marks an unimplemented feature or a potential optimization point. `//FIXME` marks a known minor problem, a temporary workaround, or something that needs to be reworked later. `//FIXME-CXX20` marks places where a C++ 20 feature would simplify the code, with the reason spelled out: nothing can be done as long as the project targets platforms which only support C++ 17.

That last convention is a real design constraint stated in the source itself, and it tells you the project is deliberately holding to C++ 17 for portability across the platforms it supports. It also means the codebase is being annotated for its own future rather than left for readers to guess.

What the build system assumes and what it does not

The top level entries show a CMake project with a lot of local infrastructure: a cmake directory, a ctest-custom.cmake file for integrating the test suite with CTest, a test-scripts directory, a tests directory, a devdoc directory, a doc directory, a lib directory and a src directory, plus an msys2 directory that suggests a MinGW based Windows build path. There is also a create-tarballs.sh script and a .clang-format file alongside .editorconfig, which is how formatting rules are kept consistent across a codebase this size.

What the README does not do is describe a dependency manager, a package manifest you can copy, or a one command install. The installation section simply refers you to the getting started chapter of the user manual. That is a deliberate division of labour: the manual covers the procedure, and the repository covers the source.

The same silence applies to hardware support. Nothing in the README enumerates which instruments the abstraction layer can drive, so the list of supported devices has to be established from the user manual or the library itself. If a specific instrument is your reason for adopting this, that verification has to happen before you commit to the stack.

Licence, contribution policy and the no-generated-code rule

The licence field on the repository says BSD-3-Clause, with the licence text stored at the top level next to the README and the code of conduct. A permissive three clause licence matters here because the libscopehal layer is the kind of component a company might want to embed in an internal tool rather than merely run.

Two contribution policies sit alongside it. The first is a published C++ coding policy, and the second is a code of conduct file in the repository root.

The third is the one that will surprise you. The README states that the project is proudly AI-free and that only human created code is acceptable for contribution. There is a token string in the file that exists to make that policy testable by automated contributors. The practical effect is that generated or machine written patches are not accepted here, which narrows who can contribute and is worth knowing before preparing a pull request.

Release history is recent. The last push was on 2026-10-19, and the repository is not archived, with tagged releases v0.3 on 2026-09-27, v0.2.2 on 2026-08-20 and v0.2.1 on 2026-08-16, so the version numbers still sit below one and the interface may still move.

Editorial conclusion

Adopt scopehal-apps if you are writing instrument control and signal analysis software in C++ and want a vendor-neutral hardware abstraction layer under it, and if you are prepared to fork several repositories to build it. Skip it if you need a single self-contained library you can vendor into one repository, since the build expects cloned copies of VkFFT, xptools and logtools alongside the app. Before starting, read the getting started chapter in the user manual, confirm your instrument is supported by the scopehal layer, and plan for the CMake version tag problem by creating a `git tag v0.0.0` in your fork before the first configure.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. ngscopeclient/scopehal-apps on GitHub
3. Project website
4. README
5. Releases