From e0ed03ff224ee3a8053094f02bcd02d4dd3fa358 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sun, 28 Jun 2009 15:01:04 -0400 Subject: [PATCH] Revert "Update dh_auto documentation." I'm reverting the documentation addition to try doing it myself, more simply and less verbosely. This reverts commit 962a2e10c930e3504ea1c0327be2fdf70d53023e. Conflicts: dh_auto.pod --- 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 -------- .../Debhelper/Buildsystem/perl_makemaker.pm | 118 ------- .../Debhelper/Buildsystem/python_distutils.pm | 129 -------- dh_auto.pod | 228 -------------- dh_auto_build | 34 +-- dh_auto_clean | 36 +-- dh_auto_configure | 43 +-- dh_auto_install | 37 +-- dh_auto_test | 44 ++- man/dh_auto_pod | 288 ------------------ 13 files changed, 70 insertions(+), 1398 deletions(-) delete mode 100644 dh_auto.pod delete mode 100755 man/dh_auto_pod diff --git a/Debian/Debhelper/Buildsystem/autoconf.pm b/Debian/Debhelper/Buildsystem/autoconf.pm index 9121a1d..60fa9e8 100644 --- a/Debian/Debhelper/Buildsystem/autoconf.pm +++ b/Debian/Debhelper/Buildsystem/autoconf.pm @@ -6,34 +6,6 @@ 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'; @@ -53,35 +25,6 @@ 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; @@ -109,79 +52,4 @@ 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 0275bfb..5662874 100644 --- a/Debian/Debhelper/Buildsystem/cmake.pm +++ b/Debian/Debhelper/Buildsystem/cmake.pm @@ -6,36 +6,6 @@ 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'; @@ -59,27 +29,6 @@ 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; @@ -93,78 +42,4 @@ 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 32ad517..d84d334 100644 --- a/Debian/Debhelper/Buildsystem/makefile.pm +++ b/Debian/Debhelper/Buildsystem/makefile.pm @@ -6,56 +6,6 @@ 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'; @@ -119,92 +69,22 @@ 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()) { @@ -212,15 +92,4 @@ 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 2621015..3567cb1 100644 --- a/Debian/Debhelper/Buildsystem/perl_build.pm +++ b/Debian/Debhelper/Buildsystem/perl_build.pm @@ -6,32 +6,6 @@ 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'; @@ -63,128 +37,31 @@ 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 102e23f..07a827a 100644 --- a/Debian/Debhelper/Buildsystem/perl_makemaker.pm +++ b/Debian/Debhelper/Buildsystem/perl_makemaker.pm @@ -6,29 +6,6 @@ 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'; @@ -65,24 +42,6 @@ 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 @@ -96,87 +55,10 @@ 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 5a04d4e..46f4c1c 100644 --- a/Debian/Debhelper/Buildsystem/python_distutils.pm +++ b/Debian/Debhelper/Buildsystem/python_distutils.pm @@ -7,37 +7,6 @@ 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); @@ -112,104 +81,17 @@ 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", @_); @@ -224,15 +106,4 @@ sub clean { $this->doit_in_sourcedir('find', '.', '-name', '*.pyc', '-exec', 'rm', '{}', ';'); } -=head1 SEE ALSO - -L - -=head1 AUTHORS - - Joey Hess - Modestas Vainius - -=cut - 1; diff --git a/dh_auto.pod b/dh_auto.pod deleted file mode 100644 index c8398b5..0000000 --- a/dh_auto.pod +++ /dev/null @@ -1,228 +0,0 @@ -=head1 NAME - -dh_auto - debhelper based package source building suite - -=head1 SYNOPTIS - -B [B<--buildsystem=>I] [B<--sourcedirectory=>I] [B<--builddirectory>[=I]] - -B B<--list> [B<-S>I] [B<-D>I] [B<-B>[I]] - -B B<--help-buildsystem> [B<-S>I] [B<-D>I] [B<-B>[I]] - -=head1 DESCRIPTION - -dh_auto is a family of debhelper programs that are responsible for managing -build process of the package sources. dh_auto takes a burden of identifying and -configuring package build system with a standard set of options that a typical -Debian package needs. However, it is also flexible enough to allow -customization of the build process in various ways. Due to good defaults, it -should be able to handle 90% of packages even without any additional arguments -passed to the dh_auto programs. Therefore, dh_auto is one of the main driving -forces behind the L command sequencer. Similarly, dh_auto programs can -be easily (either fully or partially) integrated into traditional Debian -packaging. - -One of the key dh_auto features is that it wraps around all common source build -systems and exposes their common features via well-defined command line -interface of the dh_auto programs. dh_auto is designed that each type of source -build system is handled by its corresponding I which -translates dh_auto options into the source build system specific details. -Therefore, dh_auto is capable to handle e.g. out of source tree building -transparently. - -The build process is split into 5 I: configure, build, test, -install and clean. Each step is managed by the respective dh_auto_$step -program. Each program accepts a set of shared dh_auto options, step specific -options (if any) and arbitrary number of extra arguments which are additionally -passed to the underlying build system command being executed. Whatever is -executed under the hood depends on the selected debhelper build system, -building step (i.e. dh_auto program) and dh_auto options in effect. - -=head1 DH_AUTO PROGRAMS - -=over 2 - -#DH_AUTO LIST# - -=back - -=head1 FEATURES - -=over 2 - -=item I - -dh_auto examines package source and/or build directories at each building step -looking for typical indications of the source build systems it supports. If the -build system is recognized, its corresponding building step commands are -executed. If more than one debhelper build system indicates to match the source -build system, only the first one is selected. If the build system isn't -recognized, dh_auto program silently succeeds. dh_auto programs may fail only -if wrong debhelper build system gets selected and/or source build system -commands fail or cannot be executed. - -The auto-selection process implies that a different but compatible debhelper -build system may be auto-selected at each building step. For example, GNU -Autoconf is just a configure layer on top of the simple Makefile build system. - -=item I - -In addition to the build system auto-selection, dh_auto offers a way for a user -to specify which debhelper build system to assume for the package. In such a -case, auto-selection is skipped entirely and no prior checks are made before -executing commands of the specified build system. Obviously, if a wrong build -system was specified and/or source build system commands failed or could not be -executed, the dh_auto program would fail too. - -Manual build system selection could be useful if package sources came with more -than one build system, auto-selection fails/gives wrong results due its -limitations or you want to use a third party debhelper build system (provided -by an external package (see below)). - -=item I - -Typically, the top directory of the package sources is where the debianization -directory (debian/) lives. However, sometimes the whole original source tree -might be somewhere in the subdirectory or a single Debian source package might -actually contain multiple original source packages with their contents being in -the separate subdirectories. dh_auto handles such cases by letting the user to -specify a path to the source directory. All dh_auto programs regardless of the -build system selected support source directory switching. - -=item I - -Throughout the build process of the most packages, lots of temporary files are -generated by their source build systems. Since they are of no use when binary -packages are built, it is a task of L to clean them up. If -temporary files are generated in the same directories where source files are, -it is referred as "in source building" in this documentation. However, some -build systems support the concept of "out of source tree" building when all -temporary files are generated in the arbitrary build directory avoiding -extensive pollution of the source tree. dh_auto allows to specify a path to the -build directory and then it will do out of source tree building in it if the -source build system supports this feature. - -In source building is a default mode and it is supported by most debhelper -build systems. However, some source build systems do not support in source -building or highly recommend out of source tree building. In this case, dh_auto -follows the recommendation and might default to the out of source tree building -even if the build directory was not explicitly specified. However, if the build -system does not support out of source tree building, it is an error to specify -the build directory. - -=item I - -It is very easy to write a third party debhelper build system class and ship it -in the external package. The only limitation is that support for it can only be -enabled manually (via "Manual build system selection"). Their auto-selection is -not allowed in order to keep the process stable under various system -configurations (i.e. when different sets of third party debhelper build systems -are installed). However, the user can always discover all standard and third -party debhelper build systems supported on the system by passing the L<--list> -option to any dh_auto program. - -=back - -Read section L for more details how to enable the -features listed above. - -=head1 SUPPORTED BUILD SYSTEMS - -dh_auto provides support for the most popular build systems out of the box -(listed below). See section L for more -information how each build system is auto-selected and what commands are -executed to complete each building step. To get information about a third party -debhelper build system installed on your system, use I<--help-buildsystem> -option. - -#SUPPORTED BUILD SYSTEMS# - -=head1 #SUPPORTED BUILD SYSTEMS INTRO FOR DH_AUTO PROGRAMS - -Below you will find a list of the debhelper build systems that are shipped with -debhelper itself along with their details concerning this building step. They -are listed in the order of auto-selection preference. Consult -L or L section of -L, or use L<--help--buildsystem> option for a more complete -reference about each build system. - -=head1 DH_AUTO SHARED OPTIONS - -=over 4 - -=item B<--buildsystem=>I, B<-S>I - -Select the specified debhelper I instead of trying to auto-select -one which might be applicable for the package. I specific commands -will be executed to complete a building step without any prior checks. This -option is also the only way to select a third party debhelper build system. - -=item B<--sourcedirectory>=I, B<-D>I - -Assume that the original package source tree is at the specified I -rather than the top level directory of the Debian source package tree (C<.>). -I path is assumed to be relative to the top level directory (where -debian/ is) and must exist. - -=item B<--builddirectory>=[I], B<-B>[I] - -Enable out of source building and use the specified I as the build -directory. If specified, I must be relative to the top level -directory of the Debian source package tree and generally does not need to -exist before the build process is started. If I parameter is -omitted, default build directory will be used. It is S> by default but any debhelper build system can choose -another value (see documentation of the debhelper build systems). - -If this option is not specified, building will be done in source by default -unless the selected build system enforces/prefers out of source tree building. -In such a case, the default build directory will be used even if -L<--builddirectory> is not specified. If the selected build system just prefers -out of source tree building but still allows in source building, the latter can -be re-enabled by passing a build directory path that is equal to the source -directory path. - -=item B<--list>, B<-l> - -List all debhelper build systems available on this system and exit. The list -includes both standard (listed first in the auto-selection order) and third -party build systems (clearly marked as such). The list is concluded with the -information about which build system would be auto-selected to complete the -building step or which one is manually specified with the I<--buildsystem> -option. - -=item B<--help-buildsystem> - -Print detailed help about a build system which would be auto-selected or which -is manually specified with the L<--buildsystem> option. Exit immediately -afterwards. - -=back - -=head1 DEBHELPER BUILD SYSTEM DETAILS - -This section provides more information about debhelper build systems supported -by default. They are listed in the order of auto-selection preference. The -first build system that matches auto-selection criteria is always selected and -the following ones are not even considered. Auto-selection conditions might -differ at each building step even for the same debhelper build system. - -#BUILD SYSTEM DETAILS# - -=head1 SEE ALSO - -L - -=over 2 - -=item B - -#BUILD SYSTEM MAN LIST# - -=back - -=head1 AUTHORS - - Joey Hess - Modestas Vainius diff --git a/dh_auto_build b/dh_auto_build index d16694c..56b9b5f 100755 --- a/dh_auto_build +++ b/dh_auto_build @@ -2,7 +2,7 @@ =head1 NAME -dh_auto_build - build package sources +dh_auto_build - automatically builds a package =cut @@ -11,21 +11,18 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S>] [S I>] +B [S>] [S I>] =head1 DESCRIPTION -dh_auto_build is a debhelper program that is responsible for the I step -of the L building process. Typically, this is the point when -package sources are compiled into binaries or otherwise transformed into ready -to use format. Files produced throughout this step are put to the build -directory. +dh_auto_build is a debhelper program that tries to automatically +build a package. If a Makefile is found, this is done by running make (or +MAKE, if the environment variable is set). +If there's a setup.py, or Build.PL, it is run to build the package. -You can pass additional parameters via I. However, if dh_auto_build -does not meet your needs or does not work, it is safe to skip/override it -entirely and build the package with custom commands. - -#DH_AUTO SHARED OPTIONS# +This is intended to work for about 90% of packages. If it doesn't work, +you're encouraged to skip using dh_auto_build at all, and just run the +build process manually. =head1 OPTIONS @@ -38,11 +35,6 @@ or override any standard parameters that dh_auto_build passes. =back -=head1 SUPPORTED BUILD SYSTEMS - -#SUPPORTED BUILD SYSTEMS INTRO# -#SUPPORTED BUILD SYSTEMS LIST# - =cut buildsystems_init(); @@ -50,16 +42,12 @@ buildsystems_do(); =head1 SEE ALSO -L - L -This program is a part of debhelper and its dh_auto package source building -suite. +This program is a part of debhelper. =head1 AUTHOR - Joey Hess - Modestas Vainius +Joey Hess =cut diff --git a/dh_auto_clean b/dh_auto_clean index 625675b..1b7d46c 100755 --- a/dh_auto_clean +++ b/dh_auto_clean @@ -2,7 +2,7 @@ =head1 NAME -dh_auto_clean - clean temporary files after building package sources +dh_auto_clean - automatically cleans up after a build =cut @@ -11,21 +11,19 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S>] [S I>] +B [S>] [S I>] =head1 DESCRIPTION -dh_auto_clean is a debhelper program that is responsible for the I step -of the L building process. It tries to automatically clean up after -a package build by removing all temporary files from the build directory or -even the build directory itself as appropriate. dh_auto_clean will fail only if -the source build system clean routine fails. However, if the latter does not -exist or there is nothing to clean it will exit with zero status doing nothing. +dh_auto_clean is a debhelper program that tries to automatically clean up +after a package build. If there's a Makefile and it contains a "distclean", +"realclean", or "clean" target, then this is done by running make (or MAKE, +if the environment variable is set). If there is a setup.py or Build.PL, it +is run to clean the package. -If dh_auto_clean does not meet your needs or does not work, it is safe to -skip/override it entirely and just run clean up manually. - -#DH_AUTO SHARED OPTIONS# +This is intended to work for about 90% of packages. If it doesn't work, or +tries to use the wrong clean target, you're encouraged to skip using +dh_auto_clean at all, and just run make clean manually. =head1 OPTIONS @@ -38,11 +36,6 @@ or override the any standard parameters that dh_auto_clean passes. =back -=head1 SUPPORTED BUILD SYSTEMS - -#SUPPORTED BUILD SYSTEMS INTRO# -#SUPPORTED BUILD SYSTEMS LIST# - =cut buildsystems_init(); @@ -50,15 +43,12 @@ buildsystems_do(); =head1 SEE ALSO -L - L -This program is a part of debhelper and its dh_auto package source building suite. +This program is a part of debhelper. -=head1 AUTHORS +=head1 AUTHOR - Joey Hess - Modestas Vainius +Joey Hess =cut diff --git a/dh_auto_configure b/dh_auto_configure index 3f326ce..34d6298 100755 --- a/dh_auto_configure +++ b/dh_auto_configure @@ -2,7 +2,7 @@ =head1 NAME -dh_auto_configure - configure and prepare package sources for building +dh_auto_configure - automatically configure a package prior to building =cut @@ -11,25 +11,19 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S>] [S I>] +B [S>] [S I>] =head1 DESCRIPTION -dh_auto_configure is a debhelper program that is responsible for the -I step of the L building process. Since I is -the first step, typically it is the point when build configuration options -are set, system settings are detected and various build system specific -temporary files are pre-generated in the build directory. Some simpler build -systems do not need this step. In such a case, dh_auto_configure silently -succeeds without doing anything. +dh_auto_configure is a debhelper program that tries to automatically +configure a package prior to building. It looks for and runs a ./configure +script, Makefile.PL, Build.PL, or cmake. A standard set of parameters is +determined and passed to the program that is run. If no program to run is +found, dh_auto_configure will exit without doing anything. -dh_auto_configure usually pre-configures the source build system with a set of -standard options which most Debian packages need to set anyway. Custom options -can be passed as I. If dh_auto_configure does not meet your needs or -does not work, it is safe to skip/override it entirely and just run a configure -script or its equivalent manually. - -#DH_AUTO SHARED OPTIONS# +This is intended to work for about 90% of packages. If it doesn't work, +you're encouraged to skip using dh_auto_configure at all, and just run +./configure or its equivalent manually. =head1 OPTIONS @@ -37,7 +31,7 @@ script or its equivalent manually. =item B<--> I -Pass I to the command that is run, after the standard +Pass "params" to the program that is run, after the standard parameters that dh_auto_configure passes. This can be used to supplement or override those parameters. For example: @@ -45,11 +39,6 @@ or override those parameters. For example: =back -=head1 SUPPORTED BUILD SYSTEMS - -#SUPPORTED BUILD SYSTEMS INTRO# -#SUPPORTED BUILD SYSTEMS LIST# - =cut buildsystems_init(); @@ -57,16 +46,12 @@ buildsystems_do(); =head1 SEE ALSO -L - L -This program is a part of debhelper and its dh_auto package source building -suite. +This program is a part of debhelper. -=head1 AUTHORS +=head1 AUTHOR - Joey Hess - Modestas Vainius +Joey Hess =cut diff --git a/dh_auto_install b/dh_auto_install index 5c77224..db2c6e9 100755 --- a/dh_auto_install +++ b/dh_auto_install @@ -2,7 +2,7 @@ =head1 NAME -dh_auto_install - install built files into the temporary directory under debian/ +dh_auto_install - automatically runs make install or similar =cut @@ -13,15 +13,14 @@ use Cwd; =head1 SYNOPSIS -B [S>] [S>] [S I>] +B [S>] [S I>] =head1 DESCRIPTION -dh_auto_install is a debhelper program that is responsible for the I -step of the L building process. dh_auto_install tries to run -original package installation routine to install built files into the proper -places of the file system hierarchy recreated under the (temporary) directory -in debian/. +dh_auto_install is a debhelper program that tries to automatically install +built files. If there's a Makefile and it contains a "install" target, +then this is done by running make (or MAKE, if the environment variable is +set). If there is a setup.py or Build.PL, it is used. The files are installed into debian// if there is only one binary package. In the multiple binary package case, the files are instead @@ -29,10 +28,13 @@ installed into debian/tmp/, and should be moved from there to the appropriate package build directory using L or L. -If dh_auto_install does not meet your needs or does not work, it is safe to -skip/override it entirely and just run C or the like manually. +DESTDIR is used to tell make where to install the files. +If the Makefile was generated by MakeMaker from a Makefile.PL, it will +automatically set PREFIX=/usr too, since such Makefiles need that. -#DH_AUTO SHARED OPTIONS# +This is intended to work for about 90% of packages. If it doesn't work, or +tries to use the wrong install target, you're encouraged to skip using +dh_auto_install at all, and just run make install manually. =head1 OPTIONS @@ -45,11 +47,6 @@ or override the any standard parameters that dh_auto_install passes. =back -=head1 SUPPORTED BUILD SYSTEMS - -#SUPPORTED BUILD SYSTEMS INTRO# -#SUPPORTED BUILD SYSTEMS LIST# - =cut buildsystems_init(); @@ -68,16 +65,12 @@ buildsystems_do("install", $destdir); =head1 SEE ALSO -L - L -This program is a part of debhelper and its dh_auto package source building -suite. +This program is a part of debhelper. -=head1 AUTHORS +=head1 AUTHOR - Joey Hess - Modestas Vainius +Joey Hess =cut diff --git a/dh_auto_test b/dh_auto_test index 062563f..e68bf09 100755 --- a/dh_auto_test +++ b/dh_auto_test @@ -2,7 +2,7 @@ =head1 NAME -dh_auto_test - run package test suites after building +dh_auto_test - automatically runs a package's test suites =cut @@ -11,26 +11,20 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S>] [S I>] +B [S>] [S I>] =head1 DESCRIPTION -dh_auto_test is a debhelper program that is responsible for the I step of -the L building process. Typically, this is the point when package -test suite is run to check if the sources were built successfully and/or -binaries provide expected functionality. dh_auto_test will fail if test suite -fails. However, if there's no test suite, it will exit with zero status -without doing anything. +dh_auto_test is a debhelper program that tries to automatically run a +package's test suite. If there's a Makefile and it contains a "test" +or "check" target, then this is done by running make (or MAKE, if the +environment variable is set). If the test suite fails, the command will +exit nonzero. If there's no test suite, it will exit zero without doing +anything. -If dh_auto_test does not meet your needs or does not work, it is safe to -skip/override it entirely and just run the test suite manually. - -=head1 NOTES - -If the DEB_BUILD_OPTIONS environment variable contains "nocheck", no tests will -be performed. - -#DH_AUTO SHARED OPTIONS# +This is intended to work for about 90% of packages with a test suite. If it +doesn't work, you're encouraged to skip using dh_auto_test at all, and +just run the test suite manually. =head1 OPTIONS @@ -43,10 +37,10 @@ or override the any standard parameters that dh_auto_test passes. =back -=head1 SUPPORTED BUILD SYSTEMS +=head1 NOTES -#SUPPORTED BUILD SYSTEMS INTRO# -#SUPPORTED BUILD SYSTEMS LIST# +If the DEB_BUILD_OPTIONS environment variable contains "nocheck", no +tests will be performed. =cut @@ -59,16 +53,12 @@ buildsystems_do(); =head1 SEE ALSO -L - L -This program is a part of debhelper and its dh_auto package source building -suite. +This program is a part of debhelper. -=head1 AUTHORS +=head1 AUTHOR - Joey Hess - Modestas Vainius +Joey Hess =cut diff --git a/man/dh_auto_pod b/man/dh_auto_pod deleted file mode 100755 index 01817b2..0000000 --- a/man/dh_auto_pod +++ /dev/null @@ -1,288 +0,0 @@ -#!/usr/bin/perl -w - -package CommandStrip; -use base Pod::Parser; - -sub command { - my $parser=shift; - if (!exists $parser->{_stripped_}) { - $parser->{_stripped_} = 1; - return; - } - return $parser->SUPER::command(@_); -} - -package main; - -use strict; -use warnings; -use Debian::Debhelper::Dh_Lib; -use Debian::Debhelper::Dh_Buildsystems; -use Pod::Select; -use IO::String; -use File::Spec; -use Pod::InputObjects; - -my @buildsystem_pods; -my $DH_AUTO_POD = "dh_auto.pod"; - -# Preloads build system PODs -sub get_buildsystem_pods { - my $parser = new Pod::Select(); - if (!@buildsystem_pods) { - my @buildsystems = load_all_buildsystems([ "." ]); - for my $system (@buildsystems) { - my $podfile = File::Spec->catfile("Debian/Debhelper/Buildsystem", $system->NAME() . ".pm"); - my $iostr = new IO::String(); - - open(my $fh, $podfile) or error("Unable to read $podfile"); - $system->{pod_fh} = $fh; - - # Extract build system name from POD - $parser->select('NAME'); - strip_first_command($parser, $fh, $iostr); - - # Remove empty lines and join new lines - $system->{pod_name} = join(" ", grep ! /^\s*$/, split(/\n/, ${$iostr->string_ref()})); - - push @buildsystem_pods, $system; - } - } - return @buildsystem_pods; -} - -# Strips the first command (i.e. line starting with =), prints -# everything else -sub strip_first_command { - my ($parser, $input_fh, $output_fh)=@_; - - my $iostr = new IO::String(); - seek(\*$input_fh, 0, 0); - $parser->parse_from_filehandle($input_fh, $iostr); - $iostr->pos(0); - CommandStrip->new()->parse_from_filehandle($iostr, $output_fh); - $iostr->close(); -} - -# Prints everything -sub print_everything { - my ($parser, $input_fh, $output_fh)=@_; - seek(\*$input_fh, 0, 0); - $parser->parse_from_filehandle($input_fh, $output_fh); -} - -# Prints POD paragraph -# Common parameters -name, -text. Results into =${-name} ${-text} -sub print_pod_parag { - my %args=@_; - my $output_fh = $args{output} || \*STDOUT; - print $output_fh Pod::Paragraph->new(@_)->raw_text(), "\n\n"; -} - -#sub unique_authors { -# my ($authors, $parser, $fh)=@_; -# my $iostr = new IO::String(); - -# $parser->select('AUTHOR[^\s]*'); -# seek(\*$fh, 0, 0); -# strip_first_command($parser, $fh, $iostr); -# $iostr->pos(0); -# while (my $author = <$iostr>) { -# $author =~ s/\s+/ /g; -# $author =~ s/^\s+//; -# $author =~ s/\s+$//; -# $authors->{$author} = scalar(keys %$authors) -# if !exists $authors->{$author}; -# } -# $iostr->close(); -#} - -############# Generation of dh_auto_step POD ############# - -sub get_dh_auto_shared_options_for_step { - my $step=shift; - my $parser = new Pod::Select(); - my $iostr = new IO::String(); - - $parser->select('DH_AUTO SHARED OPTIONS'); - print_everything($parser, \*DH_AUTO, $iostr); - return ${$iostr->string_ref()}; -} - -sub get_supported_buildsystems_intro_for_step { - my $step=shift; - my $parser = new Pod::Select(); - my $iostr = new IO::String(); - - # A common "SUPPORTED BUILD SYSTEMS" dh_auto POD - $parser->select('#SUPPORTED BUILD SYSTEMS INTRO FOR DH_AUTO PROGRAMS'); - strip_first_command($parser, \*DH_AUTO, $iostr); - return ${$iostr->string_ref()}; -} - -sub get_supported_buildsystems_list_for_step { - my $step=shift; - my $parser = new Pod::Select(); - my $iostr = new IO::String(); - - # Append build system list from build system PODs - for my $bs (get_buildsystem_pods()) { - my $bs_fh = $bs->{pod_fh}; - - # =head2 Build system name - print_pod_parag(output => $iostr, -name => 'head2', -text => $bs->{pod_name}); - - # Now print DH_AUTO NOTES - $parser->select('DH_AUTO NOTES'); - strip_first_command($parser, $bs_fh, $iostr); - - # And step specific help follows - $parser->select('BUILD PROCESS/' . ucfirst($step) . " step"); - strip_first_command($parser, $bs_fh, $iostr); - } - return ${$iostr->string_ref()}; -} - -sub generate_step_pod { - my $step=shift; - $step = $1 if ($step =~ /dh_auto_(.*)$/); - - my $dh_auto_step = "dh_auto_$step"; - my $dh_auto_shared_options = get_dh_auto_shared_options_for_step($step); - my $supported_bs_intro = get_supported_buildsystems_intro_for_step($step); - my $supported_bs_list = get_supported_buildsystems_list_for_step($step); - open(DH_AUTO_STEP, "podselect $dh_auto_step |") - or error("Unable to read $dh_auto_step"); - while () { - s/#DH_AUTO SHARED OPTIONS#/$dh_auto_shared_options/; - s/#SUPPORTED BUILD SYSTEMS INTRO#/$supported_bs_intro/; - s/#SUPPORTED BUILD SYSTEMS LIST#/$supported_bs_list/; - print $_; - } - close DH_AUTO_STEP; -} - -############# Generation of dh_auto POD ############# - -sub get_dh_auto_program_list_for_dh_auto { - my @steps=@_; - my $parser = new Pod::Select(); - my $collect = ""; - - $parser->select('NAME'); - foreach my $step (@steps) { - my $iostr = new IO::String(); - open (my $fh, "dh_auto_$step") or die "$_: $!"; - strip_first_command($parser, $fh, $iostr); - close $fh; - if (${$iostr->string_ref()} =~ /^(.*?) - (.*)/) { - $collect .= "=item $1(1)\n\n$2\n\n"; - } - } - return $collect; -} - -sub get_supported_buildsystems_for_dh_auto { - my $parser = new Pod::Select(); - my $iostr = new IO::String(); - - # Build system list from build system PODs (NAME + DESCRIPTION) - for my $bs (sort { $a->NAME() cmp $b->NAME() } get_buildsystem_pods()) { - my $bs_fh = $bs->{pod_fh}; - - # =head2 Build system name - print_pod_parag(output => $iostr, -name => 'head2', -text => $bs->{pod_name}); - - $parser->select('DESCRIPTION'); - strip_first_command($parser, $bs_fh, $iostr); - } - return ${$iostr->string_ref()}; -} - -sub get_buildsystem_details_for_dh_auto { - my @steps=@_; - my $parser = new Pod::Select(); - my $iostr = new IO::String(); - - # Build system details from build system PODs - for my $bs (get_buildsystem_pods()) { - my $bs_fh = $bs->{pod_fh}; - - print_pod_parag(output => $iostr, -name => 'head2', -text => $bs->NAME()); - - # Now print DH_AUTO NOTES - $parser->select('DH_AUTO NOTES'); - strip_first_command($parser, $bs_fh, $iostr); - - # And step specific documentation - for my $step (@steps) { - $parser->select('BUILD PROCESS/' . ucfirst($step) . " step"); - print_pod_parag(output => $iostr, -name => 'head3', -text => 'B<' . ucfirst($step) . " step>"); - strip_first_command($parser, $bs_fh, $iostr); - } - } - return ${$iostr->string_ref()}; -} - -sub get_dh_auto_program_man_list_for_dh_auto { - return join("\n\n", map { "L" } @_); -} - -sub get_buildsystem_man_list_for_dh_auto { - return join("\n\n", map { "LNAME() . "(7)>" } get_buildsystem_pods()); -} - -sub generate_dh_auto_pod { - my @steps=@_; - my $parser = new Pod::Select(); - my $iostr = new IO::String(); - - my $dh_auto_list = get_dh_auto_program_list_for_dh_auto(@steps); - my $supported_bs = get_supported_buildsystems_for_dh_auto(@steps); - my $bs_details = get_buildsystem_details_for_dh_auto(@steps); - my $dh_auto_man_list = get_dh_auto_program_man_list_for_dh_auto(@steps); - my $bs_man_list = get_buildsystem_man_list_for_dh_auto(); - - # Filter out all sections starting with # - $parser->select('[^#].*'); - print_everything($parser, \*DH_AUTO, $iostr); - - seek(\*$iostr, 0, 0); - while (<$iostr>) { - s/#DH_AUTO LIST#/$dh_auto_list/; - s/#SUPPORTED BUILD SYSTEMS#/$supported_bs/; - s/#BUILD SYSTEM DETAILS#/$bs_details/; - s/#DH_AUTO MAN LIST#/$dh_auto_man_list/; - s/#BUILD SYSTEM MAN LIST#/$bs_man_list/; - print $_; - } - $iostr->close(); -} - -############# Entry point ############# - -my @args; -my $outfile; -foreach (@ARGV) { - if (/^-o(.*)/) { - $outfile = $1; - } - else { - push @args, $_; - } -} - -if ($outfile) { - open(OUTFILE, ">", $outfile) or die "Unable to open output file $outfile"; - open(STDOUT, ">&OUTFILE") or die "Unable to redirect standard output"; -} - -open(DH_AUTO, $DH_AUTO_POD) or error("Unable to read $DH_AUTO_POD"); -if (@args > 0) { - generate_step_pod(@args); -} -else { - generate_dh_auto_pod(qw(configure build test install clean)); -} -close DH_AUTO; -close OUTFILE if $outfile; -- 2.39.2