-# A buildsystem plugin for building Python Distutils based
-# projects.
+# A debhelper build system class for building Python Distutils based
+# projects. It prefers out of source tree building.
#
# Copyright: © 2008 Joey Hess
# © 2008-2009 Modestas Vainius
package Debian::Debhelper::Buildsystem::python_distutils;
+=head1 NAME
+
+B<python_distutils> - Python Distutils (setup.py)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<python_distutils>] ...
+
+=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<setup.py> 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<default build directory> 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<custom> build
+directory via command line arguments to F<setup.py>. 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 Debian::Debhelper::Dh_Lib;
-use base 'Debian::Debhelper::Dh_Buildsystem';
+use Cwd ();
+use Debian::Debhelper::Dh_Lib qw(error);
+use base 'Debian::Debhelper::Buildsystem';
sub DESCRIPTION {
- "support for building Python distutils based packages"
+ "Python Distutils (setup.py)"
+}
+
+sub DEFAULT_BUILD_DIRECTORY {
+ my $this=shift;
+ return $this->_canonpath($this->get_sourcepath("build"));
+}
+
+sub new {
+ my $class=shift;
+ my $this=$class->SUPER::new(@_);
+ # Out of source tree building is prefered.
+ $this->enforce_out_of_source_building(@_);
+ return $this;
}
sub check_auto_buildable {
- return -e "setup.py";
+ my $this=shift;
+ return -e $this->get_sourcepath("setup.py");
}
-sub setup_py {
- my $self=shift;
- my $act=shift;
+sub not_our_cfg {
+ my $this=shift;
+ my $ret;
+ if (open(my $cfg, $this->get_buildpath(".pydistutils.cfg"))) {
+ $ret = not "# Created by dh_auto\n" eq <$cfg>;
+ close $cfg;
+ }
+ return $ret;
+}
- if ($self->get_builddir()) {
- unshift @_, "--build-base=" . $self->get_builddir();
+sub create_cfg {
+ my $this=shift;
+ if (open(my $cfg, ">", $this->get_buildpath(".pydistutils.cfg"))) {
+ print $cfg "# Created by dh_auto", "\n";
+ print $cfg "[build]\nbuild-base=", $this->get_build_rel2sourcedir(), "\n";
+ close $cfg;
+ return 1;
}
- doit("python", "setup.py", $act, @_);
+ return 0;
+}
+
+sub pre_building_step {
+ my $this=shift;
+ my $step=shift;
+
+ return unless grep /$step/, qw(build install clean);
+
+ # --build-base can only be passed to the build command. However,
+ # it is always read from the config file (really weird design).
+ # Therefore create such a cfg config file.
+ if ($this->get_buildpath() ne $this->DEFAULT_BUILD_DIRECTORY()) {
+ not $this->not_our_cfg() or
+ error("cannot set custom build directory: .pydistutils.cfg is in use");
+ $this->mkdir_builddir();
+ $this->create_cfg() or
+ error("cannot set custom build directory: unwritable .pydistutils.cfg");
+ # Distutils reads $HOME/.pydistutils.cfg
+ $ENV{HOME} = Cwd::abs_path($this->get_buildpath());
+ }
+}
+
+sub setup_py {
+ my $this=shift;
+ my $act=shift;
+ $this->doit_in_sourcedir("python", "setup.py", $act, @_);
}
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing but stop auto-selection process.
+
+=item I<Auto-selection>
+
+If neither F<configure>, F<Makefile.PL> exist, but F<setup.py> exists in the
+source directory.
+
+=back
+
+=cut
+
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py build>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile> F<GNUmakefile> do not exist in the build directory
+and F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
sub build {
- my $self=shift;
- $self->setup_py("build", @_);
+ my $this=shift;
+ $this->setup_py("build", @_);
}
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing but stop auto-selection process.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py install> passing temporary installation directory via
+C<--root> parameter. C<--no-compile> and C<-O0> parameters are also passed by
+default. See L<dh_auto_install(1)> for more information.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
sub install {
- my $self=shift;
+ my $this=shift;
my $destdir=shift;
- $self->setup_py("install", "--root=$destdir", "--no-compile", "-O0", @_);
+ $this->setup_py("install", "--root=$destdir", "--no-compile", "-O0", @_);
}
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py clean -a>. 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<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
sub clean {
- my $self=shift;
- $self->setup_py("clean", "-a", @_);
+ my $this=shift;
+ $this->setup_py("clean", "-a", @_);
+
+ # Config file will remain if it was created by us
+ if (!$this->not_our_cfg()) {
+ unlink($this->get_buildpath(".pydistutils.cfg"));
+ $this->rmdir_builddir(1); # only if empty
+ }
# The setup.py might import files, leading to python creating pyc
# files.
- doit('find', '.', '-name', '*.pyc', '-exec', 'rm', '{}', ';');
+ $this->doit_in_sourcedir('find', '.', '-name', '*.pyc', '-exec', 'rm', '{}', ';');
}
+=head1 SEE ALSO
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
1;