/ 
CPAN-Static-0.002
River stage zero No dependents
/ CPAN::Static::Spec

NAME

CPAN::Static::Spec - Static install specification for CPAN distributions

VERSION

version 0.002

DESCRIPTION

*THIS DOCUMENT IS STILL A DRAFT*

This document describes a way for CPAN clients to install distributions without having to run a Makefile.PL or a Build.PL

PURPOSE

Historically, Perl distributions have always been able to build, test and install without any help of a CPAN client. perl Makefile.PL, make, make test, make install. This is a powerful feature, but it is overly complicated for many modules that have no non-standard needs.

CONTEXT

This specification relies on a number of other specifications. This includes in particular on the CPAN Meta spec, Build.PL Spec. The terms must, should, may and their negations have the usual IETF semantics RFC2119.

AUTHOR TOOL REQUIREMENTS

As static install intends to be an optimization, a valid Build.PL (per CPAN::API::BuildPL) or Makefile.PL must be present as a fallback.

META REQUIREMENTS

The author tool will add an x_static_install entry to the META. This entry will contain the version of the CPAN::Static::Spec that it expects the install tool to perform. The install tool must not perform a static install if it doesn't support the specified version.

FLOW OF EXECUTION

Building a distribution has four stages. They must be performed in order, and any error in one stage must abort the entire process, unless the user explicitly asks otherwise; the CPAN client may try to fall back on dynamic install on error. Actions must be done during build-time unless noted otherwise. The order of different actions within the same phase is unspecified. Arguments that would be passed to a stage for a dynamic install must be handled by the CPAN client exactly as in CPAN::API::BuildPL.

Configuration

The cpan client b<must> be able to configure a distribution. A valid MYMETA.json (with the dynamic_config key set to 0) must be generated, it may be copied verbatim to from META.json. The same may be done for MYMETA.yml/META.yml. This action must be done during configure-time.

Building

Various actions must or may be performed during the building stage.

  • module files

    The cpan client must be able to build and install modules. It must look recursively in lib/ for all *.pm and *.pod files and copy these to the appropriate location for lib files during install. If applicable, these modules should be autosplit and their permissions should be set appropriately for that platform.

  • script files

    The cpan client must be able to build and install scripts. It must look non-recursively in script/ for all files and install these to the appropriate location for script files during intstall. Their permissions must be set appropriately for that platform for an executable and if necessary on that platform helpers must be added.

  • documentation

    The cpan client must be able to build and install platform appropriate documentation for modules and scripts from POD unless configured otherwise. The modules and scripts must be found as described for module files and script files. If generating man pages, they must be put in appropriate location for libdoc and bindoc. If generating HTML documentation, they must be put in the location for libhtml and binhtml.

  • sharedir

    Thee cpan client must be able to build and install a distribution sharedir. The cpan client must install the content of share/ to auto/share/dist/$distribution_name/ subdirectory of the appropriate directory for lib files, where $distribution_name is defined by the name field in the META file.

test

The cpan client must be able to test modules. Unless the user has explicitly asked this step to be skipped, it must look recursively in t/ for all *.t files and run them through a TAP harness. A failure of any of the tests must be considered a fatal error.

install

The cpan client must be able to install the contents of blib/. The files and the generated metadata must be installed as described in CPAN::API::BuildPL 1.0.

AUTHOR

Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.