{ "content": [ { "type": "text", "text": "# Module::Build::Authoring (perldoc)\n\n## NAME\n\nModule::Build::Authoring - Authoring Module::Build modules\n\n## DESCRIPTION\n\nWhen creating a \"Build.PL\" script for a module, something like the following code will typically\nbe used:\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **STRUCTURE**\n- **SUBCLASSING**\n- **PREREQUISITES** (2 subsections)\n- **SAVING CONFIGURATION INFORMATION**\n- **STARTING MODULE DEVELOPMENT**\n- **AUTOMATION**\n- **MIGRATION**\n- **AUTHOR**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Module::Build::Authoring", "section": "", "mode": "perldoc", "summary": "Module::Build::Authoring - Authoring Module::Build modules", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "MakeMaker", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/MakeMaker/3/json" }, { "name": "YAML", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/YAML/3/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 40, "subsections": [] }, { "name": "STRUCTURE", "lines": 22, "subsections": [] }, { "name": "SUBCLASSING", "lines": 58, "subsections": [] }, { "name": "PREREQUISITES", "lines": 1, "subsections": [ { "name": "Types of prerequisites", "lines": 33 }, { "name": "Format of prerequisites", "lines": 25 } ] }, { "name": "SAVING CONFIGURATION INFORMATION", "lines": 9, "subsections": [] }, { "name": "STARTING MODULE DEVELOPMENT", "lines": 9, "subsections": [] }, { "name": "AUTOMATION", "lines": 20, "subsections": [] }, { "name": "MIGRATION", "lines": 9, "subsections": [] }, { "name": "AUTHOR", "lines": 10, "subsections": [] }, { "name": "SEE ALSO", "lines": 1, "subsections": [ { "name": "perl", "lines": 8 } ] } ], "sections": { "NAME": { "content": "Module::Build::Authoring - Authoring Module::Build modules\n", "subsections": [] }, "DESCRIPTION": { "content": "When creating a \"Build.PL\" script for a module, something like the following code will typically\nbe used:\n\nuse Module::Build;\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\nrequires => {\n'perl' => '5.6.1',\n'Some::Module' => '1.23',\n'Other::Module' => '>= 1.2, != 1.5, < 2.0',\n},\n);\n$build->createbuildscript;\n\nA simple module could get away with something as short as this for its \"Build.PL\" script:\n\nuse Module::Build;\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\n)->createbuildscript;\n\nThe model used by \"Module::Build\" is a lot like the \"MakeMaker\" metaphor, with the following\ncorrespondences:\n\nIn Module::Build In ExtUtils::MakeMaker\n--------------------------- ------------------------\nBuild.PL (initial script) Makefile.PL (initial script)\nBuild (a short perl script) Makefile (a long Makefile)\nbuild/ (saved state info) various config text in the Makefile\n\nAny customization can be done simply by subclassing \"Module::Build\" and adding a method called\n(for example) \"ACTIONtest\", overriding the default 'test' action. You could also add a method\ncalled \"ACTIONwhatever\", and then you could perform the action \"Build whatever\".\n\nFor information on providing compatibility with \"ExtUtils::MakeMaker\", see Module::Build::Compat\nand .\n", "subsections": [] }, "STRUCTURE": { "content": "Module::Build creates a class hierarchy conducive to customization. Here is the parent-child\nclass hierarchy in classy ASCII art:\n\n/--------------------\\\n| Your::Parent | (If you subclass Module::Build)\n\\--------------------/\n|\n|\n/--------------------\\ (Doesn't define any functionality\n| Module::Build | of its own - just figures out what\n\\--------------------/ other modules to load.)\n|\n|\n/-----------------------------------\\ (Some values of $^O may\n| Module::Build::Platform::$^O | define specialized functionality.\n\\-----------------------------------/ Otherwise it's ...::Default, a\n| pass-through class.)\n|\n/--------------------------\\\n| Module::Build::Base | (Most of the functionality of\n\\--------------------------/ Module::Build is defined here.)\n", "subsections": [] }, "SUBCLASSING": { "content": "Right now, there are two ways to subclass Module::Build. The first way is to create a regular\nmodule (in a \".pm\" file) that inherits from Module::Build, and use that module's class instead\nof using Module::Build directly:\n\n------ in Build.PL: ----------\n#!/usr/bin/perl\n\nuse lib q(/nonstandard/library/path);\nuse My::Builder; # Or whatever you want to call it\n\nmy $build = My::Builder->new\n(\nmodulename => 'Foo::Bar', # All the regular args...\nlicense => 'perl',\ndistauthor => 'A N Other ',\nrequires => { Carp => 0 }\n);\n$build->createbuildscript;\n\nThis is relatively straightforward, and is the best way to do things if your My::Builder class\ncontains lots of code. The \"createbuildscript()\" method will ensure that the current value of\n@INC (including the \"/nonstandard/library/path\") is propagated to the Build script, so that\nMy::Builder can be found when running build actions. If you find that you need to \"chdir\" into a\ndifferent directories in your subclass methods or actions, be sure to always return to the\noriginal directory (available via the \"basedir()\" method) before returning control to the\nparent class. This is important to avoid data serialization problems.\n\nFor very small additions, Module::Build provides a \"subclass()\" method that lets you subclass\nModule::Build more conveniently, without creating a separate file for your module:\n\n------ in Build.PL: ----------\n#!/usr/bin/perl\n\nuse Module::Build;\nmy $class = Module::Build->subclass\n(\nclass => 'My::Builder',\ncode => q{\nsub ACTIONfoo {\nprint \"I'm fooing to death!\\n\";\n}\n},\n);\n\nmy $build = $class->new\n(\nmodulename => 'Foo::Bar', # All the regular args...\nlicense => 'perl',\ndistauthor => 'A N Other ',\nrequires => { Carp => 0 }\n);\n$build->createbuildscript;\n\nBehind the scenes, this actually does create a \".pm\" file, since the code you provide must\npersist after Build.PL is run if it is to be very useful.\n\nSee also the documentation for the \"subclass()\" in Module::Build::API method.\n", "subsections": [] }, "PREREQUISITES": { "content": "", "subsections": [ { "name": "Types of prerequisites", "content": "To specify what versions of other modules are used by this distribution, several types of\nprerequisites can be defined with the following parameters:\n\nconfigurerequires\nItems that must be installed *before* configuring this distribution (i.e. before running the\nBuild.PL script). This might be a specific minimum version of \"Module::Build\" or any other\nmodule the Build.PL needs in order to do its stuff. Clients like \"CPAN.pm\" or \"CPANPLUS\" will\nbe expected to pick \"configurerequires\" out of the META.yml file and install these items\nbefore running the \"Build.PL\".\n\nIf no configurerequires is specified, the current version of Module::Build is automatically\nadded to configurerequires.\n\nbuildrequires\nItems that are necessary for building and testing this distribution, but aren't necessary\nafter installation. This can help users who only want to install these items temporarily. It\nalso helps reduce the size of the CPAN dependency graph if everything isn't smooshed into\n\"requires\".\n\nrequires\nItems that are necessary for basic functioning.\n\nrecommends\nItems that are recommended for enhanced functionality, but there are ways to use this\ndistribution without having them installed. You might also think of this as \"can use\" or \"is\naware of\" or \"changes behavior in the presence of\".\n\ntestrequires\nItems that are necessary for testing.\n\nconflicts\nItems that can cause problems with this distribution when installed. This is pretty rare.\n" }, { "name": "Format of prerequisites", "content": "The prerequisites are given in a hash reference, where the keys are the module names and the\nvalues are version specifiers:\n\nrequires => {\nFoo::Module => '2.4',\nBar::Module => 0,\nKen::Module => '>= 1.2, != 1.5, < 2.0',\nperl => '5.6.0'\n},\n\nThe above four version specifiers have different effects. The value '2.4' means that at least\nversion 2.4 of \"Foo::Module\" must be installed. The value 0 means that any version of\n\"Bar::Module\" is acceptable, even if \"Bar::Module\" doesn't define a version. The more verbose\nvalue '>= 1.2, != 1.5, < 2.0' means that \"Ken::Module\"'s version must be at least 1.2, less than\n2.0, and not equal to 1.5. The list of criteria is separated by commas, and all criteria must be\nsatisfied.\n\nA special \"perl\" entry lets you specify the versions of the Perl interpreter that are supported\nby your module. The same version dependency-checking semantics are available, except that we\nalso understand perl's new double-dotted version numbers.\n\nXS Extensions\nModules which need to compile XS code should list \"ExtUtils::CBuilder\" as a \"buildrequires\"\nelement.\n" } ] }, "SAVING CONFIGURATION INFORMATION": { "content": "Module::Build provides a very convenient way to save configuration information that your\ninstalled modules (or your regression tests) can access. If your Build process calls the\n\"feature()\" or \"configdata()\" methods, then a \"Foo::Bar::ConfigData\" module will automatically\nbe created for you, where \"Foo::Bar\" is the \"modulename\" parameter as passed to \"new()\". This\nmodule provides access to the data saved by these methods, and a way to update the values. There\nis also a utility script called \"configdata\" distributed with Module::Build that provides a\ncommand line interface to this same functionality. See also the generated \"Foo::Bar::ConfigData\"\ndocumentation, and the \"configdata\" script's documentation, for more information.\n", "subsections": [] }, "STARTING MODULE DEVELOPMENT": { "content": "When starting development on a new module, it's rarely worth your time to create a tree of all\nthe files by hand. Some automatic module-creators are available: the oldest is \"h2xs\", which has\nshipped with perl itself for a long time. Its name reflects the fact that modules were\noriginally conceived of as a way to wrap up a C library (thus the \"h\" part) into perl extensions\n(thus the \"xs\" part).\n\nThese days, \"h2xs\" has largely been superseded by modules like \"ExtUtils::ModuleMaker\", and\n\"Module::Starter\". They have varying degrees of support for \"Module::Build\".\n", "subsections": [] }, "AUTOMATION": { "content": "One advantage of Module::Build is that since it's implemented as Perl methods, you can invoke\nthese methods directly if you want to install a module non-interactively. For instance, the\nfollowing Perl script will invoke the entire build/install procedure:\n\nmy $build = Module::Build->new(modulename => 'MyModule');\n$build->dispatch('build');\n$build->dispatch('test');\n$build->dispatch('install');\n\nIf any of these steps encounters an error, it will throw a fatal exception.\n\nYou can also pass arguments as part of the build process:\n\nmy $build = Module::Build->new(modulename => 'MyModule');\n$build->dispatch('build');\n$build->dispatch('test', verbose => 1);\n$build->dispatch('install', sitelib => '/my/secret/place/');\n\nBuilding and installing modules in this way skips creating the \"Build\" script.\n", "subsections": [] }, "MIGRATION": { "content": "Note that if you want to provide both a Makefile.PL and a Build.PL for your distribution, you\nprobably want to add the following to \"WriteMakefile\" in your Makefile.PL so that \"MakeMaker\"\ndoesn't try to run your Build.PL as a normal .PL file:\n\nPLFILES => {},\n\nYou may also be interested in looking at the \"Module::Build::Compat\" module, which can\nautomatically create various kinds of Makefile.PL compatibility layers.\n", "subsections": [] }, "AUTHOR": { "content": "Ken Williams \n\nDevelopment questions, bug reports, and patches should be sent to the Module-Build mailing list\nat .\n\nBug reports are also welcome at .\n\nThe latest development version is available from the Git repository at\n\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "perl", "content": "ExtUtils::MakeMaker(3), YAML(3)\n\nMETA.yml Specification: CPAN::Meta::Spec\n\n\n\n\n" } ] } } } }