NetBSD/src: the NetBSD source tree mirrored from CVS into Git

A mirror, not the place to send patches

The repository description is unusually blunt for a GitHub project. It is an automatic conversion of the NetBSD src CVS module, use with care, and it asks for bugs and changes to be submitted through the NetBSD bug tracking system at gnats.NetBSD.org rather than on GitHub. It also warns that links to commits here will rot, and points to nxr.NetBSD.org and cvsweb.NetBSD.org instead.

That warning is the key to understanding what this repository is. NetBSD's development happens in CVS, and the Git repository is generated from it. The README says the Git mirror is updated every few hours from CVS, so it is a faithful but lagging copy, and its commit history is a reconstruction rather than the original record. The rot in commit links follows from that: a commit identifier in the mirror does not necessarily resolve to a stable address in the canonical system, and the cross reference and cvsweb interfaces are the stable ones.

For a reader this is a good deal. The full source of a Unix operating system in one cloneable repository, with a searchable history, is a very different thing from the CVS interface. For a contributor it is a dead end, and the project says so twice. The primary language is C, the default branch is trunk, and the licence is not stated in the repository metadata, which is unusual for a project of this size and is one of the reasons to treat the mirror as a read-only artifact.

The build.sh entry point and the cross-build habit

NetBSD can be cross-built from most Unix-like operating systems, and the build command in the README is the whole of it. You go into the src directory and run build.sh with the options for a release build of a given architecture.

./build.sh -U -u -j4 -m amd64 -O ~/obj release

The flags are doing specific things. The -m selects the machine, so amd64 for x86_64, and -j4 sets the parallelism for the build, -O sets the object directory to ~/obj so the build products do not pollute the source tree. The final argument, release, selects the build flavour rather than a snapshot.

The details live in the BUILDING file, which the README points to, and the top-level Makefile is where the configuration surface is documented. That Makefile explains the priority order for variables, which run from the make command line, to /etc/mk.conf, to the environment, and it lists the ones that matter: DESTDIR for the install root, MKMAN to skip manual pages, MKOBJDIRS, MKSHARE to skip /usr/share, MKUPDATE to skip the cleandir at the start of a build, NOCLEANDIR, NOINCLUDES and NOBINARIES. The Makefile header itself points at /usr/share/mk and the bsd.README file, and at src/etc/Makefile for the release engineering options, which is a useful sign that the build system is documented in the place a developer would look.

What is in the tree and how the pieces fit together

The top level layout is the standard Unix source tree, and reading it tells you how the system is divided. sys/ is the kernel. lib/ and include/ are the C library and the headers, and usr.bin/ and usr.sbin/ hold the userland commands and the system administration binaries. bin/ is the traditional binary directory, sbin/ the system binaries, libexec/ the daemons that are not user facing, and share/ the data files. games/ is the games collection. etc/ holds the configuration files and the packaging and release machinery, distrib/ the distribution and port build infrastructure, external/ the vendored third party code, crypto/ the cryptographic implementations, common/ the code shared between the kernel and userland, compat/ the compatibility layers for other Unix systems, tools/ the build and release tools, regress/ the regression test infrastructure, rescue/ the rescue system, doc/ the documentation, dist/ the distribution files, and tests/ the ATF test suite.

Two of those directories deserve a note. compat/ is unusual and interesting, because it holds the binary and source compatibility layers that let NetBSD run programs and provide interfaces from other Unix systems, which is a design choice. external/ is where vendored dependencies live, which means the tree is large and a lot of it is not NetBSD code, a fact worth knowing before you grep through it expecting to find NetBSD's own implementation of something.

The tree also contains the file that tells you what changed between releases, UPDATING, which is a traditional and still useful mechanism for communicating the compatibility implications of an upgrade to a running system, and the Makefile.inc, which holds the shared make logic for the whole tree.

Testing with ATF and the daily build pipeline

The test suite is ATF, the Automated Testing Framework, and it runs on a running NetBSD system. The invocation is short.

cd /usr/tests; atf-run | atf-report

atf-run executes the tests and atf-report formats the result. The tests/ directory in the source tree is where those test cases live, and the regress/ directory holds the regression tests that are driven by the build system rather than by hand, which is the mechanism that catches the case where a change compiles and boots but breaks something the automatic tests notice.

The build infrastructure produces artifacts you can use without building anything. There are daily builds published under the NetBSD-daily directory, and the released images under the NetBSD release tree on the CDN. That is the practical route for most people. You are not expected to compile an operating system to use it, and the daily builds are how developers test against the current state of the tree rather than against a release. The fact that the mirror updates every few hours means the two are close, but a daily build is the artifact built by the same pipeline, and for a bug report the distinction matters.

Where NetBSD/src is the wrong tool

Three cases argue against it. The first is contributing. The project asks for bugs and patches through the NetBSD web form, points at the netbsd-users and current-users mailing lists, and offers the IRC channel on libera.chat. A pull request against the mirror is not a contribution path, and a developer who finds a bug there has to move their workflow to reach the people who can act on it. The second is treating the mirror as the source of truth for history. The README says the Git mirror is updated every few hours from CVS, and that links to commits will rot, so for archaeology, for bisecting a regression, or for establishing when a change landed, the CVS repository and the nxr and cvsweb interfaces are the right tools. A developer who bisects in the mirror is bisecting a converted history with a lag behind the real one.

The third case is a build with a specific goal. The build system is documented, but it is also the oldest kind of build system, a recursive make over a very large tree with a configuration model whose variables are documented in mk.conf(5) and in comments in the Makefile. Building a full release of NetBSD for a target architecture is a long job on modest hardware, and if what you actually want is a specific subsystem, or a toolchain, or a look at how one driver is written, then reading the tree is the point rather than building it. On the licensing question, the repository metadata does not record a licence, and for a project of this size that is worth resolving directly rather than inferring, since the terms of the individual components in external/ in particular come from their own upstream projects rather than from NetBSD.

There is also a portability dimension to weigh. NetBSD describes itself as highly portable and available on a wide range of platforms, from large-scale servers and desktop systems down to handheld and embedded devices, and the presence of a compat/ directory and a large ports infrastructure is evidence of that. The cost of that breadth is that the tree contains code for machines and configurations you will never use, so a newcomer reading it for the first time benefits from starting in sys/ or in a single lib/ directory rather than from the top.

Editorial conclusion

NetBSD/src suits a developer who wants to read the whole of a Unix operating system in one repository, grep it, or cross-build it for an architecture they do not own, and it is a faithful mirror because the conversion is automatic. It does not suit someone who wants to contribute, since the README asks for bugs and changes to go through the NetBSD bug system and the project says to use the mirror with care. Before you start, work from the CVS repository if you need the authoritative history, use nxr.NetBSD.org or cvsweb.NetBSD.org rather than commit links, which the project says will rot, and note that the last push was on 2026-10-19 and the mirror is updated every few hours from CVS.

Frequently asked questions

Official sources

1. Issues
2. NetBSD/src on GitHub
3. Project website
4. README