X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=doc%2FPROGRAMMING;h=e1440c91e46451c8c0ab10b53d054d7ebb768921;hb=a3494762925e5a42a42ce82c688f62f163ffad1b;hp=5c60a0b11f83362b173d30935fca0aa9f899d584;hpb=94f711ab1af4966a8c1099578752cddb0345e3db;p=debhelper.git diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING index 5c60a0b..e1440c9 100644 --- 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 @@ -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. -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 - - 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 @@ -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 - 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. @@ -242,9 +236,11 @@ udeb_filename($package) 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() @@ -258,4 +254,55 @@ 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 parameter that ca be used to load +a sequence addon module named Debian::Debhelper::Sequence::. +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