diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 385 |
1 files changed, 385 insertions, 0 deletions
@@ -0,0 +1,385 @@ +README for Debian devscripts package +==================================== + +Devscripts provides several scripts which may be of use to Debian +developers. The following gives a summary of the available scripts -- +please read the manpages for full details about the use of these +scripts. They are contributed by multiple developers; for details of +the authors, please see the code or manpages. + +Also, many of these scripts have dependencies on other packages, but +rather than burden the package with a large number of dependencies, +most of which will not be needed by most people, the individual +dependencies are listed as "Recommends" in the control file; lastly, +scripts that are unlikely to be used by many people have their dependencies +categorized as "Suggests" in the control file. This +ensures that the packages will be installed by default but allows +users to remove them if desired. The dependencies and recommendations +are listed in square brackets in the description below, as well as in +the Description field in the control file. +The scripts marked with an asterisk ('*') are considered "core", and as +such have their dependencies all listed as hard "Depends". + +And now, in alphabetical order, the scripts: + +- annotate-output: run a command and prepend time and stream (O for stdout, + E for stderr) for every line of output. + +- archpath: Prints arch (tla/Bazaar) package names. Also supports + calculating the package names for other branches. [tla | bazaar] + +- bts: A command-line tool for accessing the Debian Bug Tracking System, both + to send mails to control@bts.debian.org and to access the web pages and + SOAP interface of the BTS. [www-browser, libauthen-sasl-perl, + libnet-smtps-perl, libsoap-lite-perl, liburi-perl, libwww-perl, + bsd-mailx | mailx] + +- build-rdeps: Searches for all packages that build-depend on a given package. + [dctrl-tools, dose-extra, libdpkg-perl] + +- chdist: tool to easily play with several distributions. [dctrl-tools] + +- checkbashisms: check whether a /bin/sh script contains any common + bash-specific constructs. + +- cowpoke: upload a Debian source package to a cowbuilder host and build it, + optionally also signing and uploading the result to an incoming queue. + [ssh-client] + +- cvs-debi, cvs-debc: wrappers around debi and debc respectively (see below) + which allow them to be called from the CVS working directory. + [cvs-buildpackage] + +- cvs-debrelease: wrapper around debrelease which allows it to be called + from the CVS working directory. [cvs-buildpackage, dupload | dput, + ssh-client] + +- cvs-debuild: A wrapper for cvs-buildpackage to use debuild as its package + building program. [cvs-buildpackage, fakeroot, lintian, gnupg |gnupg2] + +- dcmd: run a given command replacing the name of a .changes or .dsc file + with each of the files referenced therein. * + +- dd-list: given a list of packages, pretty-print it ordered by maintainer. * + +- debbisect: bisect snapshot.debian.org to find which change in the archive + introduced a certain problem. [mmdebstrap, python3-debian] + +- debc: List contents of current package. Do this after a successful + "debuild" to see if the package looks all right. + +- debchange (abbreviation dch): Modifies debian/changelog and manages version + numbers for you. It will either increment the version number or add an + entry for the current version, depending upon the options given to it. + [libdistro-info-perl, libsoap-lite-perl]* + +- debcheckout: checkout the development repository of a Debian package. * + +- debclean: Clean a Debian source tree. Debclean will clean all Debian + source trees below the current directory, and if requested, also remove + all files that were generated from these source trees (that is .deb, .dsc + and .changes files). It will keep the .diffs and original files, though, + so that the binaries and other files can be rebuilt if necessary. + [fakeroot]* + +- debcommit: Commits changes to cvs, darcs, svn, svk, tla, bzr, git, or hg, + using new entries in debian/changelog as the commit message. Also supports + tagging Debian package releases. [cvs | darcs | subversion | svk | tla | + bzr | git-core | mercurial, libtimedate-perl] + +- debdiff: A program which examines two .deb files or two .changes files and + reports on any difference found in their file lists. Useful for ensuring + that no files were inadvertently lost between versions. Can also examine + two .dsc files and report on the changes between source versions. + For a deeper comparison one can use the diffoscope package. + [wdiff, patchutils]* + +- debdiff-apply: Apply unified diffs of two Debian source packages, such as + those generated by debdiff, to a target Debian source package. Any changes + to debian/changelog are dealt with specially, to avoid the conflicts that + changelog diffs typically produce when applied naively. May be used to check + that old patches still apply to newer versions of those packages. + [python3-debian, python3-unidiff, quilt] + +- debi: Installs the current package by using the setuid root debpkg + script described below. It assumes that the current package has + just been built (for example by debuild), and the .deb lives in the + parent directory, and will effectively run dpkg -i on the .deb. The + ability to install the package with a very short command is very + useful when troubleshooting packages. + +- debpkg: A wrapper for dpkg used by debi to allow convenient testing + of packages. For debpkg to work, it needs to be made setuid root, + and this needs to be performed by the sysadmin -- it is not + installed as setuid root by default. (Note that being able to run a + setuid root debpkg is effectively the same as having root access to + the system, so this should be done with caution.) Having debpkg as + a wrapper for dpkg can be a Good Thing (TM), as it decreases the + potential for damage by accidental wrong use of commands in + superuser mode (e.g., an inadvertent rm -rf * in the wrong directory + is disastrous as many can attest to). + +- debrelease: A wrapper around dupload or dput which figures out which + version to upload, and then calls dupload or dput to actually perform + the upload. [dupload | dput, ssh-client] + +- debrebuild: A script that provided a .buildinfo file reports the + instructions on how to try to reproduce the reported build. + [sbuild | mmdebstrap, libdistro-info-perl] + +- debrepro: A script that tests reproducibility of Debian packages. It will + build a given source directory twice, with a set of variation between the + first and second build, and compare the binary packages produced. If + diffoscope is installed, it is used to compare non-matching binaries. If + disorderfs is installed, it is used during the build to inject + non-determinism in filesystem listing operations. + [faketime, diffoscope, disorderfs] + +- debrsign: This transfers a .changes/.dsc pair to a remote machine for + signing, and runs debsign on the remote machine over an SSH connection. + [gnupg | gnupg2, debian-keyring, ssh-client] + +- debsign: Use GNU Privacy Guard to sign the changes (and possibly dsc) + files created by running dpkg-buildpackage with no-sign options. Useful + if you are building a package on a remote machine and wish to sign it on + a local one. This script is capable of automatically downloading the + .changes and .dsc files from a remote machine. [gnupg |gnupg2, + debian-keyring, ssh-client]* + +- debsnap: grab packages from https://snapshot.debian.org [libwww-perl, + libjson-perl] + +- debuild: A wrapper for building a package (i.e., dpkg-buildpackage) to + avoid problems with insufficient permissions and wrong paths etc. + Debuild will set up the proper environment for building a package. + Debuild will use the fakeroot program to build the package by default, but + can be instructed to use any other gain-root command, or can even be + installed setuid root. Debuild can also be used to run various of + the debian/rules operations with the same root-gaining procedure. + Debuild will also run lintian to check that the package does not + have any major policy violations. [fakeroot, lintian, gnupg | gnupg2]* + +- deb-reversion: increases a binary package version number and repacks the + package, useful for porters and the like. + +- deb-why-removed: shows the reason a package was removed from the archive. + [libdpkg-perl] + +- dep3changelog: generate a changelog entry from a DEP3-style patch header. + +- desktop2menu: given a freedesktop.org desktop file, generate a skeleton + for a menu file. [libfile-desktopentry-perl] + +- dget: Downloads Debian source and binary packages. Point at a .changes or + .dsc to download all references files. Specify a package name to download + it from the configured apt repository. [wget | curl] + +- diff2patches: extracts patches from a .diff.gz file placing them under + debian/ or, if present, debian/patches. [patchutils] + +- dpkg-depcheck, dpkg-genbuilddeps: Runs a specified command (such as + debian/rules build) or dpkg-buildpackage, respectively, to determine the + packages used during the build process. This information can be helpful + when trying to determine the packages needed in the Build-Depends etc. + lines in the debian/control file. [build-essential, strace] + +- dscextract: extract a single file from a Debian source package. [patchutils] + +- dscverify: check the signature and MD5 sums of a dsc file against the most + current Debian keyring on your system. [gnupg | gnupg2, debian-keyring] + +- edit-patch: add/edit a patch for a source package and commit the changes. + [quilt | dpatch | cdbs] + +- getbuildlog: download package build logs from Debian auto-builders. [wget] + +- git-deborig: try to produce Debian orig.tar using git-archive(1). + [libdpkg-perl, libgit-wrapper-perl, liblist-compare-perl, + libstring-shellquote-perl, libtry-tiny-perl] + +- grep-excuses: grep britney's excuses to find out what is happening to your + packages. [libdbd-pg-perl, libterm-size-perl, libyaml-syck-perl, wget, w3m] + +- hardening-check: report the hardening characteristics of a set of binaries. + +- list-unreleased: searches for packages marked UNRELEASED in their + changelog. + +- ltnu (Long Time No Upload): List all uploads of packages by the + given uploader or maintainer and display them ordered by the last + upload of that package, oldest uploads first. + +- manpage-alert: locate binaries without corresponding manpages. [man-db] + +- mass-bug: mass-file bug reports. [bsd-mailx | mailx] + +- mergechanges: merge .changes files from the same release but built + on different architectures. + +- mk-build-deps: Given a package name and/or control file, generate a binary + package which may be installed to satisfy the build-dependencies of the + given package. [equivs] + +- mk-origtargz: Rename upstream tarball, optionally changing the compression + and removing unwanted files. + [libfile-which-perl, unzip, xz-utils, file] + +- namecheck: Check project names are not already taken. + +- nmudiff: prepare a diff of this version (presumably an NMU against the + previously released version (as per the changelog) and submit the diff + to the BTS. [patchutils, mutt] + +- origtargz: fetch the orig tarball of a Debian package from various sources, + and unpack it. [pristine-tar] + +- plotchangelog: display information from a changelog graphically using + gnuplot. [libtimedate-perl, gnuplot] + +- pts-subscribe: subscribe to the PTS (Package Tracking System) for a + limited period of time. [bsd-mailx | mailx, at] + +- rc-alert: list installed packages which have release-critical bugs. + [wget | curl] + +- reproducible-check: reports on the reproducible status of installed + packages. For more details please see <https://reproducible-builds.org>. + +- rmadison: remotely query the Debian archive database about packages. + [liburi-perl, wget | curl] + +- sadt: run DEP-8 tests. [python3-debian] + +- salsa: manipulates salsa.debian.org repositories and users + [libgitlab-api-v4-perl] + +- suspicious-source: output a list of files which are not common source + files. [python3-magic] + +- svnpath: Prints the path to the Subversion repository of a Subversion + checkout. Also supports calculating the paths for branches and + tags in a repository independent fashion. Used by debcommit to generate + svn tags. [subversion] + +- tagpending: runs from a Debian source tree and tags bugs that are to be + closed in the latest changelog as pending. [libsoap-lite-perl] + +- transition-check: Check a list of source packages for involvement in + transitions for which uploads to unstable are currently blocked. + [libwww-perl, libyaml-syck-perl] + +- uscan: Automatically scan for and download upstream updates. Uscan can + also call a program such as uupdate to attempt to update the Debianised + version based on the new update. Whilst uscan could be used to release + the updated version automatically, it is probably better not to without + testing it first. Uscan can also verify detached OpenPGP signatures if + upstream's signing key is known. [file, gpgv | gpgv2, gnupg | gnupg2, + libfile-dirlist-perl, libfile-touch-perl, libfile-which-perl, + liblwp-protocol-https-perl, libmoo-perl, libwww-perl, unzip, xz-utils]* + +- uupdate: Update the package with an archive or patches from + an upstream author. This will be of help if you have to update your + package. It will try to apply the latest diffs to your package and + tell you how successful it was. [patch] + +- what-patch: determine what patch system, if any, a source package is using. + [patchutils] + +- whodepends: check which maintainers' packages depend on a package. + +- who-permits-upload: Retrieve information about Debian Maintainer access + control lists. [gnupg | gnupg2, libencode-locale-perl, libwww-perl, + debian-keyring] + +- who-uploads: determine the most recent uploaders of a package to the Debian + archive. [gnupg | gnupg2, debian-keyring, debian-maintainers, wget] + +- wnpp-alert: list installed packages which are orphaned or up for adoption. + [wget | curl] + +- wnpp-check: check whether there is an open request for packaging or + intention to package bug for a package. [wget | curl] + +- wrap-and-sort: wrap long lines and sort items in packaging files. + [python3-debian] + +- /usr/share/doc/devscripts/examples: This directory contains examples of + procmail and exim scripts for sorting mail arriving to Debian + mailing lists. + +Typical Maintenance cycle with devscripts +----------------------------------------- + +1. cd <source directory of package> + +2. Editing of files + +3. Log the changes with: dch -i "I changed this" + If desired, use debcommit to commit changes to cvs, svn, arch or git. + +4. Run debuild to compile it. If it fails, return to 2. (You could + also just test the compilation by running the appropriate part of + debian/rules.) + +5. Check if package contents appear to be ok with "debc" + +6. Install the package with "debi" and test the functionality it + should provide. (Note that this step requires debpkg to be setuid + root, or you to be logged in as root or similar.) + +7. If all is ok release it by running debrelease. + +8. Optionally, use debcommit --release to commit and tag the release + in revision control. + + +Wrapper scripts +--------------- + +Devscripts includes two wrappers (the above mentioned "debuild" and +"debpkg") that are intended to make life easier for Debian developers. +These wrappers unset most environment variables for security reasons, +set a secure PATH and then run the appropriate program (such as dpkg). +Processing Makefiles is inherently dangerous though, since any UNIX +command can be executed. The fakeroot command makes it possible to +build a package in a secure way: it does not require any genuine root +access, but rather pretends that it has it. It is strongly +recommended that you install the "fakeroot" package! Installation of +a package with dpkg always requires superuser mode and is therefore +inherently dangerous. Debi aims to reduce the possibility of typos +by only performing a dpkg -i as root. This does not, however, do +anything for security, as there is no problem creating a package with +a setuid-root shell using fakeroot and then installing it with debpkg. +So only allow trusted users access to a setuid root debpkg, if at all! + +The wrappers have to be manually equipped to gain the necessary +privileges to do their jobs because of security concerns. You have to +equip "debpkg" with superuser privileges. "debuild" needs superuser +privileges only if fakeroot or another gain-root command is not +available. + +You can either: + +(a) invoke these wrappers from "sudo" or "super" or any other way you + have to control superuser access, or + +(b) you can set them up to be accessible only to a group of users. + (Some people suggest that this is highly dangerous since it + creates another executable that runs with the setuid root bit set + and which won't ever ask you for a password!) If you choose this + method, it can be done by issuing the following command: + + dpkg-statoverride --update --add root root_group 4754 /usr/bin/debpkg + + once (and similarly for debuild if you really need it). This will + enable access to debpkg for all users who are members of the group + "root_group". Remember that you are in effect giving those users + superuser access to your system! This information will be stored + in the dpkg database and remembered across upgrades. + + Because of the security implications, only do this on your home + Linux box, NOT on a busy internet server (and possibly not even + there). + +Originally by Christoph Lameter <clameter@waterf.org> +Modified extensively by Julian Gilbey <jdg@debian.org> |