X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=doc%2FPROGRAMMING;h=e1440c91e46451c8c0ab10b53d054d7ebb768921;hb=a3494762925e5a42a42ce82c688f62f163ffad1b;hp=8151c3ef065c15096f1c71e5a9b64db50e66233e;hpb=bfad668fe8013de52b2f62017450da4f0e28f0f5;p=debhelper.git diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING index 8151c3e..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. @@ -77,6 +69,13 @@ All debhelper programs should respond to certain arguments, such as -v, -i, -a, and -p. To help you make this work right, Dh_Lib.pm handles argument processing. Just call init(). +You can add support for additional options to your command by passing an +options hash to init(). The hash is then passed on the Getopt::Long to +parse the command line options. For example, to add a --foo option, which +sets $dh{FOO}: + +init(options => { foo => \$dh{FOO} }); + After argument processing, some global variables are used to hold the results; programs can use them later. These variables are elements of the %dh hash. @@ -93,28 +92,25 @@ switch variable description packages -n NOSCRIPTS if set, do not make any modifications to the package's postinst, postrm, etc scripts. +-o ONLYSCRIPTS if set, only make modifications to the + package's scripts, but don't look for or + install associated files. -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) --x INCLUDE_CONFFILES - include conffiles. It's -x for obscure - historical reasons. + that, of course) Note that this should + only be used inside complex_doit(), not in + doit(). -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) --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 @@ -124,18 +120,9 @@ switch variable description 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 +--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 @@ -143,8 +130,6 @@ switch variable description Any additional command line parameters that do not start with "-" will be ignored, and you can access them later just as you normally would. -If you need a new command line option, just ask me, and I will add it. - Global variables: ---------------- @@ -206,15 +191,20 @@ 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 + order for the removal scripts. dirname($pathname) Return directory part of pathname. basename($pathname) @@ -229,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. @@ -243,5 +234,75 @@ is_udeb($package) file. udeb_filename($package) Returns the filename of the udeb package. +getpackages($type) + Returns a list of packages in the control file. + 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 +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 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