{
    "content": [
        {
            "type": "text",
            "text": "# Module::Build::Cookbook (perldoc)\n\n## NAME\n\nModule::Build::Cookbook - Examples of Module::Build Usage\n\n## DESCRIPTION\n\n\"Module::Build\" isn't conceptually very complicated, but examples are always helpful. The\nfollowing recipes should help developers and/or installers put together the pieces from the\nother parts of the documentation.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **BASIC RECIPES** (7 subsections)\n- **ADVANCED RECIPES** (4 subsections)\n- **EXAMPLES ON CPAN** (3 subsections)\n- **AUTHOR**\n- **COPYRIGHT**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Module::Build::Cookbook",
        "section": "",
        "mode": "perldoc",
        "summary": "Module::Build::Cookbook - Examples of Module::Build Usage",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "BASIC RECIPES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Installing modules that use Module::Build",
                        "lines": 35
                    },
                    {
                        "name": "Modifying Config.pm values",
                        "lines": 27
                    },
                    {
                        "name": "Installing modules using the programmatic interface",
                        "lines": 20
                    },
                    {
                        "name": "Installing to a temporary directory",
                        "lines": 9
                    },
                    {
                        "name": "Installing to a non-standard directory",
                        "lines": 8
                    },
                    {
                        "name": "Installing in the same location as ExtUtils::MakeMaker",
                        "lines": 46
                    },
                    {
                        "name": "Running a single test file",
                        "lines": 15
                    }
                ]
            },
            {
                "name": "ADVANCED RECIPES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Making a CPAN.pm-compatible distribution",
                        "lines": 12
                    },
                    {
                        "name": "Changing the order of the build process",
                        "lines": 15
                    },
                    {
                        "name": "Adding new file types to the build process",
                        "lines": 57
                    },
                    {
                        "name": "Adding new elements to the install process",
                        "lines": 30
                    }
                ]
            },
            {
                "name": "EXAMPLES ON CPAN",
                "lines": 18,
                "subsections": [
                    {
                        "name": "Modifying an action",
                        "lines": 28
                    },
                    {
                        "name": "Adding an action",
                        "lines": 20
                    },
                    {
                        "name": "Bundling Module::Build",
                        "lines": 48
                    }
                ]
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 1,
                "subsections": [
                    {
                        "name": "perl",
                        "lines": 1
                    }
                ]
            }
        ],
        "sections": {
            "NAME": {
                "content": "Module::Build::Cookbook - Examples of Module::Build Usage\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "\"Module::Build\" isn't conceptually very complicated, but examples are always helpful. The\nfollowing recipes should help developers and/or installers put together the pieces from the\nother parts of the documentation.\n",
                "subsections": []
            },
            "BASIC RECIPES": {
                "content": "",
                "subsections": [
                    {
                        "name": "Installing modules that use Module::Build",
                        "content": "In most cases, you can just issue the following commands:\n\nperl Build.PL\n./Build\n./Build test\n./Build install\n\nThere's nothing complicated here - first you're running a script called Build.PL, then you're\nrunning a (newly-generated) script called Build and passing it various arguments.\n\nThe exact commands may vary a bit depending on how you invoke perl scripts on your system. For\ninstance, if you have multiple versions of perl installed, you can install to one particular\nperl's library directories like so:\n\n/usr/bin/perl5.8.1 Build.PL\n./Build\n./Build test\n./Build install\n\nIf you're on Windows where the current directory is always searched first for scripts, you'll\nprobably do something like this:\n\nperl Build.PL\nBuild\nBuild test\nBuild install\n\nOn the old Mac OS (version 9 or lower) using MacPerl, you can double-click on the Build.PL\nscript to create the Build script, then double-click on the Build script to run its \"build\",\n\"test\", and \"install\" actions.\n\nThe Build script knows what perl was used to run Build.PL, so you don't need to re-invoke the\nBuild script with the complete perl path each time. If you invoke it with the *wrong* perl path,\nyou'll get a warning or a fatal error.\n"
                    },
                    {
                        "name": "Modifying Config.pm values",
                        "content": "\"Module::Build\" relies heavily on various values from perl's \"Config.pm\" to do its work. For\nexample, default installation paths are given by \"installsitelib\" and \"installvendorman3dir\" and\nfriends, C linker & compiler settings are given by \"ld\", \"lddlflags\", \"cc\", \"ccflags\", and so\non. *If you're pretty sure you know what you're doing*, you can tell \"Module::Build\" to pretend\nthere are different values in Config.pm than what's really there, by passing arguments for the\n\"--config\" parameter on the command line:\n\nperl Build.PL --config cc=gcc --config ld=gcc\n\nInside the \"Build.PL\" script the same thing can be accomplished by passing values for the\n\"config\" parameter to \"new()\":\n\nmy $build = Module::Build->new\n(\n...\nconfig => { cc => 'gcc', ld => 'gcc' },\n...\n);\n\nIn custom build code, the same thing can be accomplished by calling the \"config\" in\nModule::Build method:\n\n$build->config( cc => 'gcc' );     # Set\n$build->config( ld => 'gcc' );     # Set\n...\nmy $linker = $build->config('ld'); # Get\n"
                    },
                    {
                        "name": "Installing modules using the programmatic interface",
                        "content": "If you need to build, test, and/or install modules from within some other perl code (as opposed\nto having the user type installation commands at the shell), you can use the programmatic\ninterface. Create a Module::Build object (or an object of a custom Module::Build subclass) and\nthen invoke its \"dispatch()\" method to run various actions.\n\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\nlicense     => 'perl',\nrequires    => { 'Some::Module'   => '1.23' },\n);\n$build->dispatch('build');\n$build->dispatch('test', verbose => 1);\n$build->dispatch('install');\n\nThe first argument to \"dispatch()\" is the name of the action, and any following arguments are\nnamed parameters.\n\nThis is the interface we use to test Module::Build itself in the regression tests.\n"
                    },
                    {
                        "name": "Installing to a temporary directory",
                        "content": "To create packages for package managers like RedHat's \"rpm\" or Debian's \"deb\", you may need to\ninstall to a temporary directory first and then create the package from that temporary\ninstallation. To do this, specify the \"destdir\" parameter to the \"install\" action:\n\n./Build install --destdir /tmp/my-package-1.003\n\nThis essentially just prepends all the installation paths with the /tmp/my-package-1.003\ndirectory.\n"
                    },
                    {
                        "name": "Installing to a non-standard directory",
                        "content": "To install to a non-standard directory (for example, if you don't have permission to install in\nthe system-wide directories), you can use the \"installbase\" or \"prefix\" parameters:\n\n./Build install --installbase /foo/bar\n\nSee \"INSTALL PATHS\" in Module::Build for a much more complete discussion of how installation\npaths are determined.\n"
                    },
                    {
                        "name": "Installing in the same location as ExtUtils::MakeMaker",
                        "content": "With the introduction of \"--prefix\" in Module::Build 0.28 and \"INSTALLBASE\" in\n\"ExtUtils::MakeMaker\" 6.31 its easy to get them both to install to the same locations.\n\nFirst, ensure you have at least version 0.28 of Module::Build installed and 6.31 of\n\"ExtUtils::MakeMaker\". Prior versions have differing (and in some cases quite strange)\ninstallation behaviors.\n\nThe following installation flags are equivalent between \"ExtUtils::MakeMaker\" and\n\"Module::Build\".\n\nMakeMaker             Module::Build\nPREFIX=...            --prefix ...\nINSTALLBASE=...      --installbase ...\nDESTDIR=...           --destdir ...\nLIB=...               --installpath lib=...\nINSTALLDIRS=...       --installdirs ...\nINSTALLDIRS=perl      --installdirs core\nUNINST=...            --uninst ...\nINC=...               --extracompilerflags ...\nPOLLUTE=1             --extracompilerflags -DPERLPOLLUTE\n\nFor example, if you are currently installing \"MakeMaker\" modules with this command:\n\nperl Makefile.PL PREFIX=~\nmake test\nmake install UNINST=1\n\nYou can install into the same location with Module::Build using this:\n\nperl Build.PL --prefix ~\n./Build test\n./Build install --uninst 1\n\n\"prefix\" vs \"installbase\"\nThe behavior of \"prefix\" is complicated and depends on how your Perl is configured. The\nresulting installation locations will vary from machine to machine and even different\ninstallations of Perl on the same machine. Because of this, it's difficult to document where\n\"prefix\" will place your modules.\n\nIn contrast, \"installbase\" has predictable, easy to explain installation locations. Now that\n\"Module::Build\" and \"MakeMaker\" both have \"installbase\" there is little reason to use \"prefix\"\nother than to preserve your existing installation locations. If you are starting a fresh Perl\ninstallation we encourage you to use \"installbase\". If you have an existing installation\ninstalled via \"prefix\", consider moving it to an installation structure matching \"installbase\"\nand using that instead.\n"
                    },
                    {
                        "name": "Running a single test file",
                        "content": "\"Module::Build\" supports running a single test, which enables you to track down errors more\nquickly. Use the following format:\n\n./Build test --testfiles t/mytest.t\n\nIn addition, you may want to run the test in verbose mode to get more informative output:\n\n./Build test --testfiles t/mytest.t --verbose 1\n\nI run this so frequently that I define the following shell alias:\n\nalias t './Build test --verbose 1 --testfiles'\n\nSo then I can just execute \"t t/mytest.t\" to run a single test.\n"
                    }
                ]
            },
            "ADVANCED RECIPES": {
                "content": "",
                "subsections": [
                    {
                        "name": "Making a CPAN.pm-compatible distribution",
                        "content": "New versions of CPAN.pm understand how to use a Build.PL script, but old versions don't. If\nauthors want to help users who have old versions, some form of Makefile.PL should be supplied.\nThe easiest way to accomplish this is to use the \"createmakefilepl\" parameter to\n\"Module::Build->new()\" in the \"Build.PL\" script, which can create various flavors of Makefile.PL\nduring the \"dist\" action.\n\nAs a best practice, we recommend using the \"traditional\" style of Makefile.PL unless your\ndistribution has needs that can't be accomplished that way.\n\nThe \"Module::Build::Compat\" module, which is part of \"Module::Build\"'s distribution, is\nresponsible for creating these Makefile.PLs. Please see Module::Build::Compat for the details.\n"
                    },
                    {
                        "name": "Changing the order of the build process",
                        "content": "The \"buildelements\" property specifies the steps \"Module::Build\" will take when building a\ndistribution. To change the build order, change the order of the entries in that property:\n\n# Process pod files first\nmy @e = @{$build->buildelements};\nmy ($i) = grep {$e[$] eq 'pod'} 0..$#e;\nunshift @e, splice @e, $i, 1;\n\nCurrently, \"buildelements\" has the following default value:\n\n[qw( PL support pm xs pod script )]\n\nDo take care when altering this property, since there may be non-obvious (and non-documented!)\nordering dependencies in the \"Module::Build\" code.\n"
                    },
                    {
                        "name": "Adding new file types to the build process",
                        "content": "Sometimes you might have extra types of files that you want to install alongside the standard\ntypes like .pm and .pod files. For instance, you might have a Bar.dat file containing some data\nrelated to the \"Foo::Bar\" module and you'd like for it to end up as Foo/Bar.dat somewhere in\nperl's @INC path so \"Foo::Bar\" can access it easily at runtime. The following code from a sample\n\"Build.PL\" file demonstrates how to accomplish this:\n\nuse Module::Build;\nmy $build = Module::Build->new\n(\nmodulename => 'Foo::Bar',\n...other stuff here...\n);\n$build->addbuildelement('dat');\n$build->createbuildscript;\n\nThis will find all .dat files in the lib/ directory, copy them to the blib/lib/ directory during\nthe \"build\" action, and install them during the \"install\" action.\n\nIf your extra files aren't located in the \"lib/\" directory in your distribution, you can\nexplicitly say where they are, just as you'd do with .pm or .pod files:\n\nuse Module::Build;\nmy $build = new Module::Build\n(\nmodulename => 'Foo::Bar',\ndatfiles => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},\n...other stuff here...\n);\n$build->addbuildelement('dat');\n$build->createbuildscript;\n\nIf your extra files actually need to be created on the user's machine, or if they need some\nother kind of special processing, you'll probably want to subclass \"Module::Build\" and create a\nspecial method to process them, named \"process${kind}files()\":\n\nuse Module::Build;\nmy $class = Module::Build->subclass(code => <<'EOF');\nsub processdatfiles {\nmy $self = shift;\n... locate and process *.dat files,\n... and create something in blib/lib/\n}\nEOF\nmy $build = $class->new\n(\nmodulename => 'Foo::Bar',\n...other stuff here...\n);\n$build->addbuildelement('dat');\n$build->createbuildscript;\n\nIf your extra files don't go in lib/ but in some other place, see \"Adding new elements to the\ninstall process\" for how to actually get them installed.\n\nPlease note that these examples use some capabilities of Module::Build that first appeared in\nversion 0.26. Before that it could still be done, but the simple cases took a bit more work.\n"
                    },
                    {
                        "name": "Adding new elements to the install process",
                        "content": "By default, Module::Build creates seven subdirectories of the blib directory during the build\nprocess: lib, arch, bin, script, bindoc, libdoc, and html (some of these may be missing or empty\nif there's nothing to go in them). Anything copied to these directories during the build will\neventually be installed during the \"install\" action (see \"INSTALL PATHS\" in Module::Build.\n\nIf you need to create a new custom type of installable element, e.g. \"conf\", then you need to\ntell Module::Build where things in blib/conf/ should be installed. To do this, use the\n\"installpath\" parameter to the \"new()\" method:\n\nmy $build = Module::Build->new\n(\n...other stuff here...\ninstallpath => { conf => $installationpath }\n);\n\nOr you can call the \"installpath()\" method later:\n\n$build->installpath(conf => $installationpath);\n\nThe user may also specify the path on the command line:\n\nperl Build.PL --installpath conf=/foo/path/etc\n\nThe important part, though, is that *somehow* the install path needs to be set, or else nothing\nin the blib/conf/ directory will get installed, and a runtime error during the \"install\" action\nwill result.\n\nSee also \"Adding new file types to the build process\" for how to create the stuff in blib/conf/\nin the first place.\n"
                    }
                ]
            },
            "EXAMPLES ON CPAN": {
                "content": "Several distributions on CPAN are making good use of various features of Module::Build. They can\nserve as real-world examples for others.\n\nSVN-Notify-Mirror\n<http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/>\n\nJohn Peacock, author of the \"SVN-Notify-Mirror\" distribution, says:\n\n1. Using \"autofeatures\", I check to see whether two optional modules are available -\nSVN::Notify::Config and Net::SSH;\n2. If the S::N::Config module is loaded, I automatically generate test files for it during Build\n(using the \"PLfiles\" property).\n3. If the \"sshfeature\" is available, I ask if the user wishes to perform the ssh tests (since\nit requires a little preliminary setup);\n4. Only if the user has \"sshfeature\" and answers yes to the testing, do I generate a test file.\nI'm sure I could not have handled this complexity with EU::MM, but it was very easy to do\nwith M::B.\n",
                "subsections": [
                    {
                        "name": "Modifying an action",
                        "content": "Sometimes you might need an to have an action, say \"./Build install\", do something unusual. For\ninstance, you might need to change the ownership of a file or do something else peculiar to your\napplication.\n\nYou can subclass \"Module::Build\" on the fly using the \"subclass()\" method and override the\nmethods that perform the actions. You may need to read through \"Module::Build::Authoring\" and\n\"Module::Build::API\" to find the methods you want to override. All \"action\" methods are\nimplemented by a method called \"ACTION\" followed by the action's name, so here's an example of\nhow it would work for the \"install\" action:\n\n# Build.PL\nuse Module::Build;\nmy $class = Module::Build->subclass(\nclass => \"Module::Build::Custom\",\ncode => <<'SUBCLASS' );\n\nsub ACTIONinstall {\nmy $self = shift;\n# YOUR CODE HERE\n$self->SUPER::ACTIONinstall;\n}\nSUBCLASS\n\n$class->new(\nmodulename => 'Your::Module',\n# rest of the usual Module::Build parameters\n)->createbuildscript;\n"
                    },
                    {
                        "name": "Adding an action",
                        "content": "You can add a new \"./Build\" action simply by writing the method for it in your subclass. Use\n\"dependson\" to declare that another action must have been run before your action.\n\nFor example, let's say you wanted to be able to write \"./Build commit\" to test your code and\ncommit it to Subversion.\n\n# Build.PL\nuse Module::Build;\nmy $class = Module::Build->subclass(\nclass => \"Module::Build::Custom\",\ncode => <<'SUBCLASS' );\n\nsub ACTIONcommit {\nmy $self = shift;\n\n$self->dependson(\"test\");\n$self->dosystem(qw(svn commit));\n}\nSUBCLASS\n"
                    },
                    {
                        "name": "Bundling Module::Build",
                        "content": "Note: This section probably needs an update as the technology improves (see contrib/bundle.pl in\nthe distribution).\n\nSuppose you want to use some new-ish features of Module::Build, e.g. newer than the version of\nModule::Build your users are likely to already have installed on their systems. The first thing\nyou should do is set \"configurerequires\" to your minimum version of Module::Build. See\nModule::Build::Authoring.\n\nBut not every build system honors \"configurerequires\" yet. Here's how you can ship a copy of\nModule::Build, but still use a newer installed version to take advantage of any bug fixes and\nupgrades.\n\nFirst, install Module::Build into Your-Project/inc/Module-Build. CPAN will not index anything in\nthe inc directory so this copy will not show up in CPAN searches.\n\ncd Module-Build\nperl Build.PL --installbase /path/to/Your-Project/inc/Module-Build\n./Build test\n./Build install\n\nYou should now have all the Module::Build .pm files in Your-Project/inc/Module-Build/lib/perl5.\n\nNext, add this to the top of your Build.PL.\n\nmy $BundledMB = 0.30;  # or whatever version it was.\n\n# Find out what version of Module::Build is installed or fail quietly.\n# This should be cross-platform.\nmy $InstalledMB =\n`$^X -e \"eval q{require Module::Build; print Module::Build->VERSION} or exit 1\"`;\n\n# some operating systems put a newline at the end of every print.\nchomp $InstalledMB;\n\n$InstalledMB = 0 if $?;\n\n# Use our bundled copy of Module::Build if it's newer than the installed.\nunshift @INC, \"inc/Module-Build/lib/perl5\" if $BundledMB > $InstalledMB;\n\nrequire Module::Build;\n\nAnd write the rest of your Build.PL normally. Module::Build will remember your change to @INC\nand use it when you run ./Build.\n\nIn the future, we hope to provide a more automated solution for this scenario; see\n\"inc/latest.pm\" in the Module::Build distribution for one indication of the direction we're\nmoving.\n"
                    }
                ]
            },
            "AUTHOR": {
                "content": "Ken Williams <kwilliams@cpan.org>\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright (c) 2001-2008 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": ""
                    }
                ]
            }
        }
    }
}