dh: Allow creation of new sequences (such as to handle a patch target for quilt)...

[debhelper.git] / doc / PROGRAMMING

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index 3cea384f787101e83eb1ec42d11423f79ee03bf3..c3530f26f5f82319a09fcb8fa02e0849f29bb587 100644 (file)
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -46,27 +46,19 @@ Debhelper programs should default to doing exactly what policy says to do.
 
 There are always exceptions. Just ask me.
 
-Introducing Dh_Lib.pm:
----------------------
+Introducing Dh_Lib:
+------------------
 
-Dh_Lib.pm is the library used by all debhelper programs to parse their
+Dh_Lib is the library used by all debhelper programs to parse their
 arguments and set some useful variables. It's not mandatory that your
 program use Dh_Lib.pm, but it will make it a lot easier to keep it in sync
 with the rest of debhelper if it does, so this is highly encouraged.
 
-(There used to be a version of Dh_lib.pm that was a library of functions for
-shell scripts. If you want to write a debhelper command that is a shell
-script, I can dig up that old library for you. Only the perl one is
-supported now, though.)
-
-Use Dh_Lib.pm like this:
+Use Dh_Lib like this:
 
 use Debian::Debhelper::Dh_Lib
 init();
 
-The BEGIN block is there to make perl look for the module in all the right
-places.
-
 The init() function causes Dh_lib to parse the command line and do some other
 initialization tasks.
 
@@ -128,8 +120,6 @@ switch              variable        description
                                those processed here), will apply to all 
                                binary packages the program acts on, not just
                                the first
---sourcedir    SOURCEDIR       will be set to a string
---destdir      DESTDIR         will be set to a string
 --priority     PRIORITY        will be set to a number
 --mainpackage  MAINPACKAGE     controls which package is treated as the
                                main package to act on
@@ -250,5 +240,50 @@ getpackages($type)
 inhibit_log()
        Prevent logging the program's successful finish to
        debian/*debhelper.log
+load_log($package, $hashref)
+       Loads the log file for the given package and returns a list of
+       logged commands.
+       (Passing a hashref also causes it to populate the hash.)
+write_log($cmd, $package ...)
+       Writes the log files for the specified package(s), adding
+       the cmd to the end.
+
+Sequence Addons:
+---------------
+
+The dh(1) command has a --with <addon> parameter that ca be used to load
+a sequence addon module named Debian::Debhelper::Sequence::<addon>. 
+These modules can add/remove commands to the dh command sequences, by
+calling some functions from Dh_Lib:
+
+insert_before($existing_command, $new_command)
+       Insert $new_command in sequences before $existing_command
+
+insert_after($existing_command, $new_command)
+       Insert $new_command in sequences after $existing_command
+
+remove_command($existing_command)
+       Remove $existing_command from the list of commands to run
+       in all sequences.
+
+add_command($sequence, $new_command)
+       Add $new_command to the beginning of the specified sequence.
+       If the sequence does not exist, it will be created.
+
+Buildsystem Classes:
+-------------------
+
+The dh_auto_* commands are frontends that use debhelper buildsystem
+classes. These classes have names like Debian::Debhelper::Buildsystem::foo,
+and are derived from Debian::Debhelper::Buildsystem, or other, related
+classes.
+
+A buildsystem class needs to inherit or define these methods: DESCRIPTION,
+check_auto_buildable, configure, build, test, install, clean. See the comments
+inside Debian::Debhelper::Buildsystem for details. Note that this interface
+is still subject to change.
+
+Note that third-party buildsystems will not automatically be used by default,
+but can be forced to be used via the --buildsystem parameter.
 
 -- Joey Hess <joeyh@debian.org>