{ "mode": "perldoc", "parameter": "Module::Build::API", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/Module%3A%3ABuild%3A%3AAPI/json", "generated": "2026-06-09T15:19:43Z", "sections": { "NAME": { "content": "Module::Build::API - API Reference for Module Authors\n", "subsections": [] }, "DESCRIPTION": { "content": "I list here some of the most important methods in \"Module::Build\". Normally you won't need to\ndeal with these methods unless you want to subclass \"Module::Build\". But since one of the\nreasons I created this module in the first place was so that subclassing is possible (and easy),\nI will certainly write more docs as the interface stabilizes.\n\nCONSTRUCTORS", "subsections": [ { "name": "current", "content": "[version 0.20]\n\nThis method returns a reasonable facsimile of the currently-executing \"Module::Build\" object\nrepresenting the current build. You can use this object to query its \"notes()\" method,\ninquire about installed modules, and so on. This is a great way to share information between\ndifferent parts of your build process. For instance, you can ask the user a question during\n\"perl Build.PL\", then use their answer during a regression test:\n\n# In Build.PL:\nmy $color = $build->prompt(\"What is your favorite color?\");\n$build->notes(color => $color);\n\n# In t/colortest.t:\nuse Module::Build;\nmy $build = Module::Build->current;\nmy $color = $build->notes('color');\n...\n\nThe way the \"current()\" method is currently implemented, there may be slight differences\nbetween the $build object in Build.PL and the one in \"t/colortest.t\". It is our goal to\nminimize these differences in future releases of Module::Build, so please report any\nanomalies you find.\n\nOne important caveat: in its current implementation, \"current()\" will NOT work correctly if\nyou have changed out of the directory that \"Module::Build\" was invoked from.\n" }, { "name": "new", "content": "[version 0.03]\n\nCreates a new Module::Build object. Arguments to the new() method are listed below. Most\narguments are optional, but you must provide either the \"modulename\" argument, or\n\"distname\" and one of \"distversion\" or \"distversionfrom\". In other words, you must\nprovide enough information to determine both a distribution name and version.\n\naddtocleanup\n[version 0.19]\n\nAn array reference of files to be cleaned up when the \"clean\" action is performed. See\nalso the addtocleanup() method.\n\nallowpureperl\n[version 0.4005]\n\nA bool indicating the module is still functional without its xs parts. When an XS module\nis build with --pureperlonly, it will otherwise fail.\n\nautoconfigurerequires\n[version 0.34]\n\nThis parameter determines whether Module::Build will add itself automatically to\nconfigurerequires (and buildrequires) if Module::Build is not already there. The\nrequired version will be the last 'major' release, as defined by the decimal version\ntruncated to two decimal places (e.g. 0.34, instead of 0.3402). The default value is\ntrue.\n\nautofeatures\n[version 0.26]\n\nThis parameter supports the setting of features (see \"feature($name)\") automatically\nbased on a set of prerequisites. For instance, for a module that could optionally use\neither MySQL or PostgreSQL databases, you might use \"autofeatures\" like this:\n\nmy $build = Module::Build->new\n(\n...other stuff here...\nautofeatures => {\npgsupport => {\ndescription => \"Interface with Postgres databases\",\nrequires => { 'DBD::Pg' => 23.3,\n'DateTime::Format::Pg' => 0 },\n},\nmysqlsupport => {\ndescription => \"Interface with MySQL databases\",\nrequires => { 'DBD::mysql' => 17.9,\n'DateTime::Format::MySQL' => 0 },\n},\n}\n);\n\nFor each feature named, the required prerequisites will be checked, and if there are no\nfailures, the feature will be enabled (set to 1). Otherwise the failures will be\ndisplayed to the user and the feature will be disabled (set to 0).\n\nSee the documentation for \"requires\" for the details of how requirements can be\nspecified.\n\nautosplit\n[version 0.04]\n\nAn optional \"autosplit\" argument specifies a file which should be run through the\nAutoSplit::autosplit() function. If multiple files should be split, the argument may be\ngiven as an array of the files to split.\n\nIn general I don't consider autosplitting a great idea, because it's not always clear\nthat autosplitting achieves its intended performance benefits. It may even harm\nperformance in environments like modperl, where as much as possible of a module's code\nshould be loaded during startup.\n\nbuildclass\n[version 0.28]\n\nThe Module::Build class or subclass to use in the build script. Defaults to\n\"Module::Build\" or the class name passed to or created by a call to \"subclass()\". This\nproperty is useful if you're writing a custom Module::Build subclass and have a\nbootstrapping problem--that is, your subclass requires modules that may not be installed\nwhen \"perl Build.PL\" is executed, but you've listed in \"buildrequires\" so that they\nshould be available when \"./Build\" is executed.\n\nbuildrequires\n[version 0.07]\n\nModules listed in this section are necessary to build and install the given module, but\nare not necessary for regular usage of it. This is actually an important distinction -\nit allows for tighter control over the body of installed modules, and facilitates\ncorrect dependency checking on binary/packaged distributions of the module.\n\nSee the documentation for \"PREREQUISITES\" in Module::Build::Authoring for the details of\nhow requirements can be specified.\n\nconfigurerequires\n[version 0.30]\n\nModules listed in this section must be installed *before* configuring this distribution\n(i.e. before running the Build.PL script). This might be a specific minimum version of\n\"Module::Build\" or any other module the Build.PL needs in order to do its stuff. Clients\nlike \"CPAN.pm\" or \"CPANPLUS\" will be expected to pick \"configurerequires\" out of the\nMETA.yml file and install these items before running the \"Build.PL\".\n\nModule::Build may automatically add itself to configurerequires. See\n\"autoconfigurerequires\" for details.\n\nSee the documentation for \"PREREQUISITES\" in Module::Build::Authoring for the details of\nhow requirements can be specified.\n\ntestrequires\n[version 0.4004]\n\nModules listed in this section must be installed before testing the distribution.\n\nSee the documentation for \"PREREQUISITES\" in Module::Build::Authoring for the details of\nhow requirements can be specified.\n\ncreatepacklist\n[version 0.28]\n\nIf true, this parameter tells Module::Build to create a .packlist file during the\n\"install\" action, just like \"ExtUtils::MakeMaker\" does. The file is created in a\nsubdirectory of the \"arch\" installation location. It is used by some other tools (CPAN,\nCPANPLUS, etc.) for determining what files are part of an install.\n\nThe default value is true. This parameter was introduced in Module::Build version\n0.2609; previously no packlists were ever created by Module::Build.\n\ncsource\n[version 0.04]\n\nAn optional \"csource\" argument specifies a directory which contains C source files that\nthe rest of the build may depend on. Any \".c\" files in the directory will be compiled to\nobject files. The directory will be added to the search path during the compilation and\nlinking phases of any C or XS files.\n\n[version 0.3604]\n\nA list of directories can be supplied using an anonymous array reference of strings.\n\nconflicts\n[version 0.07]\n\nModules listed in this section conflict in some serious way with the given module.\n\"Module::Build\" (or some higher-level tool) will refuse to install the given module if\nthe given module/version is also installed.\n\nSee the documentation for \"PREREQUISITES\" in Module::Build::Authoring for the details of\nhow requirements can be specified.\n\ncreatelicense\n[version 0.31]\n\nThis parameter tells Module::Build to automatically create a LICENSE file at the top\nlevel of your distribution, containing the full text of the author's chosen license.\nThis requires \"Software::License\" on the author's machine, and further requires that the\n\"license\" parameter specifies a license that it knows about.\n\ncreatemakefilepl\n[version 0.19]\n\nThis parameter lets you use \"Module::Build::Compat\" during the \"distdir\" (or \"dist\")\naction to automatically create a Makefile.PL for compatibility with\n\"ExtUtils::MakeMaker\". The parameter's value should be one of the styles named in the\nModule::Build::Compat documentation.\n\nUse of this parameter is discouraged.\n\ncreatereadme\n[version 0.22]\n\nThis parameter tells Module::Build to automatically create a README file at the top\nlevel of your distribution. Currently it will simply use \"Pod::Text\" (or \"Pod::Readme\"\nif it's installed) on the file indicated by \"distversionfrom\" and put the result in\nthe README file. This is by no means the only recommended style for writing a README,\nbut it seems to be one common one used on the CPAN.\n\nIf you generate a README in this way, it's probably a good idea to create a separate\nINSTALL file if that information isn't in the generated README.\n\ndistabstract\n[version 0.20]\n\nThis should be a short description of the distribution. This is used when generating\nmetadata for META.yml and PPD files. If it is not given then \"Module::Build\" looks in\nthe POD of the module from which it gets the distribution's version. If it finds a POD\nsection marked \"=head1 NAME\", then it looks for the first line matching \"\\s+-\\s+(.+)\",\nand uses the captured text as the abstract.\n\ndistauthor\n[version 0.20]\n\nThis should be something like \"John Doe \", or if there are multiple\nauthors, an anonymous array of strings may be specified. This is used when generating\nmetadata for META.yml and PPD files. If this is not specified, then \"Module::Build\"\nlooks at the module from which it gets the distribution's version. If it finds a POD\nsection marked \"=head1 AUTHOR\", then it uses the contents of this section.\n\ndistname\n[version 0.11]\n\nSpecifies the name for this distribution. Most authors won't need to set this directly,\nthey can use \"modulename\" to set \"distname\" to a reasonable default. However, some\nagglomerative distributions like \"libwww-perl\" or \"bioperl\" have names that don't\ncorrespond directly to a module name, so \"distname\" can be set independently.\n\ndistsuffix\n[version 0.37]\n\nSpecifies an optional suffix to include after the version number in the distribution\ndirectory (and tarball) name. The only suffix currently recognized by PAUSE is 'TRIAL',\nwhich indicates that the distribution should not be indexed. For example:\n\nFoo-Bar-1.23-TRIAL.tar.gz\n\nThis will automatically do the \"right thing\" depending on \"distversion\" and\n\"releasestatus\". When \"distversion\" does not have an underscore and \"releasestatus\"\nis not 'stable', then \"distsuffix\" will default to 'TRIAL'. Otherwise it will default\nto the empty string, disabling the suffix.\n\nIn general, authors should only set this if they must override the default behavior for\nsome particular purpose.\n\ndistversion\n[version 0.11]\n\nSpecifies a version number for the distribution. See \"modulename\" or\n\"distversionfrom\" for ways to have this set automatically from a $VERSION variable in\na module. One way or another, a version number needs to be set.\n\ndistversionfrom\n[version 0.11]\n\nSpecifies a file to look for the distribution version in. Most authors won't need to set\nthis directly, they can use \"modulename\" to set it to a reasonable default.\n\nThe version is extracted from the specified file according to the same rules as\nExtUtils::MakeMaker and \"CPAN.pm\". It involves finding the first line that matches the\nregular expression\n\n/([\\$*])(([\\w\\:\\']*)\\bVERSION)\\b.*\\=/\n\neval()-ing that line, then checking the value of the $VERSION variable. Quite ugly,\nreally, but all the modules on CPAN depend on this process, so there's no real\nopportunity to change to something better.\n\nIf the target file of \"distversionfrom\" contains more than one package declaration,\nthe version returned will be the one matching the configured \"modulename\".\n\ndynamicconfig\n[version 0.07]\n\nA boolean flag indicating whether the Build.PL file must be executed to determine\nprerequisites, or whether they can be determined solely from consulting its metadata\nfile. The main reason to set this to a true value is that your module adds or removes\nprerequisites dynamically in Build.PL. If the flag is omitted, it will be treated as 1\n(true), because this is a safer way to behave.\n\nCurrently \"Module::Build\" doesn't actually do anything with this flag - it's up to\nhigher-level tools like \"CPAN.pm\" to do something useful with it. It can also be very\nhelpful for static analysis. See \"dynamicconfig\" in CPAN::Meta::Spec for details on the\nmetadata field.\n\nextracompilerflags\nextralinkerflags\n[version 0.19]\n\nThese parameters can contain array references (or strings, in which case they will be\nsplit into arrays) to pass through to the compiler and linker phases when\ncompiling/linking C code. For example, to tell the compiler that your code is C++, you\nmight do:\n\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\nextracompilerflags => ['-x', 'c++'],\n);\n\nTo link your XS code against glib you might write something like:\n\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\ndynamicconfig => 1,\nextracompilerflags => scalar `glib-config --cflags`,\nextralinkerflags => scalar `glib-config --libs`,\n);\n\nextramanifyargs\n[version 0.4006]\n\nAny extra arguments to pass to \"Pod::Man->new()\" when building man pages. One common\nchoice might be \"utf8 => 1\" to get Unicode support.\n\ngetoptions\n[version 0.26]\n\nYou can pass arbitrary command line options to Build.PL or Build, and they will be\nstored in the Module::Build object and can be accessed via the \"args()\" method. However,\nsometimes you want more flexibility out of your argument processing than this allows. In\nsuch cases, use the \"getoptions\" parameter to pass in a hash reference of argument\nspecifications, and the list of arguments to Build.PL or Build will be processed\naccording to those specifications before they're passed on to \"Module::Build\"'s own\nargument processing.\n\nThe supported option specification hash keys are:\n\ntype\nThe type of option. The types are those supported by Getopt::Long; consult its\ndocumentation for a complete list. Typical types are \"=s\" for strings, \"+\" for\nadditive options, and \"!\" for negatable options. If the type is not specified, it\nwill be considered a boolean, i.e. no argument is taken and a value of 1 will be\nassigned when the option is encountered.\n\nstore\nA reference to a scalar in which to store the value passed to the option. If not\nspecified, the value will be stored under the option name in the hash returned by\nthe \"args()\" method.\n\ndefault\nA default value for the option. If no default value is specified and no option is\npassed, then the option key will not exist in the hash returned by \"args()\".\n\nYou can combine references to your own variables or subroutines with unreferenced\nspecifications, for which the result will also be stored in the hash returned by\n\"args()\". For example:\n\nmy $loud = 0;\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\ngetoptions => {\nLoud => { store => \\$loud },\nDbd => { type => '=s' },\nQuantity => { type => '+' },\n}\n);\n\nprint STDERR \"HEY, ARE YOU LISTENING??\\n\" if $loud;\nprint \"We'll use the \", $build->args('Dbd'), \" DBI driver\\n\";\nprint \"Are you sure you want that many?\\n\"\nif $build->args('Quantity') > 2;\n\nThe arguments for such a specification can be called like so:\n\nperl Build.PL --Loud --Dbd=DBD::pg --Quantity --Quantity --Quantity\n\nWARNING: Any option specifications that conflict with Module::Build's own options\n(defined by its properties) will throw an exception. Use capitalized option names to\navoid unintended conflicts with future Module::Build options.\n\nConsult the Getopt::Long documentation for details on its usage.\n\nincludedirs\n[version 0.24]\n\nSpecifies any additional directories in which to search for C header files. May be given\nas a string indicating a single directory, or as a list reference indicating multiple\ndirectories.\n\ninstallpath\n[version 0.19]\n\nYou can set paths for individual installable elements by using the \"installpath\"\nparameter:\n\nmy $build = Module::Build->new\n(\n...other stuff here...\ninstallpath => {\nlib => '/foo/lib',\narch => '/foo/lib/arch',\n}\n);\n\ninstalldirs\n[version 0.19]\n\nDetermines where files are installed within the normal perl hierarchy as determined by\nConfig.pm. Valid values are: \"core\", \"site\", \"vendor\". The default is \"site\". See\n\"INSTALL PATHS\" in Module::Build\n\nlicense\n[version 0.07]\n\nSpecifies the licensing terms of your distribution.\n\nAs of Module::Build version 0.3614, you may use a Software::License subclass name (e.g.\n'Apache20') instead of one of the keys below.\n\nThe legacy list of valid license values include:\n\napache\nThe distribution is licensed under the Apache License, Version 2.0\n().\n\napache11\nThe distribution is licensed under the Apache Software License, Version 1.1\n().\n\nartistic\nThe distribution is licensed under the Artistic License, as specified by the\nArtistic file in the standard Perl distribution.\n\nartistic2\nThe distribution is licensed under the Artistic 2.0 License\n(.)\n\nbsd The distribution is licensed under the BSD License\n().\n\ngpl The distribution is licensed under the terms of the GNU General Public License\n().\n\nlgpl\nThe distribution is licensed under the terms of the GNU Lesser General Public\nLicense ().\n\nmit The distribution is licensed under the MIT License\n().\n\nmozilla\nThe distribution is licensed under the Mozilla Public License.\n( or\n)\n\nopensource\nThe distribution is licensed under some other Open Source Initiative-approved\nlicense listed at .\n\nperl\nThe distribution may be copied and redistributed under the same terms as Perl itself\n(this is by far the most common licensing option for modules on CPAN). This is a\ndual license, in which the user may choose between either the GPL or the Artistic\nlicense.\n\nrestrictive\nThe distribution may not be redistributed without special permission from the author\nand/or copyright holder.\n\nunrestricted\nThe distribution is licensed under a license that is not approved by\nwww.opensource.org but that allows distribution without restrictions.\n\nNote that you must still include the terms of your license in your code and\ndocumentation - this field only sets the information that is included in distribution\nmetadata to let automated tools figure out your licensing restrictions. Humans still\nneed something to read. If you choose to provide this field, you should make sure that\nyou keep it in sync with your written documentation if you ever change your licensing\nterms.\n\nYou may also use a license type of \"unknown\" if you don't wish to specify your terms in\nthe metadata.\n\nAlso see the \"createlicense\" parameter.\n\nmetaadd\n[version 0.28]\n\nA hash of key/value pairs that should be added to the META.yml file during the\n\"distmeta\" action. Any existing entries with the same names will be overridden.\n\nSee the \"MODULE METADATA\" section for details.\n\nmetamerge\n[version 0.28]\n\nA hash of key/value pairs that should be merged into the META.yml file during the\n\"distmeta\" action. Any existing entries with the same names will be overridden.\n\nThe only difference between \"metaadd\" and \"metamerge\" is their behavior on hash-valued\nand array-valued entries: \"metaadd\" will completely blow away the existing hash or\narray value, but \"metamerge\" will merge the supplied data into the existing hash or\narray value.\n\nSee the \"MODULE METADATA\" section for details.\n\nmodulename\n[version 0.03]\n\nThe \"modulename\" is a shortcut for setting default values of \"distname\" and\n\"distversionfrom\", reflecting the fact that the majority of CPAN distributions are\ncentered around one \"main\" module. For instance, if you set \"modulename\" to \"Foo::Bar\",\nthen \"distname\" will default to \"Foo-Bar\" and \"distversionfrom\" will default to\n\"lib/Foo/Bar.pm\". \"distversionfrom\" will in turn be used to set \"distversion\".\n\nSetting \"modulename\" won't override a \"dist*\" parameter you specify explicitly.\n\nneedscompiler\n[version 0.36]\n\nThe \"needscompiler\" parameter indicates whether a compiler is required to build the\ndistribution. The default is false, unless XS files are found or the \"csource\"\nparameter is set, in which case it is true. If true, ExtUtils::CBuilder is automatically\nadded to \"buildrequires\" if needed.\n\nFor a distribution where a compiler is *optional*, e.g. a dual XS/pure-Perl\ndistribution, \"needscompiler\" should explicitly be set to a false value.\n\nPLfiles\n[version 0.06]\n\nAn optional parameter specifying a set of \".PL\" files in your distribution. These will\nbe run as Perl scripts prior to processing the rest of the files in your distribution\nwith the name of the file they're generating as an argument. They are usually used as\ntemplates for creating other files dynamically, so that a file like \"lib/Foo/Bar.pm.PL\"\nmight create the file \"lib/Foo/Bar.pm\".\n\nThe files are specified with the \".PL\" files as hash keys, and the file(s) they generate\nas hash values, like so:\n\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\n...\nPLfiles => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' },\n);\n\nNote that the path specifications are *always* given in Unix-like format, not in the\nstyle of the local system.\n\nIf your \".PL\" scripts don't create any files, or if they create files with unexpected\nnames, or even if they create multiple files, you can indicate that so that\nModule::Build can properly handle these created files:\n\nPLfiles => {\n'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm',\n'lib/something.PL' => ['/lib/something', '/lib/else'],\n'lib/funny.PL' => [],\n}\n\nHere's an example of a simple PL file.\n\nmy $outputfile = shift;\nopen my $fh, \">\", $outputfile or die \"Can't open $outputfile: $!\";\n\nprint $fh <<'END';\n#!/usr/bin/perl\n\nprint \"Hello, world!\\n\";\nEND\n\nPL files are not installed by default, so its safe to put them in lib/ and bin/.\n\npmfiles\n[version 0.19]\n\nAn optional parameter specifying the set of \".pm\" files in this distribution, specified\nas a hash reference whose keys are the files' locations in the distributions, and whose\nvalues are their logical locations based on their package name, i.e. where they would be\nfound in a \"normal\" Module::Build-style distribution. This parameter is mainly intended\nto support alternative layouts of files.\n\nFor instance, if you have an old-style \"MakeMaker\" distribution for a module called\n\"Foo::Bar\" and a Bar.pm file at the top level of the distribution, you could specify\nyour layout in your \"Build.PL\" like this:\n\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\n...\npmfiles => { 'Bar.pm' => 'lib/Foo/Bar.pm' },\n);\n\nNote that the values should include \"lib/\", because this is where they would be found in\na \"normal\" Module::Build-style distribution.\n\nNote also that the path specifications are *always* given in Unix-like format, not in\nthe style of the local system.\n\npodfiles\n[version 0.19]\n\nJust like \"pmfiles\", but used for specifying the set of \".pod\" files in your\ndistribution.\n\nrecommends\n[version 0.08]\n\nThis is just like the \"requires\" argument, except that modules listed in this section\naren't essential, just a good idea. We'll just print a friendly warning if one of these\nmodules aren't found, but we'll continue running.\n\nIf a module is recommended but not required, all tests should still pass if the module\nisn't installed. This may mean that some tests may be skipped if recommended\ndependencies aren't present.\n\nAutomated tools like CPAN.pm should inform the user when recommended modules aren't\ninstalled, and it should offer to install them if it wants to be helpful.\n\nSee the documentation for \"PREREQUISITES\" in Module::Build::Authoring for the details of\nhow requirements can be specified.\n\nrecursivetestfiles\n[version 0.28]\n\nNormally, \"Module::Build\" does not search subdirectories when looking for tests to run.\nWhen this options is set it will search recursively in all subdirectories of the\nstandard 't' test directory.\n\nreleasestatus\n[version 0.37]\n\nThe CPAN Meta Spec version 2 adds \"releasestatus\" to allow authors to specify how a\ndistribution should be indexed. Consistent with the spec, this parameter can only have\none three values: 'stable', 'testing' or 'unstable'.\n\nUnless explicitly set by the author, \"releasestatus\" will default to 'stable' unless\n\"distversion\" contains an underscore, in which case it will default to 'testing'.\n\nIt is an error to specify a \"releasestatus\" of 'stable' when \"distversion\" contains an\nunderscore character.\n\nrequires\n[version 0.07]\n\nAn optional \"requires\" argument specifies any module prerequisites that the current\nmodule depends on.\n\nOne note: currently \"Module::Build\" doesn't actually *require* the user to have\ndependencies installed, it just strongly urges. In the future we may require it. There's\nalso a \"recommends\" section for things that aren't absolutely required.\n\nAutomated tools like CPAN.pm should refuse to install a module if one of its\ndependencies isn't satisfied, unless a \"force\" command is given by the user. If the\ntools are helpful, they should also offer to install the dependencies.\n\nA synonym for \"requires\" is \"prereq\", to help succour people transitioning from\n\"ExtUtils::MakeMaker\". The \"requires\" term is preferred, but the \"prereq\" term will\nremain valid in future distributions.\n\nSee the documentation for \"PREREQUISITES\" in Module::Build::Authoring for the details of\nhow requirements can be specified.\n\nscriptfiles\n[version 0.18]\n\nAn optional parameter specifying a set of files that should be installed as executable\nPerl scripts when the module is installed. May be given as an array reference of the\nfiles, as a hash reference whose keys are the files (and whose values will currently be\nignored), as a string giving the name of a directory in which to find scripts, or as a\nstring giving the name of a single script file.\n\nThe default is to install any scripts found in a bin directory at the top level of the\ndistribution, minus any keys of PLfiles.\n\nFor backward compatibility, you may use the parameter \"scripts\" instead of\n\"scriptfiles\". Please consider this usage deprecated, though it will continue to exist\nfor several version releases.\n\nsharedir\n[version 0.36]\n\nAn optional parameter specifying directories of static data files to be installed as\nread-only files for use with File::ShareDir. The \"sharedir\" property supports both\ndistribution-level and module-level share files.\n\nThe simplest use of \"sharedir\" is to set it to a directory name or an arrayref of\ndirectory names containing files to be installed in the distribution-level share\ndirectory.\n\nsharedir => 'share'\n\nAlternatively, if \"sharedir\" is a hashref, it may have \"dist\" or \"module\" keys\nproviding full flexibility in defining how share directories should be installed.\n\nsharedir => {\ndist => [ 'examples', 'moreexamples' ],\nmodule => {\nFoo::Templates => ['share/html', 'share/text'],\nFoo::Config => 'share/config',\n}\n}\n\nIf \"sharedir\" is set, then File::ShareDir will automatically be added to the \"requires\"\nhash.\n\nsign\n[version 0.16]\n\nIf a true value is specified for this parameter, Module::Signature will be used (via the\n'distsign' action) to create a SIGNATURE file for your distribution during the 'distdir'\naction, and to add the SIGNATURE file to the MANIFEST (therefore, don't add it\nyourself).\n\nThe default value is false. In the future, the default may change to true if you have\n\"Module::Signature\" installed on your system.\n\ntapharnessargs\n[version 0.280803]\n\nAn optional parameter specifying parameters to be passed to TAP::Harness when running\ntests. Must be given as a hash reference of parameters; see the TAP::Harness\ndocumentation for details. Note that specifying this parameter will implicitly set\n\"usetapharness\" to a true value. You must therefore be sure to add TAP::Harness as a\nrequirement for your module in \"buildrequires\".\n\ntestfiles\n[version 0.23]\n\nAn optional parameter specifying a set of files that should be used as\n\"Test::Harness\"-style regression tests to be run during the \"test\" action. May be given\nas an array reference of the files, or as a hash reference whose keys are the files (and\nwhose values will currently be ignored). If the argument is given as a single string\n(not in an array reference), that string will be treated as a \"glob()\" pattern\nspecifying the files to use.\n\nThe default is to look for a test.pl script in the top-level directory of the\ndistribution, and any files matching the glob pattern \"*.t\" in the t/ subdirectory. If\nthe \"recursivetestfiles\" property is true, then the \"t/\" directory will be scanned\nrecursively for \"*.t\" files.\n\nusetapharness\n[version 0.280803]\n\nAn optional parameter indicating whether or not to use TAP::Harness for testing rather\nthan Test::Harness. Defaults to false. If set to true, you must therefore be sure to add\nTAP::Harness as a requirement for your module in \"buildrequires\". Implicitly set to a\ntrue value if \"tapharnessargs\" is specified.\n\nxsfiles\n[version 0.19]\n\nJust like \"pmfiles\", but used for specifying the set of \".xs\" files in your\ndistribution.\n" }, { "name": "new_from_context", "content": "[version 0.28]\n\nWhen called from a directory containing a Build.PL script (in other words, the base\ndirectory of a distribution), this method will run the Build.PL and call \"resume()\" to\nreturn the resulting \"Module::Build\" object to the caller. Any key-value arguments given to\n\"newfromcontext()\" are essentially like command line arguments given to the Build.PL\nscript, so for example you could pass \"verbose => 1\" to this method to turn on verbosity.\n" }, { "name": "resume", "content": "[version 0.03]\n\nYou'll probably never call this method directly, it's only called from the auto-generated\n\"Build\" script (and the \"newfromcontext\" method). The \"new()\" method is only called once,\nwhen the user runs \"perl Build.PL\". Thereafter, when the user runs \"Build test\" or another\naction, the \"Module::Build\" object is created using the \"resume()\" method to re-instantiate\nwith the settings given earlier to \"new()\".\n" }, { "name": "subclass", "content": "[version 0.06]\n\nThis creates a new \"Module::Build\" subclass on the fly, as described in the \"SUBCLASSING\" in\nModule::Build::Authoring section. The caller must provide either a \"class\" or \"code\"\nparameter, or both. The \"class\" parameter indicates the name to use for the new subclass,\nand defaults to \"MyModuleBuilder\". The \"code\" parameter specifies Perl code to use as the\nbody of the subclass.\n\naddproperty\n[version 0.31]\n\npackage 'My::Build';\nuse base 'Module::Build';\nPACKAGE->addproperty( 'pedantic' );\nPACKAGE->addproperty( answer => 42 );\nPACKAGE->addproperty(\n'epoch',\ndefault => sub { time },\ncheck => sub {\nreturn 1 if /^\\d+$/;\nshift->propertyerror( \"'$' is not an epoch time\" );\nreturn 0;\n},\n);\n\nAdds a property to a Module::Build class. Properties are those attributes of a Module::Build\nobject which can be passed to the constructor and which have accessors to get and set them.\nAll of the core properties, such as \"modulename\" and \"license\", are defined using this\nclass method.\n\nThe first argument to \"addproperty()\" is always the name of the property. The second\nargument can be either a default value for the property, or a list of key/value pairs. The\nsupported keys are:\n\n\"default\"\nThe default value. May optionally be specified as a code reference, in which case the\nreturn value from the execution of the code reference will be used. If you need the\ndefault to be a code reference, just use a code reference to return it, e.g.:\n\ndefault => sub { sub { ... } },\n\n\"check\"\nA code reference that checks that a value specified for the property is valid. During\nthe execution of the code reference, the new value will be included in the $ variable.\nIf the value is correct, the \"check\" code reference should return true. If the value is\nnot correct, it sends an error message to \"propertyerror()\" and returns false.\n\nWhen this method is called, a new property will be installed in the Module::Build class, and\nan accessor will be built to allow the property to be get or set on the build object.\n\nprint $build->pedantic, $/;\n$build->pedantic(0);\n\nIf the default value is a hash reference, this generates a special-case accessor method,\nwherein individual key/value pairs may be set or fetched:\n\nprint \"stuff{foo} is: \", $build->stuff( 'foo' ), $/;\n$build->stuff( foo => 'bar' );\nprint $build->stuff( 'foo' ), $/; # Outputs \"bar\"\n\nOf course, you can still set the entire hash reference at once, as well:\n\n$build->stuff( { foo => 'bar', baz => 'yo' } );\n\nIn either case, if a \"check\" has been specified for the property, it will be applied to the\nentire hash. So the check code reference should look something like:\n\ncheck => sub {\nreturn 1 if defined $ && exists $->{foo};\nshift->propertyerror(qq{Property \"stuff\" needs \"foo\"});\nreturn 0;\n},\n\npropertyerror\n[version 0.31]\n\nMETHODS" }, { "name": "add_build_element", "content": "[version 0.26]\n\nAdds a new type of entry to the build process. Accepts a single string specifying its\ntype-name. There must also be a method defined to process things of that type, e.g. if you\nadd a build element called 'foo', then you must also define a method called\n\"processfoofiles()\".\n\nSee also \"Adding new file types to the build process\" in Module::Build::Cookbook.\n" }, { "name": "add_to_cleanup", "content": "[version 0.03]\n\nYou may call \"$self->addtocleanup(@patterns)\" to tell \"Module::Build\" that certain files\nshould be removed when the user performs the \"Build clean\" action. The arguments to the\nmethod are patterns suitable for passing to Perl's \"glob()\" function, specified in either\nUnix format or the current machine's native format. It's usually convenient to use Unix\nformat when you hard-code the filenames (e.g. in Build.PL) and the native format when the\nnames are programmatically generated (e.g. in a testing script).\n\nI decided to provide a dynamic method of the $build object, rather than just use a static\nlist of files named in the Build.PL, because these static lists can get difficult to manage.\nI usually prefer to keep the responsibility for registering temporary files close to the\ncode that creates them.\n" }, { "name": "args", "content": "[version 0.26]\n\nmy $argshref = $build->args;\nmy %args = $build->args;\nmy $argvalue = $build->args($key);\n$build->args($key, $value);\n\nThis method is the preferred interface for retrieving the arguments passed via command line\noptions to Build.PL or Build, minus the Module-Build specific options.\n\nWhen called in a scalar context with no arguments, this method returns a reference to the\nhash storing all of the arguments; in an array context, it returns the hash itself. When\npassed a single argument, it returns the value stored in the args hash for that option key.\nWhen called with two arguments, the second argument is assigned to the args hash under the\nkey passed as the first argument.\n" }, { "name": "autosplit_file", "content": "[version 0.28]\n\nInvokes the AutoSplit module on the $from file, sending the output to the \"lib/auto\"\ndirectory inside $to. $to is typically the \"blib/\" directory.\n" }, { "name": "base_dir", "content": "[version 0.14]\n\nReturns a string containing the root-level directory of this build, i.e. where the\n\"Build.PL\" script and the \"lib\" directory can be found. This is usually the same as the\ncurrent working directory, because the \"Build\" script will \"chdir()\" into this directory as\nsoon as it begins execution.\n" }, { "name": "build_requires", "content": "[version 0.21]\n\nReturns a hash reference indicating the \"buildrequires\" prerequisites that were passed to\nthe \"new()\" method.\n" }, { "name": "can_action", "content": "Returns a reference to the method that defines $action, or false otherwise. This is handy\nfor actions defined (or maybe not!) in subclasses.\n\n[version 0.32xx]\n" }, { "name": "cbuilder", "content": "[version 0.2809]\n\nReturns the internal ExtUtils::CBuilder object that can be used for compiling & linking C\ncode. If no such object is available (e.g. if the system has no compiler installed) an\nexception will be thrown.\n" }, { "name": "check_installed_status", "content": "[version 0.11]\n\nThis method returns a hash reference indicating whether a version dependency on a certain\nmodule is satisfied. The $module argument is given as a string like \"Data::Dumper\" or\n\"perl\", and the $version argument can take any of the forms described in \"requires\" above.\nThis allows very fine-grained version checking.\n\nThe returned hash reference has the following structure:\n\n{\nok => $whetherthedependencyissatisfied,\nhave => $versionalreadyinstalled,\nneed => $versionrequested, # Same as incoming $version argument\nmessage => $informativeerrormessage,\n}\n\nIf no version of $module is currently installed, the \"have\" value will be the string\n\"\". Otherwise the \"have\" value will simply be the version of the installed module.\nNote that this means that if $module is installed but doesn't define a version number, the\n\"have\" value will be \"undef\" - this is why we don't use \"undef\" for the case when $module\nisn't installed at all.\n\nThis method may be called either as an object method\n(\"$build->checkinstalledstatus($module, $version)\") or as a class method\n(\"Module::Build->checkinstalledstatus($module, $version)\").\n" }, { "name": "check_installed_version", "content": "[version 0.05]\n\nLike checkinstalledstatus(), but simply returns true or false depending on whether module\n$module satisfies the dependency $version.\n\nIf the check succeeds, the return value is the actual version of $module installed on the\nsystem. This allows you to do the following:\n\nmy $installed = $build->checkinstalledversion('DBI', '1.15');\nif ($installed) {\nprint \"Congratulations, version $installed of DBI is installed.\\n\";\n} else {\ndie \"Sorry, you must install DBI.\\n\";\n}\n\nIf the check fails, we return false and set $@ to an informative error message.\n\nIf $version is any non-true value (notably zero) and any version of $module is installed, we\nreturn true. In this case, if $module doesn't define a version, or if its version is zero,\nwe return the special value \"0 but true\", which is numerically zero, but logically true.\n\nIn general you might prefer to use \"checkinstalledstatus\" if you need detailed\ninformation, or this method if you just need a yes/no answer.\n" }, { "name": "compare_versions", "content": "[version 0.28]\n\nCompares two module versions $v1 and $v2 using the operator $op, which should be one of\nPerl's numeric operators like \"!=\" or \">=\" or the like. We do at least a halfway-decent job\nof handling versions that aren't strictly numeric, like \"0.2702\", but exotic stuff will\nlikely cause problems.\n\nIn the future, the guts of this method might be replaced with a call out to \"version.pm\".\n" }, { "name": "config", "content": "" }, { "name": "config", "content": "" }, { "name": "config", "content": "[version 0.22]\n\nWith a single argument $key, returns the value associated with that key in the \"Config.pm\"\nhash, including any changes the author or user has specified.\n\nWith $key and $value arguments, sets the value for future callers of \"config($key)\".\n\nWith no arguments, returns a hash reference containing all such key-value pairs. This usage\nis deprecated, though, because it's a resource hog and violates encapsulation.\n" }, { "name": "config_data", "content": "" }, { "name": "config_data", "content": "[version 0.26]\n\nWith a single argument, returns the value of the configuration variable $name. With two\narguments, sets the given configuration variable to the given value. The value may be any\nPerl scalar that's serializable with \"Data::Dumper\". For instance, if you write a module\nthat can use a MySQL or PostgreSQL back-end, you might create configuration variables called\n\"mysqlconnect\" and \"postgresconnect\", and set each to an array of connection parameters\nfor \"DBI->connect()\".\n\nConfiguration values set in this way using the Module::Build object will be available for\nquerying during the build/test process and after installation via the generated\n\"...::ConfigData\" module, as \"...::ConfigData->config($name)\".\n\nThe feature() and \"configdata()\" methods represent Module::Build's main support for\nconfiguration of installed modules. See also \"SAVING CONFIGURATION INFORMATION\" in\nModule::Build::Authoring.\n" }, { "name": "conflicts", "content": "[version 0.21]\n\nReturns a hash reference indicating the \"conflicts\" prerequisites that were passed to the\n\"new()\" method.\n" }, { "name": "contains_pod", "content": "[version 0.20]\n\n[Deprecated] Please see Module::Metadata instead.\n\nReturns true if the given file appears to contain POD documentation. Currently this checks\nwhether the file has a line beginning with '=pod', '=head', or '=item', but the exact\nsemantics may change in the future.\n" }, { "name": "copy_if_modified", "content": "[version 0.19]\n\nTakes the file in the \"from\" parameter and copies it to the file in the \"to\" parameter, or\nthe directory in the \"todir\" parameter, if the file has changed since it was last copied\n(or if it doesn't exist in the new location). By default the entire directory structure of\n\"from\" will be copied into \"todir\"; an optional \"flatten\" parameter will copy into \"todir\"\nwithout doing so.\n\nReturns the path to the destination file, or \"undef\" if nothing needed to be copied.\n\nAny directories that need to be created in order to perform the copying will be\nautomatically created.\n\nThe destination file is set to read-only. If the source file has the executable bit set,\nthen the destination file will be made executable.\n" }, { "name": "create_build_script", "content": "[version 0.05]\n\nCreates an executable script called \"Build\" in the current directory that will be used to\nexecute further user actions. This script is roughly analogous (in function, not in form) to\nthe Makefile created by \"ExtUtils::MakeMaker\". This method also creates some temporary data\nin a directory called \"build/\". Both of these will be removed when the \"realclean\" action\nis performed.\n\nAmong the files created in \"build/\" is a build/prereqs file containing the set of\nprerequisites for this distribution, as a hash of hashes. This file may be \"eval()\"-ed to\nobtain the authoritative set of prerequisites, which might be different from the contents of\nMETA.yml (because Build.PL might have set them dynamically). But fancy developers take heed:\ndo not put any fancy custom runtime code in the build/prereqs file, leave it as a static\ndeclaration containing only strings and numbers. Similarly, do not alter the structure of\nthe internal \"$self->{properties}{requires}\" (etc.) data members, because that's where this\ndata comes from.\n" }, { "name": "current_action", "content": "[version 0.28]\n\nReturns the name of the currently-running action, such as \"build\" or \"test\". This action is\nnot necessarily the action that was originally invoked by the user. For example, if the user\ninvoked the \"test\" action, currentaction() would initially return \"test\". However, action\n\"test\" depends on action \"code\", so currentaction() will return \"code\" while that\ndependency is being executed. Once that action has completed, currentaction() will again\nreturn \"test\".\n\nIf you need to know the name of the original action invoked by the user, see\n\"invokedaction()\" below.\n" }, { "name": "depends_on", "content": "[version 0.28]\n\nInvokes the named action or list of actions in sequence. Using this method is preferred to\ncalling the action explicitly because it performs some internal record-keeping, and it\nensures that the same action is not invoked multiple times (note: in future versions of\nModule::Build it's conceivable that this run-only-once mechanism will be changed to\nsomething more intelligent).\n\nNote that the name of this method is something of a misnomer; it should really be called\nsomething like \"invokeactionsunlessalreadyinvoked()\" or something, but for better or\nworse (perhaps better!) we were still thinking in \"make\"-like dependency terms when we\ncreated this method.\n\nSee also dispatch(). The main distinction between the two is that \"dependson()\" is meant to\ncall an action from inside another action, whereas \"dispatch()\" is meant to set the very top\naction in motion.\n" }, { "name": "dir_contains", "content": "[version 0.28]\n\nReturns true if the first directory logically contains the second directory. This is just a\nconvenience function because \"File::Spec\" doesn't really provide an easy way to figure this\nout (but \"Path::Class\" does...).\n" }, { "name": "dispatch", "content": "[version 0.03]\n\nInvokes the build action $action. Optionally, a list of options and their values can be\npassed in. This is equivalent to invoking an action at the command line, passing in a list\nof options.\n\nCustom options that have not been registered must be passed in as a hash reference in a key\nnamed \"args\":\n\n$build->dispatch('foo', verbose => 1, args => { myoption => 'value' });\n\nThis method is intended to be used to programmatically invoke build actions, e.g. by\napplications controlling Module::Build-based builds rather than by subclasses.\n\nSee also dependson(). The main distinction between the two is that \"dependson()\" is meant\nto call an action from inside another action, whereas \"dispatch()\" is meant to set the very\ntop action in motion.\n" }, { "name": "dist_dir", "content": "[version 0.28]\n\nReturns the name of the directory that will be created during the \"dist\" action. The name is\nderived from the \"distname\" and \"distversion\" properties.\n" }, { "name": "dist_name", "content": "[version 0.21]\n\nReturns the name of the current distribution, as passed to the \"new()\" method in a\n\"distname\" or modified \"modulename\" parameter.\n" }, { "name": "dist_version", "content": "[version 0.21]\n\nReturns the version of the current distribution, as determined by the \"new()\" method from a\n\"distversion\", \"distversionfrom\", or \"modulename\" parameter.\n" }, { "name": "do_system", "content": "[version 0.21]\n\nThis is a fairly simple wrapper around Perl's \"system()\" built-in command. Given a command\nand an array of optional arguments, this method will print the command to \"STDOUT\", and then\nexecute it using Perl's \"system()\". It returns true or false to indicate success or failure\n(the opposite of how \"system()\" works, but more intuitive).\n\nNote that if you supply a single argument to \"dosystem()\", it will/may be processed by the\nsystem's shell, and any special characters will do their special things. If you supply\nmultiple arguments, no shell will get involved and the command will be executed directly.\n" }, { "name": "extra_compiler_flags", "content": "" }, { "name": "extra_compiler_flags", "content": "[version 0.25]\n\nSet or retrieve the extra compiler flags. Returns an arrayref of flags.\n" }, { "name": "extra_linker_flags", "content": "" }, { "name": "extra_linker_flags", "content": "[version 0.25]\n\nSet or retrieve the extra linker flags. Returns an arrayref of flags.\n" }, { "name": "feature", "content": "" }, { "name": "feature", "content": "[version 0.26]\n\nWith a single argument, returns true if the given feature is set. With two arguments, sets\nthe given feature to the given boolean value. In this context, a \"feature\" is any optional\nfunctionality of an installed module. For instance, if you write a module that could\noptionally support a MySQL or PostgreSQL backend, you might create features called\n\"mysqlsupport\" and \"postgressupport\", and set them to true/false depending on whether the\nuser has the proper databases installed and configured.\n\nFeatures set in this way using the Module::Build object will be available for querying\nduring the build/test process and after installation via the generated \"...::ConfigData\"\nmodule, as \"...::ConfigData->feature($name)\".\n\nThe \"feature()\" and \"configdata()\" methods represent Module::Build's main support for\nconfiguration of installed modules. See also \"SAVING CONFIGURATION INFORMATION\" in\nModule::Build::Authoring.\n" }, { "name": "fix_shebang_line", "content": "[version 0.??]\n\nModify any \"shebang\" line in the specified files to use the path to the perl executable\nbeing used for the current build. Files are modified in-place. The existing shebang line\nmust have a command that contains \"\"perl\"\"; arguments to the command do not count. In\nparticular, this means that the use of \"#!/usr/bin/env perl\" will not be changed.\n\nFor an explanation of shebang lines, see .\n" }, { "name": "have_c_compiler", "content": "[version 0.21]\n\nReturns true if the current system seems to have a working C compiler. We currently\ndetermine this by attempting to compile a simple C source file and reporting whether the\nattempt was successful.\n" }, { "name": "install_base_relpaths", "content": "" }, { "name": "install_base_relpaths", "content": "" }, { "name": "install_base_relpaths", "content": "[version 0.28]\n\nSet or retrieve the relative paths that are appended to \"installbase\" for any installable\nelement. This is useful if you want to set the relative install path for custom build\nelements.\n\nWith no argument, it returns a reference to a hash containing all elements and their\nrespective values. This hash should not be modified directly; use the multiple argument\nbelow form to change values.\n\nThe single argument form returns the value associated with the element $type.\n\nThe multiple argument form allows you to set the paths for element types. $value must be a\nrelative path using Unix-like paths. (A series of directories separated by slashes, e.g.\n\"foo/bar\".) The return value is a localized path based on $value.\n\nAssigning the value \"undef\" to an element causes it to be removed.\n" }, { "name": "install_destination", "content": "[version 0.28]\n\nReturns the directory in which items of type $type (e.g. \"lib\", \"arch\", \"bin\", or anything\nelse returned by the \"installtypes()\" method) will be installed during the \"install\"\naction. Any settings for \"installpath\", \"installbase\", and \"prefix\" are taken into account\nwhen determining the return value.\n" }, { "name": "install_path", "content": "" }, { "name": "install_path", "content": "" }, { "name": "install_path", "content": "[version 0.28]\n\nSet or retrieve paths for specific installable elements. This is useful when you want to\nexamine any explicit install paths specified by the user on the command line, or if you want\nto set the install path for a specific installable element based on another attribute like\n\"installbase()\".\n\nWith no argument, it returns a reference to a hash containing all elements and their\nrespective values. This hash should not be modified directly; use the multiple argument\nbelow form to change values.\n\nThe single argument form returns the value associated with the element $type.\n\nThe multiple argument form allows you to set the paths for element types. The supplied $path\nshould be an absolute path to install elements of $type. The return value is $path.\n\nAssigning the value \"undef\" to an element causes it to be removed.\n" }, { "name": "install_types", "content": "[version 0.28]\n\nReturns a list of installable types that this build knows about. These types each correspond\nto the name of a directory in blib/, and the list usually includes items such as \"lib\",\n\"arch\", \"bin\", \"script\", \"libdoc\", \"bindoc\", and if HTML documentation is to be built,\n\"libhtml\" and \"binhtml\". Other user-defined types may also exist.\n" }, { "name": "invoked_action", "content": "[version 0.28]\n\nThis is the name of the original action invoked by the user. This value is set when the user\ninvokes Build.PL, the Build script, or programmatically through the dispatch() method. It\ndoes not change as sub-actions are executed as dependencies are evaluated.\n\nTo get the name of the currently executing dependency, see \"currentaction()\" above.\n" }, { "name": "notes", "content": "" }, { "name": "notes", "content": "" }, { "name": "notes", "content": "[version 0.20]\n\nThe \"notes()\" value allows you to store your own persistent information about the build, and\nto share that information among different entities involved in the build. See the example in\nthe \"current()\" method.\n\nThe \"notes()\" method is essentially a glorified hash access. With no arguments, \"notes()\"\nreturns the entire hash of notes. With one argument, \"notes($key)\" returns the value\nassociated with the given key. With two arguments, \"notes($key, $value)\" sets the value\nassociated with the given key to $value and returns the new value.\n\nThe lifetime of the \"notes\" data is for \"a build\" - that is, the \"notes\" hash is created\nwhen \"perl Build.PL\" is run (or when the \"new()\" method is run, if the Module::Build Perl\nAPI is being used instead of called from a shell), and lasts until \"perl Build.PL\" is run\nagain or the \"clean\" action is run.\n" }, { "name": "orig_dir", "content": "[version 0.28]\n\nReturns a string containing the working directory that was in effect before the Build script\nchdir()-ed into the \"basedir\". This might be useful for writing wrapper tools that might\nneed to chdir() back out.\n" }, { "name": "os_type", "content": "[version 0.04]\n\nIf you're subclassing Module::Build and some code needs to alter its behavior based on the\ncurrent platform, you may only need to know whether you're running on Windows, Unix, MacOS,\nVMS, etc., and not the fine-grained value of Perl's $^O variable. The \"ostype()\" method\nwill return a string like \"Windows\", \"Unix\", \"MacOS\", \"VMS\", or whatever is appropriate. If\nyou're running on an unknown platform, it will return \"undef\" - there shouldn't be many\nunknown platforms though.\n" }, { "name": "is_vmsish", "content": "" }, { "name": "is_windowsish", "content": "" }, { "name": "is_unixish", "content": "Convenience functions that return a boolean value indicating whether this platform behaves\nrespectively like VMS, Windows, or Unix. For arbitrary reasons other platforms don't get\ntheir own such functions, at least not yet.\n" }, { "name": "prefix_relpaths", "content": "" }, { "name": "prefix_relpaths", "content": "" }, { "name": "prefix_relpaths", "content": "" }, { "name": "prefix_relpaths", "content": "[version 0.28]\n\nSet or retrieve the relative paths that are appended to \"prefix\" for any installable\nelement. This is useful if you want to set the relative install path for custom build\nelements.\n\nWith no argument, it returns a reference to a hash containing all elements and their\nrespective values as defined by the current \"installdirs\" setting.\n\nWith a single argument, it returns a reference to a hash containing all elements and their\nrespective values as defined by $installdirs.\n\nThe hash returned by the above calls should not be modified directly; use the three-argument\nbelow form to change values.\n\nThe two argument form returns the value associated with the element $type.\n\nThe multiple argument form allows you to set the paths for element types. $value must be a\nrelative path using Unix-like paths. (A series of directories separated by slashes, e.g.\n\"foo/bar\".) The return value is a localized path based on $value.\n\nAssigning the value \"undef\" to an element causes it to be removed.\n" }, { "name": "get_metadata", "content": "[version 0.36]\n\nThis method returns a hash reference of metadata that can be used to create a YAML\ndatastream. It is provided for authors to override or customize the fields of META.yml. E.g.\n\npackage My::Builder;\nuse base 'Module::Build';\n\nsub getmetadata {\nmy $self, @args = @;\nmy $data = $self->SUPER::getmetadata(@args);\n$data->{customfield} = 'foo';\nreturn $data;\n}\n\nValid arguments include:\n\n* \"fatal\" -- indicates whether missing required metadata fields should be a fatal error or\nnot. For META creation, it generally should, but for MYMETA creation for end-users, it\nshould not be fatal.\n\n* \"auto\" -- indicates whether any necessary configurerequires should be automatically\nadded. This is used in META creation.\n\nThis method is a wrapper around the old preparemetadata API now that we no longer use\nYAML::Node to hold metadata.\n" }, { "name": "prepare_metadata", "content": "[version 0.36]\n\n[Deprecated] As of 0.36, authors should use \"getmetadata\" instead. This method is preserved\nfor backwards compatibility only.\n\nIt takes three positional arguments: a hashref (to which metadata will be added), an\noptional arrayref (to which metadata keys will be added in order if the arrayref exists),\nand a hashref of arguments (as provided to getmetadata). The latter argument is new as of\n0.36. Earlier versions are always fatal on errors.\n\nPrior to version 0.36, this method took a YAML::Node as an argument to hold assembled\nmetadata.\n" }, { "name": "prereq_failures", "content": "[version 0.11]\n\nReturns a data structure containing information about any failed prerequisites (of any of\nthe types described above), or \"undef\" if all prerequisites are met.\n\nThe data structure returned is a hash reference. The top level keys are the type of\nprerequisite failed, one of \"requires\", \"buildrequires\", \"conflicts\", or \"recommends\". The\nassociated values are hash references whose keys are the names of required (or conflicting)\nmodules. The associated values of those are hash references indicating some information\nabout the failure. For example:\n\n{\nhave => '0.42',\nneed => '0.59',\nmessage => 'Version 0.42 is installed, but we need version 0.59',\n}\n\nor\n\n{\nhave => '',\nneed => '0.59',\nmessage => 'Prerequisite Foo isn't installed',\n}\n\nThis hash has the same structure as the hash returned by the \"checkinstalledstatus()\"\nmethod, except that in the case of \"conflicts\" dependencies we change the \"need\" key to\n\"conflicts\" and construct a proper message.\n\nExamples:\n\n# Check a required dependency on Foo::Bar\nif ( $build->prereqfailures->{requires}{Foo::Bar} ) { ...\n\n# Check whether there were any failures\nif ( $build->prereqfailures ) { ...\n\n# Show messages for all failures\nmy $failures = $build->prereqfailures;\nwhile (my ($type, $list) = each %$failures) {\nwhile (my ($name, $hash) = each %$list) {\nprint \"Failure for $name: $hash->{message}\\n\";\n}\n}\n" }, { "name": "prereq_data", "content": "[version 0.32]\n\nReturns a reference to a hash describing all prerequisites. The keys of the hash will be the\nvarious prerequisite types ('requires', 'buildrequires', 'testrequires',\n'configurerequires', 'recommends', or 'conflicts') and the values will be references to\nhashes of module names and version numbers. Only prerequisites types that are defined will\nbe included. The \"prereqdata\" action is just a thin wrapper around the \"prereqdata()\"\nmethod and dumps the hash as a string that can be loaded using \"eval()\".\n" }, { "name": "prereq_report", "content": "[version 0.28]\n\nReturns a human-readable (table-form) string showing all prerequisites, the versions\nrequired, and the versions actually installed. This can be useful for reviewing the\nconfiguration of your system prior to a build, or when compiling data to send for a bug\nreport. The \"prereqreport\" action is just a thin wrapper around the \"prereqreport()\"\nmethod.\n" }, { "name": "prompt", "content": "[version 0.12]\n\nAsks the user a question and returns their response as a string. The first argument\nspecifies the message to display to the user (for example, \"Where do you keep your money?\").\nThe second argument, which is optional, specifies a default answer (for example, \"wallet\").\nThe user will be asked the question once.\n\nIf \"prompt()\" detects that it is not running interactively and there is nothing on STDIN or\nif the PERLMMUSEDEFAULT environment variable is set to true, the $default will be used\nwithout prompting.\n\nTo prevent automated processes from blocking, the user must either set PERLMMUSEDEFAULT\nor attach something to STDIN (this can be a pipe/file containing a scripted set of answers\nor /dev/null.)\n\nIf no $default is provided an empty string will be used instead. In non-interactive mode,\nthe absence of $default is an error (though explicitly passing \"undef()\" as the default is\nvalid as of 0.27.)\n\nThis method may be called as a class or object method.\n" }, { "name": "recommends", "content": "[version 0.21]\n\nReturns a hash reference indicating the \"recommends\" prerequisites that were passed to the\n\"new()\" method.\n" }, { "name": "requires", "content": "[version 0.21]\n\nReturns a hash reference indicating the \"requires\" prerequisites that were passed to the\n\"new()\" method.\n" }, { "name": "rscan_dir", "content": "[version 0.28]\n\nUses \"File::Find\" to traverse the directory $dir, returning a reference to an array of\nentries matching $pattern. $pattern may either be a regular expression (using \"qr//\" or just\na plain string), or a reference to a subroutine that will return true for wanted entries. If\n$pattern is not given, all entries will be returned.\n\nExamples:\n\n# All the *.pm files in lib/\n$m->rscandir('lib', qr/\\.pm$/)\n\n# All the files in blib/ that aren't *.html files\n$m->rscandir('blib', sub {-f $ and not /\\.html$/});\n\n# All the files in t/\n$m->rscandir('t');\n" }, { "name": "runtime_params", "content": "" }, { "name": "runtime_params", "content": "[version 0.28]\n\nThe \"runtimeparams()\" method stores the values passed on the command line for valid\nproperties (that is, any command line options for which \"validproperty()\" returns a true\nvalue). The value on the command line may override the default value for a property, as well\nas any value specified in a call to \"new()\". This allows you to programmatically tell if\n\"perl Build.PL\" or any execution of \"./Build\" had command line options specified that\noverride valid properties.\n\nThe \"runtimeparams()\" method is essentially a glorified read-only hash. With no arguments,\n\"runtimeparams()\" returns the entire hash of properties specified on the command line. With\none argument, \"runtimeparams($key)\" returns the value associated with the given key.\n\nThe lifetime of the \"runtimeparams\" data is for \"a build\" - that is, the \"runtimeparams\"\nhash is created when \"perl Build.PL\" is run (or when the \"new()\" method is called, if the\nModule::Build Perl API is being used instead of called from a shell), and lasts until \"perl\nBuild.PL\" is run again or the \"clean\" action is run.\n" }, { "name": "script_files", "content": "[version 0.18]\n\nReturns a hash reference whose keys are the perl script files to be installed, if any. This\ncorresponds to the \"scriptfiles\" parameter to the \"new()\" method. With an optional\nargument, this parameter may be set dynamically.\n\nFor backward compatibility, the \"scripts()\" method does exactly the same thing as\n\"scriptfiles()\". \"scripts()\" is deprecated, but it will stay around for several versions to\ngive people time to transition.\n" }, { "name": "up_to_date", "content": "" }, { "name": "up_to_date", "content": "[version 0.20]\n\nThis method can be used to compare a set of source files to a set of derived files. If any\nof the source files are newer than any of the derived files, it returns false. Additionally,\nif any of the derived files do not exist, it returns false. Otherwise it returns true.\n\nThe arguments may be either a scalar or an array reference of file names.\n" }, { "name": "y_n", "content": "[version 0.12]\n\nAsks the user a yes/no question using \"prompt()\" and returns true or false accordingly. The\nuser will be asked the question repeatedly until they give an answer that looks like \"yes\"\nor \"no\".\n\nThe first argument specifies the message to display to the user (for example, \"Shall I\ninvest your money for you?\"), and the second argument specifies the default answer (for\nexample, \"y\").\n\nNote that the default is specified as a string like \"y\" or \"n\", and the return value is a\nPerl boolean value like 1 or 0. I thought about this for a while and this seemed like the\nmost useful way to do it.\n\nThis method may be called as a class or object method.\n" }, { "name": "Autogenerated Accessors", "content": "In addition to the aforementioned methods, there are also some get/set accessor methods for the\nfollowing properties:\n\nPLfiles()" }, { "name": "allow_mb_mismatch", "content": "" }, { "name": "allow_pureperl", "content": "" }, { "name": "auto_configure_requires", "content": "" }, { "name": "autosplit", "content": "" }, { "name": "base_dir", "content": "" }, { "name": "bindoc_dirs", "content": "" }, { "name": "blib", "content": "" }, { "name": "build_bat", "content": "" }, { "name": "build_class", "content": "" }, { "name": "build_elements", "content": "" }, { "name": "build_requires", "content": "" }, { "name": "build_script", "content": "" }, { "name": "bundle_inc", "content": "" }, { "name": "bundle_inc_preload", "content": "" }, { "name": "c_source", "content": "" }, { "name": "config_dir", "content": "" }, { "name": "configure_requires", "content": "" }, { "name": "conflicts", "content": "" }, { "name": "cover", "content": "" }, { "name": "cpan_client", "content": "" }, { "name": "create_license", "content": "" }, { "name": "create_makefile_pl", "content": "" }, { "name": "create_packlist", "content": "" }, { "name": "create_readme", "content": "" }, { "name": "debug", "content": "" }, { "name": "debugger", "content": "" }, { "name": "destdir", "content": "" }, { "name": "dynamic_config", "content": "" }, { "name": "extra_manify_args", "content": "" }, { "name": "get_options", "content": "" }, { "name": "html_css", "content": "" }, { "name": "include_dirs", "content": "" }, { "name": "install_base", "content": "" }, { "name": "installdirs", "content": "" }, { "name": "libdoc_dirs", "content": "" }, { "name": "license", "content": "" }, { "name": "magic_number", "content": "" }, { "name": "mb_version", "content": "" }, { "name": "meta_add", "content": "" }, { "name": "meta_merge", "content": "" }, { "name": "metafile", "content": "" }, { "name": "metafile2", "content": "" }, { "name": "module_name", "content": "" }, { "name": "mymetafile", "content": "" }, { "name": "mymetafile2", "content": "" }, { "name": "needs_compiler", "content": "" }, { "name": "orig_dir", "content": "" }, { "name": "perl", "content": "" }, { "name": "pm_files", "content": "" }, { "name": "pod_files", "content": "" }, { "name": "pollute", "content": "" }, { "name": "prefix", "content": "" }, { "name": "prereq_action_types", "content": "" }, { "name": "program_name", "content": "" }, { "name": "pureperl_only", "content": "" }, { "name": "quiet", "content": "" }, { "name": "recommends", "content": "" }, { "name": "recurse_into", "content": "" }, { "name": "recursive_test_files", "content": "" }, { "name": "requires", "content": "" }, { "name": "scripts", "content": "" }, { "name": "sign", "content": "" }, { "name": "tap_harness_args", "content": "" }, { "name": "test_file_exts", "content": "" }, { "name": "test_requires", "content": "" }, { "name": "use_rcfile", "content": "" }, { "name": "use_tap_harness", "content": "" }, { "name": "verbose", "content": "" }, { "name": "xs_files", "content": "" } ] }, "MODULE METADATA": { "content": "If you would like to add other useful metadata, \"Module::Build\" supports this with the\n\"metaadd\" and \"metamerge\" arguments to \"new()\". The authoritative list of supported metadata\ncan be found at CPAN::Meta::Spec but for convenience - here are a few of the more useful ones:\n\nkeywords\nFor describing the distribution using keyword (or \"tags\") in order to make CPAN.org indexing\nand search more efficient and useful.\n\nresources\nA list of additional resources available for users of the distribution. This can include\nlinks to a homepage on the web, a bug tracker, the repository location, and even a\nsubscription page for the distribution mailing list.\n", "subsections": [] }, "AUTHOR": { "content": "Ken Williams \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (c) 2001-2006 Ken Williams. All rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "perl", "content": "ExtUtils::MakeMaker(3)\n\nMETA.yml Specification: CPAN::Meta::Spec\n" } ] } }, "summary": "Module::Build::API - API Reference for Module Authors", "flags": [], "examples": [], "see_also": [ { "name": "MakeMaker", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/MakeMaker/3/json" } ] }