Make it possible to pass perl code to autoscript.

[debhelper.git] / doc / PROGRAMMING

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index 3cea384f787101e83eb1ec42d11423f79ee03bf3..e1440c91e46451c8c0ab10b53d054d7ebb768921 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.
 


@@ -128,8 +120,6 @@ 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

---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
 --priority     PRIORITY        will be set to a number
 --mainpackage  MAINPACKAGE     controls which package is treated as the
                                main package to act on


@@ -201,13 +191,16 @@ isnative($package)
        is a native debian package.
        As a side effect, $dh{VERSION} is set to the version number of the
        package.
        is a native debian package.
        As a side effect, $dh{VERSION} is set to the version number of the
        package.

-autoscript($package, $scriptname, $snippetname, $sedcommands)
+autoscript($package, $scriptname, $snippetname, $sedcommands || $sub)

        Pass parameters:
         - binary package to be affected
         - script to add to
         - filename of snippet
        Pass parameters:
         - binary package to be affected
         - script to add to
         - filename of snippet

-        - sed commands to run on the snippet. Ie, s/#PACKAGE#/$PACKAGE/
-          (optional)
+        - (optional) EITHER sed commands to run on the snippet. Ie,
+          s/#PACKAGE#/$PACKAGE/ Note: Passed to the shell inside double
+           quotes.
+          OR a perl sub to invoke with $_ set to each line of the snippet in
+           turn.

        This command automatically adds shell script snippets to a debian
        maintainer script (like the postinst or prerm).
        Note that in v6 mode and up, the snippets are added in reverse
        This command automatically adds shell script snippets to a debian
        maintainer script (like the postinst or prerm).
        Note that in v6 mode and up, the snippets are added in reverse


@@ -226,9 +219,10 @@ addsubstvar($package, $substvar, $deppackage, $verinfo, $remove)
        - version info for the package (optional) (ie: ">= 1.1")
        - if this last parameter is passed, the thing that would be added
          is removed instead. This can be useful to ensure that a debhelper
        - version info for the package (optional) (ie: ">= 1.1")
        - if this last parameter is passed, the thing that would be added
          is removed instead. This can be useful to ensure that a debhelper

-         command is idempotent. Note that without this parameter, if you
-         call the function twice with the same values it will only add one
-         item to the substvars file.
+         command is idempotent. (However, we generally don't bother,
+         and rely on the user calling dh_prep.) Note that without this
+         parameter, if you call the function twice with the same values it
+         will only add one item to the substvars file.

 delsubstvar($package, $substvar)
        This function removes the entire line for the substvar from the
        package's shlibs file.
 delsubstvar($package, $substvar)
        This function removes the entire line for the substvar from the
        package's shlibs file.


@@ -242,13 +236,73 @@ udeb_filename($package)
        Returns the filename of the udeb package.
 getpackages($type)
        Returns a list of packages in the control file.
        Returns the filename of the udeb package.
 getpackages($type)
        Returns a list of packages in the control file.

-       Must pass "arch" or "indep" or "same" to specify arch-dependent or
-       -independent or same arch packages. If nothing is specified, returns all
-       packages.
+       Pass "arch" or "indep" to specify arch-dependent or
+       -independent. If nothing is specified, returns all
+       packages (including packages that are not built
+       for this architecture). Pass "both" to get the union
+       of "arch" and "indep" packages.

        As a side effect, populates %package_arches and %package_types with
        the types of all packages (not only those returned).
 inhibit_log()
        Prevent logging the program's successful finish to
        debian/*debhelper.log
        As a side effect, populates %package_arches and %package_types with
        the types of all packages (not only those returned).
 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($new_command, $sequence)
+       Add $new_command to the beginning of the specified sequence.
+       If the sequence does not exist, it will be created.
+
+add_command_options($command, $opt1, $opt2, ...)
+       Append $opt1, $opt2 etc. to the list of additional options which
+       dh passes when running the specified $command. These options are
+       not relayed to debhelper commands called via $command override.
+
+remove_command_options($command)
+       Clear all additional $command options previously added with
+       add_command_options().
+
+remove_command_options($command, $opt1, $opt2, ...)
+       Remove $opt1, $opt2 etc. from the list of additional options which
+       dh passes when running the specified $command.
+
+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>