README

   1 README for Debian devscripts package
   2 ====================================
   3
   4 Devscripts provides several scripts which may be of use to Debian
   5 developers.  The following gives a summary of the available scripts --
   6 please read the manpages for full details about the use of these
   7 scripts.  They are contributed by multiple developers; for details of
   8 the authors, please see the code or manpages.
   9
  10 Also, many of these scripts have dependencies on other packages, but
  11 rather than burden the package with a large number of dependencies,
  12 most of which will not be needed by most people, the individual
  13 dependencies are listed as "Recommends" in the control file.  This
  14 ensures that the packages will be installed by default but allows
  15 users to remove them if desired.  The dependencies and recommendations
  16 are listed in square brackets in the description below, as well as in
  17 the Description field in the control file.
  18
  19 And now, in mostly alphabetical order, the scripts:
  20
  21 - annotate-output: prepend time and stream (O for stdout E for sterr)
  22   for every line of output
  23
  24 - archpath: Prints arch (tla/Bazaar) package names. Also supports
  25   calculating the package names for other branches.
  26
  27 - bts: A command-line tool for accessing the BTS, both to
  28   send mails to control@bts.debian.org and to access the web pages and
  29   SOAP interface of the BTS. [www-browser, libauthen-sasl-perl,
  30   libnet-smtp-ssl-perl, libsoap-lite-perl, libwww-perl, bsd-mailx | mailx]
  31
  32 - build-rdeps: Searches for all packages that build-depend on a given package
  33   [dctrl-tools]
  34
  35 - chdist: A tool to easily play with several distributions. [dctrl-tools]
  36
  37 - checkbashisms: checks whether a /bin/sh script uses any common
  38   bash-specific features
  39
  40 - cowpoke: upload a Debian source package to a cowbuilder host and build it,
  41   optionally also signing and uploading the result to an incoming queue
  42   [ssh-client]
  43
  44 - cvs-debi, cvs-debc: wrappers around debi and debc respectively (see below)
  45   which allow them to be called from the CVS working directory.
  46   [cvs-buildpackage]
  47
  48 - cvs-debrelease: wrapper around debrelease which allows it to be called
  49   from the CVS working directory. [cvs-buildpackage, dupload | dput,
  50   ssh-client]
  51
  52 - cvs-debuild: A wrapper for cvs-buildpackage to use debuild as its package
  53   building program. [cvs-buildpackage, fakeroot, lintian, gnupg]
  54
  55 - dcmd: Run a given command replacing the name of a .changes or .dsc
  56   file with each of the files referenced therein
  57
  58 - dcontrol: Remotely query package and source control files for all Debian
  59   distributions. [liburl-perl, libwww-perl]
  60
  61 - dd-list: Given a list of packages, pretty-print it ordered by maintainer.
  62
  63 - debc: List contents of current package.  Do this after a successful
  64   "debuild" to see if the package looks all right.
  65
  66 - debchange (abbreviation dch): Modifies debian/changelog and manages version
  67   numbers for you.  It will either increment the version number or add a
  68   entry for the current version, depending upon the options given to it.
  69   [libparse-debcontrol-perl, libsoap-lite-perl,  lsb-release]
  70
  71 - debcheckout: checkout the development repository of a debian package
  72
  73 - debclean: Clean a Debian source tree.  Debclean will clean all Debian
  74   source trees below the current directory, and if requested, also remove
  75   all files that were generated from these source trees (that is .deb, .dsc
  76   and .changes files).  It will keep the .diffs and original files, though,
  77   so that the binaries and other files can be rebuilt if necessary.
  78   [fakeroot]
  79
  80 - debcommit: Commits changes to cvs, darcs, svn, svk, tla, bzr, git, or hg,
  81   using new entries in debian/changelog as the commit message. Also supports
  82   tagging Debian package releases. [cvs | darcs | subversion | svk | tla |
  83   bzr | git-core | mercurial]
  84
  85 - debdiff: A program which examines two .deb files or two .changes files and
  86   reports on any difference found in their file lists.  Useful for ensuring
  87   that no files were inadvertantly lost between versions.  Can also examine
  88   two .dsc files and report on the changes between source versions.
  89   [wdiff, patchutils]
  90
  91 - debi: Installs the current package by using the setuid root debpkg
  92   script described below.  It assumes that the current package has
  93   just been built (for example by debuild), and the .deb lives in the
  94   parent directory, and will effectively run dpkg -i on the .deb.  The
  95   ability to install the package with a very short command is very
  96   useful when troubleshooting packages.
  97
  98 - debpkg: A wrapper for dpkg used by debi to allow convenient testing
  99   of packages.  For debpkg to work, it needs to be made setuid root,
 100   and this needs to be performed by the sysadmin -- it is not
 101   installed as setuid root by default.  (Note that being able to run a
 102   setuid root debpkg is effectively the same as having root access to
 103   the system, so this should be done with caution.)  Having debpkg as
 104   a wrapper for dpkg can be a Good Thing (TM), as it decreases the
 105   potential for damage by accidental wrong use of commands in
 106   superuser mode (e.g., an inadvertant rm -rf * in the wrong directory
 107   is disastrous as many can attest to).
 108
 109 - debrelease: A wrapper around dupload or dput which figures out which
 110   version to upload, and then calls dupload or dput to actually perform
 111   the upload. [dupload | dput, ssh-client]
 112
 113 - debrsign: This transfers a .changes/.dsc pair to a remote machine for
 114   signing, and runs debsign on the remote machine over an SSH connection.
 115   [gnupg, debian-keyring, ssh-client]
 116
 117 - debsign: Use GNU Privacy Guard to sign the changes (and possibly dsc)
 118   files created by running dpkg-buildpackage with no-sign options.  Useful
 119   if you are building a package on a remote machine and wish to sign it on
 120   a local one.  This script is capable of automatically downloading the
 121   .changes and .dsc files from a remote machine. [gnupg, debian-keyring,
 122   ssh-client]
 123
 124 - debsnap: Grabs packages from http://snapshot.debian.net [wget]
 125
 126 - debuild: A wrapper for building a package (i.e., dpkg-buildpackage) to
 127   avoid problems with insufficient permissions and wrong paths etc.
 128   Debuild will set up the proper environment for building a package.
 129   Debuild will use the fakeroot program to build the package by default, but
 130   can be instructed to use any other gain-root command, or can even be
 131   installed setuid root.  Debuild can also be used to run various of
 132   the debian/rules operations with the same root-gaining procedure.
 133   Debuild will also run lintian to check that the package does not
 134   have any major policy violations. [fakeroot, lintian, gnupg]
 135
 136 - deb-reversion: Increases a binary package version number and repacks
 137   the package, useful for porters and the like.
 138
 139 - desktop2menu: given a freedesktop.org desktop file, generate a skeleton
 140   for a menu file [libfile-desktopentry-perl]
 141
 142 - dget: Downloads Debian source and binary packages. Point at a .changes or
 143   .dsc to download all references files. Specify a package name to download
 144   it from the configured apt repository. [wget | curl]
 145
 146 - diff2patches: Extracts patches from a .diff.gz file placing them under
 147   debian/ or, if present, debian/patches. [patchutils]
 148
 149 - dpkg-depcheck, dpkg-genbuilddeps: Runs a specified command (such as
 150   debian/rules build) or dpkg-buildpackage, respectively, to determine the
 151   packages used during the build process.  This information can be helpful
 152   when trying to determine the packages needed in the Build-Depends etc.
 153   lines in the debian/control file. [build-essential, strace]
 154
 155 - dscverify: check the signature and MD5 sums of a dsc file against the most
 156   current Debian keyring on your system. [gnupg, debian-keyring,
 157   libdigest-md5-perl]
 158
 159 - getbuildlog: Download package build logs from Debian auto-builders. [wget]
 160
 161 - grep-excuses: grep the update_excuses.html file to find out what is
 162   happening to your packages. [libterm-size-perl, wget, w3m]
 163
 164 - licensecheck: given a list of source files, attempt to determine which
 165   license (or combination of licenses) each file is placed under.
 166
 167 - list-unreleased: searches for packages marked UNRELEASED in their
 168   changelog
 169
 170 - manpage-alert: locate binaries without corresponding manpages. [man-db]
 171
 172 - mass-bug: mass-file bug reports [bsd-mailx | mailx]
 173
 174 - mergechanges: merge .changes files from the same release but built
 175   on different architectures.
 176
 177 - mk-build-deps: Given a package name and/or control file, generate a
 178   binary package which may be installed to satisfy the build-dependencies
 179   of the given package. [equivs]
 180
 181 - namecheck: Check project names are not already taken.
 182
 183 - nmudiff: prepare a diff of this version (presumably an NMU against the
 184   previously released version (as per the changelog) and submit the diff
 185   to the BTS. [patchutils, mutt]
 186
 187 - plotchangelog: display information from a changelog graphically using
 188   gnuplot. [libtimedate-perl, gnuplot]
 189
 190 - pts-subscribe: subscribe to the PTS (Package Tracking System) for a
 191   limited period of time. [bsd-mailx | mailx, at]
 192
 193 - rc-alert: list installed packages which have release-critical bugs [wget]
 194
 195 - rmadison: Remotely query the Debian archive database about packages.
 196   [liburi-perl, wget | curl]
 197
 198 - svnpath: Prints the path to the suversion repository of a subversion
 199   checkout. Also supports calculating the paths for branches and
 200   tags in a repository independent fashion. Used by debcommit to generate
 201   svn tags. [subversion]
 202
 203 - tagpending: Runs from a Debian source tree and tags bugs that are to be
 204   closed in the latest changelog as pending. [libsoap-lite-perl]
 205
 206 - transition-check: Check a list of source packages for involvement in
 207   transitions for which uploads to unstable are currently blocked
 208   [libwww-perl, libyaml-syck-perl]
 209
 210 - uscan: Automatically scan for and download upstream updates.  Uscan can
 211   also call a program such as uupdate to attempt to update the Debianised
 212   version based on the new update.  Whilst uscan could be used to release
 213   the updated version automatically, it is probably better not to without
 214   testing it first. [libcrypt-ssleay-perl, libwww-perl, unzip, lzma, xz-utils]
 215
 216 - uupdate: Update the package with an archive or patches from
 217   an upstream author.  This will be of help if you have to update your
 218   package.  It will try to apply the latest diffs to your package and
 219   tell you how successful it was. [patch]
 220
 221 - whodepends: check which maintainers' packages depend on a package
 222
 223 - who-uploads: determine the most recent uploaders of a package to the
 224   Debian archive [gnupg, debian-keyring, debian-maintainers, wget]
 225
 226 - wnpp-alert: list installed packages which are orphaned or up for adoption
 227   [wget]
 228
 229 - wnpp-check: check whether there is an open request for packaging or
 230   intention to package bug for a package [wget]
 231
 232 - /usr/share/doc/devscripts/examples: This directory contains examples of
 233   procmail and exim scripts for sorting mail arriving to Debian
 234   mailing lists.
 235
 236 Typical Maintenance cycle with devscripts
 237 -----------------------------------------
 238
 239 1. cd <source directory of package>
 240
 241 2. Editing of files
 242
 243 3. Log the changes with: dch -i "I changed this"
 244    If desired, use debcommit to commit changes to cvs, svn, arch or git.
 245
 246 4. Run debuild to compile it.  If it fails, return to 2.  (You could
 247    also just test the compilation by running the appropriate part of
 248    debian/rules.)
 249
 250 5. Check if package contents appear to be ok with "debc"
 251
 252 6. Install the package with "debi" and test the functionality it
 253    should provide.  (Note that this step requires debpkg to be setuid
 254    root, or you to be logged in as root or similar.)
 255
 256 7. If all is ok release it by running debrelease.
 257
 258 8. Optionally, use debcommit --release to commit and tag the release
 259    in revision control.
 260
 261
 262 Wrapper scripts
 263 ---------------
 264
 265 Devscripts includes two wrappers (the above mentioned "debuild" and
 266 "debpkg") that are intended to make life easier for Debian developers.
 267 These wrappers unset most environment variables for security reasons,
 268 set a secure PATH and then run the appropriate program (such as dpkg).
 269 Processing Makefiles is inherently dangerous though, since any UNIX
 270 command can be executed.  The fakeroot command makes it possible to
 271 build a package in a secure way: it does not require any genuine root
 272 access, but rather pretends that it has it.  It is strongly
 273 recommended that you install the "fakeroot" package!  Installation of
 274 a package with dpkg always requires superuser mode and is therefore
 275 inherently dangerous.  Debi aims to reduce the possibility of typos
 276 by only performing a dpkg -i as root.  This does not, however, do
 277 anything for security, as there is no problem creating a package with
 278 a setuid-root shell using fakeroot and then installing it with debpkg.
 279 So only allow trusted users access to a setuid root debpkg, if at all!
 280
 281 The wrappers have to be manually equipped to gain the necessary
 282 privileges to do their jobs because of security concerns.  You have to
 283 equip "debpkg" with superuser privileges.  "debuild" needs superuser
 284 privileges only if fakeroot or another gain-root command is not
 285 available.
 286
 287 You can either:
 288
 289 (a) invoke these wrappers from "sudo" or "super" or any other way you
 290     have to control superuser access, or
 291
 292 (b) you can set them up to be accessible only to a group of users.
 293     (Some people suggest that this is highly dangerous since it
 294     creates another executable that runs with the setuid root bit set
 295     and which won't ever ask you for a password!)  If you choose this
 296     method, it can be done by issuing the following command:
 297
 298       dpkg-statoverride --update --add root root_group 4754 /usr/bin/debpkg
 299
 300     once (and similarly for debuild if you really need it).  This will
 301     enable access to debpkg for all users who are members of the group
 302     "root_group".  Remember that you are in effect giving those users
 303     superuser access to your system!  This information will be stored
 304     in the dpkg database and remembered across upgrades.
 305
 306     Because of the security implications, only do this on your home
 307     linux box, NOT on a busy internet server (and possibly not even
 308     there).
 309
 310 Originally by Christoph Lameter <clameter@waterf.org>
 311 Modified extensively by Julian Gilbey <jdg@debian.org>