From: Yitzchak Scott-Thoennes Date: Sun, 5 Mar 2006 12:08:30 +0000 (-0800) Subject: add Module::Build 0.27_08 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=bb4e916294fdfa799a0a8b106d12e462bbe2a427;p=p5sagit%2Fp5-mst-13.2.git add Module::Build 0.27_08 Message-ID: <20060305200830.GA2660@efn.org> p4raw-id: //depot/perl@27389 --- diff --git a/MANIFEST b/MANIFEST index 18f2308..6ae4262 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1943,6 +1943,55 @@ lib/Memoize/t/tie_sdbm.t Memoize SDBM interface test lib/Memoize/t/tie_storable.t Memoize Storable interface test lib/Memoize/t/tie.t Memoize tied file test lib/Memoize/t/unmemoize.t Memoize 'unmemoize' function test +lib/Module/Build/Authoring.pod Module::Build +lib/Module/Build/Base.pm Module::Build +lib/Module/Build/Changes Module::Build +lib/Module/Build/Compat.pm Module::Build +lib/Module/Build/ConfigData.pm Module::Build +lib/Module/Build/Cookbook.pm Module::Build +lib/Module/Build/ModuleInfo.pm Module::Build +lib/Module/Build/Notes.pm Module::Build +lib/Module/Build/Platform/aix.pm Module::Build +lib/Module/Build/Platform/Amiga.pm Module::Build +lib/Module/Build/Platform/cygwin.pm Module::Build +lib/Module/Build/Platform/darwin.pm Module::Build +lib/Module/Build/Platform/Default.pm Module::Build +lib/Module/Build/Platform/EBCDIC.pm Module::Build +lib/Module/Build/Platform/MacOS.pm Module::Build +lib/Module/Build/Platform/MPEiX.pm Module::Build +lib/Module/Build/Platform/os2.pm Module::Build +lib/Module/Build/Platform/RiscOS.pm Module::Build +lib/Module/Build/Platform/Unix.pm Module::Build +lib/Module/Build/Platform/VMS.pm Module::Build +lib/Module/Build/Platform/VOS.pm Module::Build +lib/Module/Build/Platform/Windows.pm Module::Build +lib/Module/Build/PodParser.pm Module::Build +lib/Module/Build/PPMMaker.pm Module::Build +lib/Module/Build/scripts/config_data Module::Build +lib/Module/Build/t/basic.t Module::Build +lib/Module/Build/t/compat.t Module::Build +lib/Module/Build/t/destinations.t Module::Build +lib/Module/Build/t/ext.t Module::Build +lib/Module/Build/t/extend.t Module::Build +lib/Module/Build/t/files.t Module::Build +lib/Module/Build/t/install.t Module::Build +lib/Module/Build/t/lib/DistGen.pm Module::Build +lib/Module/Build/t/lib/MBTest.pm Module::Build +lib/Module/Build/t/manifypods.t Module::Build +lib/Module/Build/t/metadata.t Module::Build +lib/Module/Build/t/metadata2.t Module::Build +lib/Module/Build/t/moduleinfo.t Module::Build +lib/Module/Build/t/notes.t Module::Build +lib/Module/Build/t/parents.t Module::Build +lib/Module/Build/t/pod_parser.t Module::Build +lib/Module/Build/t/ppm.t Module::Build +lib/Module/Build/t/runthrough.t Module::Build +lib/Module/Build/t/signature.t Module::Build +lib/Module/Build/t/tilde.t Module::Build +lib/Module/Build/t/versions.t Module::Build +lib/Module/Build/t/xs.t Module::Build +lib/Module/Build/t/bundled/Tie/CPHash.pm Module::Build.pm +lib/Module/Build.pm Module::Build lib/Module/CoreList/bin/corelist Module::CoreList lib/Module/CoreList.pm Module::CoreList lib/Module/CoreList/t/corelist.t Module::CoreList @@ -3479,6 +3528,7 @@ utfebcdic.h Unicode on EBCDIC (UTF-EBCDIC, tr16) header util.c Utility routines util.h Dummy header utils/c2ph.PL program to translate dbx stabs to perl +utils/config_data.PL Module::Build tool utils/corelist.PL Module::CoreList utils/cpan.PL easily interact with CPAN from the command line utils/dprofpp.PL Perl code profile post-processor diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index 9bc368e..d8ef76b 100644 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -382,6 +382,13 @@ package Maintainers; 'CPAN' => 1, }, + 'Module::Build' => + { + 'MAINTAINER' => 'kwilliams', + 'FILES' => q[lib/Module/Build lib/Module/Build.pm], + 'CPAN' => 1, + }, + 'Module::CoreList' => { 'MAINTAINER' => 'rclamp', diff --git a/installperl b/installperl index d50ee74..2f59f45 100755 --- a/installperl +++ b/installperl @@ -806,9 +806,9 @@ sub installlib { # ignore the cpan script in lib/CPAN/bin, the instmodsh and xsubpp # scripts in lib/ExtUtils, the prove script in lib/Test/Harness, # the corelist script from lib/Module/CoreList/bin and ptar* in - # lib/Archive/Tar/bin + # lib/Archive/Tar/bin, the config_data script in lib/Module/Build/scripts # (they're installed later with other utils) - return if $name =~ /^(?:cpan|instmodsh|prove|corelist|ptar|ptardiff)\z/; + return if $name =~ /^(?:cpan|instmodsh|prove|corelist|ptar|ptardiff|config_data)\z/; # ignore the Makefiles return if $name =~ /^makefile$/i; # ignore the test extensions diff --git a/lib/Module/Build.pm b/lib/Module/Build.pm new file mode 100644 index 0000000..5aa73d8 --- /dev/null +++ b/lib/Module/Build.pm @@ -0,0 +1,1012 @@ +package Module::Build; + +# This module doesn't do much of anything itself, it inherits from the +# modules that do the real work. The only real thing it has to do is +# figure out which OS-specific module to pull in. Many of the +# OS-specific modules don't do anything either - most of the work is +# done in Module::Build::Base. + +use strict; +use File::Spec (); +use File::Path (); +use File::Basename (); + +use Module::Build::Base; + +use vars qw($VERSION @ISA); +@ISA = qw(Module::Build::Base); +$VERSION = '0.27_08'; +$VERSION = eval $VERSION; + +# Okay, this is the brute-force method of finding out what kind of +# platform we're on. I don't know of a systematic way. These values +# came from the latest (bleadperl) perlport.pod. + +my %OSTYPES = qw( + aix Unix + bsdos Unix + dgux Unix + dynixptx Unix + freebsd Unix + linux Unix + hpux Unix + irix Unix + darwin Unix + machten Unix + next Unix + openbsd Unix + netbsd Unix + dec_osf Unix + svr4 Unix + svr5 Unix + sco_sv Unix + unicos Unix + unicosmk Unix + solaris Unix + sunos Unix + cygwin Unix + os2 Unix + + dos Windows + MSWin32 Windows + + os390 EBCDIC + os400 EBCDIC + posix-bc EBCDIC + vmesa EBCDIC + + MacOS MacOS + VMS VMS + VOS VOS + riscos RiscOS + amigaos Amiga + mpeix MPEiX + ); + +# Inserts the given module into the @ISA hierarchy between +# Module::Build and its immediate parent +sub _interpose_module { + my ($self, $mod) = @_; + eval "use $mod"; + die $@ if $@; + + no strict 'refs'; + my $top_class = $mod; + while (@{"${top_class}::ISA"}) { + last if ${"${top_class}::ISA"}[0] eq $ISA[0]; + $top_class = ${"${top_class}::ISA"}[0]; + } + + @{"${top_class}::ISA"} = @ISA; + @ISA = ($mod); +} + +if (grep {-e File::Spec->catfile($_, qw(Module Build Platform), $^O) . '.pm'} @INC) { + __PACKAGE__->_interpose_module("Module::Build::Platform::$^O"); + +} elsif (exists $OSTYPES{$^O}) { + __PACKAGE__->_interpose_module("Module::Build::Platform::$OSTYPES{$^O}"); + +} else { + warn "Unknown OS type '$^O' - using default settings\n"; +} + +sub os_type { $OSTYPES{$^O} } + +1; + +__END__ + + +=head1 NAME + +Module::Build - Build and install Perl modules + + +=head1 SYNOPSIS + +Standard process for building & installing modules: + + perl Build.PL + ./Build + ./Build test + ./Build install + +Or, if you're on a platform (like DOS or Windows) that doesn't require +the "./" notation, you can do this: + + perl Build.PL + Build + Build test + Build install + + +=head1 DESCRIPTION + +C is a system for building, testing, and installing +Perl modules. It is meant to be an alternative to +C. Developers may alter the behavior of the +module through subclassing in a much more straightforward way than +with C. It also does not require a C on your system +- most of the C code is pure-perl and written in a very +cross-platform way. In fact, you don't even need a shell, so even +platforms like MacOS (traditional) can use it fairly easily. Its only +prerequisites are modules that are included with perl 5.6.0, and it +works fine on perl 5.005 if you can install a few additional modules. + +See L<"MOTIVATIONS"> for more comparisons between C +and C. + +To install C, and any other module that uses +C for its installation process, do the following: + + perl Build.PL # 'Build.PL' script creates the 'Build' script + ./Build # Need ./ to ensure we're using this "Build" script + ./Build test # and not another one that happens to be in the PATH + ./Build install + +This illustrates initial configuration and the running of three +'actions'. In this case the actions run are 'build' (the default +action), 'test', and 'install'. Other actions defined so far include: + + build html + clean install + code manifest + config_data manpages + diff ppd + dist ppmdist + distcheck prereq_report + distclean pure_install + distdir realclean + distmeta skipcheck + distsign test + disttest testcover + docs testdb + fakeinstall testpod + help versioninstall + + +You can run the 'help' action for a complete list of actions. + + +=head1 GUIDE TO DOCUMENTATION + +The documentation for C is broken up into three sections: + +=over + +=item General Usage (L) + +This is the document you are currently reading. It describes basic +usage and background information. Its main purpose is to assist the +user who wants to learn how to invoke and control C +scripts at the command line. + +=item Authoring Reference (L) + +This document describes the C API for authors who are +writing F scripts for a distribution or controlling +C processes programmatically. It describes the +methods available as well as providing general information on +subclassing C to alter and extend its behavior. Also, +there is a section on controlling the Build process from other +scripts, including how to construct an object and how to invoke +actions through it from an external script. + +=item Cookbook (L) + +This document demonstrates how to accomplish many common tasks. It +covers general command line usage and authoring of F +scripts. Includes working examples. + +=back + + +=head1 ACTIONS + +There are some general principles at work here. First, each task when +building a module is called an "action". These actions are listed +above; they correspond to the building, testing, installing, +packaging, etc., tasks. + +Second, arguments are processed in a very systematic way. Arguments +are always key=value pairs. They may be specified at C +time (i.e. C), in which case +their values last for the lifetime of the C script. They may +also be specified when executing a particular action (i.e. +C), in which case their values last only for the +lifetime of that command. Per-action command line parameters take +precedence over parameters specified at C time. + +The build process also relies heavily on the C module, and +all the key=value pairs in C are available in + +C<< $self->{config} >>. If the user wishes to override any of the +values in C, she may specify them like so: + + perl Build.PL --config cc=gcc --config ld=gcc + +The following build actions are provided by default. + +=over 4 + +=item build + +If you run the C script without any arguments, it runs the +C action, which in turn runs the C and C actions. + +This is analogous to the MakeMaker 'make all' target. + +=item clean + +This action will clean up any files that the build process may have +created, including the C directory (but not including the +C<_build/> directory and the C script itself). + +=item code + +This action builds your codebase. + +By default it just creates a C directory and copies any C<.pm> +and C<.pod> files from your C directory into the C +directory. It also compiles any C<.xs> files from C and places +them in C. Of course, you need a working C compiler (probably +the same one that built perl itself) for the compilation to work +properly. + +The C action also runs any C<.PL> files in your F +directory. Typically these create other files, named the same but +without the C<.PL> ending. For example, a file F +could create the file F. The C<.PL> files are +processed first, so any C<.pm> files (or other kinds that we deal +with) will get copied correctly. + +=item config_data + +... + +=item diff + +This action will compare the files about to be installed with their +installed counterparts. For .pm and .pod files, a diff will be shown +(this currently requires a 'diff' program to be in your PATH). For +other files like compiled binary files, we simply report whether they +differ. + +A C parameter may be passed to the action, which will be passed +to the 'diff' program. Consult your 'diff' documentation for the +parameters it will accept - a good one is C<-u>: + + ./Build diff flags=-u + +=item dist + +This action is helpful for module authors who want to package up their +module for source distribution through a medium like CPAN. It will create a +tarball of the files listed in F and compress the tarball using +GZIP compression. + +By default, this action will use the external C and C +executables on Unix-like platforms, and the C module +elsewhere. However, you can force it to use whatever executable you +want by supplying an explicit C (and optional C) parameter: + + ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe + +=item distcheck + +Reports which files are in the build directory but not in the +F file, and vice versa. (See L for details.) + +=item distclean + +Performs the 'realclean' action and then the 'distcheck' action. + +=item distdir + +Creates a "distribution directory" named C<$dist_name-$dist_version> +(if that directory already exists, it will be removed first), then +copies all the files listed in the F file to that directory. +This directory is what the distribution tarball is created from. + +=item distmeta + +Creates the F file that describes the distribution. + +F is a file containing various bits of "metadata" about the +distribution. The metadata includes the distribution name, version, +abstract, prerequisites, license, and various other data about the +distribution. This file is created as F in YAML format, so +the C module must be installed in order to create it. The +F file must also be listed in F - if it's not, a +warning will be issued. + +The current version of the F specification can be found at +L + +=item distsign + +Uses C to create a SIGNATURE file for your +distribution, and adds the SIGNATURE file to the distribution's +MANIFEST. + +=item disttest + +Performs the 'distdir' action, then switches into that directory and +runs a C, followed by the 'build' and 'test' actions in +that directory. + +=item docs + +This will generate documentation (e.g. Unix man pages and html +documents) for any installable items under B that +contain POD. If there are no C or C installation +targets defined (as will be the case on systems that don't support +Unix manpages) no action is taken for manpages. If there are no +C or C installation targets defined no action is +taken for html documents. + +=item fakeinstall + +This is just like the C action, but it won't actually do +anything, it will just report what it I have done if you had +actually run the C action. + +=item help + +This action will simply print out a message that is meant to help you +use the build process. It will show you a list of available build +actions too. + +With an optional argument specifying an action name (e.g. C), the 'help' action will show you any POD documentation it can +find for that action. + +=item html + +This will generate HTML documentation for any binary or library files +under B that contain POD. The HTML documentation will only be +installed if the install paths can be determined from values in +C. You can also supply or override install paths on the +command line by specifying C values for the C +and/or C installation targets. + +=item install + +This action will use C to install the files from +C into the system. See L +for details about how Module::Build determines where to install +things, and how to influence this process. + +If you want the installation process to look around in C<@INC> for +other versions of the stuff you're installing and try to delete it, +you can use the C parameter, which tells C to +do so: + + ./Build install uninst=1 + +This can be a good idea, as it helps prevent multiple versions of a +module from being present on your system, which can be a confusing +situation indeed. + +=item manifest + +This is an action intended for use by module authors, not people +installing modules. It will bring the F up to date with the +files currently present in the distribution. You may use a +F file to exclude certain files or directories from +inclusion in the F. F should contain a bunch +of regular expressions, one per line. If a file in the distribution +directory matches any of the regular expressions, it won't be included +in the F. + +The following is a reasonable F starting point, you can +add your own stuff to it: + + ^_build + ^Build$ + ^blib + ~$ + \.bak$ + ^MANIFEST\.SKIP$ + CVS + +See the L and L actions if you want to find out +what the C action would do, without actually doing anything. + +=item manpages + +This will generate man pages for any binary or library files under +B that contain POD. The man pages will only be installed if the +install paths can be determined from values in C. You can +also supply or override install paths by specifying there values on +the command line with the C and C installation +targets. + +=item ppd + +Build a PPD file for your distribution. + +This action takes an optional argument C which is used in +the generated ppd file to specify the (usually relative) URL of the +distribution. By default, this value is the distribution name without +any path information. + +Example: + + ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz" + +=item ppmdist + +Generates a PPM binary distribution and a PPD description file. This +action also invokes the 'ppd' action, so it can accept the same +C argument described under that action. + +This uses the same mechanism as the C action to tar & zip its +output, so you can supply C and/or C parameters to affect +the result. + +=item prereq_report + +This action prints out a list of all prerequisites, the versions required, and +the versions actually installed. This can be useful for reviewing the +configuration of your system prior to a build, or when compiling data to send +for a bug report. + +=item pure_install + +This action is identical to the C action. In the future, +though, if C starts writing to the file file +F<$(INSTALLARCHLIB)/perllocal.pod>, C won't, and that +will be the only difference between them. + +=item realclean + +This action is just like the C action, but also removes the +C<_build> directory and the C script. If you run the +C action, you are essentially starting over, so you will +have to re-create the C script again. + +=item skipcheck + +Reports which files are skipped due to the entries in the +F file (See L for details) + +=item test + +This will use C to run any regression tests and report +their results. Tests can be defined in the standard places: a file +called C in the top-level directory, or several files ending +with C<.t> in a C directory. + +If you want tests to be 'verbose', i.e. show details of test execution +rather than just summary information, pass the argument C. + +If you want to run tests under the perl debugger, pass the argument +C. + +In addition, if a file called C exists in the top-level +directory, this file will be executed as a Perl script and its output +will be shown to the user. This is a good place to put speed tests or +other tests that don't use the C format for output. + +To override the choice of tests to run, you may pass a C +argument whose value is a whitespace-separated list of test scripts to +run. This is especially useful in development, when you only want to +run a single test to see whether you've squashed a certain bug yet: + + ./Build test --test_files t/something_failing.t + +You may also pass several C arguments separately: + + ./Build test --test_files t/one.t --test_files t/two.t + +or use a C-style pattern: + + ./Build test --test_files 't/01-*.t' + +=item testcover + +Runs the C action using C, generating a +code-coverage report showing which parts of the code were actually +exercised during the tests. + +To pass options to C, set the C<$DEVEL_COVER_OPTIONS> +environment variable: + + DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover + +=item testdb + +This is a synonym for the 'test' action with the C +argument. + +=item testpod + +This checks all the files described in the C action and +produces C-style output. If you are a module author, +this is useful to run before creating a new release. + +=item versioninstall + +** Note: since C is so new, and since we just recently added +support for it here too, this feature is to be considered +experimental. ** + +If you have the C module installed on your system, you can +use this action to install a module into the version-specific library +trees. This means that you can have several versions of the same +module installed and C a specific one like this: + + use only MyModule => 0.55; + +To override the default installation libraries in C, +specify the C parameter when you run the C script: + + perl Build.PL --versionlib /my/version/place/ + +To override which version the module is installed as, specify the +C parameter when you run the C script: + + perl Build.PL --version 0.50 + +See the C documentation for more information on +version-specific installs. + +=back + + +=head1 OPTIONS + +=head2 Command Line Options + +The following options can be used during any invocation of C +or the Build script, during any action. For information on other +options specific to an action, see the documentation for the +respective action. + +NOTE: There is some preliminary support for options to use the more +familiar long option style. Most options can be preceded with the +C<--> long option prefix, and the underscores changed to dashes +(e.g. --use-rcfile). Additionally, the argument to boolean options is +optional, and boolean options can be negated by prefixing them with +'no' or 'no-' (e.g. --noverbose or --no-verbose). + +=over 4 + +=item quiet + +Suppress informative messages on output. + +=item use_rcfile + +Load the F<~/.modulebuildrc> option file. This option can be set to +false to prevent the custom resource file from being loaded. + +=item verbose + +Display extra information about the Build on output. + +=back + + +=head2 Default Options File (F<.modulebuildrc>) + +When Module::Build starts up, it will look for a file, +F<$ENV{HOME}/.modulebuildrc>. If the file exists, the options +specified there will be used as defaults, as if they were typed on the +command line. The defaults can be overridden by specifying new values +on the command line. + +The action name must come at the beginning of the line, followed by any +amount of whitespace and then the options. Options are given the same +as they would be on the command line. They can be separated by any +amount of whitespace, including newlines, as long there is whitespace at +the beginning of each continued line. Anything following a hash mark (C<#>) +is considered a comment, and is stripped before parsing. If more than +one line begins with the same action name, those lines are merged into +one set of options. + +Besides the regular actions, there are two special pseudo-actions: the +key C<*> (asterisk) denotes any global options that should be applied +to all actions, and the key 'Build_PL' specifies options to be applied +when you invoke C. + + * verbose=1 # global options + diff flags=-u + install --install_base /home/ken + --install_path html=/home/ken/docs/html + +If you wish to locate your resource file in a different location, you +can set the environment variable 'MODULEBUILDRC' to the complete +absolute path of the file containing your options. + + +=head1 INSTALL PATHS + +When you invoke Module::Build's C action, it needs to figure +out where to install things. The nutshell version of how this works +is that default installation locations are determined from +F, and they may be overridden by using the C +parameter. An C parameter lets you specify an +alternative installation root like F, and a C lets +you specify a temporary installation directory like F in +case you want to create bundled-up installable packages. + +Natively, Module::Build provides default installation locations for +the following types of installable items: + +=over 4 + +=item lib + +Usually pure-Perl module files ending in F<.pm>. + +=item arch + +"Architecture-dependent" module files, usually produced by compiling +XS, Inline, or similar code. + +=item script + +Programs written in pure Perl. In order to improve reuse, try to make +these as small as possible - put the code into modules whenever +possible. + +=item bin + +"Architecture-dependent" executable programs, i.e. compiled C code or +something. Pretty rare to see this in a perl distribution, but it +happens. + +=item bindoc + +Documentation for the stuff in C