Manual for the librules helper                          -*- Text -*-
------------------------------
Last modified: 2004-01-01

This file documents an experimental new debian/rules helper, a
makefile called "librules.mk", which does all the boring work of
building a package.

Usage:

The very first non-comment thing in your debian/rules should be the
following line:
librules_interface = 2
This helps to spot incompatibilities with debian/rules and the
librules.mk file currently in use.
(See the section "Incompatible changes" for what to look for when
upgrading from an old version.)

Include "debian/librules.mk" just after that line.  Precede it with a
variable definition "librules_native_pkg=yes" if the package you are building
is a Debian native package.

Define a target debian/stamp/build that builds the package (like the
build target does in conventional debian/rules files).  Put "touch $@"
as the last action in that rule.

For every binary package <package> you want to build:

   - If the package is "arch: all", make debian/stamp/binary/indep depend
     on debian/stamp/binary/<package>; otherwise make debian/stamp/binary/arch
     depend on that target

   - Write a target debian/stamp/binary/<package> using the following template:

debian/stamp/binary/<package>: package=<package>
debian/stamp/binary/<package>: debian/stamp/build
        $(prebinary)
        # Add here your own commands
        $(postbinary)
        touch $@

     The $(prebinary) macro will create a skeletal build tree for the
     package.  It also install the copyright file (debian/copyright)
     and the Debian changelog file (debian/changelog).  If there is a
     debian/NEWS, it will install it as NEWS.Debian to the
     documentation directory, compressed.

     See below for instructions about how to write your own install commands.

     The $(postbinary) macro fixes directory permissions, generates the binary
     control file and builds the package.

   - You may want to define targets "clean", "clean-binary" and "clean-build"
     to reverse the effects of your own commands in the build and binary targets.
     The librules.mk file cleans up for itself, you don't need to worry about that.


How to write your own commands for binary targets:

Use the following macros to install files:

      $(install_exec) SOURCE TARGET
      $(install_exec) SOURCE SOURCE ... DIRECTORY
          installs one or more binary executables
          (TARGET need not be a directory name)

      $(install_nonex) SOURCE TARGET
      $(install_nonex) SOURCE SOURCE ... DIRECTORY
          install one or more non-executable files
          (TARGET need not be a directory name)

      $(install_dir) DIRECTORY
          create the directory

      $(install_script) SOURCE TARGET
      $(install_script) SOURCE SOURCE ... DIRECTORY
          install one or more executable scripts          
          (TARGET need not be a directory name)

      $(install_prerm)
      $(install_postrm)
      $(install_preinst)
      $(install_postinst)
          install debian/prerm.$(package) etc.
          to DEBIAN using the appropriate name

The macros above are wrappers around the "install" utility.

      $(install_symlink) SOURCE [TARGET]
           Install a symlink from SOURCE to TARGET
           (This macro is a wrapper around ln -s)

      $(gzip) FILE ...
           Compress the given files
           (This is a wrapper around gzip)

      $(strip_lib) FILE ...
           Strip the given files the way shared libraries are stripped
           (This is a wrapper around strip)


*Never* refer to a file in the install target tree by their real name.
Use the following macros instead:

      $(rootdir) - the directory that masquerades as / in the target tree
                   (usually a subdirectory under debian/tmp)
      $(ctldir)  - the directory where control files are installed
                   (usually $(rootdir)/DEBIAN)
      $(bindir)  - the main binary directory
                   (usually $(rootdir)/usr/bin)
      $(docdir)  - the main doc directory
                   (usually $(rootdir)/usr/share/doc/<package>)
      ...
(see librules.mk for what's available)


If your debian/rules needs the dpkg-architecture variables, add the
definition "librules_need_archvars=yes" before the include at the top
of the file.  If you use this feature, you need to Build-Depend on
"dpkg-dev (>= 1.4.1.5)".

If you want to patch/unpatch the package, add the definitions
"librules_patch_support=yes" and "librules_patches=file1.diff
file2.diff ... filen.diff" before the include at the top of the file.
If you use this, you need to Build-Depend on "patch".


Incompatible changes
--------------------

From 1 to 2:
   - {pre,post}{rm,inst} scripts are not installed by default
     (previously prerm and postinst were unconditionally installed)