Blame README

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