1README for Debian devscripts package
2====================================
3
4Devscripts provides several scripts which may be of use to Debian
5developers. The following gives a summary of the available scripts --
6please read the manpages for full details about the use of these
7scripts. They are contributed by multiple developers; for details of
8the authors, please see the code or manpages.
9
10Also, many of these scripts have dependencies on other packages, but
11rather than burden the package with a large number of dependencies,
12most of which will not be needed by most people, the individual
13dependencies are listed as "Recommends" in the control file; lastly,
14scripts that are unlikely to be used by many people have their dependencies
15categorized as "Suggests" in the control file. This
16ensures that the packages will be installed by default but allows
17users to remove them if desired. The dependencies and recommendations
18are listed in square brackets in the description below, as well as in
19the Description field in the control file.
20The scripts marked with an asterisk ('*') are considered "core", and as
21such have their dependencies all listed as hard "Depends".
22
23And now, in alphabetical order, the scripts:
24
25- annotate-output: run a command and prepend time and stream (O for stdout,
26 E for stderr) for every line of output.
27
28- archpath: Prints arch (tla/Bazaar) package names. Also supports
29 calculating the package names for other branches. [tla | bazaar]
30
31- bts: A command-line tool for accessing the Debian Bug Tracking System, both
32 to send mails to control@bts.debian.org and to access the web pages and
33 SOAP interface of the BTS. [www-browser, libauthen-sasl-perl,
34 libnet-smtps-perl, libsoap-lite-perl, liburi-perl, libwww-perl,
35 bsd-mailx | mailx]
36
37- build-rdeps: Searches for all packages that build-depend on a given package.
38 [dctrl-tools, dose-extra, libdpkg-perl]
39
40- chdist: tool to easily play with several distributions. [dctrl-tools]
41
42- checkbashisms: check whether a /bin/sh script contains any common
43 bash-specific constructs.
44
45- cowpoke: upload a Debian source package to a cowbuilder host and build it,
46 optionally also signing and uploading the result to an incoming queue.
47 [ssh-client]
48
49- cvs-debi, cvs-debc: wrappers around debi and debc respectively (see below)
50 which allow them to be called from the CVS working directory.
51 [cvs-buildpackage]
52
53- cvs-debrelease: wrapper around debrelease which allows it to be called
54 from the CVS working directory. [cvs-buildpackage, dupload | dput,
55 ssh-client]
56
57- cvs-debuild: A wrapper for cvs-buildpackage to use debuild as its package
58 building program. [cvs-buildpackage, fakeroot, lintian, gnupg |gnupg2]
59
60- dcmd: run a given command replacing the name of a .changes or .dsc file
61 with each of the files referenced therein. *
62
63- dd-list: given a list of packages, pretty-print it ordered by maintainer. *
64
65- debbisect: bisect snapshot.debian.org to find which change in the archive
66 introduced a certain problem. [mmdebstrap, python3-debian]
67
68- debc: List contents of current package. Do this after a successful
69 "debuild" to see if the package looks all right.
70
71- debchange (abbreviation dch): Modifies debian/changelog and manages version
72 numbers for you. It will either increment the version number or add an
73 entry for the current version, depending upon the options given to it.
74 [libdistro-info-perl, libsoap-lite-perl]*
75
76- debcheckout: checkout the development repository of a Debian package. *
77
78- debclean: Clean a Debian source tree. Debclean will clean all Debian
79 source trees below the current directory, and if requested, also remove
80 all files that were generated from these source trees (that is .deb, .dsc
81 and .changes files). It will keep the .diffs and original files, though,
82 so that the binaries and other files can be rebuilt if necessary.
83 [fakeroot]*
84
85- debcommit: Commits changes to cvs, darcs, svn, svk, tla, bzr, git, or hg,
86 using new entries in debian/changelog as the commit message. Also supports
87 tagging Debian package releases. [cvs | darcs | subversion | svk | tla |
88 bzr | git-core | mercurial, libtimedate-perl]
89
90- debdiff: A program which examines two .deb files or two .changes files and
91 reports on any difference found in their file lists. Useful for ensuring
92 that no files were inadvertently lost between versions. Can also examine
93 two .dsc files and report on the changes between source versions.
94 For a deeper comparison one can use the diffoscope package.
95 [wdiff, patchutils]*
96
97- debdiff-apply: Apply unified diffs of two Debian source packages, such as
98 those generated by debdiff, to a target Debian source package. Any changes
99 to debian/changelog are dealt with specially, to avoid the conflicts that
100 changelog diffs typically produce when applied naively. May be used to check
101 that old patches still apply to newer versions of those packages.
102 [python3-debian, python3-unidiff, quilt]
103
104- debi: Installs the current package by using the setuid root debpkg
105 script described below. It assumes that the current package has
106 just been built (for example by debuild), and the .deb lives in the
107 parent directory, and will effectively run dpkg -i on the .deb. The
108 ability to install the package with a very short command is very
109 useful when troubleshooting packages.
110
111- debpkg: A wrapper for dpkg used by debi to allow convenient testing
112 of packages. For debpkg to work, it needs to be made setuid root,
113 and this needs to be performed by the sysadmin -- it is not
114 installed as setuid root by default. (Note that being able to run a
115 setuid root debpkg is effectively the same as having root access to
116 the system, so this should be done with caution.) Having debpkg as
117 a wrapper for dpkg can be a Good Thing (TM), as it decreases the
118 potential for damage by accidental wrong use of commands in
119 superuser mode (e.g., an inadvertent rm -rf * in the wrong directory
120 is disastrous as many can attest to).
121
122- debrelease: A wrapper around dupload or dput which figures out which
123 version to upload, and then calls dupload or dput to actually perform
124 the upload. [dupload | dput, ssh-client]
125
126- debrebuild: A script that provided a .buildinfo file reports the
127 instructions on how to try to reproduce the reported build.
128 [sbuild | mmdebstrap, libdistro-info-perl]
129
130- debrepro: A script that tests reproducibility of Debian packages. It will
131 build a given source directory twice, with a set of variation between the
132 first and second build, and compare the binary packages produced. If
133 diffoscope is installed, it is used to compare non-matching binaries. If
134 disorderfs is installed, it is used during the build to inject
135 non-determinism in filesystem listing operations.
136 [faketime, diffoscope, disorderfs]
137
138- debrsign: This transfers a .changes/.dsc pair to a remote machine for
139 signing, and runs debsign on the remote machine over an SSH connection.
140 [gnupg | gnupg2, debian-keyring, ssh-client]
141
142- debsign: Use GNU Privacy Guard to sign the changes (and possibly dsc)
143 files created by running dpkg-buildpackage with no-sign options. Useful
144 if you are building a package on a remote machine and wish to sign it on
145 a local one. This script is capable of automatically downloading the
146 .changes and .dsc files from a remote machine. [gnupg |gnupg2,
147 debian-keyring, ssh-client]*
148
149- debsnap: grab packages from https://snapshot.debian.org [libwww-perl,
150 libjson-perl]
151
152- debuild: A wrapper for building a package (i.e., dpkg-buildpackage) to
153 avoid problems with insufficient permissions and wrong paths etc.
154 Debuild will set up the proper environment for building a package.
155 Debuild will use the fakeroot program to build the package by default, but
156 can be instructed to use any other gain-root command, or can even be
157 installed setuid root. Debuild can also be used to run various of
158 the debian/rules operations with the same root-gaining procedure.
159 Debuild will also run lintian to check that the package does not
160 have any major policy violations. [fakeroot, lintian, gnupg | gnupg2]*
161
162- deb-reversion: increases a binary package version number and repacks the
163 package, useful for porters and the like.
164
165- deb-why-removed: shows the reason a package was removed from the archive.
166 [libdpkg-perl]
167
168- dep3changelog: generate a changelog entry from a DEP3-style patch header.
169
170- desktop2menu: given a freedesktop.org desktop file, generate a skeleton
171 for a menu file. [libfile-desktopentry-perl]
172
173- dget: Downloads Debian source and binary packages. Point at a .changes or
174 .dsc to download all references files. Specify a package name to download
175 it from the configured apt repository. [wget | curl]
176
177- diff2patches: extracts patches from a .diff.gz file placing them under
178 debian/ or, if present, debian/patches. [patchutils]
179
180- dpkg-depcheck, dpkg-genbuilddeps: Runs a specified command (such as
181 debian/rules build) or dpkg-buildpackage, respectively, to determine the
182 packages used during the build process. This information can be helpful
183 when trying to determine the packages needed in the Build-Depends etc.
184 lines in the debian/control file. [build-essential, strace]
185
186- dscextract: extract a single file from a Debian source package. [patchutils]
187
188- dscverify: check the signature and MD5 sums of a dsc file against the most
189 current Debian keyring on your system. [gnupg | gnupg2, debian-keyring]
190
191- edit-patch: add/edit a patch for a source package and commit the changes.
192 [quilt | dpatch | cdbs]
193
194- getbuildlog: download package build logs from Debian auto-builders. [wget]
195
196- git-deborig: try to produce Debian orig.tar using git-archive(1).
197 [libdpkg-perl, libgit-wrapper-perl, liblist-compare-perl,
198 libstring-shellquote-perl, libtry-tiny-perl]
199
200- grep-excuses: grep britney's excuses to find out what is happening to your
201 packages. [libdbd-pg-perl, libterm-size-perl, libyaml-syck-perl, wget, w3m]
202
203- hardening-check: report the hardening characteristics of a set of binaries.
204
205- list-unreleased: searches for packages marked UNRELEASED in their
206 changelog.
207
208- ltnu (Long Time No Upload): List all uploads of packages by the
209 given uploader or maintainer and display them ordered by the last
210 upload of that package, oldest uploads first.
211
212- manpage-alert: locate binaries without corresponding manpages. [man-db]
213
214- mass-bug: mass-file bug reports. [bsd-mailx | mailx]
215
216- mergechanges: merge .changes files from the same release but built
217 on different architectures.
218
219- mk-build-deps: Given a package name and/or control file, generate a binary
220 package which may be installed to satisfy the build-dependencies of the
221 given package. [equivs]
222
223- mk-origtargz: Rename upstream tarball, optionally changing the compression
224 and removing unwanted files.
225 [libfile-which-perl, unzip, xz-utils, file]
226
227- namecheck: Check project names are not already taken.
228
229- nmudiff: prepare a diff of this version (presumably an NMU against the
230 previously released version (as per the changelog) and submit the diff
231 to the BTS. [patchutils, mutt]
232
233- origtargz: fetch the orig tarball of a Debian package from various sources,
234 and unpack it. [pristine-tar]
235
236- plotchangelog: display information from a changelog graphically using
237 gnuplot. [libtimedate-perl, gnuplot]
238
239- pts-subscribe: subscribe to the PTS (Package Tracking System) for a
240 limited period of time. [bsd-mailx | mailx, at]
241
242- rc-alert: list installed packages which have release-critical bugs.
243 [wget | curl]
244
245- reproducible-check: reports on the reproducible status of installed
246 packages. For more details please see <https://reproducible-builds.org>.
247
248- rmadison: remotely query the Debian archive database about packages.
249 [liburi-perl, wget | curl]
250
251- sadt: run DEP-8 tests. [python3-debian]
252
253- salsa: manipulates salsa.debian.org repositories and users
254 [libgitlab-api-v4-perl]
255
256- suspicious-source: output a list of files which are not common source
257 files. [python3-magic]
258
259- svnpath: Prints the path to the Subversion repository of a Subversion
260 checkout. Also supports calculating the paths for branches and
261 tags in a repository independent fashion. Used by debcommit to generate
262 svn tags. [subversion]
263
264- tagpending: runs from a Debian source tree and tags bugs that are to be
265 closed in the latest changelog as pending. [libsoap-lite-perl]
266
267- transition-check: Check a list of source packages for involvement in
268 transitions for which uploads to unstable are currently blocked.
269 [libwww-perl, libyaml-syck-perl]
270
271- uscan: Automatically scan for and download upstream updates. Uscan can
272 also call a program such as uupdate to attempt to update the Debianised
273 version based on the new update. Whilst uscan could be used to release
274 the updated version automatically, it is probably better not to without
275 testing it first. Uscan can also verify detached OpenPGP signatures if
276 upstream's signing key is known. [file, gpgv | gpgv2, gnupg | gnupg2,
277 libfile-dirlist-perl, libfile-touch-perl, libfile-which-perl,
278 liblwp-protocol-https-perl, libmoo-perl, libwww-perl, unzip, xz-utils]*
279
280- uupdate: Update the package with an archive or patches from
281 an upstream author. This will be of help if you have to update your
282 package. It will try to apply the latest diffs to your package and
283 tell you how successful it was. [patch]
284
285- what-patch: determine what patch system, if any, a source package is using.
286 [patchutils]
287
288- whodepends: check which maintainers' packages depend on a package.
289
290- who-permits-upload: Retrieve information about Debian Maintainer access
291 control lists. [gnupg | gnupg2, libencode-locale-perl, libwww-perl,
292 debian-keyring]
293
294- who-uploads: determine the most recent uploaders of a package to the Debian
295 archive. [gnupg | gnupg2, debian-keyring, debian-maintainers, wget]
296
297- wnpp-alert: list installed packages which are orphaned or up for adoption.
298 [wget | curl]
299
300- wnpp-check: check whether there is an open request for packaging or
301 intention to package bug for a package. [wget | curl]
302
303- wrap-and-sort: wrap long lines and sort items in packaging files.
304 [python3-debian]
305
306- /usr/share/doc/devscripts/examples: This directory contains examples of
307 procmail and exim scripts for sorting mail arriving to Debian
308 mailing lists.
309
310Typical Maintenance cycle with devscripts
311-----------------------------------------
312
3131. cd <source directory of package>
314
3152. Editing of files
316
3173. Log the changes with: dch -i "I changed this"
318 If desired, use debcommit to commit changes to cvs, svn, arch or git.
319
3204. Run debuild to compile it. If it fails, return to 2. (You could
321 also just test the compilation by running the appropriate part of
322 debian/rules.)
323
3245. Check if package contents appear to be ok with "debc"
325
3266. Install the package with "debi" and test the functionality it
327 should provide. (Note that this step requires debpkg to be setuid
328 root, or you to be logged in as root or similar.)
329
3307. If all is ok release it by running debrelease.
331
3328. Optionally, use debcommit --release to commit and tag the release
333 in revision control.
334
335
336Wrapper scripts
337---------------
338
339Devscripts includes two wrappers (the above mentioned "debuild" and
340"debpkg") that are intended to make life easier for Debian developers.
341These wrappers unset most environment variables for security reasons,
342set a secure PATH and then run the appropriate program (such as dpkg).
343Processing Makefiles is inherently dangerous though, since any UNIX
344command can be executed. The fakeroot command makes it possible to
345build a package in a secure way: it does not require any genuine root
346access, but rather pretends that it has it. It is strongly
347recommended that you install the "fakeroot" package! Installation of
348a package with dpkg always requires superuser mode and is therefore
349inherently dangerous. Debi aims to reduce the possibility of typos
350by only performing a dpkg -i as root. This does not, however, do
351anything for security, as there is no problem creating a package with
352a setuid-root shell using fakeroot and then installing it with debpkg.
353So only allow trusted users access to a setuid root debpkg, if at all!
354
355The wrappers have to be manually equipped to gain the necessary
356privileges to do their jobs because of security concerns. You have to
357equip "debpkg" with superuser privileges. "debuild" needs superuser
358privileges only if fakeroot or another gain-root command is not
359available.
360
361You can either:
362
363(a) invoke these wrappers from "sudo" or "super" or any other way you
364 have to control superuser access, or
365
366(b) you can set them up to be accessible only to a group of users.
367 (Some people suggest that this is highly dangerous since it
368 creates another executable that runs with the setuid root bit set
369 and which won't ever ask you for a password!) If you choose this
370 method, it can be done by issuing the following command:
371
372 dpkg-statoverride --update --add root root_group 4754 /usr/bin/debpkg
373
374 once (and similarly for debuild if you really need it). This will
375 enable access to debpkg for all users who are members of the group
376 "root_group". Remember that you are in effect giving those users
377 superuser access to your system! This information will be stored
378 in the dpkg database and remembered across upgrades.
379
380 Because of the security implications, only do this on your home
381 Linux box, NOT on a busy internet server (and possibly not even
382 there).
383
384Originally by Christoph Lameter <clameter@waterf.org>
385Modified extensively by Julian Gilbey <jdg@debian.org>
386