crosstool-NG: building cross toolchains from source, sample by sample

What crosstool-NG actually generates, and for whom

A toolchain is the set of programs that compile, assemble and link your code, and some of its parts end up inside the resulting binaries. Static libraries are the example the README gives. crosstool-NG's stated aim is building toolchains, which means it is a generator rather than a toolchain you download. That distinction matters: the output is a directory of cross compilers, linkers, headers and libraries produced from source on your machine.

The audience follows from that. If your target is an aarch64 board running glibc and you need the same compiler for a musl-based variant, a prebuilt package rarely covers both. crosstool-NG lets you describe each combination as a configuration and rebuild it. The samples/ directory shows the range: aarch64-rpi3-linux-gnu, aarch64-unknown-linux-musl, aarch64-unknown-linux-uclibc, aarch64-w64-mingw32, and older targets such as alphaev56-unknown-linux-gnu. A Windows-targeting toolchain and a uClibc toolchain sit in the same tree, which is the point.

It is not for someone who wants a compiler in five minutes. It builds from source, and the README points to the project website for how to configure, install and use it rather than reproducing those steps.

Kconfig, samples and a make script called ct-ng

The mechanism is visible in the repository layout. There is a kconfig/ directory, the same configuration system the Linux kernel uses, and a config/ directory holding the option definitions. A configuration file records your choices, and the build reads it to decide which components to fetch, patch, configure and compile.

The README states a fact that surprises people: if you run ct-ng --help you get help for make(2), because ct-ng is in fact a make script. The README calls this out directly and says there is no clean workaround. So expect make semantics, including the way targets and variables behave, rather than a bespoke CLI.

samples/ is the second half of the workflow. Each sample is a stored configuration for a known target, and the naming convention encodes the triple and libc: aarch64-rpi4-linux-gnu for a Raspberry Pi 4 with glibc, aarch64-unknown-linux-musl for a musl build. Starting from a sample and editing it is the intended path, because the sample already resolves the component versions that are known to work together. The packages/ directory holds the per-component build descriptions, and scripts/ holds the build logic. Nothing here is a binary distribution: the whole tree is Shell, Kconfig and make.

Installing crosstool-NG and building a first aarch64 toolchain

The README gives the clone command and nothing else about installation, deferring to the documentation site for how to configure, install and use the tool. So the honest starting point is the repository itself:

git clone https://github.com/crosstool-ng/crosstool-ng

After cloning, the top-level entries include bootstrap, configure.ac, Makefile.am and ct-ng.in. The autotools files and the .in suffix indicate that ct-ng is generated from ct-ng.in during the build, which is why bootstrap and configure exist in the tree. The documentation site is where the project describes the configure and make steps; the README does not spell them out, and neither does it list host dependencies. That is a real gap for a first-time user, and it is worth reading the docs before running anything.

Once ct-ng is available, the sample list is the way in. The samples/ directory contains entries such as aarch64-rpi4-linux-gnu and aarch64-unknown-linux-musl, so you pick the one closest to your target rather than starting from an empty configuration. The README documents ct-ng only through the note that ct-ng --help returns make help, so the documented entry point to the configuration is the make script itself:

ct-ng --help

Running that prints make help, which is the behaviour the README warns about. From there the build is driven the way any make script is, and the documentation site is where the project describes the rest of the workflow.

Expect a long build. The toolchain is compiled from source, and the README's framing makes clear that components are fetched and built rather than installed from packages. When it finishes, the resulting toolchain is a directory of cross tools you can put on your PATH. The README does not document rollback or cleanup of a partial build, so if a component fails mid-way, the state of the build directory is something the README leaves to you.

Where crosstool-NG is the wrong tool

The first limitation is the one the README admits itself: ct-ng --help prints make help. Anyone expecting a purpose-built command line interface with subcommand help will be misled by the tool's own help output, and the README says there is no clean workaround. That is unusual candour and it is also a usability cost.

The second is the documentation split. The README covers the introduction, the repository layout, contribution workflow and where to report bugs, but it sends you to crosstool-ng.github.io for configuration, installation and usage. If you are offline or the site does not answer your specific question, the repository alone will not walk you through a build. Host dependencies are not enumerated in the README either.

The third is the build itself. Building a toolchain from source is slow and sensitive to the host environment, and a failure in one component can leave a partially built tree. The README does not document rollback, so recovery means understanding the build directory rather than running an undo command.

Finally, if your target is already served by a distribution cross package or a vendor SDK with the exact triple and libc you need, crosstool-NG adds build time for no gain. It earns its place when the combination you need is not the one that is packaged.

crosstool-NG compared with Buildroot

The related searches pair crosstool-ng with buildroot, and the difference in approach is real. Buildroot is a build system that produces a complete root filesystem image: it builds a toolchain, but the toolchain is one output among many, and the usual goal is the image. crosstool-NG's stated aim is building toolchains, full stop. Its output is the toolchain, and there is no root filesystem, no image, no package selection for the target system.

So the choice follows from the deliverable. If you need an image to flash, Buildroot is the closer fit. If you need a compiler that you will point at a codebase you build and deploy yourself, crosstool-NG keeps the scope narrow. There is overlap, because Buildroot can also produce a toolchain, but the two projects are organised around different end products.

A second comparison worth making is against prebuilt cross compilers from a distribution. Those are faster to obtain and need no build, but you take the libc and version combination the packager chose. crosstool-NG exists precisely because that choice is sometimes wrong for a target, and the samples for musl, uClibc and mingw targets show the range it is meant to cover.

Maintenance, releases and licence questions

The repository is not archived, and the last push was on 2026-09-20. The most recent release listed is crosstool-ng-1.29.0 on 2026-08-23, preceded by two release candidates in July and August 2026. That pattern, release candidates before a tagged release, is worth noting if you depend on stable tags: the project appears to test through rc builds rather than tagging directly.

Upgrade cost is tied to how you consume it. If you build from a configuration you maintain, moving to a new release means re-checking the component versions your configuration pins, because the packages/ directory describes how each component is fetched and built. A configuration that names older component versions may need updating. If you track master, you are following a tree whose contribution workflow asks for signed-off commits and tested changes.

The licence situation needs care rather than a summary. The repository's licence is reported as NOASSERTION, which means the licence could not be automatically determined, and the tree contains both a COPYING and a LICENSE file plus a licenses.d/ directory. A toolchain bundles multiple upstream components, each with its own licence, and the configuration you choose determines which ones are included. The project's own files are the place to check what applies to your build; this is a factual matter of which components your configuration selects, not something to assume from the project name.

Editorial conclusion

Adopt crosstool-NG if you need a cross toolchain whose libc, architecture and component versions you control, and you are willing to spend the build time. Do not adopt it if a distribution package or a vendor SDK already gives you the exact target triple you need, or if you expect a GUI. Before committing, verify which sample matches your target in the samples/ directory, check that your host has the dependencies the build needs, and confirm the licence terms of every component your configuration selects, since the repository itself carries a NOASSERTION licence identifier.

Frequently asked questions

Official sources

1. crosstool-ng/crosstool-ng on GitHub
2. Issues
3. README
4. Releases