README.md (5831B)
1 # taler-packaging ng 2 3 This directory contains the improved implementation of container-based 4 packaging for GNU Taler and associated packages. 5 6 The major improvement is that a component can be built *without* having to 7 rebuild every single package. 8 9 Instead, all dependencies are managed via apt. Each package is built in a 10 fresh environment, with build dependencies pulled in via apt. Previously built 11 packages are available via a file-based apt source. 12 13 Build-time dependencies are automatically installed, making sure that 14 missing build-time dependencies would be detected. 15 16 The packaging logic is also the same for Debian and Ubuntu. 17 18 ## Prerequisites 19 20 You need "podman". On Debian bookworm, you will get shitty performance unless you: 21 22 ``` 23 # apt install containers-storage 24 ``` 25 26 Then check with 27 28 ``` 29 # podman info --debug 30 ``` 31 32 that you get "graphDriverName: overlay" 33 34 If not, try 35 36 ``` 37 # podman system reset 38 ``` 39 40 (deletes all containers, enables reset of the storage layer). 41 42 43 ## Prerequisites for Cross-Builds 44 45 To build for other architecture, you need to install the following packages: 46 ``` 47 apt-get install qemu-user-static binfmt-support 48 ``` 49 50 ## Structure 51 52 * `packages/$DISTRO-$DISTRO_VERNAME`: Output folder for debian packages. 53 Also contains a `Packages.gz` metadata file generated by `dpkg-scanpackages` 54 so that this folder can be directly consumed as a trusted package source. 55 56 * `buildconfig/*`: Per-component configuration, see "Versions" below. 57 * `buildscripts/*`: Build scripts used during the package build steps. 58 * `distros/*`: Files for building for a specific distro. 59 * `server-side/*.sh`: Scripts that must be installed in taler-packaing@taler.net:$HOME 60 61 62 ## Versions 63 64 Each component is configured by these files in `buildconfig/`: 65 66 * `$component.giturl`: the upstream repository. 67 * `$component.tag`: the git tag that is built. It determines the version of the 68 resulting debian package. 69 * `$component.debpath`: the directory within the repository that contains the 70 `debian/` folder, relative to the repository root. Optional, defaults to the 71 repository root itself. 72 73 `debpath` exists so that one repository can provide several packages that are 74 built independently. Their tag files are separate, but the tags all come from 75 the same repository, so `upgrade` moves all of them to the same tag. This 76 affects every component built from `taler-typescript-core` 77 (`taler-wallet-cli`, `taler-harness` and the `*-webui` packages), each of which 78 has a `packages/$component` debpath. 79 80 Supported tag syntax (see `buildscripts/generic`): 81 82 * `v$maj.$min.$patch`, e.g. `v1.2.3`: release version. 83 * `v$maj.$min.$patch-dev.$n`, e.g. `v1.2.3-dev.4`: dev version. 84 * `deb-v$maj.$min.$patch-$revision`, e.g. `deb-v1.2.3-1`: release version with a 85 debian revision, for rebuilds that only change `debian/`. 86 87 Debian revisions of dev versions are *not* supported. Other tag formats occur 88 in some of the repositories (`debian-1.2.3`, `v1.2.3-debian-1`, `v1.2.3a`, ...) 89 and are ignored by `taler-pkg`. 90 91 Tags are ordered by major, minor and patch first. Within one release, dev 92 versions sort before the release and debian revisions after it: 93 94 ``` 95 v1.2.3-dev.1 < v1.2.3-dev.2 < v1.2.3 < deb-v1.2.3-1 < v1.2.4-dev.1 96 ``` 97 98 ### From git tag to debian version 99 100 `buildscripts/generic` derives the debian version of a package from the tag in 101 two steps. `get_tag_debver` strips the `v` / `deb-v` prefix and rewrites 102 `-dev.$n` into `~dev$n`, which sorts before the corresponding release. 103 `make_codename_version` then appends the distro codename. If the version has no 104 debian revision at that point, `-0` is inserted first: a plain `1.2.3+trixie` 105 would be *newer* than `1.2.3`, and `1.2.3~trixie` would be older than any real 106 `1.2.3-$revision`, so both would break version requirements in dependencies. 107 108 Examples, for codename `trixie`: 109 110 ``` 111 v1.2.3 => 1.2.3-0+trixie 112 v1.2.3-dev.4 => 1.2.3~dev4-0+trixie 113 v1.2.3-dev.10 => 1.2.3~dev10-0+trixie 114 deb-v1.2.3 => 1.2.3-0+trixie 115 deb-v1.2.3-1 => 1.2.3-1+trixie 116 ``` 117 118 The resulting versions sort the same way as the tags they come from, so bumping 119 a tag file always produces a package that apt considers newer: 120 121 ``` 122 1.2.3~dev1-0+trixie < 1.2.3~dev10-0+trixie < 1.2.3-0+trixie < 1.2.3-1+trixie 123 ``` 124 125 126 ## Recipes 127 128 ### Building for a distribution 129 130 ``` 131 ./taler-pkg build $DISTRO 132 ``` 133 134 ### Bumping component versions 135 136 ``` 137 # Show current vs. latest version 138 ./taler-pkg show-latest 139 140 # Show which tag files would change 141 ./taler-pkg upgrade --dry 142 143 # Bump all components to the latest release tag 144 ./taler-pkg upgrade 145 146 # Bump only some components 147 ./taler-pkg upgrade gnunet taler-exchange 148 149 # Also consider dev tags 150 ./taler-pkg upgrade --dev 151 152 # Set a version manually 153 echo $desired_version > buildconfig/$component.tag 154 ``` 155 156 `upgrade` looks at every `buildconfig/*.tag` file, queries the corresponding 157 repository for its tags and writes back the newest one. Without `--dev`, only 158 release and `deb-v` tags are considered, with `--dev` also dev tags. 159 160 Components are only bumped forwards. A tag file that already points to a 161 version newer than the newest candidate is left alone, which is what happens to 162 components pinned to a dev tag when running without `--dev`. Tag files with 163 unsupported syntax and components without a `.giturl` are also left alone. 164 165 Components that share a repository, i.e. those distinguished by a `debpath`, 166 always end up on the same tag. 167 168 `upgrade` only changes tag files; run `./taler-pkg build $DISTRO` afterwards. 169 170 ### Forcing a rebuild 171 172 ``` 173 rm packages/$distro/$component.built.tag 174 ``` 175 176 ### Adding a new distro 177 178 A new distro needs just needs a Dockerfile in ``distros/Dockerfile.$distro``. 179 180 181 ## Future Improvements 182 183 * caching (gradle, npm, ...) between builds 184 * git checkouts on host, allowing fully offline builds 185 * more automation for common tasks 186 * more distros