Debian/Debhelper/Buildsystem/python_distutils.pm

   1 # A debhelper build system class for building Python Distutils based
   2 # projects. It prefers out of source tree building.
   3 #
   4 # Copyright: © 2008 Joey Hess
   5 #            © 2008-2009 Modestas Vainius
   6 # License: GPL-2+
   7
   8 package Debian::Debhelper::Buildsystem::python_distutils;
   9
  10 =head1 NAME
  11
  12 B<python_distutils> - Python Distutils (setup.py)
  13
  14 =head1 SYNOPSIS
  15
  16 B<dh_auto_*> [B<--buildsystem>=I<python_distutils>] ...
  17
  18 =head1 DESCRIPTION
  19
  20 Python Distribution Utilities (Distutils for short) is a standard Python build
  21 system. It is used to package most of the Python modules in the source
  22 distribution form. Typically, only two steps (build and install) are needed to
  23 finish installation of the Distutils based Python module. This build system can
  24 be typically identified by presence of the F<setup.py> in the source directory.
  25
  26 =head1 DH_AUTO NOTES
  27
  28 Out of source tree building is done by default but in source building is also
  29 supported. PLEASE NOTE that B<default build directory> is B<$srcdir/build>
  30 where $srcdir is a path to the source directory.
  31
  32 Due to design flaws of Distutils, it is not possible to set a B<custom> build
  33 directory via command line arguments to F<setup.py>. Therefore, the same effect
  34 is achieved by writing appropriate F<.pydistutils.cfg> file to the build
  35 directory and pointing $HOME environment variable to the build directory.
  36
  37 =head1 BUILD PROCESS
  38
  39 =cut
  40
  41 use strict;
  42 use Cwd ();
  43 use Debian::Debhelper::Dh_Lib qw(error);
  44 use base 'Debian::Debhelper::Buildsystem';
  45
  46 sub DESCRIPTION {
  47         "Python Distutils (setup.py)"
  48 }
  49
  50 sub DEFAULT_BUILD_DIRECTORY {
  51         my $this=shift;
  52         return $this->_canonpath($this->get_sourcepath("build"));
  53 }
  54
  55 sub new {
  56         my $class=shift;
  57         my $this=$class->SUPER::new(@_);
  58         # Out of source tree building is prefered.
  59         $this->enforce_out_of_source_building(@_);
  60         return $this;
  61 }
  62
  63 sub check_auto_buildable {
  64         my $this=shift;
  65         return -e $this->get_sourcepath("setup.py");
  66 }
  67
  68 sub not_our_cfg {
  69         my $this=shift;
  70         my $ret;
  71         if (open(my $cfg, $this->get_buildpath(".pydistutils.cfg"))) {
  72                 $ret = not "# Created by dh_auto\n" eq <$cfg>;
  73                 close $cfg;
  74         }
  75         return $ret;
  76 }
  77
  78 sub create_cfg {
  79         my $this=shift;
  80         if (open(my $cfg, ">", $this->get_buildpath(".pydistutils.cfg"))) {
  81                 print $cfg "# Created by dh_auto", "\n";
  82                 print $cfg "[build]\nbuild-base=", $this->get_build_rel2sourcedir(), "\n";
  83                 close $cfg;
  84                 return 1;
  85         }
  86         return 0;
  87 }
  88
  89 sub pre_building_step {
  90         my $this=shift;
  91         my $step=shift;
  92
  93         return unless grep /$step/, qw(build install clean);
  94
  95         # --build-base can only be passed to the build command. However,
  96         # it is always read from the config file (really weird design).
  97         # Therefore create such a cfg config file.
  98         if ($this->get_buildpath() ne $this->DEFAULT_BUILD_DIRECTORY()) {
  99                 not $this->not_our_cfg() or
 100                     error("cannot set custom build directory: .pydistutils.cfg is in use");
 101                 $this->mkdir_builddir();
 102                 $this->create_cfg() or
 103                     error("cannot set custom build directory: unwritable .pydistutils.cfg");
 104                 # Distutils reads $HOME/.pydistutils.cfg
 105                 $ENV{HOME} = Cwd::abs_path($this->get_buildpath());
 106         }
 107 }
 108
 109 sub setup_py {
 110         my $this=shift;
 111         my $act=shift;
 112         $this->doit_in_sourcedir("python", "setup.py", $act, @_);
 113 }
 114
 115 =head2 Configure step
 116
 117 =over 4
 118
 119 =item I<Behaviour>
 120
 121 Do nothing but stop auto-selection process.
 122
 123 =item I<Auto-selection>
 124
 125 If neither F<configure>, F<Makefile.PL> exist, but F<setup.py> exists in the
 126 source directory.
 127
 128 =back
 129
 130 =cut
 131
 132 =head2 Build step
 133
 134 =over 4
 135
 136 =item I<Behaviour>
 137
 138 Execute C<python setup.py build>.
 139
 140 =item I<Auto-selection>
 141
 142 If F<Makefile>, F<makefile> F<GNUmakefile> do not exist in the build directory
 143 and F<setup.py> file exists in the source directory.
 144
 145 =back
 146
 147 =cut
 148 sub build {
 149         my $this=shift;
 150         $this->setup_py("build", @_);
 151 }
 152
 153 =head2 Test step
 154
 155 =over 4
 156
 157 =item I<Behaviour>
 158
 159 Do nothing but stop auto-selection process.
 160
 161 =item I<Auto-selection>
 162
 163 F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
 164 F<setup.py> file exists in the source directory.
 165
 166 =back
 167
 168 =cut
 169
 170 =head2 Install step
 171
 172 =over 4
 173
 174 =item I<Behaviour>
 175
 176 Execute C<python setup.py install> passing temporary installation directory via
 177 C<--root> parameter. C<--no-compile> and C<-O0> parameters are also passed by
 178 default. See L<dh_auto_install(1)> for more information.
 179
 180 =item I<Auto-selection>
 181
 182 F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
 183 F<setup.py> file exists in the source directory.
 184
 185 =back
 186
 187 =cut
 188 sub install {
 189         my $this=shift;
 190         my $destdir=shift;
 191         $this->setup_py("install", "--root=$destdir", "--no-compile", "-O0", @_);
 192 }
 193
 194 =head2 Clean step
 195
 196 =over 4
 197
 198 =item I<Behaviour>
 199
 200 Execute C<python setup.py clean -a>. Additional parameters (if specified) are
 201 passed to the latter command. F<.pydistutils.cfg> is also removed if it was
 202 created (together with the build directory if it is ends up empty). Finally,
 203 recursively find and delete all *.pyc files from the source directory.
 204
 205 =item I<Auto-selection>
 206
 207 F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
 208 F<setup.py> file exists in the source directory.
 209
 210 =back
 211
 212 =cut
 213 sub clean {
 214         my $this=shift;
 215         $this->setup_py("clean", "-a", @_);
 216
 217         # Config file will remain if it was created by us
 218         if (!$this->not_our_cfg()) {
 219                 unlink($this->get_buildpath(".pydistutils.cfg"));
 220                 $this->rmdir_builddir(1); # only if empty
 221         }
 222         # The setup.py might import files, leading to python creating pyc
 223         # files.
 224         $this->doit_in_sourcedir('find', '.', '-name', '*.pyc', '-exec', 'rm', '{}', ';');
 225 }
 226
 227 =head1 SEE ALSO
 228
 229 L<dh_auto(7)>
 230
 231 =head1 AUTHORS
 232
 233  Joey Hess <joeyh@debian.org>
 234  Modestas Vainius <modestas@vainius.eu>
 235
 236 =cut
 237
 238 1;