BUILDING-PACKAGES.md

   1 Building packages
   2 =================
   3
   4 PowerDNS uses the pdns-builder tool to generate packages for its products. The actual workflow can be found in the [builder-support](https://github.com/PowerDNS/pdns/tree/master/builder-support) directory of the git repository.
   5 The [build-tags.yml](https://github.com/PowerDNS/pdns/blob/master/.github/workflows/build-tags.yml) workflow automatically builds packages when a tag is pushed, so there is no need to trigger a manual build for releases, and actually doing so would be worse from a provenance point of view where full automation is always better.
   6
   7 Building packages on your own computer
   8 --------------------------------------
   9
  10 This requires a working Docker installation.
  11
  12 1. Clone our git repo (`git clone https://github.com/PowerDNS/pdns.git`)
  13 2. Check out the version you want, it can be a git tag like dnsdist-1.8.1, a git commit ID or branch
  14 3. Update submodules (`git submodule update --init --recursive`)
  15 4. Execute `builder/build.sh` to see what arguments it supports
  16 5. Then run `builder/build.sh` with the arguments you want (for example, `builder/build.sh -m recursor debian-bookworm`)
  17
  18 Building packages from GitHub actions
  19 -------------------------------------
  20
  21 You can build packages from your own fork of the PowerDNS repository. Go to the [PowerDNS/pdns](https://github.com/PowerDNS/pdns) repository and click on `Fork` at the top right of the screen. When asked if you would like to only copy the master branch, say no, as otherwise you will not be able to build packages from tagged releases. If you have already done so and have not done any modification to your fork, the easiest way is to delete and recreate it.
  22
  23 On your fork, go to the `Actions` tab. You will be greeted by a message stating `Workflows aren’t being run on this forked repository`. You can click `I understand my workflows, go ahead and enable them`.
  24
  25 Please be aware that by default some of the workflows are executed once every day, and enabling them will consume billing time our of your GitHub actions quota, although at the moment GitHub disables these by default: `This scheduled workflow is disabled because scheduled workflows are disabled by default in forks`.
  26
  27 On the left side, click on `Trigger specific package build`.
  28
  29 Locate the `Run workflow` dropdown item on the top right side of the screen, inside the blue region stating `This workflow has a workflow_dispatch event trigger.` It will open a menu with several options:
  30 - `Branch`: you can keep `master` here, unless you need to build for an operating system which is not in the list, in which case you will have to create a new branch and add the required file(s) for this OS. See `Adding a new OS` below.
  31 - `Product to build`: select the product you want to build packages for, for example `dnsdist`
  32 - `OSes to build for, space separated`: keep one or more OSes you want to build packages for, for example `ubuntu-focal`
  33 - `git ref to checkout`: the exact version you want to build. It can be the name of branch, a git tag or a git commit ID. Most likely you will be willing to build from a tagged release, like `dnsdist-1.8.1`.
  34 - `is this a release build?`: Keep `NO`
  35
  36 Click `Run workflow` to start the build.
  37
  38 If you reload the page, you should now see your build in progress as a `Trigger specific package build` workflow run. It will take some time to finish, but you can look at the progress by clicking on it.
  39
  40 Once it's done, you can retrieve the generated package in the list of artifacts on the `Summary` page of the workflow run, by clicking on the `Summary` link on the top right of the screen.
  41
  42 Adding a new OS to the list
  43 ---------------------------
  44
  45 Adding a new OS is usually easy, provided that it does not differ too much from an existing one. For example, to add support for Debian Bookworm (already present in the current repository), one had to:
  46
  47 Copy the existing instructions for Debian Buster:
  48 ```
  49 cp builder-support/dockerfiles/Dockerfile.target.debian-buster builder-support/dockerfiles/Dockerfile.target.debian-bookworm
  50 ```
  51
  52 In the new `builder-support/dockerfiles/Dockerfile.target.debian-bookworm` file, replace every occurence of `debian-buster` by `debian-bookworm`, and of `debian:buster` by `debian:bookworm`
  53
  54 Create symbolic links for the amd64 and arm64 versions:
  55 ```
  56 ln -s builder-support/dockerfiles/Dockerfile.target.debian-bookworm builder-support/dockerfiles/Dockerfile.target.debian-bookworm-amd64
  57 ln -s builder-support/dockerfiles/Dockerfile.target.debian-bookworm builder-support/dockerfiles/Dockerfile.target.debian-bookworm-arm64
  58 ```
  59
  60 Then add the new target to the list of OSes in the `.github/workflows/builder-dispatch.yml` workflow file:
  61 ```
  62 default: >-
  63   el-7
  64   el-8
  65   el-9
  66   debian-buster
  67   debian-bullseye
  68   debian-bookworm
  69   ubuntu-focal
  70   ubuntu-jammy
  71 ```
  72
  73 If release packages should be automatically built for this new target, then `.github/workflows/build-packages.yml` has to be updated as well:
  74 ``
  75 ```
  76 default: >-
  77   el-7
  78   el-8
  79   el-9
  80   debian-buster
  81   debian-bullseye
  82   debian-bookworm
  83   ubuntu-focal
  84   ubuntu-jammy
  85 ```
  86
  87 Not forgetting to update the list of hashes later in the same file:
  88 ```
  89 pkghashes-el-7: ${{ steps.pkghashes.outputs.pkghashes-el-7 }}
  90 pkghashes-el-8: ${{ steps.pkghashes.outputs.pkghashes-el-8 }}
  91 pkghashes-el-9: ${{ steps.pkghashes.outputs.pkghashes-el-9 }}
  92 pkghashes-debian-buster: ${{ steps.pkghashes.outputs.pkghashes-debian-buster }}
  93 pkghashes-debian-bullseye: ${{ steps.pkghashes.outputs.pkghashes-debian-bullseye }}
  94 pkghashes-debian-bookworm: ${{ steps.pkghashes.outputs.pkghashes-debian-bookworm }}
  95 pkghashes-ubuntu-focal: ${{ steps.pkghashes.outputs.pkghashes-ubuntu-focal }}
  96 pkghashes-ubuntu-jammy: ${{ steps.pkghashes.outputs.pkghashes-ubuntu-jammy }}
  97 ```