X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=doc%2FPROGRAMMING;h=bd79628c4f22cd27f78a9617111665e96c7bc0c4;hb=9803d8bb635132458142416d32273c9c754b2aca;hp=9996dc73a9ee1a3292458829d823c11176e0ebe2;hpb=f86a603fb6be7944e4b9da327a738e8c023e13f5;p=debhelper.git diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING index 9996dc7..bd79628 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,11 @@ 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) +--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 --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 +132,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: ---------------- @@ -215,6 +202,8 @@ autoscript($package, $scriptname, $snippetname, $sedcommands) (optional) 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) @@ -250,5 +239,47 @@ getpackages($type) 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. + +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, build, test, install, clean. See the comments +inside Debian::Debhelper::Buildsystem for details. + +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