]>
Commit | Line | Data |
---|---|---|
4e88abc3 FG |
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-package.sh $CRATE` | |
40 | ||
41 | `new-package.sh` (which is actually just a convenience symlink to `update.sh` | |
42 | will 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 ~bpo12+pve --distribution proxmox-rust --force-distribution "Backport to Debian Bookworm / 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-bookworm-amd64-sbuild DISTRIBUTION=bookworm ./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-bookworm-amd64-sbuild DISTRIBUTION=bookworm ./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`. |