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 "Suggests" in the control file.  The
dependencies and recommendations are listed after the program name in
the description below, as well as in the Description field in the
control file.

And now, in mostly alphabetical order, the scripts:

- annotate-output: prepend time and stream (O for stdout E for sterr)
  for every line of output

- archpath: Prints arch (tla/Bazaar) package names. Also supports
  calculating the package names for other branches.

- bts [www-browser, libwww-perl, mailx | mailutils]: A command-line
  tool for accessing the BTS, both to send mails to
  control@bts.debian.org and to access the web pages of the BTS.

- checkbashisms: checks whether a /bin/sh script uses any common
  bash-specific features

- cvs-debi, cvs-debc [cvs-buildpackage]: wrappers around debi and debc
  respectively (see below) which allow them to be called from the CVS
  working directory.

- cvs-debrelease [cvs-buildpackage, dupload | dput, ssh]: wrapper
  around debrelease which allows it to be called from the CVS working
  directory.

- cvs-debuild [cvs-buildpackage, fakeroot, lintian | linda, gnupg]: A
  wrapper for cvs-buildpackage to use debuild as its package building
  program.

- dd-list: Given a list of packages, pretty-print it ordered by maintainer.

- debc: List contents of current package.  Do this after a successful
  "debuild" to see if the package looks all right.

- debchange (abbreviation dch) [libwww-perl]: 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.

- debclean [fakeroot]: 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.

- debcommit [cvs | subversion | tla | bazaar | git]: Commits changes to 
  cvs, svn, arch or git, using new entries in debian/changelog as the
  commit message. Also supports tagging Debian package releases.

- debdiff [wdiff, patchutils]: 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 inadvertantly
  lost between versions.  Can also examine two .dsc files and report
  on the changes between source versions.

- debi: Installs the current package by using the setuid root debpkg
  script described above.  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 inadvertant rm -rf * in the wrong directory
  is disastrous as many can attest to).

- debrelease [dupload | dput, ssh]: A wrapper around dupload or dput
  which figures out which version to upload, and then calls dupload or
  dput to actually perform the upload.

- debrsign [gnupg, debian-keyring, ssh]: This transfers a
  .changes/.dsc pair to a remote machine for signing, and runs debsign
  on the remote machine over an SSH connection.

- debsign [gnupg, debian-keyring, ssh]: 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.

- debuild [fakeroot, lintian | linda, gnupg]: 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.

- deb-reversion: Increases a binary package version number and repacks
  the package, useful for porters and the like.

- 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.

- dpkg-depcheck, dpkg-genbuilddeps [build-essential, strace]: 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.

- dscverify [gnupg, debian-keyring, libdigest-md5-perl]: check the
  signature and MD5 sums of a dsc file against the most current Debian
  keyring on your system.

- grep-excuses [wget]: grep the update_excuses.html file to find out
  what is happening to your packages.

- mass-bug [mailx | mailutils]: mass-file bug reports

- mergechanges: merge .changes files from the same release but built
  on different architectures.

- nmudiff [patchutils, mutt]: 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.

- plotchangelog [libtimedate-perl, gnuplot]: display information from
  a changelog graphically using gnuplot.

- pts-subscribe [mailx | mailutils, at]: subscribe to the PTS (Package
  Tracking System) for a limited period of time.

- rc-alert [wget]: list installed packages which have release-critical
  bugs

- rmadison [wget]: Remotely query the Debian archive database about
  packages.

- svnpath [subversion]: Prints the path to the suversion 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.

- tagpending [wget]: shell script which runs from a Debian source tree and
  tags bugs that are to be closed in the latest changelog as pending.

- uscan [libwww-perl]: 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.

- uupdate [patch]: 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.

- whodepends: check which maintainers' packages depend on a package

- who-uploads [gnupg, debian-keyring, wget]: determine the most recent
  uploaders of a package to the Debian archive

- wnpp-alert [wget]: list installed packages which are orphaned or up
  for adoption

- /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>