debcargo-conf/README-PROXMOX.rst

==================================
 debcargo-conf README for Proxmox
==================================

Introduction
============
This repository is a fork of the Debian rust-team's debcargo-conf repository located at:

https://salsa.debian.org:rust-team/debcargo-conf

It should be periodically re-synced by merging the current master from salsa.

This repository tracks each crates packaging metadata in `src/$CRATE/debian`.
For most crates, only `d/copyright`, `d/copyright.debcargo.hint` (automatically
generated as template for `d/copyright`), `d/changelog` and `d/debcargo.toml`
are needed. If needed, patches and a quilt series file can be put into
`d/patches` as usual.

For more complicated crates, it is also possible to override `d/rules` or other
files from the packaging directory. Any file not contained in
`src/$CRATE/debian` will be automatically generated by the debcargo tool,
including `d/control` and, if applicable, `d/tests/control` for autopkgtests.

`README.rst` contains more detailed information, including how to setup sbuild
for proper integration into the build.sh script contained in this repository.
These instructions can also be used to create a schroot for a specific Debian
release for building (adding the Proxmox devel repository can be done using
`sbuild-shell`).

**Note**: crate names are *debianized* by replacing `_` with `-`, but the
scripts used in this repository all take the original crate name as argument.

Packaging
=========

New crates
----------

`./new-package.sh $CRATE`

`new-package.sh` (which is actually just a convenience symlink to `update.sh`
will download the crate from crates.io, extract it into the `build` directory,
generate the three default files in `src/$CRATE/debian`, and print some hints
on what to do next, such as filling out `d/copyright` based on the generated
hint file.

An old version of an existing crate
-----------------------------------

`./update.sh $CRATE $OLDVER`

Should be avoided if at all possible, e.g. by patching reverse dependencies to
become compatible with the current version. If really needed, passing the
version as argument to `update.sh` will generate a new directory in
`src/$CRATE-$VER`, with appropriately named source and binary packages. This
will only work if the current upstream version is already packaged.

Updating an existing crate
--------------------------

`./update.sh $CRATE`

`update.sh` will download the current upstream version from crates.io, update
`d/changelog` and `d/copyright.debcargo.hint` and provide hints about the next
steps (such as updating `d/copyright` with changed information).

Next steps
----------

`./update.sh` will also already prepare the crate for (test-) building in the
`build` directory, and can be re-run (e.g., after changing patches or any other
file in the packaging overlay directory).

Changelog handling
==================

The following dch command will amend the changelog for backporting to Debian
Buster based Proxmox products:

`DEBFULLNAME="Proxmox Support Team" DEBEMAIL="support@proxmox.com" dch -l ~bpo12+pve --distribution proxmox-rust --force-distribution "Backport to Debian Bookworm / Proxmox" --changelog src/$CRATE/debian/changelog`

Run `./repackage.sh $CRATE` or `./repackage.sh $CRATE $OLDVER` to regenerate
the files in `build` (you may have to delete the `build/$CRATE` directory first).

Building
========

After running `update.sh`, `new.sh` or `repackage.sh`, a copy of the crate
source code and the generated packaging files are available in `build`::

  $ ls src/proc-macro2/debian
  changelog
  copyright
  copyright.debcargo.hint
  debcargo.toml
  $ ./repackage.sh proc-macro2
  $ cd build
  $ ls
  build.sh
  proc-macro2
  rust-proc-macro2_1.0.7.orig.tar.gz
  $ ls proc-macro2/debian
  cargo-checksum.json
  changelog
  compat
  control
  copyright
  copyright.debcargo.hint
  debcargo.toml
  rules
  source
  tests
  watch

Using build.sh / sbuild
-----------------------

Running `./build.sh $CRATE` inside the `build` directory will build the crate
using `sbuild` with the default schroot `debcargo-unstable-amd64-sbuild`. To
build for another distribution, like Proxmox products based on Debian Buster,
the CHROOT and DISTRIBUTION environment variables can be set::

  CHROOT=debcargo-bookworm-amd64-sbuild DISTRIBUTION=bookworm ./build.sh $CRATE

The `IGNORE_MISSING_BUILD_DEPS` environment variable can be set to `1` to skip
checks for installed build dependencies on the host (sbuild of course still
needs them inside the build environment).

Binary packages needed for building which are not yet uploaded to the
repositories can be passed to the build environment as extra arguments::

  CHROOT=debcargo-bookworm-amd64-sbuild DISTRIBUTION=bookworm ./build.sh $CRATE $DEB1 $DEB2 $DEB3

By default, `build.sh` will run autopkgtests with additional dependencies as a
post-build step. This extra step can be disabled by setting the
`SKIP_AUTOPKGTEST` environment variable to `1`.

Using arbitrary builders
------------------------

`build.sh` can be used to generate a regular source package, which can then be
passed to any build software that can handle Debian source packages::

  SKIP_MISSING_BUILD_DEPS=1 SOURCEONLY=1 ./build.sh $CRATE

Using dpkg-buildpackage
-----------------------

The `build/$CRATE` directory contains a fully prepared unpacked Debian source
package, so entering it and calling `dpkg-buildpackage -b` should work
(provided all build dependencies are installed).

Further Reading
===============

Handling broken tests, extra build- or run-time dependencies, file exclusion
and much more are possible via `debcargo.toml`. A fully commented example is
available in `/usr/share/doc/debcargo/examples/debcargo.toml.example.gz`, and
some more concrete hints are available in upstream's `README.rst`.