Penguin
Recent Changes
Blame: debhelper(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of debhelper(1) version 1 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 DEBHELPER
2 !!!DEBHELPER
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 DEBHELPER COMMANDS
7 DEBHELPER CONFIG FILES
8 SHARED DEBHELPER OPTIONS
9 COMMON DEBHELPER OPTIONS
10 NOTES
11 ENVIRONMENT
12 SEE ALSO
13 AUTHOR
14 ----
15 !!NAME
16
17
18 debhelper - the debhelper tool suite
19 !!SYNOPSIS
20
21
22 __dh___''*'' [[__-v__] [[__-a__] [[__-i__]
23 [[__-s__] [[__--no-act__] [[__-ppackage__]
24 [[__-Npackage] [[-Ptmpdir__]
25 !!DESCRIPTION
26
27
28 Debhelper is used to help you build a debian package. The
29 philosophy behind debhelper is to provide a collection of
30 small, simple, and easily understood tools that are used in
31 debian/rules to automate various common aspects of building
32 a package. This means less work for you, the packager. It
33 also, to some degree means that these tools can be changed
34 if debian policy changes, and packages that use them will
35 require only a rebuild to comply with the new
36 policy.
37
38
39 A typical debian/rules file that uses debhelper will call
40 several debhelper commands in sequence. Debhelper commands
41 are all named with a ``dh_'' prefix. Examples of rules files
42 that use debhelper are in
43 ''/usr/share/doc/debhelper/examples/''
44
45
46 To create a new debian package using debhelper, you can just
47 copy one of the sample rules files and edit it by hand. Or
48 you can try the dh-make package, which contains a dh_make
49 command that partially automates the process. For a more
50 gentle introduction, the maint-guide debian package contains
51 a tutorial about making your first package using
52 debhelper.
53 !!DEBHELPER COMMANDS
54
55
56 Here is the complete list of available debhelper commands.
57 See their man pages for additional
58 documentation.
59
60
61 dh_builddeb(1)
62
63
64 build debian packages
65
66
67 dh_clean(1)
68
69
70 clean up package build directories
71
72
73 dh_compress(1)
74
75
76 compress files and fix symlinks in package build
77 directories
78
79
80 dh_fixperms(1)
81
82
83 fix permissions of files in package build
84 directories
85
86
87 dh_gencontrol(1)
88
89
90 generate and install control file
91
92
93 dh_install(1)
94
95
96 install files into package build directories
97
98
99 dh_installchangelogs(1)
100
101
102 install changelogs into package build
103 directories
104
105
106 dh_installcron(1)
107
108
109 install cron scripts into etc/cron.*
110
111
112 dh_installdeb(1)
113
114
115 install files into the DEBIAN directory
116
117
118 dh_installdebconf(1)
119
120
121 install files used by debconf in package build
122 directories
123
124
125 dh_installdirs(1)
126
127
128 create subdirectories in package build
129 directories
130
131
132 dh_installdocs(1)
133
134
135 install documentation into package build
136 directories
137
138
139 dh_installemacsen(1)
140
141
142 register an emacs add on package
143
144
145 dh_installexamples(1)
146
147
148 install example files into package build
149 directories
150
151
152 dh_installinfo(1)
153
154
155 install and register info files
156
157
158 dh_installinit(1)
159
160
161 install init scripts into package build
162 directories
163
164
165 dh_installlogrotate(1)
166
167
168 install logrotate config files
169
170
171 dh_installman(1)
172
173
174 install man pages into package build
175 directories
176
177
178 dh_installmanpages(1)
179
180
181 old-style man page installer
182
183
184 dh_installmenu(1)
185
186
187 install debian menu files into package build
188 directories
189
190
191 dh_installmime(1)
192
193
194 install mime files into package build
195 directories
196
197
198 dh_installmodules(1)
199
200
201 register modules with modutils
202
203
204 dh_installpam(1)
205
206
207 install pam support files
208
209
210 dh_installwm(1)
211
212
213 register a window manager
214
215
216 dh_installxaw(1)
217
218
219 install xaw wrappers config files into package build
220 directories
221
222
223 dh_installxfonts(1)
224
225
226 register X fonts
227
228
229 dh_link(1)
230
231
232 create symlinks in package build directories
233
234
235 dh_listpackages(1)
236
237
238 list binary packages debhelper will act on
239
240
241 dh_makeshlibs(1)
242
243
244 automatically create shlibs file
245
246
247 dh_md5sums(1)
248
249
250 generate DEBIAN/md5sums file
251
252
253 dh_movefiles(1)
254
255
256 move files out of debian/tmp into subpackages
257
258
259 dh_perl(1)
260
261
262 calculates perl scripts
263
264
265 dh_shlibdeps(1)
266
267
268 calculate shared library dependancies
269
270
271 dh_strip(1)
272
273
274 strip executables, shared libraries, and some static
275 libraries
276
277
278 dh_suidregister(1)
279
280
281 obsolete suid registration program
282
283
284 dh_testdir(1)
285
286
287 test directory before building debian package
288
289
290 dh_testroot(1)
291
292
293 ensure that a package is built as root
294
295
296 dh_testversion(1)
297
298
299 ensure that the correct version of debhelper is
300 installed
301
302
303 dh_undocumented(1)
304
305
306 make symlinks to undocumented.7.gz man page
307 !!DEBHELPER CONFIG FILES
308
309
310 Many debhelper commands make use of files in ''debian/''
311 to control what they do. Besides the common
312 ''debian/changelog'' and ''debian/control'', which are
313 in all packages, not just those using debhelper, some
314 additional files can be used to configure the behavior of
315 specific debhelper commands. These files are typically named
316 debian/package.foo (where ``package'' of course, is replaced
317 with the package that is being acted on).
318
319
320 For example, dh_installdocs uses files named
321 debian/package.docs to list the documentation files it will
322 install. See the man pages of individual commands for
323 details about the names and formats of the files they
324 use.
325
326
327 Note that if a package is the first (or only) binary package
328 listed in debian/control, debhelper will use debian/foo if
329 no debian/package.foo file can be found.
330
331
332 In some rare cases, you may want to have different versions
333 of these files for different architectures. If files named
334 debian/package.foo.arch exist, where ``arch'' is the same as
335 the output of ``dpkg --print-architecture'', then they will
336 be used in preference to other, more general
337 files.
338
339
340 In many cases, these config files are used to specify
341 various types of files. Documentation or example files to
342 install, files to move, and so on. When appropriate, in
343 cases like these, you can use standard shell wildcard
344 characters ('?' and '*') in the files.
345 !!SHARED DEBHELPER OPTIONS
346
347
348 The following command line options are supported by all
349 debhelper programs.
350
351
352 __-v__, __--verbose__
353
354
355 Verbose mode: show all commands that modify the package
356 build directory.
357
358
359 __--no-act__
360
361
362 Do not really do anything. If used with -v, the result is
363 that the command will output what it would have
364 done.
365
366
367 __-a__, __--arch__
368
369
370 Act on all architecture dependent packages.
371
372
373 __-i__, __--indep__
374
375
376 Act on all architecture independent packages.
377
378
379 __-__''ppackage'',
380 __--package=__''package''
381
382
383 Act on the package named ``package''. This option may be
384 specified multiple times to make debhelper operate on a
385 given set of packages.
386
387
388 __-s__, __--same-arch__
389
390
391 This is a smarter version of the -a flag, that is used in
392 some rare circumstances. It understands that if the control
393 file lists ``Architecture: i386'' for the package, the
394 package should not be acted on on other architectures. So
395 this flag makes the command act on all ``Architecture: any''
396 packages, as well as on any packages that have the current
397 architecture explicitly specified. Contrast to the -a flag,
398 which makes the command work on all packages that are not
399 architecture independant.
400
401
402 __-N__''package'',
403 __--no-package=__''package''
404
405
406 Do not act on the specified package even if an -a, -i, or -p
407 option lists the package as one that should be acted
408 on.
409
410
411 __-P__''tmpdir'',
412 __--tmpdir=__''tmpdir''
413
414
415 Use ``tmpdir'' for package build directory. The default is
416 debian/
417 !!COMMON DEBHELPER OPTIONS
418
419
420 The following command line options are supported by some
421 debhelper programs. See the man page of each program for a
422 complete explanation of what each option does.
423
424
425 __-n__
426
427
428 Do not modify postinst/postrm/etc scripts.
429
430
431 __-X__''item'',
432 __--exclude=__''item''
433
434
435 Exclude an item from processing. This option may be used
436 multiple times, to exclude more than one thing.
437
438
439 __-A__, __-all__
440
441
442 Makes files or other items that are specified on the command
443 line take effect in ALL packages acted on,
444 not just the first.
445 !!NOTES
446
447
448 __Multiple binary package support__
449
450
451 If your source package generates more than one binary
452 package, debhelper programs will default to acting on all
453 binary packages when run. If your source package happens to
454 generate one architecture dependent package, and another
455 architecture independent package, this is not the correct
456 behavior, because you need to generate the architecture
457 dependent packages in the binary-arch debian/rules target,
458 and the architecture independent packages in the
459 binary-indep debian/rules target.
460
461
462 To facilitate this, as well as give you more control over
463 which packages are acted on by debhelper programs, all
464 debhelper programs accept the __-a__, __-i__,
465 __-p__, and __-s__ parameters. These parameters are
466 cumulative. If none are given, debhelper programs default to
467 acting on all packages listed in the control
468 file.
469
470
471 See ''/usr/share/doc/debhelper/examples/rules.multi'' for
472 an example of how to use this in a package that generates
473 multiple binary packages.
474
475
476 __Automatic generation of debian install
477 scripts__
478
479
480 Some debhelper commands will automatically generate parts of
481 debian install scripts. If you want these automatically
482 generated things included in your debian install scripts,
483 then you need to add ``#DEBHELPER#'' to your scripts, in the
484 place the code should be added. ``#DEBHELPER#'' will be
485 replaced by any auto-generated code when you run
486 dh_installdeb.
487
488
489 All scripts that automatically generate code in this way let
490 it be disabled by the -n parameter (see above).
491
492
493 Note that the inserted code will be shell code, so you
494 cannot directly use it in a perl script. If you would like
495 to embed it into a perl script, here is one way to do that
496 (note that I made sure that $1, $2, etc
497 are set with the set command):
498
499
500 my $temp=
501
502
503 __Automatic generation of miscellaneous
504 dependencies.__
505
506
507 Some debhelper commands may make the generated package need
508 to depend on some other packages. For example, if you use
509 ''dh_installdebconf''(1), your package will generally
510 need to depend on debconf. Or if you use
511 ''dh_installxfonts''(1), your package will generally need
512 to depend on a particular version of xutils. Keeping track
513 of these miscellaneous dependencies can be annoying since
514 they are dependant on how debhelper does things, so
515 debhelper offers a way to automate it.
516
517
518 All commands of this type, besides documenting what
519 dependencies may be needed on their man pages, will
520 automatically generate a substvar called ${misc:Depends}. If
521 you put that token into your debian/control file, it will be
522 expanded to the dependencies debhelper figures you
523 need.
524
525
526 This is entirely independent of the standard
527 ${shlibs:Depends} generated by ''dh_makeshlibs''(1), and
528 the ${perl:Depends} generated by ''dh_perl''(1). You can
529 choose not to use any of these, if debhelper's guesses don't
530 match reality.
531
532
533 __Package build directories__
534
535
536 By default, all debhelper programs assume that the temporary
537 directory used for assembling the tree of files in a package
538 is debian/
539
540
541 Sometimes, you might want to use some other temporary
542 directory. This is supported by the -P flag. For example,
543 ``dh_installdocs -Pdebian/tmp'', will use debian/tmp as the
544 temporary directory. Note that if you use -P, the debhelper
545 programs can only be acting on a single package at a time.
546 So if you have a package that builds many binary packages,
547 you will need to also use the -p flag to specify which
548 binary package the debhelper program will act
549 on.
550
551
552 __Debhelper compatibility levels__
553
554
555 From time to time, major non-backwards-compatible changes
556 need to be made to debhelper, to keep it clean and
557 well-designed as needs change and its author gains more
558 experience. To prevent such major changes from breaking
559 existing packages, the concept of debhelper compatability
560 levels was introduced. You tell debhelper which
561 compatability level it should use, and it modifies its
562 behavior in various ways.
563
564
565 You tell debhelper what compatability level to use by
566 writing a number to debian/compat. For example, to turn on
567 V4 mode:
568
569
570 % echo 4
571 These are the available compatablity levels:
572
573
574 V1
575
576
577 This is the original debhelper compatability level, and so
578 it is the default one. In this mode, debhelper will use
579 debian/tmp as the package tree directory for the first
580 binary package listed in the control file, while using
581 debian/
582
583
584 V2
585
586
587 In this mode, debhelper will consistently use
588 debian/
589
590
591 V3
592
593
594 This mode works like V2, with the following
595 additions:
596
597
598 -
599
600
601 Debhelper config files support globbing via * and ?, when
602 appropriate. To turn this off and use those characters raw,
603 just prefix with a backslash.
604
605
606 -
607
608
609 dh_makeshlibs makes the postinst and postrm scripts call
610 ldconfig.
611
612
613 -
614
615
616 Every file in etc/ is automatically flagged as a conffile by
617 dh_installdeb.
618
619
620 V4
621
622
623 This is the reccommended mode of operation. It does
624 everything V3 does, plus:
625
626
627 -
628
629
630 dh_makeshlibs -V will not include the debian part of the
631 version number in the generated dependancy line in the
632 shlibs file.
633
634
635 -
636
637
638 dh_installinit uses the new invoke-rc.d program in its
639 generated maintainer scripts. (This may later be rolled back
640 into V3).
641
642
643 -
644
645
646 dh_fixperms will make all files in bin/ directories and in
647 etc/init.d executable.
648
649
650 -
651
652
653 dh_link will correct existing links to conform with
654 policy.
655
656
657 __Doc directory symlinks__
658
659
660 Sometimes it is useful to make a package not contain a
661 /usr/share/doc/package directory at all, instead placing
662 just a dangling symlink in the binary package, that points
663 to some other doc directory. Policy says this is ok if your
664 package depends on the package whose doc directory it uses.
665 To accomplish this, just don't tell debhelper to install any
666 documentation files into the package, and use dh_link to set
667 up the symlink (or do it by hand), and debhelper should do
668 the right thing: notice it is a dangling symlink and not try
669 to install a copyright file or changelog.
670
671
672 __Other notes__
673
674
675 In general, if any debhelper program needs a directory to
676 exist under debian/, it will create it. I haven't bothered
677 to document this in all the man pages, but for example,
678 dh_installdeb knows to make debian/
679
680
681 If you are generating a debian package that has arch-indep
682 and arch-dependent portions, and you are using dh_movefiles
683 to move the arch-indep files out of debian/tmp, you need to
684 make sure that dh_movefiles does this even if only the
685 arch-dependent package is being built (for ports to other
686 architectures). I handle this in the example rules file
687 ``rules.multi'' by calling dh_movefiles in the install
688 target.
689
690
691 Once your package uses debhelper to build, be sure to add
692 debhelper to your Build-Depends line in
693 debian/control.
694 !!ENVIRONMENT
695
696
697 DH_VERBOSE
698
699
700 Set to 1 to enable verbose mode. Debhelper will output every
701 command it runs that modifies files on the build
702 system.
703
704
705 DH_COMPAT
706
707
708 Temporarily specifies what compatibility level debhelper
709 should run at, overriding any value in
710 debian/compat.
711
712
713 DH_NO_ACT
714
715
716 Set to 1 to enable no-act mode.
717
718
719 DH_OPTIONS
720
721
722 Anything in this variable will be prepended to the command
723 line arguments of all debhelper commands. This is useful in
724 some situations, for example, if you need to pass -p to all
725 debhelper commands that will be run. If you use
726 DH_OPTIONS , be sure to build depend on
727 ``debhelper
728 DH_OPTIONS is by using
729 ``Target-specific Variable Values'' in your debian/rules
730 file. See the make documentation for details on doing
731 this.
732 !!SEE ALSO
733
734
735 ''/usr/share/doc/debhelper/examples/''
736
737
738 A set of example debian/rules files that use
739 debhelper.
740
741
742 http://kitenet.net/programs/debhelper/
743
744
745 Debhelper web site.
746 !!AUTHOR
747
748
749 Joey Hess
750 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.