Make it possible to pass perl code to autoscript.

[debhelper.git] / doc / PROGRAMMING

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index bd79628c4f22cd27f78a9617111665e96c7bc0c4..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()


@@ -265,7 +269,25 @@ 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:
 -------------------
 
 Buildsystem Classes:
 -------------------


@@ -276,8 +298,9 @@ and are derived from Debian::Debhelper::Buildsystem, or other, related
 classes.
 
 A buildsystem class needs to inherit or define these methods: DESCRIPTION,
 classes.
 
 A buildsystem class needs to inherit or define these methods: DESCRIPTION,

-check_auto_buildable, build, test, install, clean. See the comments
-inside Debian::Debhelper::Buildsystem for details.
+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.
 
 Note that third-party buildsystems will not automatically be used by default,
 but can be forced to be used via the --buildsystem parameter.