- building & installing Perl modules.
| README (Module-Build-0.4231) | : | README (Module-Build-0.4232) |
|---|
| NAME | | NAME |
|
| | | |
| Module::Build - Build and install Perl modules | | Module::Build - Build and install Perl modules |
| | |
| SYNOPSIS | | SYNOPSIS |
|
| | | |
| Standard process for building & installing modules: | | Standard process for building & installing modules: |
| | |
| perl Build.PL | | perl Build.PL |
| ./Build | | ./Build |
| ./Build test | | ./Build test |
| ./Build install | | ./Build install |
| | |
| Or, if you're on a platform (like DOS or Windows) that doesn't require | | Or, if you're on a platform (like DOS or Windows) that doesn't require |
| the "./" notation, you can do this: | | the "./" notation, you can do this: |
| | |
| perl Build.PL | | perl Build.PL |
| Build | | Build |
| Build test | | Build test |
| Build install | | Build install |
| | |
| DESCRIPTION | | DESCRIPTION |
|
| | | "Module::Build" is a system for building, testing, and installing Perl |
| Module::Build is a system for building, testing, and installing Perl | | modules. It is meant to be an alternative to "ExtUtils::MakeMaker". |
| modules. It is meant to be an alternative to ExtUtils::MakeMaker. | | |
| Developers may alter the behavior of the module through subclassing. It | | Developers may alter the behavior of the module through subclassing. It |
|
| also does not require a make on your system - most of the Module::Build | | also does not require a "make" on your system - most of the |
| code is pure-perl and written in a very cross-platform way. | | "Module::Build" code is pure-perl and written in a very cross-platform |
| | way. |
| | |
|
| See "COMPARISON" for more comparisons between Module::Build and other | | See "COMPARISON" for more comparisons between "Module::Build" and other |
| installer tools. | | installer tools. |
| | |
|
| To install Module::Build, and any other module that uses Module::Build | | To install "Module::Build", and any other module that uses |
| for its installation process, do the following: | | "Module::Build" for its installation process, do the following: |
| | |
| perl Build.PL # 'Build.PL' script creates the 'Build' script | | perl Build.PL # 'Build.PL' script creates the 'Build' script |
| ./Build # Need ./ to ensure we're using this "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 test # and not another one that happens to be in the PATH |
| ./Build install | | ./Build install |
| | |
| This illustrates initial configuration and the running of three | | This illustrates initial configuration and the running of three |
| 'actions'. In this case the actions run are 'build' (the default | | 'actions'. In this case the actions run are 'build' (the default |
| action), 'test', and 'install'. Other actions defined so far include: | | action), 'test', and 'install'. Other actions defined so far include: |
| | |
| <action_list> | | <action_list> |
| | |
| You can run the 'help' action for a complete list of actions. | | You can run the 'help' action for a complete list of actions. |
| | |
| GUIDE TO DOCUMENTATION | | GUIDE TO DOCUMENTATION |
|
| | | The documentation for "Module::Build" is broken up into sections: |
| The documentation for Module::Build is broken up into sections: | | |
| | |
| General Usage (Module::Build) | | General Usage (Module::Build) |
|
| | | This is the document you are currently reading. It describes basic |
| This is the document you are currently reading. It describes basic | | usage and background information. Its main purpose is to assist the |
| usage and background information. Its main purpose is to assist the | | user who wants to learn how to invoke and control "Module::Build" |
| user who wants to learn how to invoke and control Module::Build | | scripts at the command line. |
| scripts at the command line. | | |
| | |
| Authoring Reference (Module::Build::Authoring) | | Authoring Reference (Module::Build::Authoring) |
|
| | | This document describes the structure and organization of |
| This document describes the structure and organization of | | "Module::Build", and the relevant concepts needed by authors who are |
| Module::Build, and the relevant concepts needed by authors who are | | writing Build.PL scripts for a distribution or controlling |
| writing Build.PL scripts for a distribution or controlling | | "Module::Build" processes programmatically. |
| Module::Build processes programmatically. | | |
| | |
| API Reference (Module::Build::API) | | API Reference (Module::Build::API) |
|
| | | This is a reference to the "Module::Build" API. |
| This is a reference to the Module::Build API. | | |
| | |
| Cookbook (Module::Build::Cookbook) | | Cookbook (Module::Build::Cookbook) |
|
| | | This document demonstrates how to accomplish many common tasks. It |
| This document demonstrates how to accomplish many common tasks. It | | covers general command line usage and authoring of Build.PL scripts. |
| covers general command line usage and authoring of Build.PL scripts. | | Includes working examples. |
| Includes working examples. | | |
| | |
| ACTIONS | | ACTIONS |
|
| | | |
| There are some general principles at work here. First, each task when | | There are some general principles at work here. First, each task when |
|
| building a module is called an "action". These actions are listed | | building a module is called an "action". These actions are listed above; |
| above; they correspond to the building, testing, installing, packaging, | | they correspond to the building, testing, installing, packaging, etc., |
| etc., tasks. | | tasks. |
| | |
| Second, arguments are processed in a very systematic way. Arguments are | | Second, arguments are processed in a very systematic way. Arguments are |
|
| always key=value pairs. They may be specified at perl Build.PL time | | 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 | | (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 | | values last for the lifetime of the "Build" script. They may also be |
| specified when executing a particular action (i.e. Build test | | specified when executing a particular action (i.e. "Build test |
| verbose=1), in which case their values last only for the lifetime of | | verbose=1"), in which case their values last only for the lifetime of |
| that command. Per-action command line parameters take precedence over | | that command. Per-action command line parameters take precedence over |
|
| parameters specified at perl Build.PL time. | | parameters specified at "perl Build.PL" time. |
| | |
|
| The build process also relies heavily on the Config.pm module. If the | | 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 | | user wishes to override any of the values in "Config.pm", she may |
| them like so: | | specify them like so: |
| | |
| perl Build.PL --config cc=gcc --config ld=gcc | | perl Build.PL --config cc=gcc --config ld=gcc |
| | |
| The following build actions are provided by default. | | The following build actions are provided by default. |
| | |
| build | | build |
|
| | [version 0.01] |
| | |
|
| [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. |
| 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. | | This is analogous to the "MakeMaker" *make all* target. |
| | |
| clean | | clean |
|
| | [version 0.01] |
| | |
|
| [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 |
| This action will clean up any files that the build process may have | | "_build/" directory and the "Build" script itself). |
| created, including the blib/ directory (but not including the _build/ | | |
| directory and the Build script itself). | | |
| | |
| code | | code |
|
| | [version 0.20] |
| | |
|
| [version 0.20] | | This action builds your code base. |
| | | |
| This action builds your code base. | | |
| | |
|
| By default it just creates a blib/ directory and copies any .pm and | | By default it just creates a "blib/" directory and copies any ".pm" |
| .pod files from your lib/ directory into the blib/ directory. It also | | and ".pod" files from your "lib/" directory into the "blib/" |
| compiles any .xs files from lib/ and places them in blib/. Of course, | | directory. It also compiles any ".xs" files from "lib/" and places |
| you need a working C compiler (probably the same one that built perl | | them in "blib/". Of course, you need a working C compiler (probably |
| itself) for the compilation to work properly. | | 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 | | The "code" action also runs any ".PL" files in your lib/ directory. |
| .PL ending. For example, a file lib/Foo/Bar.pm.PL could create the | | Typically these create other files, named the same but without the |
| file lib/Foo/Bar.pm. The .PL files are processed first, so any .pm | | ".PL" ending. For example, a file lib/Foo/Bar.pm.PL could create the |
| files (or other kinds that we deal with) will get copied correctly. | | 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 | | config_data |
|
| | [version 0.26] |
| | |
|
| [version 0.26] | | ... |
| | | |
| ... | | |
| | |
| diff | | diff |
|
| | [version 0.14] |
| | |
|
| [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": |
| | |
|
| This action will compare the files about to be installed with their | | ./Build diff flags=-u |
| 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 | | dist |
|
| | [version 0.02] |
| | |
|
| [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 |
| This action is helpful for module authors who want to package up | | will create a tarball of the files listed in MANIFEST and compress |
| their module for source distribution through a medium like CPAN. It | | the tarball using GZIP compression. |
| will create a tarball of the files listed in MANIFEST and compress | | |
| the tarball using GZIP compression. | | By default, this action will use the "Archive::Tar" module. However, |
| | | you can force it to use binary "tar" and "gzip" executables by |
| By default, this action will use the Archive::Tar module. However, | | supplying an explicit "tar" (and optional "gzip") parameter: |
| you can force it to use binary "tar" and "gzip" executables by | | |
| supplying an explicit tar (and optional gzip) parameter: | | |
| | |
|
| ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe | | ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe |
| | |
| distcheck | | distcheck |
|
| | [version 0.05] |
| | |
|
| [version 0.05] | | Reports which files are in the build directory but not in the |
| | | MANIFEST file, and vice versa. (See "manifest" for details.) |
| Reports which files are in the build directory but not in the | | |
| MANIFEST file, and vice versa. (See "manifest" for details.) | | |
| | |
| distclean | | distclean |
|
| | [version 0.05] |
| | |
|
| [version 0.05] | | Performs the 'realclean' action and then the 'distcheck' action. |
| | | |
| Performs the 'realclean' action and then the 'distcheck' action. | | |
| | |
| distdir | | distdir |
|
| | [version 0.05] |
| | |
|
| [version 0.05] | | Creates a "distribution directory" named "$dist_name-$dist_version" |
| | | (if that directory already exists, it will be removed first), then |
| Creates a "distribution directory" named $dist_name-$dist_version (if | | copies all the files listed in the MANIFEST file to that directory. |
| that directory already exists, it will be removed first), then copies | | This directory is what the distribution tarball is created from. |
| all the files listed in the MANIFEST file to that directory. This | | |
| directory is what the distribution tarball is created from. | | |
| | |
| distinstall | | distinstall |
|
| | [version 0.37] |
| | |
|
| [version 0.37] | | Performs the 'distdir' action, then switches into that directory and |
| | | runs a "perl Build.PL", followed by the 'build' and 'install' |
| Performs the 'distdir' action, then switches into that directory and | | actions in that directory. Use PERL_MB_OPT or .modulebuildrc to set |
| runs a perl Build.PL, followed by the 'build' and 'install' actions | | options that should be applied during subprocesses |
| in that directory. Use PERL_MB_OPT or .modulebuildrc to set options | | |
| that should be applied during subprocesses | | |
| | |
| distmeta | | distmeta |
|
| | [version 0.21] |
| | |
|
| [version 0.21] | | Creates the META.yml file that describes the distribution. |
| | | |
| Creates the META.yml file that describes the distribution. | | |
| | |
|
| META.yml is a file containing various bits of metadata about the | | META.yml is a file containing various bits of *metadata* about the |
| distribution. The metadata includes the distribution name, version, | | distribution. The metadata includes the distribution name, version, |
| abstract, prerequisites, license, and various other data about the | | abstract, prerequisites, license, and various other data about the |
| distribution. This file is created as META.yml in a simplified YAML | | distribution. This file is created as META.yml in a simplified YAML |
| format. | | format. |
| | |
|
| META.yml file must also be listed in MANIFEST - if it's not, a | | META.yml file must also be listed in MANIFEST - if it's not, a |
| warning will be issued. | | warning will be issued. |
| | |
|
| The current version of the META.yml specification can be found on | | The current version of the META.yml specification can be found on |
| CPAN as CPAN::Meta::Spec. | | CPAN as CPAN::Meta::Spec. |
| | |
| distsign | | distsign |
|
| | [version 0.16] |
| | |
|
| [version 0.16] | | Uses "Module::Signature" to create a SIGNATURE file for your |
| | | distribution, and adds the SIGNATURE file to the distribution's |
| Uses Module::Signature to create a SIGNATURE file for your | | MANIFEST. |
| distribution, and adds the SIGNATURE file to the distribution's | | |
| MANIFEST. | | |
| | |
| disttest | | disttest |
|
| | [version 0.05] |
| | |
|
| [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 |
| Performs the 'distdir' action, then switches into that directory and | | in that directory. Use PERL_MB_OPT or .modulebuildrc to set options |
| runs a perl Build.PL, followed by the 'build' and 'test' actions in | | that should be applied during subprocesses |
| that directory. Use PERL_MB_OPT or .modulebuildrc to set options that | | |
| should be applied during subprocesses | | |
| | |
| docs | | docs |
|
| | [version 0.20] |
| | |
|
| [version 0.20] | | This will generate documentation (e.g. Unix man pages and HTML |
| | | documents) for any installable items under blib/ that contain POD. |
| This will generate documentation (e.g. Unix man pages and HTML | | If there are no "bindoc" or "libdoc" installation targets defined |
| documents) for any installable items under blib/ that contain POD. If | | (as will be the case on systems that don't support Unix manpages) no |
| there are no bindoc or libdoc installation targets defined (as will | | action is taken for manpages. If there are no "binhtml" or "libhtml" |
| be the case on systems that don't support Unix manpages) no action is | | installation targets defined no action is taken for HTML documents. |
| taken for manpages. If there are no binhtml or libhtml installation | | |
| targets defined no action is taken for HTML documents. | | |
| | |
| fakeinstall | | fakeinstall |
|
| | [version 0.02] |
| | |
|
| [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 |
| This is just like the install action, but it won't actually do | | actually run the "install" action. |
| anything, it will just report what it would have done if you had | | |
| actually run the install action. | | |
| | |
| help | | help |
|
| | [version 0.03] |
| | |
|
| [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 |
| This action will simply print out a message that is meant to help you | | build actions too. |
| 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 |
| With an optional argument specifying an action name (e.g. Build help | | it can find for that action. |
| test), the 'help' action will show you any POD documentation it can | | |
| find for that action. | | |
| | |
| html | | html |
|
| | [version 0.26] |
| | |
|
| [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. |
| | |
| | With an optional "html_links" argument set to a false value, you can |
| | skip the search for other documentation to link to, because that can |
| | waste a lot of time if there aren't any links to generate anyway: |
| | |
|
| This will generate HTML documentation for any binary or library files | | ./Build html --html_links 0 |
| 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. | | |
| | |
| With an optional html_links argument set to a false value, you can | | |
| skip the search for other documentation to link to, because that can | | |
| waste a lot of time if there aren't any links to generate anyway: | | |
| | | |
| ./Build html --html_links 0 | | |
| | |
| install | | install |
|
| | [version 0.01] |
| | |
|
| [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 |
| This action will use ExtUtils::Install to install the files from | | Module::Build determines where to install things, and how to |
| blib/ into the system. See "INSTALL PATHS" for details about how | | influence this process. |
| 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, |
| If you want the installation process to look around in @INC for other | | you can use the "uninst" parameter, which tells "ExtUtils::Install" |
| versions of the stuff you're installing and try to delete it, you can | | to do so: |
| use the uninst parameter, which tells ExtUtils::Install to do so: | | |
| | | ./Build install uninst=1 |
| ./Build install uninst=1 | | |
| | | This can be a good idea, as it helps prevent multiple versions of a |
| 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 |
| module from being present on your system, which can be a confusing | | situation indeed. |
| situation indeed. | | |
| | |
| installdeps | | installdeps |
|
| | [version 0.36] |
| | |
|
| [version 0.36] | | This action will use the "cpan_client" parameter as a command to |
| | | install missing prerequisites. You will be prompted whether to |
| This action will use the cpan_client parameter as a command to | | install optional dependencies. |
| install missing prerequisites. You will be prompted whether to | | |
| install optional dependencies. | | The "cpan_client" option defaults to 'cpan' but can be set as an |
| | | option or in .modulebuildrc. It must be a shell command that takes a |
| The cpan_client option defaults to 'cpan' but can be set as an option | | list of modules to install as arguments (e.g. 'cpanp -i' for |
| or in .modulebuildrc. It must be a shell command that takes a list of | | CPANPLUS). If the program part is a relative path (e.g. 'cpan' or |
| modules to install as arguments (e.g. 'cpanp -i' for CPANPLUS). If | | 'cpanp'), it will be located relative to the perl program that |
| the program part is a relative path (e.g. 'cpan' or 'cpanp'), it will | | executed Build.PL. |
| be located relative to the perl program that executed Build.PL. | | |
| | | /opt/perl/5.8.9/bin/perl Build.PL |
| /opt/perl/5.8.9/bin/perl Build.PL | | ./Build installdeps --cpan_client 'cpanp -i' |
| ./Build installdeps --cpan_client 'cpanp -i' | | # installs to 5.8.9 |
| # installs to 5.8.9 | | |
| | |
| manifest | | manifest |
|
| | [version 0.05] |
| | |
|
| [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 |
| This is an action intended for use by module authors, not people | | files currently present in the distribution. You may use a |
| installing modules. It will bring the MANIFEST up to date with the | | MANIFEST.SKIP file to exclude certain files or directories from |
| files currently present in the distribution. You may use a | | inclusion in the MANIFEST. MANIFEST.SKIP should contain a bunch of |
| MANIFEST.SKIP file to exclude certain files or directories from | | regular expressions, one per line. If a file in the distribution |
| inclusion in the MANIFEST. MANIFEST.SKIP should contain a bunch of | | directory matches any of the regular expressions, it won't be |
| regular expressions, one per line. If a file in the distribution | | included in the MANIFEST. |
| 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: |
| The following is a reasonable MANIFEST.SKIP starting point, you can | | |
| add your own stuff to it: | | ^_build |
| | | ^Build$ |
| ^_build | | ^blib |
| ^Build$ | | ~$ |
| ^blib | | \.bak$ |
| ~$ | | ^MANIFEST\.SKIP$ |
| \.bak$ | | CVS |
| ^MANIFEST\.SKIP$ | | |
| CVS | | See the "distcheck" and "skipcheck" actions if you want to find out |
| | | what the "manifest" action would do, without actually doing |
| See the "distcheck" and "skipcheck" actions if you want to find out | | anything. |
| what the manifest action would do, without actually doing anything. | | |
| | |
| manifest_skip | | manifest_skip |
|
| | [version 0.3608] |
| | |
|
| [version 0.3608] | | This is an action intended for use by module authors, not people |
| | | installing modules. It will generate a boilerplate MANIFEST.SKIP |
| This is an action intended for use by module authors, not people | | file if one does not already exist. |
| installing modules. It will generate a boilerplate MANIFEST.SKIP file | | |
| if one does not already exist. | | |
| | |
| manpages | | manpages |
|
| | [version 0.28] |
| | |
|
| [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 |
| This will generate man pages for any binary or library files under | | install paths can be determined from values in "Config.pm". You can |
| blib/ that contain POD. The man pages will only be installed if the | | also supply or override install paths by specifying there values on |
| install paths can be determined from values in Config.pm. You can | | the command line with the "bindoc" and "libdoc" installation |
| also supply or override install paths by specifying there values on | | targets. |
| the command line with the bindoc and libdoc installation targets. | | |
| | |
| pardist | | pardist |
|
| | [version 0.2806] |
| | |
|
| [version 0.2806] | | Generates a PAR binary distribution for use with PAR or PAR::Dist. |
| | | |
| 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 | | It requires that the PAR::Dist module (version 0.17 and up) is |
| installed on your system. | | installed on your system. |
| | |
|
| ppd | | ppd [version 0.20] |
| | |
|
| [version 0.20] | | Build a PPD file for your distribution. |
| | |
|
| 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. |
| | |
|
| This action takes an optional argument codebase which is used in the | | Example: |
| 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" |
| ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.g | | |
| z" | | |
| | |
| ppmdist | | ppmdist |
|
| | [version 0.23] |
| | |
|
| [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 |
| Generates a PPM binary distribution and a PPD description file. This | | "codebase" argument described under that action. |
| 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 |
| This uses the same mechanism as the dist action to tar & zip its | | the result. |
| output, so you can supply tar and/or gzip parameters to affect the | | |
| result. | | |
| | |
| prereq_data | | prereq_data |
|
| | [version 0.32] |
| | |
|
| [version 0.32] | | This action prints out a Perl data structure of all prerequisites |
| | | and the versions required. The output can be loaded again using |
| This action prints out a Perl data structure of all prerequisites and | | "eval()". This can be useful for external tools that wish to query a |
| the versions required. The output can be loaded again using eval(). | | Build script for prerequisites. |
| This can be useful for external tools that wish to query a Build | | |
| script for prerequisites. | | |
| | |
| prereq_report | | prereq_report |
|
| | [version 0.28] |
| | |
|
| [version 0.28] | | This action prints out a list of all prerequisites, the versions |
| | | required, and the versions actually installed. This can be useful |
| This action prints out a list of all prerequisites, the versions | | for reviewing the configuration of your system prior to a build, or |
| required, and the versions actually installed. This can be useful for | | when compiling data to send for a bug report. |
| reviewing the configuration of your system prior to a build, or when | | |
| compiling data to send for a bug report. | | |
| | |
| pure_install | | pure_install |
|
| | [version 0.28] |
| | |
|
| [version 0.28] | | This action is identical to the "install" action. In the future, |
| | | though, when "install" starts writing to the file |
| This action is identical to the install action. In the future, | | $(INSTALLARCHLIB)/perllocal.pod, "pure_install" won't, and that will |
| though, when install starts writing to the file | | be the only difference between them. |
| $(INSTALLARCHLIB)/perllocal.pod, pure_install won't, and that will be | | |
| the only difference between them. | | |
| | |
| realclean | | realclean |
|
| | [version 0.01] |
| | |
|
| [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 |
| This action is just like the clean action, but also removes the | | "realclean" action, you are essentially starting over, so you will |
| _build directory and the Build script. If you run the realclean | | have to re-create the "Build" script again. |
| action, you are essentially starting over, so you will have to | | |
| re-create the Build script again. | | |
| | |
| retest | | retest |
|
| | [version 0.2806] |
| | |
|
| [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 |
| This is just like the test action, but doesn't actually build the | | therefore will test against a *previously* installed version of the |
| distribution first, and doesn't add blib/ to the load path, and | | distribution. This can be used to verify that a certain installed |
| therefore will test against a previously installed version of the | | distribution still works, or to see whether newer versions of a |
| distribution. This can be used to verify that a certain installed | | distribution still pass the old regression tests, and so on. |
| distribution still works, or to see whether newer versions of a | | |
| distribution still pass the old regression tests, and so on. | | |
| | |
| skipcheck | | skipcheck |
|
| | [version 0.05] |
| | |
|
| [version 0.05] | | Reports which files are skipped due to the entries in the |
| | | MANIFEST.SKIP file (See "manifest" for details) |
| Reports which files are skipped due to the entries in the | | |
| MANIFEST.SKIP file (See "manifest" for details) | | |
| | |
| test | | test |
|
| | [version 0.01] |
| | |
|
| [version 0.01] | | This will use "Test::Harness" or "TAP::Harness" to run any |
| | | regression tests and report their results. Tests can be defined in |
| This will use Test::Harness or TAP::Harness to run any regression | | the standard places: a file called "test.pl" in the top-level |
| tests and report their results. Tests can be defined in the standard | | directory, or several files ending with ".t" in a "t/" directory. |
| 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 | | If you want tests to be 'verbose', i.e. show details of test |
| execution rather than just summary information, pass the argument | | execution rather than just summary information, pass the argument |
| verbose=1. | | "verbose=1". |
| | |
|
| If you want to run tests under the perl debugger, pass the argument | | If you want to run tests under the perl debugger, pass the argument |
| debugger=1. | | "debugger=1". |
| | |
|
| If you want to have Module::Build find test files with different file | | If you want to have Module::Build find test files with different |
| name extensions, pass the test_file_exts argument with an array of | | file name extensions, pass the "test_file_exts" argument with an |
| extensions, such as [qw( .t .s .z )]. | | array of extensions, such as "[qw( .t .s .z )]". |
| | |
|
| If you want test to be run by TAP::Harness, rather than | | If you want test to be run by "TAP::Harness", rather than |
| Test::Harness, pass the argument tap_harness_args as an array | | "Test::Harness", pass the argument "tap_harness_args" as an array |
| reference of arguments to pass to the TAP::Harness constructor. | | reference of arguments to pass to the TAP::Harness constructor. |
| | |
|
| In addition, if a file called visual.pl exists in the top-level | | 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 | | directory, this file will be executed as a Perl script and its |
| will be shown to the user. This is a good place to put speed tests or | | output will be shown to the user. This is a good place to put speed |
| other tests that don't use the Test::Harness format for output. | | 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 | | 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 | | 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. This is especially useful in development, when you only want |
| to run a single test to see whether you've squashed a certain bug | | to run a single test to see whether you've squashed a certain bug |
| yet: | | yet: |
| | |
|
| ./Build test --test_files t/something_failing.t | | ./Build test --test_files t/something_failing.t |
| | |
|
| You may also pass several test_files arguments separately: | | You may also pass several "test_files" arguments separately: |
| | |
|
| ./Build test --test_files t/one.t --test_files t/two.t | | ./Build test --test_files t/one.t --test_files t/two.t |
| | |
|
| or use a glob()-style pattern: | | or use a "glob()"-style pattern: |
| | |
|
| ./Build test --test_files 't/01-*.t' | | ./Build test --test_files 't/01-*.t' |
| | |
| testall | | testall |
|
| | [version 0.2807] |
| | |
|
| [version 0.2807] | | [Note: the 'testall' action and the code snippets below are |
| | | currently in alpha stage, see |
| [Note: the 'testall' action and the code snippets below are currently | | <http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.htm |
| in alpha stage, see | | l> ] |
| http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html | | |
| ] | | Runs the "test" action plus each of the "test$type" actions defined |
| | | by the keys of the "test_types" parameter. |
| 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. |
| 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( |
| my $mb = Module::Build->subclass( | | sub ACTION_testspecial { shift->generic_test(type => 'special'); } |
| code => q( | | sub ACTION_testauthor { shift->generic_test(type => 'author'); } |
| sub ACTION_testspecial { shift->generic_test(type => 'special'); } | | ) |
| sub ACTION_testauthor { shift->generic_test(type => 'author'); } | | )->new( |
| ) | | ... |
| )->new( | | test_types => { |
| ... | | special => '.st', |
| test_types => { | | author => ['.at', '.pt' ], |
| special => '.st', | | }, |
| author => ['.at', '.pt' ], | | ... |
| }, | | |
| ... | | |
| | |
| testcover | | testcover |
|
| | [version 0.26] |
| | |
|
| [version 0.26] | | Runs the "test" action using "Devel::Cover", generating a |
| | | code-coverage report showing which parts of the code were actually |
| Runs the test action using Devel::Cover, generating a code-coverage | | exercised during the tests. |
| report showing which parts of the code were actually exercised during | | |
| the tests. | | |
| | |
|
| To pass options to Devel::Cover, set the $DEVEL_COVER_OPTIONS | | To pass options to "Devel::Cover", set the $DEVEL_COVER_OPTIONS |
| environment variable: | | environment variable: |
| | |
|
| DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover | | DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover |
| | |
| testdb | | testdb |
|
| | [version 0.05] |
| | |
|
| [version 0.05] | | This is a synonym for the 'test' action with the "debugger=1" |
| | | argument. |
| This is a synonym for the 'test' action with the debugger=1 argument. | | |
| | |
| testpod | | testpod |
|
| | [version 0.25] |
| | |
|
| [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 checks all the files described in the docs action and produces | | this is useful to run before creating a new release. |
| Test::Harness-style output. If you are a module author, this is | | |
| useful to run before creating a new release. | | |
| | |
| testpodcoverage | | testpodcoverage |
|
| | [version 0.28] |
| | |
|
| [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 |
| This checks the pod coverage of the distribution and produces | | useful to run before creating a new release. |
| Test::Harness-style output. If you are a module author, this is | | |
| useful to run before creating a new release. | | |
| | |
| versioninstall | | versioninstall |
|
| | [version 0.16] |
| | |
|
| [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. ** |
| | |
|
| ** Note: since only.pm is so new, and since we just recently added | | If you have the "only.pm" module installed on your system, you can |
| support for it here too, this feature is to be considered | | use this action to install a module into the version-specific |
| experimental. ** | | library trees. This means that you can have several versions of the |
| | same module installed and "use" a specific one like this: |
| | |
|
| If you have the only.pm module installed on your system, you can use | | use only MyModule => 0.55; |
| 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: |
| | |
|
| To override the default installation libraries in only::config, | | perl Build.PL --versionlib /my/version/place/ |
| 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 |
| | "version" parameter when you run the "Build.PL" script: |
| | |
|
| To override which version the module is installed as, specify the | | perl Build.PL --version 0.50 |
| version 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. |
| See the only.pm documentation for more information on | | |
| version-specific installs. | | |
| | |
| OPTIONS | | OPTIONS |
|
| | | Command Line Options |
| Command Line Options | | The following options can be used during any invocation of "Build.PL" or |
| | | |
| The following options can be used during any invocation of Build.PL or | | |
| the Build script, during any action. For information on other options | | the Build script, during any action. For information on other options |
| specific to an action, see the documentation for the respective action. | | specific to an action, see the documentation for the respective action. |
| | |
| NOTE: There is some preliminary support for options to use the more | | NOTE: There is some preliminary support for options to use the more |
|
| familiar long option style. Most options can be preceded with the -- | | familiar long option style. Most options can be preceded with the "--" |
| long option prefix, and the underscores changed to dashes (e.g. | | long option prefix, and the underscores changed to dashes (e.g. |
|
| --use-rcfile). Additionally, the argument to boolean options is | | "--use-rcfile"). Additionally, the argument to boolean options is |
| optional, and boolean options can be negated by prefixing them with no | | optional, and boolean options can be negated by prefixing them with "no" |
| or no- (e.g. --noverbose or --no-verbose). | | or "no-" (e.g. "--noverbose" or "--no-verbose"). |
| | |
| quiet | | quiet |
|
| | | Suppress informative messages on output. |
| Suppress informative messages on output. | | |
| | |
| verbose | | verbose |
|
| | | Display extra information about the Build on output. "verbose" will |
| Display extra information about the Build on output. verbose will | | turn off "quiet" |
| turn off quiet | | |
| | |
| cpan_client | | cpan_client |
|
| | | Sets the "cpan_client" command for use with the "installdeps" |
| Sets the cpan_client command for use with the installdeps action. See | | action. See "installdeps" for more details. |
| installdeps for more details. | | |
| | |
| use_rcfile | | use_rcfile |
|
| | | Load the ~/.modulebuildrc option file. This option can be set to |
| Load the ~/.modulebuildrc option file. This option can be set to | | false to prevent the custom resource file from being loaded. |
| false to prevent the custom resource file from being loaded. | | |
| | |
| allow_mb_mismatch | | allow_mb_mismatch |
|
| | | Suppresses the check upon startup that the version of Module::Build |
| Suppresses the check upon startup that the version of Module::Build | | we're now running under is the same version that was initially |
| we're now running under is the same version that was initially | | invoked when building the distribution (i.e. when the "Build.PL" |
| invoked when building the distribution (i.e. when the Build.PL script | | script was first run). As of 0.3601, a mismatch results in a warning |
| was first run). As of 0.3601, a mismatch results in a warning instead | | instead of a fatal error, so this option effectively just suppresses |
| of a fatal error, so this option effectively just suppresses the | | the warning. |
| warning. | | |
| | |
| debug | | debug |
|
| | Prints Module::Build debugging information to STDOUT, such as a |
| | trace of executed build actions. |
| | |
|
| Prints Module::Build debugging information to STDOUT, such as a trace | | Default Options File (.modulebuildrc) |
| of executed build actions. | | |
| | | |
| Default Options File (.modulebuildrc) | | |
| | | |
| [version 0.28] | | [version 0.28] |
| | |
| When Module::Build starts up, it will look first for a file, | | 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 | | $ENV{HOME}/.modulebuildrc. If it's not found there, it will look in the |
| .modulebuildrc file in the directories referred to by the environment | | .modulebuildrc file in the directories referred to by the environment |
|
| variables HOMEDRIVE + HOMEDIR, USERPROFILE, APPDATA, WINDIR, SYS$LOGIN. | | variables "HOMEDRIVE" + "HOMEDIR", "USERPROFILE", "APPDATA", "WINDIR", |
| If the file exists, the options specified there will be used as | | "SYS$LOGIN". If the file exists, the options specified there will be |
| defaults, as if they were typed on the command line. The defaults can | | used as defaults, as if they were typed on the command line. The |
| be overridden by specifying new values on the command line. | | 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 | | 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 | | amount of whitespace and then the options. Options are given the same as |
| as they would be on the command line. They can be separated by any | | they would be on the command line. They can be separated by any amount |
| amount of whitespace, including newlines, as long there is whitespace | | of whitespace, including newlines, as long there is whitespace at the |
| at the beginning of each continued line. Anything following a hash mark | | beginning of each continued line. Anything following a hash mark ("#") |
| (#) is considered a comment, and is stripped before parsing. If more | | is considered a comment, and is stripped before parsing. If more than |
| than one line begins with the same action name, those lines are merged | | one line begins with the same action name, those lines are merged into |
| into one set of options. | | one set of options. |
| | |
| Besides the regular actions, there are two special pseudo-actions: the | | Besides the regular actions, there are two special pseudo-actions: the |
|
| key * (asterisk) denotes any global options that should be applied to | | key "*" (asterisk) denotes any global options that should be applied to |
| all actions, and the key 'Build_PL' specifies options to be applied | | all actions, and the key 'Build_PL' specifies options to be applied when |
| when you invoke perl Build.PL. | | you invoke "perl Build.PL". |
| | |
| * verbose=1 # global options | | * verbose=1 # global options |
| diff flags=-u | | diff flags=-u |
| install --install_base /home/ken | | install --install_base /home/ken |
| --install_path html=/home/ken/docs/html | | --install_path html=/home/ken/docs/html |
| installdeps --cpan_client 'cpanp -i' | | installdeps --cpan_client 'cpanp -i' |
| | |
| If you wish to locate your resource file in a different location, you | | If you wish to locate your resource file in a different location, you |
|
| can set the environment variable MODULEBUILDRC to the complete absolute | | can set the environment variable "MODULEBUILDRC" to the complete |
| path of the file containing your options. | | absolute path of the file containing your options. |
| | | |
| Environment variables | | |
| | |
|
| | Environment variables |
| MODULEBUILDRC | | MODULEBUILDRC |
|
| | [version 0.28] |
| | |
|
| [version 0.28] | | Specifies an alternate location for a default options file as |
| | | described above. |
| Specifies an alternate location for a default options file as | | |
| described above. | | |
| | |
| PERL_MB_OPT | | PERL_MB_OPT |
|
| | [version 0.36] |
| | |
|
| [version 0.36] | | Command line options that are applied to Build.PL or any Build |
| | | action. The string is split as the shell would (e.g. whitespace) and |
| Command line options that are applied to Build.PL or any Build | | the result is prepended to any actual command-line arguments. |
| action. The string is split as the shell would (e.g. whitespace) and | | |
| the result is prepended to any actual command-line arguments. | | |
| | |
| INSTALL PATHS | | INSTALL PATHS |
|
| | | |
| [version 0.19] | | [version 0.19] |
| | |
|
| When you invoke Module::Build's build action, it needs to figure out | | 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 | | where to install things. The nutshell version of how this works is that |
| default installation locations are determined from Config.pm, and they | | default installation locations are determined from Config.pm, and they |
|
| may be overridden by using the install_path parameter. An install_base | | may be overridden by using the "install_path" parameter. An |
| parameter lets you specify an alternative installation root like | | "install_base" parameter lets you specify an alternative installation |
| /home/foo, and a destdir lets you specify a temporary installation | | root like /home/foo, and a "destdir" lets you specify a temporary |
| directory like /tmp/install in case you want to create bundled-up | | installation directory like /tmp/install in case you want to create |
| installable packages. | | bundled-up installable packages. |
| | |
| Natively, Module::Build provides default installation locations for the | | Natively, Module::Build provides default installation locations for the |
| following types of installable items: | | following types of installable items: |
| | |
|
| lib | | lib Usually pure-Perl module files ending in .pm. |
| | | |
| Usually pure-Perl module files ending in .pm. | | |
| | |
| arch | | arch |
|
| | | "Architecture-dependent" module files, usually produced by compiling |
| "Architecture-dependent" module files, usually produced by compiling | | XS, Inline, or similar code. |
| XS, Inline, or similar code. | | |
| | |
| script | | script |
|
| | | Programs written in pure Perl. In order to improve reuse, try to |
| Programs written in pure Perl. In order to improve reuse, try to make | | make these as small as possible - put the code into modules whenever |
| these as small as possible - put the code into modules whenever | | possible. |
| possible. | | |
| | | bin "Architecture-dependent" executable programs, i.e. compiled C code |
| bin | | or something. Pretty rare to see this in a perl distribution, but it |
| | | happens. |
| "Architecture-dependent" executable programs, i.e. compiled C code or | | |
| something. Pretty rare to see this in a perl distribution, but it | | |
| happens. | | |
| | |
| bindoc | | bindoc |
|
| | | Documentation for the stuff in "script" and "bin". Usually generated |
| Documentation for the stuff in script and bin. Usually generated from | | from the POD in those files. Under Unix, these are manual pages |
| the POD in those files. Under Unix, these are manual pages belonging | | belonging to the 'man1' category. |
| to the 'man1' category. | | |
| | |
| libdoc | | libdoc |
|
| | | Documentation for the stuff in "lib" and "arch". This is usually |
| Documentation for the stuff in lib and arch. This is usually | | generated from the POD in .pm files. Under Unix, these are manual |
| generated from the POD in .pm files. Under Unix, these are manual | | pages belonging to the 'man3' category. |
| pages belonging to the 'man3' category. | | |
| | |
| binhtml | | binhtml |
|
| | | This is the same as "bindoc" above, but applies to HTML documents. |
| This is the same as bindoc above, but applies to HTML documents. | | |
| | |
| libhtml | | libhtml |
|
| | | This is the same as "libdoc" above, but applies to HTML documents. |
| This is the same as libdoc above, but applies to HTML documents. | | |
| | |
| Four other parameters let you control various aspects of how | | Four other parameters let you control various aspects of how |
| installation paths are determined: | | installation paths are determined: |
| | |
| installdirs | | installdirs |
|
| | | The default destinations for these installable things come from |
| The default destinations for these installable things come from | | entries in your system's "Config.pm". You can select from three |
| entries in your system's Config.pm. You can select from three | | different sets of default locations by setting the "installdirs" |
| different sets of default locations by setting the installdirs | | parameter as follows: |
| parameter as follows: | | |
| | | 'installdirs' set to: |
| 'installdirs' set to: | | core site vendor |
| core site vendor | | |
| | | uses the following defaults from Config.pm: |
| uses the following defaults from Config.pm: | | |
| | | lib => installprivlib installsitelib installvendorlib |
| lib => installprivlib installsitelib installvendorlib | | arch => installarchlib installsitearch installvendorarch |
| arch => installarchlib installsitearch installvendorarch | | script => installscript installsitescript installvendorscript |
| script => installscript installsitescript installvendorscript | | bin => installbin installsitebin installvendorbin |
| bin => installbin installsitebin installvendorbin | | bindoc => installman1dir installsiteman1dir installvendorman1dir |
| bindoc => installman1dir installsiteman1dir installvendorman1dir | | libdoc => installman3dir installsiteman3dir installvendorman3dir |
| libdoc => installman3dir installsiteman3dir installvendorman3dir | | binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [ |
| binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*] | | *] |
| libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*] | | libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [ |
| | | *] |
| * Under some OS (eg. MSWin32) the destination for HTML documents is | | |
| determined by the C<Config.pm> entry C<installhtmldir>. | | * 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 | | The default value of "installdirs" is "site". If you're creating |
| this: | | vendor distributions of module packages, you may want to do |
| | | something like this: |
| perl Build.PL --installdirs vendor | | |
| | | perl Build.PL --installdirs vendor |
| or | | |
| | | or |
| ./Build install --installdirs vendor | | |
| | | ./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 | | If you're installing an updated version of a module that was |
| to "core" to overwrite the module in its present location. | | included with perl itself (i.e. a "core module"), then you may set |
| | | "installdirs" to "core" to overwrite the module in its present |
| (Note that the 'script' line is different from MakeMaker - | | location. |
| unfortunately there's no such thing as "installsitescript" or | | |
| "installvendorscript" entry in Config.pm, so we use the | | (Note that the 'script' line is different from "MakeMaker" - |
| "installsitebin" and "installvendorbin" entries to at least get the | | unfortunately there's no such thing as "installsitescript" or |
| general location right. In the future, if Config.pm adds some more | | "installvendorscript" entry in "Config.pm", so we use the |
| appropriate entries, we'll start using those.) | | "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 | | install_path |
|
| | Once the defaults have been set, you can override them. |
| | |
|
| Once the defaults have been set, you can override them. | | On the command line, that would look like this: |
| | |
|
| On the command line, that would look like this: | | perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib
/arch |
| | |
|
| perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/a
rch | | or this: |
| | |
|
| or this: | | ./Build install --install_path lib=/foo/lib --install_path arch=/foo/l |
| | | ib/arch |
| ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib | | |
| /arch | | |
| | |
| install_base | | 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. |
| | |
|
| You can also set the whole bunch of installation paths by supplying | | The exact layout under the directory you specify may vary by system |
| the install_base parameter to point to a directory on your system. | | - we try to do the "sensible" thing on each platform. |
| 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 | | 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: |
| | |
|
| If you want to install everything into a temporary directory first | | perl Build.PL --destdir /tmp/foo |
| (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 | | or |
| | |
|
| ./Build install --destdir /tmp/foo | | ./Build install --destdir /tmp/foo |
| | |
|
| This will effectively install to "/tmp/foo/$sitelib", | | This will effectively install to "/tmp/foo/$sitelib", |
| "/tmp/foo/$sitearch", and the like, except that it will use | | "/tmp/foo/$sitearch", and the like, except that it will use |
| File::Spec to make the pathnames work correctly on whatever platform | | "File::Spec" to make the pathnames work correctly on whatever |
| you're installing on. | | platform you're installing on. |
| | |
| prefix | | prefix |
|
| | | Provided for compatibility with "ExtUtils::MakeMaker"'s PREFIX |
| Provided for compatibility with ExtUtils::MakeMaker's PREFIX | | argument. "prefix" should be used when you want Module::Build to |
| argument. prefix should be used when you want Module::Build to | | install your modules, documentation, and scripts in the same place |
| install your modules, documentation, and scripts in the same place as | | as "ExtUtils::MakeMaker"'s PREFIX mechanism. |
| ExtUtils::MakeMaker's PREFIX mechanism. | | |
| | | The following are equivalent. |
| The following are equivalent. | | |
| | | perl Build.PL --prefix /tmp/foo |
| perl Build.PL --prefix /tmp/foo | | perl Makefile.PL PREFIX=/tmp/foo |
| perl Makefile.PL PREFIX=/tmp/foo | | |
| | | Because of the complex nature of the prefixification logic, the |
| Because of the complex nature of the prefixification logic, the | | behavior of PREFIX in "MakeMaker" has changed subtly over time. |
| behavior of PREFIX in MakeMaker has changed subtly over time. | | Module::Build's --prefix logic is equivalent to the PREFIX logic |
| Module::Build's --prefix logic is equivalent to the PREFIX logic | | found in "ExtUtils::MakeMaker" 6.30. |
| found in ExtUtils::MakeMaker 6.30. | | |
| | | The maintainers of "MakeMaker" do understand the troubles with the |
| The maintainers of MakeMaker do understand the troubles with the | | PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of |
| PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of | | "MakeMaker", which was released in 2006. |
| MakeMaker, which was released in 2006. | | |
| | | If you don't need to retain compatibility with old versions |
| If you don't need to retain compatibility with old versions | | (pre-6.31) of "ExtUtils::MakeMaker" or are starting a fresh Perl |
| (pre-6.31) of ExtUtils::MakeMaker or are starting a fresh Perl | | installation we recommend you use "install_base" instead (and |
| installation we recommend you use install_base instead (and | | "INSTALL_BASE" in "ExtUtils::MakeMaker"). See "Installing in the |
| INSTALL_BASE in ExtUtils::MakeMaker). See "Installing in the same | | same location as ExtUtils::MakeMaker" in Module::Build::Cookbook for |
| location as ExtUtils::MakeMaker" in Module::Build::Cookbook for | | further information. |
| further information. | | |
| | |
| COMPARISON | | COMPARISON |
|
| | | A comparison between "Module::Build" and other CPAN distribution |
| A comparison between Module::Build and other CPAN distribution | | |
| installers. | | installers. |
| | |
|
| * ExtUtils::MakeMaker requires make and use of a Makefile. | | * ExtUtils::MakeMaker requires "make" and use of a Makefile. |
| Module::Build does not, nor do other pure-perl installers following | | "Module::Build" does not, nor do other pure-perl installers |
| the Build.PL spec such as Module::Build::Tiny. In practice, this is | | following the Build.PL spec such as Module::Build::Tiny. In |
| usually not an issue for the end user, as make is already required to | | practice, this is usually not an issue for the end user, as "make" |
| install most CPAN modules, even on Windows. | | is already required to install most CPAN modules, even on Windows. |
| | | |
| * ExtUtils::MakeMaker has been a core module in every version of Perl | | * ExtUtils::MakeMaker has been a core module in every version of Perl |
| 5, and must maintain compatibility to install the majority of CPAN | | 5, and must maintain compatibility to install the majority of CPAN |
| modules. Module::Build was added to core in Perl 5.10 and removed | | modules. "Module::Build" was added to core in Perl 5.10 and removed |
| from core in Perl 5.20, and (like ExtUtils::MakeMaker) is only | | from core in Perl 5.20, and (like ExtUtils::MakeMaker) is only |
| updated to fix critical issues and maintain compatibility. | | updated to fix critical issues and maintain compatibility. |
| Module::Build and other non-core installers like Module::Build::Tiny | | "Module::Build" and other non-core installers like |
| are installed from CPAN by declaring themselves as a configure phase | | Module::Build::Tiny are installed from CPAN by declaring themselves |
| prerequisite, and in this way any installer can be used in place of | | as a "configure" phase prerequisite, and in this way any installer |
| ExtUtils::MakeMaker. | | can be used in place of ExtUtils::MakeMaker. |
| | | |
| * Customizing the build process with ExtUtils::MakeMaker involves | | * Customizing the build process with ExtUtils::MakeMaker involves |
| overriding certain methods that form the Makefile by defining the | | overriding certain methods that form the Makefile by defining the |
| subs in the MY:: namespace, requiring in-depth knowledge of Makefile, | | subs in the "MY::" namespace, requiring in-depth knowledge of |
| but allowing targeted customization of the entire build. Customizing | | Makefile, but allowing targeted customization of the entire build. |
| Module::Build involves subclassing Module::Build itself, adding or | | Customizing "Module::Build" involves subclassing "Module::Build" |
| overriding pure-perl methods that represent build actions, which are | | itself, adding or overriding pure-perl methods that represent build |
| invoked as arguments passed to the generated ./Build script. This is | | actions, which are invoked as arguments passed to the generated |
| a simpler concept but requires redefining the standard build actions | | "./Build" script. This is a simpler concept but requires redefining |
| to invoke your customizations. Module::Build::Tiny does not allow for | | the standard build actions to invoke your customizations. |
| customization. | | Module::Build::Tiny does not allow for customization. |
| | | |
| * Module::Build provides more features and a better experience for | | * "Module::Build" provides more features and a better experience for |
| distribution authors than ExtUtils::MakeMaker. However, tools | | distribution authors than ExtUtils::MakeMaker. However, tools |
| designed specifically for authoring, such as Dist::Zilla and its | | designed specifically for authoring, such as Dist::Zilla and its |
| spinoffs Dist::Milla and Minilla, provide these features and more, | | spinoffs Dist::Milla and Minilla, provide these features and more, |
| and generate a configure script (Makefile.PL/Build.PL) that will use | | and generate a configure script (Makefile.PL/Build.PL) that will use |
| any of the various installers separately on the end user side. | | any of the various installers separately on the end user side. |
| App::ModuleBuildTiny is an alternative standalone authoring tool for | | App::ModuleBuildTiny is an alternative standalone authoring tool for |
| distributions using Module::Build::Tiny, which requires only a simple | | distributions using Module::Build::Tiny, which requires only a |
| two-line Build.PL. | | simple two-line Build.PL. |
| | |
| TO DO | | TO DO |
|
| | | |
| The current method of relying on time stamps to determine whether a | | 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 | | derived file is out of date isn't likely to scale well, since it |
| requires tracing all dependencies backward, it runs into problems on | | 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 | | 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. | | signature or the like, if available. See "cons" for an example. |
| | |
| - append to perllocal.pod | | - append to perllocal.pod |
| - add a 'plugin' functionality | | - add a 'plugin' functionality |
| | |
| AUTHOR | | AUTHOR |
|
| | | |
| Ken Williams <kwilliams@cpan.org> | | Ken Williams <kwilliams@cpan.org> |
| | |
| Development questions, bug reports, and patches should be sent to the | | Development questions, bug reports, and patches should be sent to the |
| Module-Build mailing list at <module-build@perl.org>. | | Module-Build mailing list at <module-build@perl.org>. |
| | |
| Bug reports are also welcome at | | Bug reports are also welcome at |
| <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>. | | <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>. |
| | |
| The latest development version is available from the Git repository at | | The latest development version is available from the Git repository at |
| <https://github.com/Perl-Toolchain-Gang/Module-Build> | | <https://github.com/Perl-Toolchain-Gang/Module-Build> |
| | |
| COPYRIGHT | | COPYRIGHT |
|
| | | |
| Copyright (c) 2001-2006 Ken Williams. All rights reserved. | | Copyright (c) 2001-2006 Ken Williams. All rights reserved. |
| | |
| This library is free software; you can redistribute it and/or modify it | | This library is free software; you can redistribute it and/or modify it |
| under the same terms as Perl itself. | | under the same terms as Perl itself. |
| | |
| SEE ALSO | | SEE ALSO |
|
| | | |
| perl(1), Module::Build::Cookbook, Module::Build::Authoring, | | perl(1), Module::Build::Cookbook, Module::Build::Authoring, |
| Module::Build::API, ExtUtils::MakeMaker | | Module::Build::API, ExtUtils::MakeMaker |
| | |
| META.yml Specification: CPAN::Meta::Spec | | META.yml Specification: CPAN::Meta::Spec |
| | |
|
| http://www.dsmit.com/cons/ | | <http://www.dsmit.com/cons/> |
| | |
|
| http://search.cpan.org/dist/PerlBuildSystem/ | | <http://search.cpan.org/dist/PerlBuildSystem/> |
| | | |
| End of changes. 176 change blocks. |
|---|
| 637 lines changed or deleted | | 569 lines changed or added |
|---|
"Fossies" - the Fresh Open Source Software Archive 