{
    "content": [
        {
            "type": "text",
            "text": "# Module::Build::Bundling (perldoc)\n\n## NAME\n\nModule::Build::Bundling - How to bundle Module::Build with a distribution\n\n## SYNOPSIS\n\n# Build.PL\nuse inc::latest 'Module::Build';\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\n)->createbuildscript;\n\n## DESCRIPTION\n\nWARNING -- THIS IS AN EXPERIMENTAL FEATURE\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **BUNDLING OTHER CONFIGURATION DEPENDENCIES**\n- **AUTHOR**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Module::Build::Bundling",
        "section": "",
        "mode": "perldoc",
        "summary": "Module::Build::Bundling - How to bundle Module::Build with a distribution",
        "synopsis": "# Build.PL\nuse inc::latest 'Module::Build';\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\n)->createbuildscript;",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 42,
                "subsections": []
            },
            {
                "name": "BUNDLING OTHER CONFIGURATION DEPENDENCIES",
                "lines": 56,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 1,
                "subsections": [
                    {
                        "name": "perl",
                        "lines": 1
                    }
                ]
            }
        ],
        "sections": {
            "NAME": {
                "content": "Module::Build::Bundling - How to bundle Module::Build with a distribution\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "# Build.PL\nuse inc::latest 'Module::Build';\n\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\n)->createbuildscript;\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "WARNING -- THIS IS AN EXPERIMENTAL FEATURE\n\nIn order to install a distribution using Module::Build, users must have Module::Build available\non their systems. There are two ways to do this. The first way is to include Module::Build in\nthe \"configurerequires\" metadata field. This field is supported by recent versions CPAN and\nCPANPLUS and is a standard feature in the Perl core as of Perl 5.10.1. Module::Build now adds\nitself to \"configurerequires\" by default.\n\nThe second way supports older Perls that have not upgraded CPAN or CPANPLUS and involves\nbundling an entire copy of Module::Build into the distribution's \"inc/\" directory. This is the\nsame approach used by Module::Install, a modern wrapper around ExtUtils::MakeMaker for\nMakefile.PL based distributions.\n\nThe \"trick\" to making this work for Module::Build is making sure the highest version\nModule::Build is used, whether this is in \"inc/\" or already installed on the user's system. This\nensures that all necessary features are available as well as any new bug fixes. This is done\nusing the experimental inc::latest module, available on CPAN.\n\nA \"normal\" Build.PL looks like this (with only the minimum required fields):\n\nuse Module::Build;\n\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense     => 'perl',\n)->createbuildscript;\n\nA \"bundling\" Build.PL replaces the initial \"use\" line with a nearly transparent replacement:\n\nuse inc::latest 'Module::Build';\n\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\n)->createbuildscript;\n\nFor *authors*, when \"Build dist\" is run, Module::Build will be automatically bundled into \"inc\"\naccording to the rules for inc::latest.\n\nFor *users*, inc::latest will load the latest Module::Build, whether installed or bundled in\n\"inc/\".\n",
                "subsections": []
            },
            "BUNDLING OTHER CONFIGURATION DEPENDENCIES": {
                "content": "The same approach works for other configuration dependencies -- modules that *must* be available\nfor Build.PL to run. All other dependencies can be specified as usual in the Build.PL and CPAN\nor CPANPLUS will install them after Build.PL finishes.\n\nFor example, to bundle the Devel::AssertOS::Unix module (which ensures a \"Unix-like\" operating\nsystem), one could do this:\n\nuse inc::latest 'Devel::AssertOS::Unix';\nuse inc::latest 'Module::Build';\n\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\n)->createbuildscript;\n\nThe \"inc::latest\" module creates bundled directories based on the packlist file of an installed\ndistribution. Even though \"inc::latest\" takes module name arguments, it is better to think of it\nas bundling and making available entire *distributions*. When a module is loaded through\n\"inc::latest\", it looks in all bundled distributions in \"inc/\" for a newer module than can be\nfound in the existing @INC array.\n\nThus, the module-name provided should usually be the \"top-level\" module name of a distribution,\nthough this is not strictly required. For example, Module::Build has a number of heuristics to\nmap module names to packlists, allowing users to do things like this:\n\nuse inc::latest 'Devel::AssertOS::Unix';\n\neven though Devel::AssertOS::Unix is contained within the Devel-CheckOS distribution.\n\nAt the current time, packlists are required. Thus, bundling dual-core modules, *including\nModule::Build*, may require a 'forced install' over versions in the latest version of perl in\norder to create the necessary packlist for bundling. This limitation will hopefully be addressed\nin a future version of Module::Build.\n\nWARNING -- How to Manage Dependency Chains\nBefore bundling a distribution you must ensure that all prerequisites are also bundled and load\nin the correct order. For Module::Build itself, this should not be necessary, but it is\nnecessary for any other distribution. (A future release of Module::Build will hopefully address\nthis deficiency.)\n\nFor example, if you need \"Wibble\", but \"Wibble\" depends on \"Wobble\", your Build.PL might look\nlike this:\n\nuse inc::latest 'Wobble';\nuse inc::latest 'Wibble';\nuse inc::latest 'Module::Build';\n\nModule::Build->new(\nmodulename => 'Foo::Bar',\nlicense => 'perl',\n)->createbuildscript;\n\nAuthors are strongly suggested to limit the bundling of additional dependencies if at all\npossible and to carefully test their distribution tarballs on older versions of Perl before\nuploading to CPAN.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "David Golden <dagolden@cpan.org>\n\nDevelopment questions, bug reports, and patches should be sent to the Module-Build mailing list\nat <module-build@perl.org>.\n\nBug reports are also welcome at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "",
                "subsections": [
                    {
                        "name": "perl",
                        "content": ""
                    }
                ]
            }
        }
    }
}