diff options
Diffstat (limited to 'doc/PROGRAMMING')
| -rw-r--r-- | doc/PROGRAMMING | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING new file mode 100644 index 00000000..e7b6e355 --- /dev/null +++ b/doc/PROGRAMMING @@ -0,0 +1,318 @@ +This file documents things you should know to write a new debhelper program. +Any program with a name that begins with dh_ should conform to these +guidelines (with the historical exception of dh_make). + +Standardization: +--------------- + +There are lots of debhelper commands. To make the learning curve shallower, +I want them all to behave in a standard manner: + +All debhelper programs have names beginning with "dh_". This is so we don't +pollute the name space too much. + +Debhelper programs should never output anything to standard output except +error messages, important warnings, and the actual commands they run that +modify files under debian/ (this last only if they are passed -v, and if you +output the commands, you should indent them with 1 tab). This is so we don't +have a lot of noise output when all the debhelper commands in a debian/rules +are run, so the important stuff is clearly visible. + +Debhelper programs should accept all options listed in the "SHARED +DEBHELPER OPTIONS" section of debhelper(7), including any long forms of +these options, like --verbose . If necessary, the options may be ignored. + +If debhelper commands need config files, they should use +debian/package.filename as the name of the config file (replace filename +with whatever your command wants), and debian/filename should also be +checked for config information for the first binary package in +debian/control. Also, debhelper commands should accept the same sort of +information that appears in the config files, on their command lines, if +possible, and apply that information to the first package they act on. +The config file format should be as simple as possible, generally just a +list of files to act on. + +Debhelper programs should never modify the debian/postinst, debian/prerm, +etc scripts. Instead, they can add lines to debian/postinst.debhelper, etc. +The autoscript() function (see below) is one easy way to do this. +dh_installdeb is an exception, it will run after the other commands and +merge these modifications into the actual postinst scripts. + +In general, files named debian/*.debhelper are internal to debhelper, and +their existence or use should not be relied on by external programs such as +the build process of a package. These files will be deleted by dh_clean. + +Debhelper programs should default to doing exactly what policy says to do. + +There are always exceptions. Just ask me. + +Introducing Dh_Lib: +------------------ + +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. + +Use Dh_Lib like this: + +use Debian::Debhelper::Dh_Lib +init(); + +The init() function causes Dh_lib to parse the command line and do some other +initialization tasks. + +Argument processing: +------------------- + +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. + +switch variable description +-v VERBOSE should the program verbosely output what it is + doing? +--no-act NO_ACT should the program not actually do anything? +-i,-a,-p,-N DOPACKAGES a space delimited list of the binary packages + to act on (in Dh_Lib.pm, this is an array) +-i DOINDEP set if we're acting on binary independent + packages +-a DOARCH set if we're acting on binary dependent + 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) +-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) Note that this should + only be used inside complex_doit(), not in + doit(). +-d D_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) +-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 + parameters were passed along with the -V +-A PARAMS_ALL generally means that additional command line + parameters passed to the program (other than + those processed here), will apply to all + binary packages the program acts on, not just + the first +--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 + +Any additional command line parameters that do not start with "-" will be +ignored, and you can access them later just as you normally would. + +Global variables: +---------------- + +The following keys are also set in the %dh hash when you call init(): + +MAINPACKAGE the name of the first binary package listed in + debian/control +FIRSTPACKAGE the first package we were instructed to act on. This package + typically gets special treatment; additional arguments + specified on the command line may effect it. + +Functions: +--------- + +Dh_Lib.pm also contains a number of functions you may find useful. + +doit(@command) + Pass this function an array that is a + shell command. It will run the command (unless $dh{NO_ACT} is set), and + if $dh{VERBOSE} is set, it will also output the command to stdout. You + should use this function for almost all commands your program performs + that manipulate files in the package build directories. +complex_doit($command) + Pass this function a string that is a shell command, it will run it + similarly to how doit() does. You can pass more complicated commands + to this (ie, commands involving piping redirection), however, you + have to worry about things like escaping shell metacharacters. +verbose_print($message) + Pass this command a string, and it will echo it if $dh{VERBOSE} is set. +error($errormsg) + Pass this command a string, it will output it to standard error and + exit. +warning($message) + Pass this command a string, and it will output it to standard error + as a warning message. +tmpdir($dir) + Pass this command the name of a binary package, it will return the + name of the tmp directory that will be used as this package's + package build directory. Typically, this will be "debian/package". +compat($num) + Pass this command a number, and if the current compatibility level + is less than or equal to that number, it will return true. + Looks at DH_COMPAT to get the compatibility level. +pkgfile($package, $basename) + Pass this command the name of a binary package, and the base name of a + file, and it will return the actual filename to use. This is used + for allowing debhelper programs to have configuration files in the + debian/ directory, so there can be one config file per binary + package. The convention is that the files are named + debian/package.filename, and debian/filename is also allowable for + the $dh{MAINPACKAGE}. If the file does not exist, nothing is returned. + + If the *entire* behavior of a command, when run without any special + options, is determined by the existence of 1 or more pkgfiles, + or by the existence of a file or directory in a location in the + tmpdir, it can be marked as such, which allows dh to automatically + skip running it. This is done by inserting a special comment, + of the form: + + # PROMISE: DH NOOP WITHOUT pkgfilea pkgfileb tmp(need/this) + +pkgext($package) + Pass this command the name of a binary package, and it will return + the name to prefix to files in debian/ for this package. For the + $dh{MAINPACKAGE}, it returns nothing (there is no prefix), for the other + packages, it returns "package.". +isnative($package) + Pass this command the name of a package, it returns 1 if 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 || $sub) + Pass parameters: + - binary package to be affected + - script to add to + - filename of snippet + - (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) + Return base of pathname, +addsubstvar($package, $substvar, $deppackage, $verinfo, $remove) + This function adds a dependency on some package to the specified + substvar in a package's substvar's file. It needs all these + parameters: + - binary package that gets the item + - name of the substvar to add the item to + - the package that will be depended on + - 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. (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. +excludefile($filename) + This function returns true if -X has been used to ask for the file + to be excluded. +is_udeb($package) + Returns true if the package is marked as a udeb in the control + 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 <addon> parameter that ca be used to load +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_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 <joeyh@debian.org> |