Skip to content

Docker images for cross compiling prebuilt binaries for Node.js native addons.

License

Notifications You must be signed in to change notification settings

prebuild/docker-images

Repository files navigation

docker-images

Docker images for cross compiling prebuilt binaries for Node.js. Used by prebuildify-cross.

Release Release Common Changelog

About

All images include Node.js LTS, Python 3.x, npm and a preconfigured build toolchain suitable for node-gyp and prebuildify. For example:

> docker run --rm ghcr.io/prebuild/alpine node -v
v16.15.1

Images are tagged with a major, minor and full version as well as latest. For example, use the following to pin to major version 2:

FROM ghcr.io/prebuild/alpine:2

Versioning guarantees

Within a major version range, we will not change toolchains, environment variables, working directories, users and more. However, the Node.js version will change without notice. We use Node.js LTS (at the time of building images) for a light maintenance effort. This is okay because prebuildify can target (the headers of) older Node.js versions while itself running on a newer version.

Images that are based on dockcross (see below) may inadvertently introduce breaking changes because dockcross does not use semantic versions (dockcross/dockcross#399) and does not maintain a changelog that would allow us to easily categorize changes and then tag our images accordingly. If this concerns you we recommend pinning to an exact version (x.x.x) which we treat as immutable.

Images

Compile in AlmaLinux 8 with Red Hat Developer Toolset 11. This increases compatibility with Linux flavors because prebuilds will be compiled with GCC 11 but at runtime they will only require glibc 2.28. For comparison, compiling on Ubuntu 24.04 would require glibc 2.35.

Node.js binaries are built with a similar approach but the Node.js project uses RHEL 8 (which requires a Red Hat subscription) instead of AlmaLinux.

Preconfigures prebuildify to tag prebuilds with the libc flavor, to set them apart from musl prebuilds, e.g. linux-x64/node.glibc.node.

This image is not updated anymore and does not support Node.js 18 and C++ 20. Instead use almalinux-devtoolset11.

Compile in CentOS 7 with Red Hat Developer Toolset 7. This increases compatibility with Linux flavors because prebuilds will be compiled with GCC 7 but at runtime they will only require glibc 2.17. Makes prebuilds compatible with Debian 8, Ubuntu 14.04, RHEL 7, CentOS 7 and other Linux flavors with an old glibc.

The RHEL folks put in a ton of work to make the devtoolsets work on their older base systems (libc mainly), which involves shipping a delta library that contains the new stuff that can be statically linked in where it's used.

-- @rvagg (prebuild/docker-images#8)

Preconfigures prebuildify to tag prebuilds with the libc flavor, to set them apart from musl prebuilds, e.g. linux-x64/node.glibc.node.

Compile in Alpine, which uses musl instead of glibc and therefore can't run regular linux prebuilds. Worse, it sometimes does successfully load such a prebuild during npm install - which prevents a compilation fallback from kicking in - and then segfaults at runtime. You can fix this situation in two ways: by shipping an alpine prebuild and/or by shipping a centos7-devtoolset7 prebuild, because the latter will be skipped in Alpine thanks to the glibc tag.

Preconfigures prebuildify to tag prebuilds with the libc flavor, to set them apart from glibc prebuilds, e.g. linux-x64/node.musl.node.

Cross-compile for Linux ARM. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (6).

Cross-compile for Linux ARM. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (7).

Cross-compile for Linux ARM. This image uses musl instead of glibc for Alpine linux. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (7).

Cross-compile for Linux ARM. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (8).

Cross-compile for Linux ARM. This image uses an old version of glibc (glibc 2.27) for compatibility. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (8).

Cross-compile for Linux ARM. This image uses musl instead of glibc for Alpine linux. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (8).

Cross-compile for Android ARM. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (7).

Cross-compile for Android ARM. This image thinly wraps a dockcross image. Preconfigures prebuildify to tag prebuilds with the armv version (8).

Old images

Images were previously hosted on Docker Hub. These are no longer updated:

Development

Releasing

Update CHANGELOG.md according to Common Changelog, for which you might like hallmark to pull commit messages into the changelog:

hallmark cc add minor

Tweak CHANGELOG.md as needed until hallmark lint is happy. Then commit, tag and push. For example:

git add CHANGELOG.md
git commit -m "2.1.0"
git tag -a v2.1.0 -m v2.1.0
git push --follow-tags

The git tag triggers CI/CD to publish new images to GHCR. A changelog entry is required.

License

GPL-3.0-only © 2019 prebuild contributors.