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.
-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.
-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
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
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:
----------------
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)
- 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.
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()
+ 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>
projects / debhelper.git / blobdiff