summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README385
1 files changed, 385 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..b46d0cf
--- /dev/null
+++ b/README
@@ -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>