README-PROXMOX.rst

   1 ==================================
   2  debcargo-conf README for Proxmox
   3 ==================================
   4
   5 Introduction
   6 ============
   7 This repository is a fork of the Debian rust-team's debcargo-conf repository located at:
   8
   9 https://salsa.debian.org:rust-team/debcargo-conf
  10
  11 It should be periodically re-synced by merging the current master from salsa.
  12
  13 This repository tracks each crates packaging metadata in `src/$CRATE/debian`.
  14 For most crates, only `d/copyright`, `d/copyright.debcargo.hint` (automatically
  15 generated as template for `d/copyright`), `d/changelog` and `d/debcargo.toml`
  16 are needed. If needed, patches and a quilt series file can be put into
  17 `d/patches` as usual.
  18
  19 For more complicated crates, it is also possible to override `d/rules` or other
  20 files from the packaging directory. Any file not contained in
  21 `src/$CRATE/debian` will be automatically generated by the debcargo tool,
  22 including `d/control` and, if applicable, `d/tests/control` for autopkgtests.
  23
  24 `README.rst` contains more detailed information, including how to setup sbuild
  25 for proper integration into the build.sh script contained in this repository.
  26 These instructions can also be used to create a Debian Buster schroot for
  27 building (adding a the Proxmox devel repository can be done using
  28 `sbuild-shell`).
  29
  30 **Note**: crate names are *debianized* by replacing `_` with `-`, but the
  31 scripts used in this repository all take the original crate name as argument.
  32
  33 Packaging
  34 =========
  35
  36 New crates
  37 ----------
  38
  39 `./new.sh $CRATE`
  40
  41 `new.sh` (which is actually just a convenience symlink to `update.sh` will
  42 download the crate from crates.io, extract it into the `build` directory,
  43 generate the three default files in `src/$CRATE/debian`, and print some hints
  44 on what to do next, such as filling out `d/copyright` based on the generated
  45 hint file.
  46
  47 An old version of an existing crate
  48 -----------------------------------
  49
  50 `./update.sh $CRATE $OLDVER`
  51
  52 Should be avoided if at all possible, e.g. by patching reverse dependencies to
  53 become compatible with the current version. If really needed, passing the
  54 version as argument to `update.sh` will generate a new directory in
  55 `src/$CRATE-$VER`, with appropriately named source and binary packages. This
  56 will only work if the current upstream version is already packaged.
  57
  58 Updating an existing crate
  59 --------------------------
  60
  61 `./update.sh $CRATE`
  62
  63 `update.sh` will download the current upstream version from crates.io, update
  64 `d/changelog` and `d/copyright.debcargo.hint` and provide hints about the next
  65 steps (such as updating `d/copyright` with changed information).
  66
  67 Next steps
  68 ----------
  69
  70 `./update.sh` will also already prepare the crate for (test-) building in the
  71 `build` directory, and can be re-run (e.g., after changing patches or any other
  72 file in the packaging overlay directory).
  73
  74 Changelog handling
  75 ==================
  76
  77 The following dch command will amend the changelog for backporting to Debian
  78 Buster based Proxmox products:
  79
  80 `DEBFULLNAME="Proxmox Support Team" DEBEMAIL="support@proxmox.com" dch -l ~bpo10+pve --distribution proxmox-rust --force-distribution "Backport to Debian Buster / Proxmox" --changelog src/$CRATE/debian/changelog`
  81
  82 Run `./repackage.sh $CRATE` or `./repackage.sh $CRATE $OLDVER` to regenerate
  83 the files in `build` (you may have to delete the `build/$CRATE` directory first).
  84
  85 Building
  86 ========
  87
  88 After running `update.sh`, `new.sh` or `repackage.sh`, a copy of the crate
  89 source code and the generated packaging files are available in `build`::
  90
  91   $ ls src/proc-macro2/debian
  92   changelog
  93   copyright
  94   copyright.debcargo.hint
  95   debcargo.toml
  96   $ ./repackage.sh proc-macro2
  97   $ cd build
  98   $ ls
  99   build.sh
 100   proc-macro2
 101   rust-proc-macro2_1.0.7.orig.tar.gz
 102   $ ls proc-macro2/debian
 103   cargo-checksum.json
 104   changelog
 105   compat
 106   control
 107   copyright
 108   copyright.debcargo.hint
 109   debcargo.toml
 110   rules
 111   source
 112   tests
 113   watch
 114
 115 Using build.sh / sbuild
 116 -----------------------
 117
 118 Running `./build.sh $CRATE` inside the `build` directory will build the crate
 119 using `sbuild` with the default schroot `debcargo-unstable-amd64-sbuild`. To
 120 build for another distribution, like Proxmox products based on Debian Buster,
 121 the CHROOT and DISTRIBUTION environment variables can be set::
 122
 123   CHROOT=debcargo-buster-amd64-sbuild DISTRIBUTION=buster ./build.sh $CRATE
 124
 125 The `IGNORE_MISSING_BUILD_DEPS` environment variable can be set to `1` to skip
 126 checks for installed build dependencies on the host (sbuild of course still
 127 needs them inside the build environment).
 128
 129 Binary packages needed for building which are not yet uploaded to the
 130 repositories can be passed to the build environment as extra arguments::
 131
 132   CHROOT=debcargo-buster-amd64-sbuild DISTRIBUTION=buster ./build.sh $CRATE $DEB1 $DEB2 $DEB3
 133
 134 By default, `build.sh` will run autopkgtests with additional dependencies as a
 135 post-build step. This extra step can be disabled by setting the
 136 `SKIP_AUTOPKGTEST` environment variable to `1`.
 137
 138 Using arbitrary builders
 139 ------------------------
 140
 141 `build.sh` can be used to generate a regular source package, which can then be
 142 passed to any build software that can handle Debian source packages::
 143
 144   SKIP_MISSING_BUILD_DEPS=1 SOURCEONLY=1 ./build.sh $CRATE
 145
 146 Using dpkg-buildpackage
 147 -----------------------
 148
 149 The `build/$CRATE` directory contains a fully prepared unpacked Debian source
 150 package, so entering it and calling `dpkg-buildpackage -b` should work
 151 (provided all build dependencies are installed).
 152
 153 Further Reading
 154 ===============
 155
 156 Handling broken tests, extra build- or run-time dependencies, file exclusion
 157 and much more are possible via `debcargo.toml`. A fully commented example is
 158 available in `/usr/share/doc/debcargo/examples/debcargo.toml.example.gz`, and
 159 some more concrete hints are available in upstream's `README.rst`.