--- /dev/null
+NAME
+ Module::Build - Build and install Perl modules
+
+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
+
+DESCRIPTION
+ `Module::Build' is a system for building, testing, and installing Perl
+ modules. It is meant to be an alternative to `ExtUtils::MakeMaker'.
+ Developers may alter the behavior of the module through subclassing in a
+ much more straightforward way than with `MakeMaker'. It also does not
+ require a `make' on your system - most of the `Module::Build' 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 "MOTIVATIONS" for more comparisons between `ExtUtils::MakeMaker' and
+ `Module::Build'.
+
+ To install `Module::Build', and any other module that uses
+ `Module::Build' 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:
+
+ <action_list>
+
+ You can run the 'help' action for a complete list of actions.
+
+GUIDE TO DOCUMENTATION
+ The documentation for `Module::Build' is broken up into three sections:
+
+ General Usage (Module::Build)
+ 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 `Module::Build'
+ scripts at the command line.
+
+ Authoring Reference (Module::Build::Authoring)
+ This document describes the structure and organization of
+ `Module::Build', and the relevant concepts needed by authors who are
+ writing Build.PL scripts for a distribution or controlling
+ `Module::Build' processes programmatically.
+
+ API Reference (Module::Build::API)
+ This is a reference to the `Module::Build' API.
+
+ Cookbook (Module::Build::Cookbook)
+ This document demonstrates how to accomplish many common tasks. It
+ covers general command line usage and authoring of Build.PL scripts.
+ Includes working examples.
+
+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 `perl Build.PL' time
+ (i.e. `perl Build.PL destdir=/my/secret/place'), in which case their
+ values last for the lifetime of the `Build' script. They may also be
+ specified when executing a particular action (i.e. `Build test
+ verbose=1'), in which case their values last only for the lifetime of
+ that command. Per-action command line parameters take precedence over
+ parameters specified at `perl Build.PL' time.
+
+ The build process also relies heavily on the `Config.pm' module. If the
+ user wishes to override any of the values in `Config.pm', she may
+ specify them like so:
+
+ perl Build.PL --config cc=gcc --config ld=gcc
+
+ The following build actions are provided by default.
+
+ build
+ [version 0.01]
+
+ If you run the `Build' script without any arguments, it runs the
+ `build' action, which in turn runs the `code' and `docs' actions.
+
+ This is analogous to the MakeMaker 'make all' target.
+
+ clean
+ [version 0.01]
+
+ This action will clean up any files that the build process may have
+ created, including the `blib/' directory (but not including the
+ `_build/' directory and the `Build' script itself).
+
+ code
+ [version 0.20]
+
+ This action builds your codebase.
+
+ By default it just creates a `blib/' directory and copies any `.pm'
+ and `.pod' files from your `lib/' directory into the `blib/'
+ directory. It also compiles any `.xs' files from `lib/' and places
+ them in `blib/'. Of course, you need a working C compiler (probably
+ the same one that built perl itself) for the compilation to work
+ properly.
+
+ The `code' action also runs any `.PL' files in your lib/ directory.
+ Typically these create other files, named the same but without the
+ `.PL' ending. For example, a file lib/Foo/Bar.pm.PL could create the
+ file lib/Foo/Bar.pm. The `.PL' files are processed first, so any
+ `.pm' files (or other kinds that we deal with) will get copied
+ correctly.
+
+ config_data
+ [version 0.26]
+
+ ...
+
+ diff
+ [version 0.14]
+
+ 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 `flags' 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 `-u':
+
+ ./Build diff flags=-u
+
+ dist
+ [version 0.02]
+
+ 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 MANIFEST and compress
+ the tarball using GZIP compression.
+
+ By default, this action will use the external `tar' and `gzip'
+ executables on Unix-like platforms, and the `Archive::Tar' module
+ elsewhere. However, you can force it to use whatever executable you
+ want by supplying an explicit `tar' (and optional `gzip') parameter:
+
+ ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
+
+ distcheck
+ [version 0.05]
+
+ Reports which files are in the build directory but not in the
+ MANIFEST file, and vice versa. (See manifest for details.)
+
+ distclean
+ [version 0.05]
+
+ Performs the 'realclean' action and then the 'distcheck' action.
+
+ distdir
+ [version 0.05]
+
+ Creates a "distribution directory" named `$dist_name-$dist_version'
+ (if that directory already exists, it will be removed first), then
+ copies all the files listed in the MANIFEST file to that directory.
+ This directory is what the distribution tarball is created from.
+
+ distmeta
+ [version 0.21]
+
+ Creates the META.yml file that describes the distribution.
+
+ META.yml 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 META.yml in YAML format. It is
+ recommended that the `YAML' module be installed to create it. If the
+ `YAML' module is not installed, an internal module supplied with
+ Module::Build will be used to write the META.yml file, and this will
+ most likely be fine.
+
+ META.yml file must also be listed in MANIFEST - if it's not, a
+ warning will be issued.
+
+ The current version of the META.yml specification can be found at
+ http://module-build.sourceforge.net/META-spec-current.html
+
+ distsign
+ [version 0.16]
+
+ Uses `Module::Signature' to create a SIGNATURE file for your
+ distribution, and adds the SIGNATURE file to the distribution's
+ MANIFEST.
+
+ disttest
+ [version 0.05]
+
+ Performs the 'distdir' action, then switches into that directory and
+ runs a `perl Build.PL', followed by the 'build' and 'test' actions
+ in that directory.
+
+ docs
+ [version 0.20]
+
+ This will generate documentation (e.g. Unix man pages and html
+ documents) for any installable items under blib/ that contain POD.
+ If there are no `bindoc' or `libdoc' 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 `binhtml' or `libhtml'
+ installation targets defined no action is taken for html documents.
+
+ fakeinstall
+ [version 0.02]
+
+ This is just like the `install' action, but it won't actually do
+ anything, it will just report what it *would* have done if you had
+ actually run the `install' action.
+
+ help
+ [version 0.03]
+
+ 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. `Build
+ help test'), the 'help' action will show you any POD documentation
+ it can find for that action.
+
+ html
+ [version 0.26]
+
+ This will generate HTML documentation for any binary or library
+ files under blib/ that contain POD. The HTML documentation will only
+ be installed if the install paths can be determined from values in
+ `Config.pm'. You can also supply or override install paths on the
+ command line by specifying `install_path' values for the `binhtml'
+ and/or `libhtml' installation targets.
+
+ install
+ [version 0.01]
+
+ This action will use `ExtUtils::Install' to install the files from
+ `blib/' into the system. See "INSTALL PATHS" 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 `@INC' for
+ other versions of the stuff you're installing and try to delete it,
+ you can use the `uninst' parameter, which tells `ExtUtils::Install'
+ 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.
+
+ manifest
+ [version 0.05]
+
+ This is an action intended for use by module authors, not people
+ installing modules. It will bring the MANIFEST up to date with the
+ files currently present in the distribution. You may use a
+ MANIFEST.SKIP file to exclude certain files or directories from
+ inclusion in the MANIFEST. MANIFEST.SKIP 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 MANIFEST.
+
+ The following is a reasonable MANIFEST.SKIP starting point, you can
+ add your own stuff to it:
+
+ ^_build
+ ^Build$
+ ^blib
+ ~$
+ \.bak$
+ ^MANIFEST\.SKIP$
+ CVS
+
+ See the distcheck and skipcheck actions if you want to find out what
+ the `manifest' action would do, without actually doing anything.
+
+ manpages
+ [version 0.28]
+
+ This will generate man pages for any binary or library files under
+ blib/ that contain POD. The man pages will only be installed if the
+ install paths can be determined from values in `Config.pm'. You can
+ also supply or override install paths by specifying there values on
+ the command line with the `bindoc' and `libdoc' installation
+ targets.
+
+ pardist
+ [version 0.2806]
+
+ Generates a PAR binary distribution for use with PAR or PAR::Dist.
+
+ It requires that the PAR::Dist module (version 0.17 and up) is
+ installed on your system.
+
+ ppd [version 0.20]
+
+ Build a PPD file for your distribution.
+
+ This action takes an optional argument `codebase' 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"
+
+ ppmdist
+ [version 0.23]
+
+ Generates a PPM binary distribution and a PPD description file. This
+ action also invokes the 'ppd' action, so it can accept the same
+ `codebase' argument described under that action.
+
+ This uses the same mechanism as the `dist' action to tar & zip its
+ output, so you can supply `tar' and/or `gzip' parameters to affect
+ the result.
+
+ prereq_report
+ [version 0.28]
+
+ 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.
+
+ pure_install
+ [version 0.28]
+
+ This action is identical to the `install' action. In the future,
+ though, when `install' starts writing to the file
+ $(INSTALLARCHLIB)/perllocal.pod, `pure_install' won't, and that will
+ be the only difference between them.
+
+ realclean
+ [version 0.01]
+
+ This action is just like the `clean' action, but also removes the
+ `_build' directory and the `Build' script. If you run the
+ `realclean' action, you are essentially starting over, so you will
+ have to re-create the `Build' script again.
+
+ retest
+ [version 0.2806]
+
+ This is just like the `test' action, but doesn't actually build the
+ distribution first, and doesn't add blib/ to the load path, and
+ therefore will test against a *previously* installed version of the
+ distribution. This can be used to verify that a certain installed
+ distribution still works, or to see whether newer versions of a
+ distribution still pass the old regression tests, and so on.
+
+ skipcheck
+ [version 0.05]
+
+ Reports which files are skipped due to the entries in the
+ MANIFEST.SKIP file (See manifest for details)
+
+ test
+ [version 0.01]
+
+ This will use `Test::Harness' to run any regression tests and report
+ their results. Tests can be defined in the standard places: a file
+ called `test.pl' in the top-level directory, or several files ending
+ with `.t' in a `t/' directory.
+
+ If you want tests to be 'verbose', i.e. show details of test
+ execution rather than just summary information, pass the argument
+ `verbose=1'.
+
+ If you want to run tests under the perl debugger, pass the argument
+ `debugger=1'.
+
+ In addition, if a file called `visual.pl' 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 `Test::Harness' format for
+ output.
+
+ To override the choice of tests to run, you may pass a `test_files'
+ 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 `test_files' arguments separately:
+
+ ./Build test --test_files t/one.t --test_files t/two.t
+
+ or use a `glob()'-style pattern:
+
+ ./Build test --test_files 't/01-*.t'
+
+ testall
+ [verion 0.2807]
+
+ [Note: the 'testall' action and the code snippets below are
+ currently in alpha stage, see
+ "http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.htm
+ l" ]
+
+ Runs the `test' action plus each of the `test$type' actions defined
+ by the keys of the `test_types' parameter.
+
+ Currently, you need to define the ACTION_test$type method yourself
+ and enumerate them in the test_types parameter.
+
+ my $mb = Module::Build->subclass(
+ code => q(
+ sub ACTION_testspecial { shift->generic_test(type => 'special'); }
+ sub ACTION_testauthor { shift->generic_test(type => 'author'); }
+ )
+ )->new(
+ ...
+ test_types => {
+ special => '.st',
+ author => '.at',
+ },
+ ...
+
+ testcover
+ [version 0.26]
+
+ Runs the `test' action using `Devel::Cover', generating a
+ code-coverage report showing which parts of the code were actually
+ exercised during the tests.
+
+ To pass options to `Devel::Cover', set the `$DEVEL_COVER_OPTIONS'
+ environment variable:
+
+ DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
+
+ testdb
+ [version 0.05]
+
+ This is a synonym for the 'test' action with the `debugger=1'
+ argument.
+
+ testpod
+ [version 0.25]
+
+ This checks all the files described in the `docs' action and
+ produces `Test::Harness'-style output. If you are a module author,
+ this is useful to run before creating a new release.
+
+ testpodcoverage
+ [version 0.28]
+
+ This checks the pod coverage of the distribution and produces
+ `Test::Harness'-style output. If you are a module author, this is
+ useful to run before creating a new release.
+
+ versioninstall
+ [version 0.16]
+
+ ** Note: since `only.pm' 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 `only.pm' 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 `use' a specific one like this:
+
+ use only MyModule => 0.55;
+
+ To override the default installation libraries in `only::config',
+ specify the `versionlib' parameter when you run the `Build.PL'
+ script:
+
+ perl Build.PL --versionlib /my/version/place/
+
+ To override which version the module is installed as, specify the
+ `versionlib' parameter when you run the `Build.PL' script:
+
+ perl Build.PL --version 0.50
+
+ See the `only.pm' documentation for more information on
+ version-specific installs.
+
+OPTIONS
+ Command Line Options
+
+ The following options can be used during any invocation of `Build.PL' 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 `--'
+ 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).
+
+ quiet
+ Suppress informative messages on output.
+
+ use_rcfile
+ Load the ~/.modulebuildrc option file. This option can be set to
+ false to prevent the custom resource file from being loaded.
+
+ verbose
+ Display extra information about the Build on output.
+
+ allow_mb_mismatch
+ Suppresses the check upon startup that the version of Module::Build
+ we're now running under is the same version that was initially
+ invoked when building the distribution (i.e. when the `Build.PL'
+ script was first run). Use with caution.
+
+ Default Options File (.modulebuildrc)
+
+ [version 0.28]
+
+ When Module::Build starts up, it will look first for a file,
+ $ENV{HOME}/.modulebuildrc. If it's not found there, it will look in the
+ the .modulebuildrc file in the directories referred to by the
+ environment variables `HOMEDRIVE' + `HOMEDIR', `USERPROFILE', `APPDATA',
+ `WINDIR', `SYS$LOGIN'. 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 (`#')
+ 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 `*' (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 `perl Build.PL'.
+
+ * 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.
+
+INSTALL PATHS
+ [version 0.19]
+
+ When you invoke Module::Build's `build' 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 Config.pm, and they
+ may be overridden by using the `install_path' parameter. An
+ `install_base' parameter lets you specify an alternative installation
+ root like /home/foo, and a `destdir' lets you specify a temporary
+ installation directory like /tmp/install in case you want to create
+ bundled-up installable packages.
+
+ Natively, Module::Build provides default installation locations for the
+ following types of installable items:
+
+ lib Usually pure-Perl module files ending in .pm.
+
+ arch
+ "Architecture-dependent" module files, usually produced by compiling
+ XS, Inline, or similar code.
+
+ 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.
+
+ bin "Architecture-dependent" executable programs, i.e. compiled C code
+ or something. Pretty rare to see this in a perl distribution, but it
+ happens.
+
+ bindoc
+ Documentation for the stuff in `script' and `bin'. Usually generated
+ from the POD in those files. Under Unix, these are manual pages
+ belonging to the 'man1' category.
+
+ libdoc
+ Documentation for the stuff in `lib' and `arch'. This is usually
+ generated from the POD in .pm files. Under Unix, these are manual
+ pages belonging to the 'man3' category.
+
+ binhtml
+ This is the same as `bindoc' above, but applies to html documents.
+
+ libhtml
+ This is the same as `bindoc' above, but applies to html documents.
+
+ Four other parameters let you control various aspects of how
+ installation paths are determined:
+
+ installdirs
+ The default destinations for these installable things come from
+ entries in your system's `Config.pm'. You can select from three
+ different sets of default locations by setting the `installdirs'
+ parameter as follows:
+
+ 'installdirs' set to:
+ core site vendor
+
+ uses the following defaults from Config.pm:
+
+ lib => installprivlib installsitelib installvendorlib
+ arch => installarchlib installsitearch installvendorarch
+ script => installscript installsitebin installvendorbin
+ bin => installbin installsitebin installvendorbin
+ bindoc => installman1dir installsiteman1dir installvendorman1dir
+ libdoc => installman3dir installsiteman3dir installvendorman3dir
+ binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
+ libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
+
+ * Under some OS (eg. MSWin32) the destination for html documents is
+ determined by the C<Config.pm> entry C<installhtmldir>.
+
+ The default value of `installdirs' is "site". If you're creating
+ vendor distributions of module packages, you may want to do
+ something like this:
+
+ perl Build.PL --installdirs vendor
+
+ or
+
+ ./Build install --installdirs vendor
+
+ If you're installing an updated version of a module that was
+ included with perl itself (i.e. a "core module"), then you may set
+ `installdirs' to "core" to overwrite the module in its present
+ location.
+
+ (Note that the 'script' line is different from MakeMaker -
+ unfortunately there's no such thing as "installsitescript" or
+ "installvendorscript" entry in `Config.pm', so we use the
+ "installsitebin" and "installvendorbin" entries to at least get the
+ general location right. In the future, if `Config.pm' adds some more
+ appropriate entries, we'll start using those.)
+
+ install_path
+ Once the defaults have been set, you can override them.
+
+ On the command line, that would look like this:
+
+ perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
+
+ or this:
+
+ ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
+
+ install_base
+ You can also set the whole bunch of installation paths by supplying
+ the `install_base' parameter to point to a directory on your system.
+ For instance, if you set `install_base' to "/home/ken" on a Linux
+ system, you'll install as follows:
+
+ lib => /home/ken/lib/perl5
+ arch => /home/ken/lib/perl5/i386-linux
+ script => /home/ken/bin
+ bin => /home/ken/bin
+ bindoc => /home/ken/man/man1
+ libdoc => /home/ken/man/man3
+ binhtml => /home/ken/html
+ libhtml => /home/ken/html
+
+ Note that this is *different* from how MakeMaker's `PREFIX'
+ parameter works. `install_base' just gives you a default layout
+ under the directory you specify, which may have little to do with
+ the `installdirs=site' layout.
+
+ The exact layout under the directory you specify may vary by system
+ - we try to do the "sensible" thing on each platform.
+
+ destdir
+ If you want to install everything into a temporary directory first
+ (for instance, if you want to create a directory tree that a package
+ manager like `rpm' or `dpkg' could create a package from), you can
+ use the `destdir' parameter:
+
+ perl Build.PL --destdir /tmp/foo
+
+ or
+
+ ./Build install --destdir /tmp/foo
+
+ This will effectively install to "/tmp/foo/$sitelib",
+ "/tmp/foo/$sitearch", and the like, except that it will use
+ `File::Spec' to make the pathnames work correctly on whatever
+ platform you're installing on.
+
+ prefix
+ Provided for compatibility with ExtUtils::MakeMaker's PREFIX
+ argument. `prefix' should be used when you wish Module::Build to
+ install your modules, documentation and scripts in the same place
+ ExtUtils::MakeMaker does.
+
+ The following are equivalent.
+
+ perl Build.PL --prefix /tmp/foo
+ perl Makefile.PL PREFIX=/tmp/foo
+
+ Because of the very complex nature of the prefixification logic, the
+ behavior of PREFIX in MakeMaker has changed subtly over time.
+ Module::Build's --prefix logic is equivalent to the PREFIX logic
+ found in ExtUtils::MakeMaker 6.30.
+
+ If you do not need to retain compatibility with ExtUtils::MakeMaker
+ or are starting a fresh Perl installation we recommand you use
+ `install_base' instead (and `INSTALL_BASE' in ExtUtils::MakeMaker).
+ See Module::Build::Cookbook for further information.
+
+MOTIVATIONS
+ There are several reasons I wanted to start over, and not just fix what
+ I didn't like about MakeMaker:
+
+ * I don't like the core idea of MakeMaker, namely that `make' should
+ be involved in the build process. Here are my reasons:
+
+ + When a person is installing a Perl module, what can you assume
+ about their environment? Can you assume they have `make'? No,
+ but you can assume they have some version of Perl.
+
+ + When a person is writing a Perl module for intended
+ distribution, can you assume that they know how to build a
+ Makefile, so they can customize their build process? No, but you
+ can assume they know Perl, and could customize that way.
+
+ For years, these things have been a barrier to people getting the
+ build/install process to do what they want.
+
+ * There are several architectural decisions in MakeMaker that make it
+ very difficult to customize its behavior. For instance, when using
+ MakeMaker you do `use ExtUtils::MakeMaker', but the object created
+ in `WriteMakefile()' is actually blessed into a package name that's
+ created on the fly, so you can't simply subclass
+ `ExtUtils::MakeMaker'. There is a workaround `MY' package that lets
+ you override certain MakeMaker methods, but only certain explicitly
+ preselected (by MakeMaker) methods can be overridden. Also, the
+ method of customization is very crude: you have to modify a string
+ containing the Makefile text for the particular target. Since these
+ strings aren't documented, and *can't* be documented (they take on
+ different values depending on the platform, version of perl, version
+ of MakeMaker, etc.), you have no guarantee that your modifications
+ will work on someone else's machine or after an upgrade of MakeMaker
+ or perl.
+
+ * It is risky to make major changes to MakeMaker, since it does so
+ many things, is so important, and generally works. `Module::Build'
+ is an entirely separate package so that I can work on it all I want,
+ without worrying about backward compatibility.
+
+ * Finally, Perl is said to be a language for system administration.
+ Could it really be the case that Perl isn't up to the task of
+ building and installing software? Even if that software is a bunch
+ of stupid little `.pm' files that just need to be copied from one
+ place to another? My sense was that we could design a system to
+ accomplish this in a flexible, extensible, and friendly manner. Or
+ die trying.
+
+TO DO
+ The current method of relying on time stamps to determine whether a
+ derived file is out of date isn't likely to scale well, since it
+ requires tracing all dependencies backward, it runs into problems on
+ NFS, and it's just generally flimsy. It would be better to use an MD5
+ signature or the like, if available. See `cons' for an example.
+
+ - append to perllocal.pod
+ - add a 'plugin' functionality
+
+AUTHOR
+ Ken Williams <kwilliams@cpan.org>
+
+ Development questions, bug reports, and patches should be sent to the
+ Module-Build mailing list at <module-build@perl.org>.
+
+ Bug reports are also welcome at
+ <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
+
+ The latest development version is available from the Subversion
+ repository at <https://svn.perl.org/modules/Module-Build/trunk/>
+
+COPYRIGHT
+ Copyright (c) 2001-2006 Ken Williams. All rights reserved.
+
+ This library is free software; you can redistribute it and/or modify it
+ under the same terms as Perl itself.
+
+SEE ALSO
+ perl(1), Module::Build::Cookbook, Module::Build::Authoring,
+ Module::Build::API, ExtUtils::MakeMaker, YAML
+
+ META.yml Specification:
+ http://module-build.sourceforge.net/META-spec-current.html
+
+ http://www.dsmit.com/cons/
+
+ http://search.cpan.org/dist/PerlBuildSystem/
+
projects / dh-make-perl / blobdiff