Merge branch 'master' into buildsystems

[debhelper.git] / doc / PROGRAMMING

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index 0d96457fff6cc4114d5726affe4082eef778ca0a..4e7ea463dfed10678a65e62bba35998c501d4b85 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.
 
 
 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.
 
 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();
 
 
 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.
 
 The init() function causes Dh_lib to parse the command line and do some other
 initialization tasks.
 


@@ -106,27 +98,19 @@ switch             variable        description
 -X             EXCLUDE         exclude a something from processing (you
                                decide what this means for your program)
                                (This is an array)
 -X             EXCLUDE         exclude a something from processing (you
                                decide what this means for your program)
                                (This is an array)

-                EXCLUDE_FIND   same as DH_EXCLUDE, except all items are put
+-X              EXCLUDE_FIND   same as EXCLUDE, except all items are put

                                into a string in a way that they will make
                                find find them. (Use ! in front to negate
                                that, of course) Note that this should
                                only be used inside complex_doit(), not in
                                doit().
                                into a string in a way that they will make
                                find find them. (Use ! in front to negate
                                that, of course) Note that this should
                                only be used inside complex_doit(), not in
                                doit().

--x             INCLUDE_CONFFILES
-                               include conffiles. It's -x for obscure
-                               historical reasons.

 -d             D_FLAG          you decide what this means to your program
 -d             D_FLAG          you decide what this means to your program

--r             R_FLAG          you decide what this means to your program
--k             K_FLAG          you decide what this means to your program
+-k             K_FLAG          used to turn on keeping of something

 -P             TMPDIR          package build directory (implies only one
                                package is being acted on)
 -u             U_PARAMS        will be set to a string, that is typically
                                parameters your program passes on to some
                                other program. (This is an array)
 -P             TMPDIR          package build directory (implies only one
                                package is being acted on)
 -u             U_PARAMS        will be set to a string, that is typically
                                parameters your program passes on to some
                                other program. (This is an array)

--m             M_PARAMS        will be set to a string, you decide what it
-                               means to your program
--l             L_PARAMS        will be set to a string, you decide what it
-                               means to your program

 -V             V_FLAG          will be set to a string, you decide what it
                                means to your program
 -V             V_FLAG_SET      will be 1 if -V was specified, even if no
 -V             V_FLAG          will be set to a string, you decide what it
                                means to your program
 -V             V_FLAG_SET      will be 1 if -V was specified, even if no


@@ -136,23 +120,12 @@ switch            variable        description
                                those processed here), will apply to all 
                                binary packages the program acts on, not just
                                the first
                                those processed here), will apply to all 
                                binary packages the program acts on, not just
                                the first

---init-script  INIT_SCRIPT     will be set to a string, which specifies an
-                               init script name (probably only
-                               dh_installinit will ever use this)
---sourcedir    SOURCEDIR       will be set to a string (probably only
-                               dh_movefiles will ever use this)
---destdir      DESTDIR         will be set to a string (probably only
-                               dh_builddeb will ever use this)
---filename     FILENAME        will be set to a string
---flavor       FLAVOR          will be set to a string (probably only
-                               dh_installemacsen will ever use this)
---number       PRIORITY        will be set to a number (deprecated)

 --priority     PRIORITY        will be set to a number
 --priority     PRIORITY        will be set to a number

+--mainpackage  MAINPACKAGE     controls which package is treated as the
+                               main package to act on

 --name         NAME            a name to use for installed files, instead of
                                the package name
 --error-handler        ERROR_HANDLER   a function to call on error
 --name         NAME            a name to use for installed files, instead of
                                the package name
 --error-handler        ERROR_HANDLER   a function to call on error

---language     LANGUAGE        specify what language a file is in
---add-udeb     SHLIBS_UDEB     used by dh_makeshlibs

 
 Any additional command line parameters that do not start with "-" will be 
 ignored, and you can access them later just as you normally would.
 
 Any additional command line parameters that do not start with "-" will be 
 ignored, and you can access them later just as you normally would.


@@ -267,5 +240,45 @@ getpackages($type)
 inhibit_log()
        Prevent logging the program's successful finish to
        debian/*debhelper.log
 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.
+
+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>
 
 -- Joey Hess <joeyh@debian.org>