Blame README

Packit Service d63224
NAME
Packit Service d63224
    inc::latest - use modules bundled in inc/ if they are newer than
Packit Service d63224
    installed ones
Packit Service d63224
Packit Service d63224
VERSION
Packit Service d63224
    version 0.500
Packit Service d63224
Packit Service d63224
SYNOPSIS
Packit Service d63224
      # in Makefile.PL or Build.PL
Packit Service d63224
      use inc::latest 'Some::Configure::Prereq';
Packit Service d63224
Packit Service d63224
DESCRIPTION
Packit Service d63224
    WARNING -- THIS IS AN EXPERIMENTAL MODULE. It was originally bundled (as
Packit Service d63224
    an experiment) with Module::Build and has been split out for more
Packit Service d63224
    general use.
Packit Service d63224
Packit Service d63224
    The "inc::latest" module helps bootstrap configure-time dependencies for
Packit Service d63224
    CPAN distributions. These dependencies get bundled into the "inc"
Packit Service d63224
    directory within a distribution and are used by Makefile.PL or Build.PL.
Packit Service d63224
Packit Service d63224
    Arguments to "inc::latest" are module names that are checked against
Packit Service d63224
    both the current @INC array and against specially-named directories in
Packit Service d63224
    "inc". If the bundled version is newer than the installed one (or the
Packit Service d63224
    module isn't installed, then, the bundled directory is added to the
Packit Service d63224
    start of @INC and the module is loaded from there.
Packit Service d63224
Packit Service d63224
    There are actually two variations of "inc::latest" -- one for authors
Packit Service d63224
    and one for the "inc" directory. For distribution authors, the
Packit Service d63224
    "inc::latest" installed in the system will record modules loaded via
Packit Service d63224
    "inc::latest" and can be used to create the bundled files in "inc",
Packit Service d63224
    including writing the second variation as "inc/latest.pm".
Packit Service d63224
Packit Service d63224
    This second "inc::latest" is the one that is loaded in a distribution
Packit Service d63224
    being installed (e.g. from Makefile.PL or Build.PL). This bundled
Packit Service d63224
    "inc::latest" is the one that determines which module to load.
Packit Service d63224
Packit Service d63224
  Special notes on bundling
Packit Service d63224
    The "inc::latest" module creates bundled directories based on the
Packit Service d63224
    packlist file of an installed distribution. Even though "inc::latest"
Packit Service d63224
    takes module name arguments, it is better to think of it as bundling and
Packit Service d63224
    making available entire *distributions*. When a module is loaded through
Packit Service d63224
    "inc::latest", it looks in all bundled distributions in "inc/" for a
Packit Service d63224
    newer module than can be found in the existing @INC array.
Packit Service d63224
Packit Service d63224
    Thus, the module-name provided should usually be the "top-level" module
Packit Service d63224
    name of a distribution, though this is not strictly required.
Packit Service d63224
    "inc::latest" has a number of heuristics to discover module names,
Packit Service d63224
    allowing users to do things like this:
Packit Service d63224
Packit Service d63224
      use inc::latest 'Devel::AssertOS::Unix';
Packit Service d63224
Packit Service d63224
    even though Devel::AssertOS::Unix is contained within the Devel-CheckOS
Packit Service d63224
    distribution.
Packit Service d63224
Packit Service d63224
    At the current time, packlists are required. Thus, bundling dual-core
Packit Service d63224
    modules may require a 'forced install' over versions in the latest
Packit Service d63224
    version of perl in order to create the necessary packlist for bundling.
Packit Service d63224
Packit Service d63224
  Managing dependency chains
Packit Service d63224
    Before bundling a distribution you must ensure that all prerequisites
Packit Service d63224
    are also bundled and load in the correct order.
Packit Service d63224
Packit Service d63224
    For example, if you need "Wibble", but "Wibble" depends on "Wobble", and
Packit Service d63224
    you have bundled "Module::Build", your Build.PL might look like this:
Packit Service d63224
Packit Service d63224
      use inc::latest 'Wobble';
Packit Service d63224
      use inc::latest 'Wibble';
Packit Service d63224
      use inc::latest 'Module::Build';
Packit Service d63224
Packit Service d63224
      Module::Build->new(
Packit Service d63224
        module_name => 'Foo::Bar',
Packit Service d63224
        license => 'perl',
Packit Service d63224
      )->create_build_script;
Packit Service d63224
Packit Service d63224
    Authors are strongly suggested to limit the bundling of additional
Packit Service d63224
    dependencies if at all possible and to carefully test their distribution
Packit Service d63224
    tarballs before uploading to CPAN.
Packit Service d63224
Packit Service d63224
USAGE
Packit Service d63224
  As bundled in inc/
Packit Service d63224
    Using "Author-mode", a special stub module will be created in your
Packit Service d63224
    distribute directory as inc/latest.pm. In your Makefile.PL or Build.PL,
Packit Service d63224
    you can then load "inc::latest" to load bundled modules.
Packit Service d63224
Packit Service d63224
    When calling "use", the bundled "inc::latest" takes a single module name
Packit Service d63224
    and optional arguments to pass to that module's own import method.
Packit Service d63224
Packit Service d63224
      use inc::latest 'Foo::Bar' qw/foo bar baz/;
Packit Service d63224
Packit Service d63224
    The implementation is private. Only the "import" method is public.
Packit Service d63224
Packit Service d63224
  Author-mode
Packit Service d63224
    When you have inc::latest installed from CPAN, then you are in
Packit Service d63224
    author-mode if any of the Author-mode methods are available. For
Packit Service d63224
    example:
Packit Service d63224
Packit Service d63224
      if ( inc::latest->can('write') ) {
Packit Service d63224
        inc::latest->write('inc');
Packit Service d63224
      }
Packit Service d63224
Packit Service d63224
    Using author-mode, you can create the stub inc/latest.pm and bundle
Packit Service d63224
    modules into inc.
Packit Service d63224
Packit Service d63224
    loaded_modules()
Packit Service d63224
          my @list = inc::latest->loaded_modules;
Packit Service d63224
Packit Service d63224
        This takes no arguments and always returns a list of module names
Packit Service d63224
        requested for loading via "use inc::latest 'MODULE'", regardless of
Packit Service d63224
        whether the load was successful or not.
Packit Service d63224
Packit Service d63224
    write()
Packit Service d63224
          inc::latest->write( 'inc' );
Packit Service d63224
Packit Service d63224
        This writes the bundled version of inc::latest to the directory name
Packit Service d63224
        given as an argument. It almost all cases, it should be '"inc"'.
Packit Service d63224
Packit Service d63224
    bundle_module()
Packit Service d63224
          for my $mod ( inc::latest->loaded_modules ) {
Packit Service d63224
            inc::latest->bundle_module($mod, $dir);
Packit Service d63224
          }
Packit Service d63224
Packit Service d63224
        If $mod corresponds to a packlist, then this function creates a
Packit Service d63224
        specially-named directory in $dir and copies all .pm files from the
Packit Service d63224
        modlist to the new directory (which almost always should just be
Packit Service d63224
        'inc'). For example, if Foo::Bar is the name of the module, and $dir
Packit Service d63224
        is 'inc', then the directory would be 'inc/inc_Foo-Bar' and contain
Packit Service d63224
        files like this:
Packit Service d63224
Packit Service d63224
          inc/inc_Foo-Bar/Foo/Bar.pm
Packit Service d63224
Packit Service d63224
        Currently, $mod must have a packlist. If this is not the case (e.g.
Packit Service d63224
        for a dual-core module), then the bundling will fail. You may be
Packit Service d63224
        able to create a packlist by forced installing the module on top of
Packit Service d63224
        the version that came with core Perl.
Packit Service d63224
Packit Service d63224
SUPPORT
Packit Service d63224
  Bugs / Feature Requests
Packit Service d63224
    Please report any bugs or feature requests through the issue tracker at
Packit Service d63224
    <https://github.com/dagolden/inc-latest/issues>. You will be notified
Packit Service d63224
    automatically of any progress on your issue.
Packit Service d63224
Packit Service d63224
  Source Code
Packit Service d63224
    This is open source software. The code repository is available for
Packit Service d63224
    public review and contribution under the terms of the license.
Packit Service d63224
Packit Service d63224
    <https://github.com/dagolden/inc-latest>
Packit Service d63224
Packit Service d63224
      git clone https://github.com/dagolden/inc-latest.git
Packit Service d63224
Packit Service d63224
AUTHORS
Packit Service d63224
    *   David Golden <dagolden@cpan.org>
Packit Service d63224
Packit Service d63224
    *   Eric Wilhelm <ewilhelm@cpan.org>
Packit Service d63224
Packit Service d63224
COPYRIGHT AND LICENSE
Packit Service d63224
    This software is Copyright (c) 2009 by David Golden.
Packit Service d63224
Packit Service d63224
    This is free software, licensed under:
Packit Service d63224
Packit Service d63224
      The Apache License, Version 2.0, January 2004
Packit Service d63224