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.

Note also most of them have changed significantly between devscripts
version 1.x and 2.x.

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

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

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

- debrelease: A wrapper around dupload which figures out which version
  to upload, and then calls dupload to actually perform the upload.

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

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

- debdiff: A program which examines two .deb files and reports on any
  difference found in their file lists.  Useful for ensuring that no
  files were inadvertantly lost between 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.

- debit: Like debi, but also runs debian-test to test the package
  after installation.

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

- debclean: Clean a Debian source tree.  Debclean will remove all
  files that were generated from the current directory and all
  directories below by calling debian/rules clean and removing .deb,
  .dsc and ..changes files.  It will keep important .diffs and
  original files, though, so that the binaries and other files can be
  rebuilt if necessary.

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

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

- dscverify: check the signature and MD5 sums of a dsc file against
  the most current Debian keyring on your system.

- plotchangelog: display information from a changelog graphically
  using gnuplot.

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

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


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.  Debpkg 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 priviledges.  "debuild" needs superuser
priviledges 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:

      chgrp root_group /usr/bin/debpkg
      chmod 4754 /usr/bin/debpkg

    after each upgrade (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!

    You can avoid having to do this on each upgrade by using
    suidmanager.  Devscripts fully supports suidmanager.  Make sure
    that the suidmanager package is installed and then run (as root):

      suidregister /usr/bin/debpkg root root_group 4754

    If you have some good reason not to use fakeroot it is also
    suggested that you run (as root):

      suidregister /usr/bin/debuild root root_group 4754

    The above method is recommended especially for the beginner for
    whom the other tools to gain superuser privileges may not be well
    known.  Only do this on your home linux box, NOT on a busy
    internet server!

Originally by Christoph Lameter <clameter@waterf.org>
Modified extensively by Julian Gilbey <jdg@debian.org>
