diff options
Diffstat (limited to 'packaging/building-native-packages-locally.md')
| -rw-r--r-- | packaging/building-native-packages-locally.md | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/packaging/building-native-packages-locally.md b/packaging/building-native-packages-locally.md new file mode 100644 index 00000000..6ad1d604 --- /dev/null +++ b/packaging/building-native-packages-locally.md @@ -0,0 +1,101 @@ +# Build native (DEB/RPM) packages for testing + +This document provides instructions for developers who need to build native packages locally for testing. + +## Requirements + +To build native packages locally, you will need the following: + +* A working Docker or Podman host. +* A local copy of the source tree you want to build from. + +## Building the packages + +In the root of the source tree from which you want to build, clean up any existing files left over from a previous build +and then run: + +```bash +docker run -it --rm -e VERSION=0.1 -v $PWD:/netdata netdata/package-builders:<tag> +``` + +or + +```bash +podman run -it --rm -e VERSION=0.1 -v $PWD:/netdata netdata/package-builders:<tag> +``` + +The `<tag>` should be the lowercase distribution name with no spaces, followed by the +release of that distribution. For example, `centos7` to build on CentOS 7, or `ubuntu20.04` +to build on Ubuntu 20.04. Note that we use Rocky Linux for builds on CentOS/RHEL 8 or newer. See +[netdata/package-builders](https://hub.docker.com/r/netdata/package-builders/tags) for all available tags. + +The value passed in the `VERSION` environment variable can be any version number accepted by the type of package +being built. As a general rule, it needs to start with a digit, and must include a `.` somewhere. + +Once it finishes, the built packages can be found under `artifacts/` in the source tree. + +If an error is encountered and the build is being run interactively, it will drop to a shell to allow you to +inspect the state of the container and look at build logs. + +### Detailed explanation + +The environments used for building our packages are fully self-contianed Docker images built from [Dockerfiles](https://github.com/netdata/helper-images/tree/master/package-builders) +These are published on Docker +Hub with the image name `netdata/package-builders`, and tagged using the name and version of the distribution +(with the tag corresponding to the suffix on the associated Dockerfile). + +The build code expects the following requirements to be met: + +- It expects the source tree it should build from to be located at `/netdata`, and expects that said source tree + is clean (no artifacts left over from previous builds). +- It expects an environment variable named `VERSION` to be defined, and uses this to control what version number + will be shown in the package metadata and filenames. + +Internally, the source tree gets copied to a temporary location for the build process so that the source tree can +be mounted directly from the host without worrying about leaving a dirty tree behind, any templating or file +movements required for the build to work are done, the package build command is invoked with the correct arguments, +and then the resultant packages are copied to the `artifacts/` directory in the original source tree so they are +accessible after the container exits. + +## Finding build logs after a failed build + +Build logs and artifacts can be found in the build directory, whose location varies by distribution. + +On DEB systems (Ubuntu and Debian), the build directory inside the container is located at `/usr/src/netdata` + +On RPM systems except openSUSE, the build directory inside the container is located under `/root/rpmbuild/BUILD/` +and varies based on the package version number. + +On openSUSE, the build directory inside the container is located under `/usr/src/packages/BUILD`and varies based +on the package version number. + +## Building for other architectures + +If you need to test a build for an architecture that does not match your host system, you can do so by setting up +QEMU user-mode emulation. This requires a Linux kernel with binfmt\_misc support (all modern distributions provide +this out of the box, but I’m not sure about WSL or Docker Desktop). + +The quick and easy way to do this is to run the following: + +```bash +docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + +or + +```bash +podman run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + +This will set up the required QEMU user-mode emulation until you reboot. Note that if using Podman, you will need +to run this as root and not as a rootless container (the package builds work fine in a rootless container though, +even if doing cross-architecture builds). + +Once you have that set up, the command to build the packages is the same as above, you just need to add a correct +`--platform` option to the `docker run` or `podman run` command. The current list of architectures we build for, +and the correct value for the `--platform` option is: + +- 32-bit ARMv7: `linux/arm/v7` +- 64-bit ARMv8: `linux/arm64/v8` +- 32-bit x86: `linux/i386` +- 64-bit x86: `linux/amd64` |