From 962a2e10c930e3504ea1c0327be2fdf70d53023e Mon Sep 17 00:00:00 2001 From: Modestas Vainius Date: Thu, 18 Jun 2009 02:11:45 +0300 Subject: Update dh_auto documentation. * dh_auto.pod -> dh_auto.7 - contains general information about dh_auto, its features, build systems supported by default (the latter is injected by man/dh_auto_pod script from Debian/Debhelper/Buildsystem/*.pm PODs via placeholders (#PLACEHOLDER#)) * POD in Debian/Debhelper/Buildsystem/*.pm -> dh_auto_.7 - build system specific information. * dh_auto_* -> dh_auto_*.1 - relatively shorty description of the specific dh_auto_* program and build system specific info for that step injected from Debian/Debhelper/Buildsystem/*.pm with man/dh_auto_pod script. * man/dh_auto_pod $step - generates full dh_auto_$step POD (replaces placeholders). * man/dh_auto_pod - generates full dh_auto.pod (replaces placeholders). Signed-off-by: Modestas Vainius --- Debian/Debhelper/Buildsystem/autoconf.pm | 132 +++++++++++++++++++++++ Debian/Debhelper/Buildsystem/cmake.pm | 125 +++++++++++++++++++++ Debian/Debhelper/Buildsystem/makefile.pm | 131 ++++++++++++++++++++++ Debian/Debhelper/Buildsystem/perl_build.pm | 123 +++++++++++++++++++++ Debian/Debhelper/Buildsystem/perl_makemaker.pm | 118 ++++++++++++++++++++ Debian/Debhelper/Buildsystem/python_distutils.pm | 129 ++++++++++++++++++++++ 6 files changed, 758 insertions(+) (limited to 'Debian') diff --git a/Debian/Debhelper/Buildsystem/autoconf.pm b/Debian/Debhelper/Buildsystem/autoconf.pm index 60fa9e85..9121a1d7 100644 --- a/Debian/Debhelper/Buildsystem/autoconf.pm +++ b/Debian/Debhelper/Buildsystem/autoconf.pm @@ -6,6 +6,34 @@ package Debian::Debhelper::Buildsystem::autoconf; +=head1 NAME + +B - GNU Autoconf (configure) + +=head1 SYNOPSIS + +B [B<--buildsystem>=I] ... + +=head1 DESCRIPTION + +GNU Autoconf is a popular cross-platform build system. Autoconf F +script prepares the source for building and generates necessary Fs +and other temporary files in the build directory. Then a standard set of +make targets needs to be executed in the build directory to complete source +build process. GNU Autoconf build system can be typically identified by +presence of the F script in the source directory. + +=head1 DH_AUTO NOTES + +Both in source (default) and out of source tree building modes are supported. +However, please note that some original source packages might not be compatible +with out of source tree building mode of Autoconf and hence build process may +fail later even if the I step succeeds. + +=head1 BUILD PROCESS + +=cut + use strict; use Debian::Debhelper::Dh_Lib qw(dpkg_architecture_value sourcepackage); use base 'Debian::Debhelper::Buildsystem::makefile'; @@ -25,6 +53,35 @@ sub check_auto_buildable { return 0; } +=head2 Configure step + +=over 4 + +=item I + +Execute F from the source directory with working directory set to +the build directory. A set of standard arguments are passed to the F +script: + + --build=`dpkg_architecture -qDEB_BUILD_GNU_TYPE` + --prefix=/usr + --includedir=${prefix}/include + --mandir=${prefix}/share/man + --infodir=${prefix}/share/info + --sysconfdir=/etc + --localstatedir=/var + --libexecdir=${prefix}/lib/$name_of_debian_source_package + --disable-maintainer-mode + --disable-dependency-tracking + --host=`dpkg_architecture -qDEB_HOST_GNU_TYPE` (if different from --build) + +=item I + +If executable file F exists in the source directory. + +=back + +=cut sub configure { my $this=shift; @@ -52,4 +109,79 @@ sub configure { $this->doit_in_builddir($this->get_source_rel2builddir("configure"), @opts, @_); } +=head2 Build step + +=over 4 + +=item I + +Execute C in the build directory. See I build system +documentation for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head2 Test step + +=over 4 + +=item I + +Execute either C or C in the build directory. See +I build system documentation for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head2 Install step + +=over 4 + +=item I + +Execute C in the build directory with $destdir +set to the appropriate temporary installation directory. See I build +system documentation for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head2 Clean step + +=over 4 + +=item I + +Remove the build directory if building out of source tree or execute C if building in source. See I build system documentation +for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head1 SEE ALSO + +L + +L + +=head1 AUTHORS + + Joey Hess + Modestas Vainius + +=cut + 1; diff --git a/Debian/Debhelper/Buildsystem/cmake.pm b/Debian/Debhelper/Buildsystem/cmake.pm index 56628740..0275bfb8 100644 --- a/Debian/Debhelper/Buildsystem/cmake.pm +++ b/Debian/Debhelper/Buildsystem/cmake.pm @@ -6,6 +6,36 @@ package Debian::Debhelper::Buildsystem::cmake; +=head1 NAME + +B - CMake (CMakeLists.txt) + +=head1 SYNOPSIS + +B [B<--buildsystem>=I] ... + +=head1 DESCRIPTION + +CMake is a family of tools designed to build, test and package software. CMake +generates Fs and other temporary files in the build directory from +the directives present in the F and a couple of other build +system source files. Then a standard set of make targets needs to be executed +in the build directory to complete source building process. CMake is available +in the cmake package that is essential throughout the whole build process. + +=head1 DH_AUTO NOTES + +Out of source tree building is done by default if this debhelper build system +is selected. This is due to the fact that there is no way to properly clean up +build directory from temporary files unless it is removed completely. +Therefore I step cannot be fully implemented if building is done in +source. However, the user may still enable in source building by explicitly +specifying a build directory path that is equal to the source directory path. + +=head1 BUILD PROCESS + +=cut + use strict; use base 'Debian::Debhelper::Buildsystem::makefile'; @@ -29,6 +59,27 @@ sub new { return $this; } +=head2 Configure step + +=over 4 + +=item I + +Execute C in the build directory passing a path to the source directory +and defining the following flags: + + -DCMAKE_INSTALL_PREFIX=/usr + -DCMAKE_SKIP_RPATH=ON + -DCMAKE_VERBOSE_MAKEFILE=ON + +=item I + +If F file exists but neither F, F, +F or F exist in the source directory. + +=back + +=cut sub configure { my $this=shift; my @flags; @@ -42,4 +93,78 @@ sub configure { $this->doit_in_builddir("cmake", $this->get_source_rel2builddir(), @flags); } +=head2 Build step + +=over 4 + +=item I + +Execute C in the build directory. See I build system documentation +for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head2 Test step + +=over 4 + +=item I + +Execute C in the build directory. See I build system +documentation for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head2 Install step + +=over 4 + +=item I + +Execute C in the build directory with $destdir +set to the appropriate temporary installation directory. See I build +system documentation for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head2 Clean step + +=over 4 + +=item I + +Remove the build directory if building out of source tree (complete clean up) +or execute C if building in source (incomplete clean up). See +I build system documentation for more information. + +=item I + +It is normal for the I build system to be auto-selected at this step. + +=back + +=head1 SEE ALSO + +L + +L + +=head1 AUTHORS + + Modestas Vainius + +=cut + 1; diff --git a/Debian/Debhelper/Buildsystem/makefile.pm b/Debian/Debhelper/Buildsystem/makefile.pm index d84d3349..32ad5178 100644 --- a/Debian/Debhelper/Buildsystem/makefile.pm +++ b/Debian/Debhelper/Buildsystem/makefile.pm @@ -6,6 +6,56 @@ package Debian::Debhelper::Buildsystem::makefile; +=head1 NAME + +B - make (Makefile) + +=head1 SYNOPSIS + +B [B<--buildsystem>=I] ... + +=head1 DESCRIPTION + +Makefile based projects use C to control build process. C utility +is the most popular tool on *NIX for building & installing packages from +source. It is also a basis for most other popular build systems. For example, +GNU Autoconf (autoconf) or CMake (cmake) generate Fs during I +step and leave the rest of build process for C to handle. + +=head1 DH_AUTO NOTES + +Since C itself does not strictly define standard target names, a couple +of the most popular targets are tried for each building step. Whichever first +of them is discovered to exist, it is run. If neither of the tried targets +exist in the actual, the building step is assumed to have completed +successfully. However, if executed C target fails, the respective dh_auto +program will fail too. + +If MAKE environment variable is set, its value is executed rather than default +C command. + +Both in source (default) and out of source tree building modes are supported. +Either F, F or F file should be present in the +build directory for this debhelper build system to work. + +=head1 BUILD PROCESS + +=head2 Configure step + +=over 4 + +=item I + +Do nothing (auto-selection continues). + +=item I + +It will never be auto-selected at this step. + +=back + +=cut + use strict; use Debian::Debhelper::Dh_Lib qw(escape_shell); use base 'Debian::Debhelper::Buildsystem'; @@ -69,22 +119,92 @@ sub check_auto_buildable { return 0; } +=head2 Build step + +=over 4 + +=item I + +Execute C (without arguments) with working directory changed to the build +directory. + +=item I + +If either F, F or F exists in the build +directory, but F does not exist in the source directory. + +=back + +=cut sub build { my $this=shift; $this->doit_in_builddir($this->{makecmd}, @_); } +=head2 Test step + +=over 4 + +=item I + +Try to C either I or I target (the first existing one) with +working directory changed to the build directory. + +=item I + +If either F, F or F exists in the build +directory, but F does not exist in the source directory. + +=back + +=cut sub test { my $this=shift; $this->make_first_existing_target(['test', 'check'], @_); } +=head2 Install step + +=over 4 + +=item I + +Try to run C with working directory changed to +the build directory. $desdir is the path to the appropriate temporary +installation directory under debian/ (see L). + +=item I + +If either F, F or F exists in the build +directory, but F does not exist in the source directory. + +=back + +=cut sub install { my $this=shift; my $destdir=shift; $this->make_first_existing_target(['install'], "DESTDIR=$destdir", @_); } +=head2 Clean step + +=over 4 + +=item I + +When building in source, try to C either I, I or +I target (the first existing one) in the source directory. When building +out of source tree, recursively remove the whole build directory. + +=item I + +If either F, F or F exists in the build +directory, but F does not exist in the source directory. + +=back + +=cut sub clean { my $this=shift; if (!$this->rmdir_builddir()) { @@ -92,4 +212,15 @@ sub clean { } } +=head1 SEE ALSO + +L + +=head1 AUTHORS + + Joey Hess + Modestas Vainius + +=cut + 1; diff --git a/Debian/Debhelper/Buildsystem/perl_build.pm b/Debian/Debhelper/Buildsystem/perl_build.pm index 3567cb1a..26210152 100644 --- a/Debian/Debhelper/Buildsystem/perl_build.pm +++ b/Debian/Debhelper/Buildsystem/perl_build.pm @@ -6,6 +6,32 @@ package Debian::Debhelper::Buildsystem::perl_build; +=head1 NAME + +B - Perl Module::Build (Build.PL) + +=head1 SYNOPSIS + +B [B<--buildsystem>=I] ... + +=head1 DESCRIPTION + +Module::Build is a system for building, testing, and installing Perl modules. +It does not require a C on your system - most of the Module::Build code is +pure-perl and written in a very cross-platform way. Its only prerequisites are +modules that are included with perl 5.6.0. Typically, Module::Build build system +can be identified by presence of the F script in the source +directory. + +=head1 DH_AUTO NOTES + +Out of source tree building is not supported. C +environment variable is exported in each building step. + +=head1 BUILD PROCESS + +=cut + use strict; use base 'Debian::Debhelper::Buildsystem'; @@ -37,31 +63,128 @@ sub new { return $this; } +=head2 Configure step + +=over 4 + +=item I + +Execute C passing C parameter by default. +Environment variable C is set before running the script. + +=item I + +If F, F, F do not exist, but F +exists in the source directory. + +=back + +=cut sub configure { my $this=shift; $ENV{PERL_MM_USE_DEFAULT}=1; $this->do_perl("Build.PL", "installdirs=vendor", @_); } +=head2 Build step + +=over 4 + +=item I + +Execute C. + +=item I + +If F, F, F (build directory) and F +(source directory) do not exist, but F and F files exist in +the source directory. + +=back + +=cut sub build { my $this=shift; $this->do_perl("Build", @_); } +=head2 Test step + +=over 4 + +=item I + +Execute C. + +=item I + +If F, F, F (build directory) and F +(source directory) do not exist, but F and F files exist in +the source directory. + +=back + +=cut sub test { my $this=shift; $this->do_perl("Build", "test", @_); } +=head2 Install step + +=over 4 + +=item I + +Execute C. $destdir is +the path to the temporary installation directory (see L). + +=item I + +If F, F, F (build directory) and F +(source directory) do not exist, but F and F files exist in +the source directory. + +=back + +=cut sub install { my $this=shift; my $destdir=shift; $this->do_perl("Build", "install", "destdir=$destdir", "create_packlist=0", @_); } +=head2 Clean step + +=over 4 + +=item I + +Execute C. + +=item I + +If F, F, F (build directory) and F +(source directory) do not exist, but F and F files exist in +the source directory. + +=back + +=cut sub clean { my $this=shift; $this->do_perl("Build", "--allow_mb_mismatch", 1, "distclean", @_); } +=head1 SEE ALSO + +L + +=head1 AUTHORS + + Joey Hess + Modestas Vainius + +=cut + 1; diff --git a/Debian/Debhelper/Buildsystem/perl_makemaker.pm b/Debian/Debhelper/Buildsystem/perl_makemaker.pm index 07a827ac..102e23f5 100644 --- a/Debian/Debhelper/Buildsystem/perl_makemaker.pm +++ b/Debian/Debhelper/Buildsystem/perl_makemaker.pm @@ -6,6 +6,29 @@ package Debian::Debhelper::Buildsystem::perl_makemaker; +=head1 NAME + +B - Perl ExtUtils::MakeMaker (Makefile.PL) + +=head1 SYNOPSIS + +B [B<--buildsystem>=I] ... + +=head1 DESCRIPTION + +Perl ExtUtils::MakeMaker utility is designed to write a Makefile for an +extension module from a Makefile.PL (at configure step). The rest of build +process is handled by C. Typically, ExtUtils::MakeMaker build system can +be identified by presence of the F script in the source directory. + +=head1 DH_AUTO NOTES + +Out of source tree building is not supported. + +=head1 BUILD PROCESS + +=cut + use strict; use base 'Debian::Debhelper::Buildsystem::makefile'; @@ -42,6 +65,24 @@ sub new { return $this; } +=head2 Configure step + +=over + +=item I + +Execute C script passing C and +C parameters. Environment variables C +and C are exported before running the script. + +=item I + +If F file exists but F does not exist in the source +directory. + +=back + +=cut sub configure { my $this=shift; # If set to a true value then MakeMaker's prompt function will @@ -55,10 +96,87 @@ sub configure { @_); } +=head2 Build step + +=over 4 + +=item I + +Execute C in the build directory. See I build system +documentation for more information. + +=item I + +Both F and F exist in the source directory. + +=back + +=head2 Test step + +=over 4 + +=item I + +Execute C in the source directory. See I build system +documentation for more information. + +=item I + +Both F and F exist in the source directory. + +=back + +=cut + +=head2 Install step + +=over 4 + +=item I + +Execute C in the source directory +with $destdir set to the appropriate temporary installation directory. See +I build system documentation for more information. + +=item I + +Both F and F exist in the source directory. + +=back + +=cut sub install { my $this=shift; my $destdir=shift; $this->SUPER::install($destdir, "PREFIX=/usr", @_); } +=head2 Clean step + +=over 4 + +=item I + +Execute C in the source directory. See I build system +documentation for more information. + +=item I + +Both F and F exist in the source directory. + +=back + +=head1 SEE ALSO + +L + +L + +=head1 AUTHORS + + Joey Hess + Modestas Vainius + +=cut + 1; diff --git a/Debian/Debhelper/Buildsystem/python_distutils.pm b/Debian/Debhelper/Buildsystem/python_distutils.pm index ad4ea877..8266fa0b 100644 --- a/Debian/Debhelper/Buildsystem/python_distutils.pm +++ b/Debian/Debhelper/Buildsystem/python_distutils.pm @@ -7,6 +7,37 @@ package Debian::Debhelper::Buildsystem::python_distutils; +=head1 NAME + +B - Python Distutils (setup.py) + +=head1 SYNOPSIS + +B [B<--buildsystem>=I] ... + +=head1 DESCRIPTION + +Python Distribution Utilities (Distutils for short) is a standard Python build +system. It is used to package most of the Python modules in the source +distribution form. Typically, only two steps (build and install) are needed to +finish installation of the Distutils based Python module. This build system can +be typically identified by presence of the F in the source directory. + +=head1 DH_AUTO NOTES + +Out of source tree building is done by default but in source building is also +supported. PLEASE NOTE that B is B<$srcdir/build> +where $srcdir is a path to the source directory. + +Due to design flaws of Distutils, it is not possible to set a B build +directory via command line arguments to F. Therefore, the same effect +is achieved by writing appropriate F<.pydistutils.cfg> file to the build +directory and pointing $HOME environment variable to the build directory. + +=head1 BUILD PROCESS + +=cut + use strict; use Cwd (); use Debian::Debhelper::Dh_Lib qw(error); @@ -81,17 +112,104 @@ sub setup_py { $this->doit_in_sourcedir("python", "setup.py", $act, @_); } +=head2 Configure step + +=over 4 + +=item I + +Do nothing but stop auto-selection process. + +=item I + +If neither F, F exist, but F exists in the +source directory. + +=back + +=cut + +=head2 Build step + +=over 4 + +=item I + +Execute C. + +=item I + +If F, F F do not exist in the build directory +and F file exists in the source directory. + +=back + +=cut sub build { my $this=shift; $this->setup_py("build", @_); } +=head2 Test step + +=over 4 + +=item I + +Do nothing but stop auto-selection process. + +=item I + +F, F, F do not exist in the build directory and +F file exists in the source directory. + +=back + +=cut + +=head2 Install step + +=over 4 + +=item I + +Execute C passing temporary installation directory via +C<--root> parameter. C<--no-compile> and C<-O0> parameters are also passed by +default. See L for more information. + +=item I + +F, F, F do not exist in the build directory and +F file exists in the source directory. + +=back + +=cut sub install { my $this=shift; my $destdir=shift; $this->setup_py("install", "--root=$destdir", "--no-compile", "-O0", @_); } +=head2 Clean step + +=over 4 + +=item I + +Execute C. Additional parameters (if specified) are +passed to the latter command. F<.pydistutils.cfg> is also removed if it was +created (together with the build directory if it is ends up empty). Finally, +recursively find and delete all *.pyc files from the source directory. + +=item I + +F, F, F do not exist in the build directory and +F file exists in the source directory. + +=back + +=cut sub clean { my $this=shift; $this->setup_py("clean", "-a", @_); @@ -106,4 +224,15 @@ sub clean { $this->doit_in_sourcedir('find', '.', '-name', '*.pyc', '-exec', 'rm', '{}', ';'); } +=head1 SEE ALSO + +L + +=head1 AUTHORS + + Joey Hess + Modestas Vainius + +=cut + 1; -- cgit v1.2.3