trunk/maint-guide/maint-guide.sgml

<!doctype debiandoc system>

<debiandoc>

 <book>

  <titlepag>

   <title>Debian New Maintainers Guide</title>

   <author>
   Josip Rodin <email/jrodin@jagor.srce.hr/
   </author>

   <version>version 0.7, <date></version>

   <copyright>
   <copyrightsummary>Copyright &copy; 1998 Josip Rodin.</copyrightsummary>

   <p>This document is licensed under the terms of GNU GPL v2 or higher. The
   documents that I have merged (and adapted to debhelper) are:

   <p>The New-Maintainer's Debian Packaging Howto, copyright &copy; 1997
   Will Lowe <email/lowe@debian.org/.
   <p>Freely redistributable in all electronic or other forms provided that
   this copyright notice is retained and that and content modifications from
   my original are clearly marked as such.
   <p>Contributions were also made to this document by Igor Grobman
   <email/igor@digicron.com/ and James A. Treacy <email/treacy@debian.org/.

   <p>Debmake manual (Making a Debian Package), copyright &copy; 1997
   Jaldhar Vyas <email/jaldhar@debian.org/.
   <p>Included are some tips picked up from the Debian Users and Developers
   mailing lists or suggested by readers.
   </copyright>

  </titlepag>

  <toc sect>

  <chapt id="start">Getting started "The Right Way"

  <p>This document will try to describe building of a Debian GNU/Linux package
  to the common Debian user (and wannabe developer) in common language, and
  well covered with working examples. There is an old Roman saying, <em>Longum
  iter est per preaecepta, breve et efficax per exempla!</em> (It's a long way
  by the rules, but short and efficient with examples!).

  <p>One of the things that makes Debian such a top-notch Linux distribution
  is its package system. While there is a vast quantity of software already
  in the Debian format, sometimes you need to install software that isn't.
  You may be wondering how you can make your own packages and perhaps you
  think it is a very difficult task. Well,  if you are a real novice on Linux,
  it is hard, but if you were rookie, you wouldn't be reading this doc now. :-)
  You do need to know a little about Unix programming but you certainly
  don't need to be a wizard.

  <sect id="needprogs">Programs you need for development

  <p>Before you start anything, you should make sure that you properly install
  some packages with <manref name="dpkg" section="8"> (ie. `dpkg -i package`).
  This document has been written while the 2.0 'hamm' distribution was the
  officially stable release of Debian, and 2.1 'slink' was frozen (to be
  released), and for safety reasons packages named here are the ones from 2.0.

  <p>Following packages come with standard installation of Debian 2.0, so
  you probably have them already. Still, you should check it with `dpkg -s
  package`.

  <list>
  <item><em>binutils</em> - these programs used to assemble and link
  object files - the stuff programs are made of. (see `info binutils`)

  <item><em>cpp</em> - the C preprocessor. (see <manref name="cpp" section="1">)

  <item><em>cpio</em> - this is an archiver like tar or zip. (see
  <manref name="cpio" section="1">)

  <item><em>dpkg-dev</em> - this package contains the tools needed to unpack,
  build and upload Debian source packages. It also contains the packaging
  and dpkg-internals manual. (see <manref name="dpkg-source" section="1">)

  <item><em>file</em> - this handy program can determine what type a file is.
  (see <manref name="file" section="1">)

  <item><em>fileutils</em> - the essential Linux utilities, like ls, chmod,
  rm and others. (see `info --file /usr/info/fileutils.info.gz`)

  <item><em>gcc</em> - the GNU C compiler. Most Linux programs are written
  in the C programming language. (see <manref name="gcc" section="1">)

  <item><em>libc6-dev</em> - the C libraries and header files gcc needs to
  link with to create object files. Although some programs still reccommend
  and/or use libc5, you are encouraged to use the newer version (libc6).
  (see `info libc`)

  <item><em>make</em> - usually creation of a program takes several steps.
  Rather than having to type out the same commands over and over again, you
  can use the make program to automate the process. (see `info make`)

  <item><em>patch</em> - this very useful utility will take file containing
  a difference listing (produced by the diff program) and apply it to the
  original file, producing a patched version. (see <manref name="patch" section="1">)

  <item><em>perl</em> - this is one of the most used interpreted scripting
  languages on today's un*x systems, often reffered to as "Unix's Swiss Army
  Chainsaw". (see <manref name="perl" section="1">)
  </list>

  <p>From the devel section of the distribution you'll probably need
  to install this yourself:

  <list>
  <item><em>fakeroot</em> and <em>libtricks</em> - these let you emulate
  being root which is neccessary for some parts of the build process.
  Currently under development, but do the work. (see <manref name="fakeroot" section="1">)

  <item><em>lintian</em> - this package can let you know of any common
  mistakes after you build the package, and explain the errors. Also
  requires diffstat, small utility that produces histograms from diff output.
  (see <manref name="lintian" section="1">, <manref name="diffstat" section="1">,
  /usr/doc/lintian/lintian.html/index.html)
  </list>

  <p>And from the utils section you'll need these packages:

  <list>
  <item><em>dh-make</em> and <em>debhelper</em> - dh-make is neccessary to
  create the skeleton of our example package, and it will use some the
  debhelper tools for creating packages. They are not essential for creation
  of packages, but it is <em>highly</em> recommended for new maintainers.
  It makes the whole process very much easier to start, and control
  afterwards. (see <manref name="dh_make" section="1">,
  <manref name="debhelper" section="1">, /usr/doc/debhelper/README)

  <item><em>debmake</em> and <em>devscripts</em> - these packages contain some
  programs that may be useful, but they are also not neccessary for building
  packages. debmake functions similar to dh-make, and devscripts is collection
  of scripts. (see <manref name="deb-make" section="1">, /usr/doc/devscripts/README.debian.gz)
  </list>

  <p>Finnally, these <em>very important</em> packages are in the doc section
  of the distribution:

  <list>
  <item><em>debian-policy</em> - includes the structure and contents of the
  archive, several OS design issues, Linux Filesystem Structure Standard,
  and the most important thing (for you) is that it describes requirements
  that each package must satisfy to be included in the distribution.
  (see /usr/doc/debian-policy/policy.html/index.html)

  <item><em>developers-reference</em> - for all matters not specifically
  about the technical details of packaging, like the structure of the
  archive, how to rename, orphan, pick up packages, how to do NMUs, how to
  manage bugs, when and where to upload etc.
  (see /usr/doc/developers-reference/developers-reference.html/index.html)

  <item><em>packaging-manual</em> - describes the technical aspects of
  creating Debian binary and source packages.
  (see /usr/doc/packaging-manual/packaging.html/index.html)
  </list>

  <p>Also you need the encryption package <manref name="pgp" section="1">
  to digitally <em>sign</em> your package. This is especially important if
  you want to distribute your package to other people (and you'll be doing
  that when your package gets included in Debian distribution). However,
  due to a rather wacky U.S. export law, you cannot simply download this
  from your nearest Debian ftp site. But, your FTP site will however have
  a file called README.non-us, which will tell you how to get a copy of
  pgp (hint: ftp://nonus.debian.org/debian-non-US/).

  <p>The short descriptions that are given above only serve to introduce
  you to what each package does. Before continuing please thoroughly read
  how to the documentation of each program, at least the standard usage.
  It may seem like heavy going now, but later on you'll be <em>very</em>
  glad you read it.

  <sect id="otherinfo">Other information

  <p>There are two types of packages you can make, source and binary.
  A source package contains code which you can compile into a program.
  A binary package contains just the finished program. Don't mix terms
  like source of the program and the source package of the program!
  Please read the other manuals if you need more details on terminology.

  <p>Debian uses the term 'maintainer' for person that makes packages,
  'author' for the person that made the program, and 'upstream maintainer'
  for the person who currently maintains that program. Usually author and
  the upstream maintainer are the same person - and sometimes even the
  maintainer is the same person. If you made a program, and want it to get
  in Debian, feel free to submit your application to become a maintainer.

  <p>After you build your package (or while doing that), you will have
  to become an official Debian maintainer if you wish your program to get
  into the next distribution (if the program is useful, why not?).
  That process is explained in Developer's Reference. Please read it.

  <chapt id="first">First steps

  <p>While the documentation at the <url name="Developers corner" id="http://www.debian.org/devel/">
  is not so clear about where and how should new maintainers start their
  work, this document will explain every little (at first maybe irrelevant)
  step, and help you create that first package, and to gain some experience
  in building next releases of that and maybe other packages later on.

  <sect id="choose">Choose your program.

  <p>You have probably chosen the package you want to build, but here are
  some pointers for you as the uninitiated:

  <list>
  <item>check if the package is in the distribution already. If you use the
  'stable' distribution, maybe it's best that you go to the
  <url name="package search page" id="http://www.debian.org/distrib/packages.html">.
  If you use <em>current</em> 'unstable' distribution, check it out with
  these commands:
  <example>
  dpkg -s program
  dpkg -l '*program*'
  </example>

  <item>consult the <url name="WNPP page" id="http://www.debian.org/doc/prospective-packages.html">
  to see if anyone else is building that same program. If so, contact the
  current maintainer if you feel you need to. If not - find another
  interesting program that nobody maintains.</item>

  <item>program <em>must</em> have a license, if possible free as according
  to the <url name="Debian Free Software Guidelines" id="http://www.debian.org/social_contract.html#guidelines">.
  If it doesn't conform to some of these rules, it still can be included in
  'contrib' or 'non-free' sections of Debian. If you are unsure about where
  should it go, ask on <email/debian-legal@lists.debian.org/.
  </item>

  <item>program certainly should <em>not</em> run setuid root, or even
  better - it shouldn't need to be setuid or setgid anything.</item>

  <item>program should not be a daemon, or something that goes in */sbin
  directories.</item>

  <item>program should result in binary executable form, don't try
  libraries yet.</item>

  <item>it should be well documented, or at least understandable
  (to anyone).</item>

  <item>you should contact program's author(s) to check if they agree
  with packaging it. It is important to be able to consult with author(s)
  about the program in case of any program specific problems, so don't
  try to package unmaintained pieces of software.</item>

  <item>and last but not the least, you must know that it works, and
  have it tried for some time.</item>
  </list>

  <p>Of course, these things are just safety measures, and intended to save
  you from rageous users if you do something wrong in some setuid ftp daemon...
  When you gain some more experience in packaging, you'll be able to do such
  packages, but even the most experienced developers consult debian-devel
  mailing list when they are in doubt. And people there will gladly help.

  <p>For more help about these, check in Developer's Reference.

  <sect id="getsrc">Get the program, and try it out.

  <p>So the first thing to do is to find and download the original package.
  I presume that you already have the source file that you picked up at
  the authors homepage. Linux sources usually come in tar/gzip format,
  with extension .tar.gz or .tgz, and usually contain the subdirectory
  called program-version and all the sources in it. If your program's
  source comes as some other sort of archive (for instance, the filename
  ends in <TT>.Z</TT> or <TT>.zip</TT>), unpack it with appropriate tools,
  or ask on debian-mentors if you're not sure how to unpack it correctly
  (hint: issue `file archive.extension`).

  <p>As an example, I'll use program named 'gentoo', an X11 GTK+ file
  manager.

  <p>Create subdirectory under /usr/local/src named as your program's name
  (/usr/local/src/gentoo in this case). Place the downloaded archive in it,
  and uncompress it with `tar -xzf gentoo-0.9.12.tar.gz`. That (a bit
  lenghty) proccess will make no output (except if there are any errors - 
  then you must download it again or check if it is really a tar/gzip
  archive), but you will get the sources unpacked in a subdirectory called
  'gentoo-0.9.12' in /usr/local/src/gentoo.

  <p>Change to that directory and <em>throughly</em> read the documentation.
  It is usually in files named README*, INSTALL*, *.lsm or *.html. In there
  you will find instructions on how to correctly compile and install the
  program (most probably to /usr/local/bin directory).

  <p>The process varies from program to program, but a lot of modern
  programs come with a `configure' script that configures the source under
  your system and makes sure that your system is in condition to compile it.
  After configuring (with `./configure`), programs are usually compiled
  with `make`, and get installed in destination directories by typing
  `make install`.
  
  <p>So, do compile, install and try that program, to make sure it works okay
  and doesn't break something else while it's installing or running.

  <sect id="naming">Stuff prior to `dh_make'

  <p>For the correct building of the program, you should move the source
  directory to &lt;packagename&gt;-&lt;version&gt;. As you can see, the
  example program gentoo doesn't need that, but maybe your program will.
  So, make the program's original name lowercase, if it already is not.
  If it consists of more than one word, contract them to one word or make
  an abbreviation. For example, program "John's little editor for X"
  package would be named johnledx or jle4x, or whatever you decide, as
  long as it's under some reasonable limit, like 15 characters.

  <p>Also check for the exact version of the program (not the package!).
  If that piece of software is not numbered with versions like X.Y.Z, but
  with release date, feel free to use date (if the date was 19th of
  December, 1998. use it US-like shortened, 19981219) as the version number.
  Some won't be numbered at all, in which case you should contact the
  upstream maintainer to see if they've got some other revision-tracking
  method.

  <p>Before you proceed to the dh_make proccess, you should set the
  $EMAIL environment variable to your e-mail address, and you'll do that
  by issuing this at in your shell (this is for bash):
  
  <p><example>
  export EMAIL=your.login@somewhere.net
  </example>

  <sect id="dh_make">Running `dh_make'

  <p>Make sure you're in the program source directory, and issue this:

  <p><example>
  dh_make
  </example>
   
  <p>Some information will come up. It will ask you what sort of package you
  want to create. Gentoo is a single binary package - it creates only one
  binary, and thus one .deb file - so we will select the first option, with
  the 's' key. As a new maintainer you are discouraged to create multi-binary
  packages, or the libraries, as explained earlier.

  <chapt id="modify">Modifying the source

  <p>When dh_make is finished, and you adjusted program's own Makefile,
  you can `cd ..` to see a new directory that has been created, and it is
  called 'gentoo-0.9.12.orig'. It contains the original source code which
  will hereafter remain untouched. The 'gentoo-0.9.12' directory still
  exists, and there you will make changes.

  <p>Normally, programs install themselves in the /usr/local subdirectories.
  But, Debian packages must not use that directory, since it is reserved for
  system administrator's (or user's) private use. This means that you have to
  take a look at gentoo's Makefile. This is the script <manref name="make" section="1">
  will use to automate building this program. For more details on Makefiles,
  look in <ref id="rules">.

  <p>Note that there isn't space here to go into <em>all</em> the details
  of fixing but here are a few problems you often run across.

  <sect id="destdir">The $DESTDIR problem

  <p><example>
  # Where to put binary on 'make install'?
  BIN     = /usr/local/bin
  # Where to put icons on 'make install'? Note: if you change this,
  # gentoo will not find the icons as it starts up. You're going to
  # have to alter gentoo's icon path (in the config window, "Paths"
  # tab) to get it work.
  ICONS   = /usr/local/lib/gentoo/
  </example>

  <p>Before all that, you should insert a new two lines that say:

  <p><example>
  # Edited for Debian GNU/Linux.
  DESTDIR =
  </example>
  because the build process requires it (will be explained later).

  <p>Then the Makefile mentions the location of the final binary. Just
  change that to this:
  <p><example>
  # Where to put binary on 'make install'?
  BIN     = $(DESTDIR)/usr/X11R6/bin
  </example>

  <p>But why in that directory, and not some other? Because Debian has
  defined some rules on where programs are to be installed. That is specified
  in Linux Filesystem Structure Standard (/usr/doc/debian-policy/fsstnd).
  So, we should install the binary in /usr/X11R6/bin instead of /usr/local/bin,
  and the man page (it doesn't exist here, but almost every program has one,
  so we'll make one later) in /usr/man/man1 instead of /usr/local/man/man1.

  <p>After that we have a bit harder situation. If you change one line to:

  <p><example>
  ICONS   = $(DESTDIR)/usr/share/gentoo/
  </example>
  which conforms to the policy, you will have to edit some real C sources.
  But where and what to search? You can find this out by issuing:
  <p><example>
  grep -n usr/local/lib *.[ch]
  </example>
  (in every subdirectory that contains .c and .h files). Grep will tell
  you the name of the file and the line in it, when he finds an occurence.
  Now edit those files and in those lines replace usr/local/lib with
  usr/share - and that is it. Just replace usr/local/lib with your location,
  and be very careful that you don't mess up the rest of the code, if you
  don't know much about programming in C. :-)

  <p>After that you should find the install target (search for line
  that starts with 'install:') and rename all references to directories
  other than ones defined at the top of the Makefile. In this case,
  it does that and polishes things up a bit. Previously, install target
  said:

  <p><example>
  # ----------------------------------------- Installation

  # You're going to have to be root to do this!
  install:        gentoo-target
                  install ./gentoo $(BIN)
                  install icons $(ICONS)
                  install gentoorc-example $(HOME)/.gentoorc
  </example>

  <p>After our change it says:
  <example>
  # ----------------------------------------- Installation

  # You're going to have to be root to do this!
  install:        gentoo-target
                  install -d $(BIN) $(ICONS) $(DESTDIR)/etc
                  install ./gentoo $(BIN)
                  install -m644 icons/* $(ICONS)
                  install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
                  install -d $(DESTDIR)/usr/doc/gentoo/html
                  cp -a docs/* $(DESTDIR)/usr/doc/gentoo/html
  </example>

  <p>A careful reader will notice that I changed 'gentoo' to 'gentoo-target'
  in the 'install:' line. That is called bug fix :-)

  <p>Whenever you make changes that are not specifically related to Debian
  package, be sure to send them to the upstream maintainer so they can be
  included in the next program revision.

  <sect id="nolibs">Differring libraries

  <p>There is one other common problem: libraries are often different from
  platform to platform. For example, Makefile can contain a reference to
  a library which doesn't exist on Debian. In that case, we need to change
  it to a library which does exist in Debian, and serves the same purpose.
  The best way is to comment out (<em>not to delete!</em>) those lines
  because there may be others that will try to compile on different platforms
  so that they can have some hints about what could be the problem.

  <p>So, if there is a line in your program's Makefile that says something
  like this (and your program doesn't compile):

  <p><example>
  LIBS = -lcurses -lsomething -lsomethingelse
  </example>

  <p>Change it to this, and it will most probably work:
  <p><example>
  LIBS = -lncurses -lsomething -lsomethingelse
  #LIBS = -lcurses -lsomething -lsomethingelse
  </example>

  <chapt id="crules">The debian/control and debian/rules file

  <p>There is a new subdirectory in gentoo-0.9.12, it is called 'debian'.
  There are a number of files in this directory. We will be editing these
  in order to customize the behavior of the package. The most important of
  them are 'control' and 'rules'.

  <sect id="control">the `control' file

  <p>This file contains various values which dpkg and dselect will use to
  manage the package. Here is the control file dh_make creates for us.

  <p><example>1 Source: gentoo
  2 Section: unknown
  3 Priority: optional
  4 Maintainer: Josip Rodin &lt;jrodin@jagor.srce.hr&gt;
  5 Standards-Version: 2.4.0.0
  6
  7 Package: gentoo
  8 Architecture: any
  9 Depends: ${shlibs:Depends}
  10 Description: Missing
  11 Missing
  </example>
  (I've added the line numbers.)

  <p>Lines 1-5 are the control information for the source package. Line 1
  is the name of the source package.

  <p>Line 2 is the section of the distribution this package goes into. Lets
  change it to x11.

  <p>Line 3 describes how important it is that the user install this package.
  As it is a normal priority package, but still pretty unstable, we'll leave
  it as optional. Section and priority are actually only used by dselect
  when it sorts packages and selects defaults. See the policy manual for
  guidance on what to set these fields to.

  <p>Line 4 is the name and email address of the maintainer.

  <p>Line 5 is the version of the Debian policy standards this package follows
  (two major versions of the installed debian-policy package).

  <p>Lines 7-11 are the control information for the binary package.

  <p>Line 7 is the name of the binary package.

  <p>Line 8 describes the CPU architecture the binary package was compiled
  for. We can leave this as any as <manref name="dpkg-gencontrol" section="1">
  will fill in the appropriate value.

  <p>Line 9 shows one of the most powerful features of the Debian packaging
  system. Packages can relate to each other in various ways. Apart from
  depends other relationship fields are Recommends:, Suggests:, Pre-depends:,
  Conflicts:, Provides:, and Replaces: . This is what they mean:

  <p><list>
  <item>Depends:
  <p><manref name="dpkg" section="8"> and <manref name="dselect" section="8">
  will not install your program unless the packages it depends on are
  installed. Use this if your program absolutely will not run unless a
  particular package is present.</item>

  <item>Recommends:
  <p><manref name="dselect" section="8"> will not install your package unless
  the packages it recommends are installed. <manref name="dpkg" section="8">
  will let you do it though. Use this for packages that are not strictly
  neccessary but are typically used with your program.</item>

  <item>Suggests:
  <p>When a user installs your program <manref name="dselect" section="8">
  will prompt him to install any package it suggests. <manref name="dpkg" section="8">
  doesn't care. Use this for packages which will work nicely with your
  program but are not neccessary.</item>

  <item>Pre-Depends:
  <p>This is stronger than depends. <manref name="dpkg" section="8"> and 
  <manref name="dselect" section="8"> will not install your package unless
  the packages it pre-depends on are installed <em>and correctly configured</em>.
  Use this very sparingly and only after discussing it on the debian-devel
  mailing list. Read: don't use it at all. :-)</item>

  <item>Conflicts:
  <p><manref name="dpkg" section="8"> and <manref name="dselect" section="8">
  will not install your program until all the packages it conflicts with have
  been removed.</item>

  <item>Provides:
  <p>For some types of packages where there are multiple alternatives virtual
  names have been defined. You can get the full list in /usr/doc/debian-policy/virtual-package-names-list.text.gz.
  Use this if your program provides a virtual package.</item>

  <item>Replaces:
  <p>Use this when your program replaces another package.
  <manref name="dpkg" section="8"> and <manref name="dselect" section="8">
  will remove replaced packages before installing yours.</item>
  </list>

  <p>All these fields have uniform syntax. They are a list of package names
  separated by commas. These package names may also be lists of alternative
  package names, separated by vertical bar symbols <tt>|</tt> (pipe symbols).
  The fields may restrict their applicability to particular versions of each
  named package. This is done in parentheses after each individual package
  name; the parentheses should contain a relation from the list below followed
  by a version number. The relations allowed are <tt>&lt;&lt;</tt>,
  <tt>&lt;=</tt>, <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for strictly
  earlier, earlier or equal, exactly equal, later or equal and strictly later,
  respectively.
  
  <p>The last feature I want to show you is $(shlibs:Depends). This will be
  automatically filled in by dh_shlibdeps (see later) with the names of any
  shared libraries, such as libc6 or xlib6g, your program uses, so you don't
  have to specify them yourself. Having said all that, we can leave line 9
  exactly as it is, because gentoo won't depend on any other package.

  <p>Line 10 is where the list of suggestions go. Here it is only the
  'menu', because gentoo should be in the X11 window managers' menus. This
  is controlled also by the file debian/menu. See <manref name="menufile"
  section="5">, <manref name="update-menus" section="1">.

  <p>Line 11 is the short description. Most people screens are 80 columns
  wide so this shouldn't be longer than about 50 characters. I'll change
  it to "A fully GUI configurable GTK+ file manager".

  <p>Line 12 is where the long description goes. This should be a paragraph
  which gives more detail about the package. Column 1 of each line should
  be empty. There must be no blank lines. Put a . in column 2 to simulate
  this. Also, there must be no blank lines after the long description.

  <p>Here is the updated control file:

  <p><example>
  1  Source: gentoo
  2  Section: x11
  3  Priority: optional
  4  Maintainer: Josip Rodin &lt;jrodin@jagor.srce.hr&gt;
  5  Standards-Version: 2.4.1.2
  6
  7  Package: gentoo
  8  Architecture: any
  9  Depends: ${shlibs:Depends}
  10 Suggests: menu (>= 1.5)
  11 Description: A fully GUI configurable GTK+ file manager
  12 gentoo is a file manager for Linux written from scratch in pure C. It
  13 uses the GTK+ toolkit for all of its interface needs. gentoo provides
  14 100% GUI configurability; no need to edit config files by hand and re-
  15 start the program. gentoo supports identifying the type of various
  16 files (using extension, regular expressions, or the 'file' command),
  17 and can display files of different types with different colors and icons.
  18 .
  19 gentoo borrows some of its look and feel from the classic Amiga file
  20 manager "Directory OPUS" (written by Jonathan Potter).
  </example>

  <sect id="rules">the `rules' file

  <p>Now we go back to the 'debian' directory to take a look at rules which
  <manref name="dpkg-buildpackage" section="1"> will use to actually create
  the package. This file is actually another Makefile, since it is executed
  with 'make -f', but different than the one in the upstream source.

  <p>Every 'rules' file, as any other Makefile, consists of several rules
  of how to build the source. Rules consist of targets, filenames or names
  of actions that should be carried out (for example, 'build:' or 'install:').
  Rules that you want to execute you should call as the command line arguments
  (for example, 'rules build' or 'rules install'). After the target name,
  you can name the dependency, program or file that that rule depends on.
  After that there can be any number of commands (starting with &lt;tab&gt;!),
  until an empty line is found. There begins another rule. Comments begin
  with hashes ('#'), and end with end of the line. You can invoke rules
  either from other rules or from command line (ie. `debian/rules clean`).

  <p>You are probably confused now, but it will all be clear upon examination
  of the 'rules' file that dh_make gives us as a default.

  <p><example>
  1  #!/usr/bin/make -f
  2  # Made with the aid of dh_make, by Craig Small
  3  # Sample debian/rules that uses debhelper. GNU copyright 1997 by Joey Hess.
  4  # Some lines taken from debmake, by Cristoph Lameter.
  5
  6  # Uncomment this to turn on verbose mode.
  7  #export DH_VERBOSE=1
  8
  9  build: build-stamp
  10 build-stamp:
  11    dh_testdir
  12
  13    
  14    # Add here commands to compile the package.
  15    $(MAKE)
  16
  17    touch build-stamp
  17
  18 clean:
  19    dh_testdir
  20    dh_testroot
  21    rm -f build-stamp install-stamp
  22
  23    # Add here commands to clean up after the build process.
  24    -$(MAKE) clean
  25
  26    dh_clean
  27
  28 install: install-stamp
  29 install-stamp: build-stamp
  30    dh_testdir
  31    dh_testroot
  32    dh_clean -k
  33    dh_installdirs
  34
  35    # Add here commands to install the package into debian/tmp.
  36    $(MAKE) install DESTDIR=`pwd`/debian/tmp
  37
  38    touch install-stamp
  39
  40 # Build architecture-independent files here.
  41 binary-indep: build install
  42 # We have nothing to do by default.
  43
  44 # Build architecture-dependent files here.
  45 binary-arch: build install
  46 #  dh_testversion
  47    dh_testdir
  48    dh_testroot
  49    dh_installdocs
  50    dh_installexamples
  51    dh_installmenu
  52 #  dh_installemacsen
  53 #  dh_installinit
  54    dh_installcron
  55    dh_installmanpages
  56 #  dh_undocumented
  57    dh_installchangelogs
  58    dh_strip
  59    dh_compress
  60    dh_fixperms
  61    dh_suidregister
  62    dh_installdeb
  63    dh_shlibdeps
  64    dh_gencontrol
  65 #  dh_makeshlibs
  66    dh_md5sums
  67    dh_builddeb
  68
  69 source diff:
  70    @echo >&2 'source and diff are obsolete - use dpkg-source -b'; false
  71
  72 binary: binary-indep binary-arch
  73 .PHONY: build clean binary-indep binary-arch binary
  </example>

  <p>You are probably familiar with lines like line 1 from shell and perl
  scripts. It means this file is to be run through make. Empty lines are
  ignored. Lines beggining with '#' (hash) are treated as comments and also
  ignored. Line 15 runs the applications own Makefile to compile the program.

  <p>Things rarely work perfectly the first time so lines 18-26 clean up any
  unneeded junk left over from previous failed attempts.

  <p>The installation process starts with line 28. In line 33, all neccessary
  directories are created in the 'debian' directory. Line 36 runs the install
  target from gentoo's Makefile - and installs in the debian/tmp directory -
  this is why we specified $(DESTDIR) as the root installation directory in
  gentoo's Makefile.

  <p>As the comments suggest, lines 40-42 are used to build architecture
  independant files.

  <p>Lines 45-67 run several small utilities from the debhelper package that
  do things to your package to make it conform to Debian policy.
  
  <p>The names start with dh_ and after that you can see what every little
  utility really does:

  <list>
  <item><manref name="dh_testdir" section="1"> check that you are in the
  right directory (/usr/local/gentoo/gentoo-0.9.12/),
  <item><manref name="dh_testroot" section="1"> checks that you have root
  permissions,
  <item><manref name="dh_installdirs" section="1"> creates directories
  mentioned in 'dirs' file [doesn't exist here],
  <item><manref name="dh_installdocs" section="1"> copies documentation to
  debian/tmp/usr/doc/gentoo directory,
  <item><manref name="dh_installmenu" section="1"> copies menu file to
  debian/tmp/usr/lib/menu/gentoo,
  <item><manref name="dh_installmanpages" section="1"> copies manpages and
  links them correctly,
  <item><manref name="dh_installchangelogs" section="1"> copies changelogs
  to debian/tmp/usr/doc/gentoo directory,
  <item><manref name="dh_installinit" section="1"> copies init.d script
  [doesn't exist here],
  <item><manref name="dh_installcron" section="1"> copies crontab script to
  debian/tmp/etc/cron.* [doesn't exist here],
  <item><manref name="dh_installexamples" section="1"> copies example files
  to debian/tmp/usr/doc/gentoo/examples [doesn't exist here],
  <item><manref name="dh_strip" section="1"> strips debugging headers from
  executable files to make them smaller,
  <item><manref name="dh_compress" section="1"> gzips man pages and
  documentation larger than 4 kb,
  <item><manref name="dh_fixperms" section="1"> checks and fixes invalid
  permissions in debian/tmp directory,
  <item><manref name="dh_suidregister" section="1"> sets up files to register
  setuid executables with <manref name="suidregister" section="8"> [doesn't exist here],
  <item><manref name="dh_installdeb" section="1"> copies package related
  files under debian/tmp directory,
  <item><manref name="dh_shlibdeps" section="1"> calculates dependencies
  of the executables,
  <item><manref name="dh_gencontrol" section="1"> generates and installes
  the control file,
  <item><manref name="dh_makeshlibs" section="1"> generates shared libs
  dependencies file [doesn't exist here],
  <item><manref name="dh_md5sums" section="1"> generates MD5 checksums, and
  finally,
  <item><manref name="dh_builddeb" section="1"> finally builds the package.
  </list>

  <p>Every one of these dh_* scripts has its own man page, for more
  information please read it. There are other dh_* scripts not mentioned
  here, and if you might need them, read the debhelper documentation.

  <p>Lines 69-73 are just macros used by the rules file and not important
  to know about.

  <p>The important part to know about the rules file created by dh_make is
  that it is just a suggestion. It will work for simple packages but for
  more complicated ones, don't be afraid to add and subtract from it to fit
  your needs. This especially applies to the binary-arch sections, where
  you should comment out lines that call features you don't need, in this
  case I'll comment out lines 50, 54 and 61 because gentoo doesn't need them.
  Only thing that you should not change are the names of the rules, because
  they are needed to be named this way because all the tools use these names.
  
  <p>Of course, some tuning is required here: on the line 57 I'll add 'FIXES'
  because that is the name of the changelog file. For any other option,
  please read the man page of called dh_* program.

  <chapt id="dother">Other files in debian/ dir

  <sect id="copyright">copyright

  <p>This file contains the packages copyright information. this is
  what the default dh_make creates looks like.

  <p><example>
  1  This package was debianized by Josip Rodin jrodin@jagor.srce.hr on
  2  Wed, 11 Nov 1998 21:02:14 +0100.
  3
  4  It was downloaded from &lt;fill in ftp site&gt;
  5
  6  Upstream Author(s): &lt;put author(s) name and email here&gt;
  7
  8  Copyright:
  9
  10 &lt;Must follow here&gt;
  </example>

  <p>The important things to add to this file are the place you got the
  package from and the actual copyright notice. If the copyright is one
  of the popular free software licenses such as GNU, BSD or the Artistic
  license, you should not include the entire text, you can just refer to
  the appropriate file in /usr/doc/copyright, that exists on every Debian
  system. Gentoo is licensed under the GNU public license, so we'll change
  the file to this:

  <p><example>
  1  This package was debianized by Josip Rodin jrodin@jagor.srce.hr on
  2  Wed, 11 Nov 1998 21:02:14 +0100.
  3
  4  It was downloaded from http://www.obsession.se/gentoo/
  5
  6  Upstream Author(s): Emil Brink &lt;emil@obsession.se&gt;
  7
  8  Copyright (c) Obsession Development, 1998.
  9
  10 gentoo is released under the GNU GPL license as free, open source soft-
  11 ware. Hopefully it will seem useful to someone. NO WARRANTY.
  12
  13 On Debian GNU/Linux systems, the complete text of the GNU General
  14 Public License can be found in /usr/doc/copyright/GPL'.
  </example>

  <sect id="readdeb">README.debian

  <p>Any extra details or discrepancies between the original package and
  your debianized version should be documented here. This is what the
  default dh_make creates looks like:

  <example>
  gentoo for DEBIAN
  ----------------------

  Comments regarding the Package

  Josip Rodin &lt;jrodin@jagor.srce.hr&gt;, Wed, 11 Nov 1998 21:02:14 +0100
  </example>

  <p>We don't particularly have anything to put there so we'll delete it.

  <sect id="changelog">changelog

  <p>As you keep working on a package behavior will change, new features
  will be added and bugs will be fixed. People downloading your package can
  look at this file and see what has changed. This is what the default
  changelog that dh_make creates looks like:

  <p><example>
  1  gentoo (0.9.12-1) unstable; urgency=low
  2
  3   * Initial Release.
  4
  5  -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 21:02:14 +0100
  6
  7  Local variables:
  8  mode: debian-changelog
  9  add-log-mailing-address: "jrodin@jagor.srce.hr"
  10 End:
  </example>

  <p>Line 1 is the package name, version, distribution, and urgency.
  Distribution should be unstable or experimental, and urgency shouldn't
  be changed to anything higher than 'low'. :-)
  
  <p>Lines 3-5 are a log entry, where you document changes made in this
  package revision (not the upstream changes - there is special file for
  that purpose). New lines must be inserted just before the uppermost line
  that begins with asterisk ('*'). You can do it with dch, emacs (lines
  7-10 are mode information for the Emacs editor), or just some text editor.
  You will end up with something like this:

  <p><example>
  1  gentoo (0.9.12-1) unstable; urgency=low
  2
  3   * Initial Release.
  4   * This is my first Debian package.
  5
  6  -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 21:02:14 +0100
  7
  8  Local variables:
  9  mode: debian-changelog
  10  add-log-mailing-address: "jrodin@jagor.srce.hr"
  11 End:
  </example>

  <p>When you release a new version, you should increment the version number.
  You can do that with 'dch -n &lt;comments&gt;', emacs or any text editor.
  Tip: how to easily get the date in this format? Use the
  <manref name="822-date" section="1"> program.
  New version information is added at the top of the changelog file. This is
  what the changelog looks like afterwards:

  <p><example>
  1  gentoo (0.9.12-2) unstable; urgency=low
  2
  3   * Comments about the second revision
  4
  5  -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 22:15:39 +0100
  6
  7  gentoo (0.9.12-1) unstable; urgency=low
  8
  9   * Initial Release.
  10  * This is my first Debian package.
  11
  12 -- Josip Rodin &lt;jrodin@jagor.srce.hr&gt; Wed, 11 Nov 1998 21:02:14 +0100
  13
  14 Local variables:
  15 mode: debian-changelog
  16 add-log-mailing-address: "jrodin@jagor.srce.hr"
  17 End:
  </example>

  <sect id="conffiles">conffiles

  <p>One of the most annoying things about software is when you spend a
  great deal of time and effort customizing a program only to have an
  upgrade stomp all over your changes. Debian solves this problem by
  marking configuration files so that when you upgrade a package you will
  be prompted whether you want to keep your old configuration or not. You
  do this by entering the full path to each configuration file (they are
  usually in /etc,) one per line in a file called conffiles. Gentoo has
  one conffile, /etc/gentoorc, and we'll enter that in the file.

  <sect id="dirs">dirs

  <p>This file specifies the directories which our package will create.
  By default, it looks like this:
  <p><example>
  1 usr/bin
  2 usr/sbin
  </example>

  <p>Note that the preceding slash is not included. We would have normally
  changed it to look like this:
  <p><example>
  1 usr/X11R6/bin
  2 usr/X11R6/man/man1
  </example>
  
  but those directories are already created on every system that has got
  X11R6 packages installed, so we won't need this.

  <sect id="maintscripts">postinst, preinst, postrm, prerm

  <p>These files are called maintainer scripts, and you should try to avoid
  maintainer scripts if you possibly can because they are too complex. For
  more information look in the Packaging Manual.

  <sect id="manpage">manpage.1.ex

  <p>The files ending in *.ex are examples of how to add that kind of
  support into the package. To use one of them, edit it and remove
  the .ex extension.

  <p>Your program should have a man page. If it doesn't, this is a skeleton
  you can fill out. See the man pages for <manref name="man" section="7">
  for a brief description of how to create a man page. Be sure to rename
  this file to the name of the program and make the extension the manual
  section it should go into. Here's a short list:

  <p><example>
  Section |     Description     |     Notes
     1     User commands          Executable commands or scripts.
     2     System calls           Functions provided by the kernel.
     3     Library calls          Functions within system libraries.
     4     Special files          Usually found in /dev
     5     File formats           E.g. /etc/passwd's format
     6     Games                  Or other frivolous programs
     7     Macro packages         Such as man macros.
     8     System administration  Programs typically only run by root.
     9     Kernel routines        Non-standard calls and internals.
  </example>
  
  <p>So gentoo's manpage should be called gentoo.1, or gentoo.1x because it
  is an X11 program. There was no gentoo.1 man page in the original source
  so I wrote it from the example.

  <sect id="menu">menu.ex

  <p>X Window users have a window manager with menus that can be customized
  to launch programs. If they have installed the Debian menu package,
  a set of menus for every program on the system will be created for them.
  It isn't required by Debian policy, but users will surely appreciate it.
  We can add Gentoo to the menus by editing this file. Here's the default
  that dh_make creates:
  
  <p><example>
  ?package(gentoo):needs=X11|text|vc|wm section=Apps/see-menu-manual\
    title="gentoo" command="/usr/bin/gentoo"
  </example>

  <p>The first field specifies what kind of interface the program needs
  (i.e. text or X11.) The next is the menu and submenu the entry should
  appear in. The current list of sections is in /usr/doc/menu/html/ch2.html#s2.2
  The third is the name of the program. The fourth is the icon for the
  program or none if there isn't one. The fifth is the actual text which
  will appear in the menu. The sixth is the command that runs the program.

  <p>Now we'll change the menu entry to this:
  <p><example>
  ?package(gentoo):needs=X11 section=Apps/Misc\
    title="gentoo" command="/usr/X11R6/bin/gentoo"
  </example>

  <sect id="watch">watch.ex

  <p>You can use this file in addition to the <manref name="uscan" section="1">
  and <manref name="uupdate" section="1"> programs (in the devscripts package)
  to watch the site you got the original source from. See the man pages for
  more details. Gentoo can't use this feature so we'll delete the file.

  <p>We are now finally ready to build the package...

  <chapt id="build">Building the package

  <p>Go into Gentoo's main directory (/usr/local/src/gentoo/gentoo-0.9.12/)
  and then issue this:
  <p><example>
  dpkg-buildpackage
  </example>

  <p>This will do everything for you, you'll just have to enter your
  PGP secret key, twice. After it's done, you will see four new files
  in /usr/local/gentoo directory:

  <p><list>
  <item><em>gentoo_0.9.12-1_i386.deb</em>
  <p>is the completed binary package. You can use dpkg or dselect to
  install and remove this just like any other package.

  <item><em>gentoo_0.9.12-1_i386.changes</em>
  <p>As you keep working on the package, behavior will change and new
  features will be added. People downloading your package can look at
  this file and see what has changed. The file is generated from the
  gentoo-0.9.12/debian/changelog file, it contains changes to current
  revision of the package). It also lists the files in the package. The
  long strings of numbers are MD5 sums for the file. Person downloading
  your files can test them with <manref name="md5sum" section="1"> and
  if the numbers don't match, they'll know the file is corrupt or has
  been hacked. This file is PGP signed, so that people can be even more
  sure that it's really yours.

  <item><em>gentoo_0.9.12.orig.tar.gz</em>
  <p>This is the original source code gathered up so that if someone else
  wants to recreate your package from scratch they can. Or if they aren't
  using Debian packaging system, but need to download the source and compile.

  <item><em>gentoo_0.9.12-1.dsc</em>
  <p>This is a summary of the contents of the source code. The file is
  generated from the gentoo-0.9.12/debian/control file, and is used when
  unpacking the source with <manref name="dpkg-source" section="1">. This
  file is PGP signed, so that people can be sure that it's really yours.
  </list>

  <sect id="errcheck">Checking your package for errors

  <p>Run <manref name="lintian" section="1"> on your .changes file; this
  program will check for many common packaging errors. The command is:
  
  <p><example>
  lintian -i gentoo_0.9.12-1_i386.changes
  </example>
  
  <p>If it appears that there are some errors (lines beginning with E:),
  read the explanation (the N: lines), correct mistakes, and rebuild with
  dpkg-buildpackage. If there are lines that begin with W:, those are only
  warnings, so you can be pretty much sure that your package is okay (but
  it sure needs some fine tuning).

  <p>Install the package to test it yourself. Try to install it on machines
  other than your own and watch closely for any errors.

  <p>When you build a new upstream version, you should do the following:

  <list>
  <item>upgrade from the previous version (and from the version in last
  Debian release),
  <item>downgrade back again.
  <item>install the package as a new package (i.e., with no previous version
  installed),
  <item>uninstall it, reinstall it again, and then purge it.
  </list>

  <sect id="upload">Uploading your package

  <p>Now that you have tested your new package throughly, you'll need to
  upload these files to master.debian.org, using <manref name="dupload" section="1">.
  First you have to set up dupload's config file. Copy the defaults from
  /etc to your home directory:
  
  <p><example>
  cp /etc/dupload.conf ~/.dupload.conf
  </example>

  <p>Then edit that file (~/.dupload.conf), find part that begins with
  '$cfg{master}' and change these lines (not neccessarilly in this order):
  <example>
          login => getlogin() || $ENV{USER} || $ENV{LOGNAME},
          visibleuser => getlogin() || $ENV{USER} || $ENV{LOGNAME},
          visiblename => "",
          fullname => "",
  </example>
  to values equivalent to these (change my settings to yours):
  <example>
          login => "joy",
          visibleuser => "jrodin",
          visiblename => "jagor.srce.hr",
          fullname => "Josip Rodin",
  </example>

  <p>Then connect to your internet provider, make sure once again that
  you are in /usr/local/src/gentoo directory, and issue this command:
  
  <p><example>
  dupload --to master gentoo_0.9.12-1_i386.changes
  </example>

  <p>Dupload will ask for your password on master.debian.org, upload the
  packages, and give a short announcement about your upload on
  <email/debian-devel-changes@lists.debian.org/.
  <p>If you live in Europe, you can use some other upload queues instead
  of master. For details look in <manref name="dupload" section="1">,
  <manref name="dupload" section="5"> and the Developer's Reference.

  <sect id="whereishelp">Where to ask for help

  <p>Before you decide to ask you question in some public place, please
  just RTFM. That includes documentation in /usr/doc/dpkg, /usr/doc/debian,
  /usr/doc/debhelper and the man/info pages for all the programs mentioned
  in this article. When you receive a bug report (yes actual bug reports!)
  you will know that it is time that you dig in to
  <url name="Debian Bug Tracking System" id="http://www.debian.org/Bugs/">
  and read the documentation there.

  <p>By joining the Debian Mentors' mailing list at <email/debian-mentors@lists.debian.org/
  you can team up with an experienced Debian developer who will help you
  with questions you might have. You can subscribe to it by sending e-mail
  to <email/debian-mentors-request@lists.debian.org/ with the word
  'subscribe' in the message body.

  <p>If you still have questions, ask on the Debian Developers' mailing list
  at <email/debian-devel@lists.debian.org/. You can subscribe to it by
  sending e-mail to <email/debian-devel-request@lists.debian.org/ with the
  word 'subscribe' in the message body.

  <p>Even if it all worked well, it's time to start praying. Why? Because
  in just a few hours (or days) users from all around the world will start
  to use your package, and if you made some critical error you'll get
  mailbombed by numerous angry Debian users... Just kidding. :-)

  <p>Relax and be ready for bug reports, because there is a lot more work
  to be done before it will be fully in line with Debian policies (once again,
  read the <em>real documentation</em> for details). Good luck!

 </book>

</debiandoc>