Make it possible to pass perl code to autoscript.

[debhelper.git] / doc / PROGRAMMING

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index 9963181ea7998fdf20acce05ced6f233da81d0e3..e1440c91e46451c8c0ab10b53d054d7ebb768921 100644 (file)
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -120,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


@@ -193,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


@@ -218,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.


@@ -234,9 +236,11 @@ 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()
        As a side effect, populates %package_arches and %package_types with
        the types of all packages (not only those returned).
 inhibit_log()


@@ -250,13 +254,13 @@ write_log($cmd, $package ...)
        Writes the log files for the specified package(s), adding
        the cmd to the end.
 
        Writes the log files for the specified package(s), adding
        the cmd to the end.
 

-Sequence Addons
+Sequence Addons:

 ---------------
 
 The dh(1) command has a --with <addon> parameter that ca be used to load
 ---------------
 
 The dh(1) command has a --with <addon> parameter that ca be used to load

-a sequence addon named Debian::Debhelper::Sequence::<addon>. 
-These addons can add/remove commands to the dh command sequences, by calling
-some functions from Dh_Lib:
+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_before($existing_command, $new_command)
        Insert $new_command in sequences before $existing_command


@@ -265,6 +269,40 @@ insert_after($existing_command, $new_command)
        Insert $new_command in sequences after $existing_command
 
 remove_command($existing_command)
        Insert $new_command in sequences after $existing_command
 
 remove_command($existing_command)

-       Remove $existing_command from the list of commands to run.
+       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>