This page was generated by Text::SmartLinks v0.01 at 2014-04-23 13:01:07 GMT.
(syn 276721d)
  [ Index of Synopses ]

TITLE

Synopsis 22: Distributions, Recommendations, Delivery and Installation

AUTHORS

    Elizabeth Mattijsen <liz@dijkmat.nl>

VERSION

    Created: 15 March 2014
    Last Modified: 15 March 2014
    Version: 1

Terminology

Because many of the concepts used in this document may be overloaded by other concepts in the mind of the reader, it seems like a good idea to define some terminology first. Please note that these definitions only apply within the context of Perl 6.

compilation unit

A piece of code that can be compiled as a unit. It can either exist in a file (and be compiled using use or require), or be presented as a stream of characters for compilation with EVAL. An example of a compilation unit in a file:

  lib/JSON/Fast.pm6

distribution

A distribution is an archive of some form that can be used to install zero or more compilation units (each stored in a separate file), with any possibly associated files needed for execution. For example:

  lib/JSON/Fast.pm6
  lib/JSON/PurePerl.pm6

It has a name for identification, which may or may not coincide with the compilation units in the distribution. An example of a distribution name:

  JSON-Fast

It also has a version, to distinguish it from other distributions with the same name. For instance:

  1.23

Which, together, are used to create the filename of the distribution, for instance:

  JSON-Fast.1.23.tar.gz

Please note that by changing the :: from the module specification to a - for the filename of the archive, we are effectively disallowing an owner to upload a distribution for "JSON-Fast" and "JSON::Fast" at the same time. This seems unlikely to become a problem.

A Perl 6 distribution must contain a configuration file named META6.json, containing JSON-encoded information about the contents of the distribution.

owner

The owner of a distribution is responsible for the development of a distribution. This can either be a single person, or a (semi-)official organisation. The owner of a distribution has a (mnemonic) name, e.g.:

  JRANDOM

Please note that the owner is not necessarily the developer of a distribution, although if the owner is a single individual, this is pretty likely.

content storage

A service to which an owner can upload a distribution to and other people can download specific distributions from. This is most likely some online web-service, but it does not need to be. It has a logical name that is essentially a URL. An example would be:

  cpan

The (mnemonic) name of the owner usually coincides with the userid or login name used to upload distributions, but does not need to be.

auth

The auth of a distribution, is the combination of the content storage name with the name of the owner, separated by a colon. For example:

  cpan:JRANDOM

Please note that this is not an authority, merely an indication of the location where the distribution for that owner was obtained. Typically the auth of a distribution is used to try to load compilation units of already installed distributions, such as in:

  use JSON::Fast:auth<cpan:JRANDOM>;

identity

The identity of a distribution, is the combination of name of the content storage, the name of the owner, name and version of a distribution, separated by colons. For example:

 cpan:JRANDOM:JSON-Fast:1.23

There should really be only one unique distribution for a given identity in the world.

The content storage should accept an identity and either directly return the archive for that distribution, or return a URL from which that distribution can be downloaded.

recommendation manager

A service that will translate a request for a compilation unit (with optional owner and/or version and/or content storage specification, like a use statement) into a list of zero or more identities of distributions that match the request.

The recommendation manager is only used during the installation process of the distribution for a wanted compilation unit.

A recommendation manager can be run by a community (like the current Perl 6 ecosystem or the packages list for Perl 5 on CPAN), or by company (for use inside the company itself), or by any reviewing / grading service (for use by anybody wanting to use that service), or by any other person willing to put in the effort.

A request for:

  JSON::PurePerl

would yield the identity:

  cpan:JRANDOM:JSON-Fast:1.23

because the compilation unit JSON::PurePerl is part of the JSON::Fast distribution.

However, a request for:

  JSON::Fast:auth<github:JRANDOM>

would not find anything, because it has the wrong content storage specification ("github" instead of "cpan").

Please note that a recommendation manager does not need to be bound to a single content storage. In fact, a recommendation manager would be best if being able to supply identities from the best of all worlds. And potentially be able to recommend identities responding to more natural language queries, but that is probably outside the scope of this specification.

A bundle of distributions is basically just a collection of identities that listen to a name (such as Rakudo *). A recommendation manager may provide bundles as part of its service. And packagers may use this information as the source for bundling distributions in their specific packaging system.

Distribution

A Perl 6 distribution consists of an archive of some form (presumably a .tar.gz, .tar.bz2 or .zip file) which is expected to at least contain a file called "META6.json". The existence of this file indicates that this distribution is a Perl 6 distribution. This is important for those archive networks that also serve as a content-distribution system for other types of distributions (such as PAUSE / CPAN), so that they can adapt the processing of the contents, or decide to ignore any processing at all (such as CPAN-testers not being able to test Perl 6 distributions (yet)).

META6.json

The META6.json file is a JSON-file that must at least contain a perl, name, version and description section.

perl

Mandatory. The minimal perl version for which this distribution can be installed. Specified as a version string. So:

  "perl" : "v6.0.1"

would not allow installation on Perl version 6.0.0.

name

Mandatory. The name identifying this distribution. This is usually the name of the main module that this distribution provides. An example of this would be:

  "name" : "JSON::Fast"

version

Mandatory. The version literal for this distribution. An example of this would be:

  "version" : "v1.23"

description

Mandatory. A one line description of this distribution. So, for instance:

  "description" : "Providing fast JSON encoding/decoding"

authors

Optional. A list of (mnemonic) names of people who work / have worked on this distribution. For informational purposes only. An example:

  "authors" : [
    "Janet Random",
    "Sam Helpedwithit"
  ]

Please note that for identification purposes, only the owner (who uploaded the distribution to the content storage) should be used.

provides

Optional. A list of module - local filename pairs that this distribution makes available to be used. For example:

  "provides" : {
    "JSON::Fast"     : "lib/JSON/Fast.pm6"
    "JSON::PurePerl" : "lib/JSON/PurePerl.pm6"
  }

Please note that the filenames specified only indicate the names of the files in the distribution. The installer may need to mangle filenames to be able support file systems that do not support the file names given (e.g. when they contain unicode characters where the file system does not support them). This also implies that any installer needs to keep a local database that is able to convert from the module names given, to the actual associated file).

depends

Optional. A list of run-time dependencies, specified as use strings. To indicate alternatives, it is possible to specify a list of use strings, instead of just a single use string. So:

  "depends" : [
    "Sereal:auth<cpan:*>:ver(1..*)",
    [ "Archive::Compress", "Archive::Zlib" ]
  ]

would indicate a dependency on Sereal, and either Archive::Compress or Archive::Zlib.

An installer has the option to automatically install any dependencies, if the user has so indicated. Dependencies and alternatives should be tried in the order they are specified. In the case of alternatives, the first one for which the recommendation manager returns an identity should be installed. Failure of installation of an alternative may allow automatic attempts on other alternatives.

Please note that the use strings of compilation units are specified. It is the responsibility of the recommendation manager to turn these into identities of distributions that can be downloaded.

emulates

Optional. A hash in which the key is the compunit (provided by the distribution) to be aliased, and the value is the use string that should match to get that compilation unit. An example of this would be:

  "emulates" : {
    "JSON::Fast" : "JSON::XS:auth<cpan:MLEHMANN>"
  }

If then later, a program would say:

  use JSON::XS;

it would in fact load the JSON::Fast compunit, but make it appear as a JSON::XS compunit, but only if there was no "real" JSON::XS compunit installed that would match the use specification. In other words: if the real thing is available, then it will be used. If it is not, it will fall back to the indicated compilation unit. And it will look like you are using the thing you asked for.

Conversely, if one would do a:

  use JSON::Fast;

then later doing a:

  use JSON::XS:auth<cpan:MLEHMANN>;

in the same scope would become a no-op, just as if the compunit had already been loaded.

Please note that it is responsibility of the emulating compunit to actually provide a compatible interface with emulated compunit.

supersedes

Optional. Has the same meaning as "emulates" for the "CompUnitRepo". But has additional meaning for external packagers: it indicates a potential superseding of the indicated compilation unit from the packagers point of view. See "superseded_by".

superseded_by

Optional. Has the reverse meaning of "emulates" for the "CompUnitRepo". It is a hash in which the key is compunit provided by the distribution, and the value is the use string of the compunit it should be aliased to if that compunit is available. So in this case:

  "superseded_by" : {
    "JSON::Fast" : "SuperJSON:ver(v1.0 .. *)"
  }

it would mean that if a program attempts to load the JSON::Fast compunit of this distribution, it should instead use any SuperJSON compunit that is installed that has a version of 1.0 or higher. In other words: please don't use my compunit, unless you really have to.

This tag has additional meaning for packagers: if a packager detects a valid supersedes and superseded_by pair in its collection of distributions to be packaged, the packager may decide to only supply the distribution providing the superseded_by compilation unit.

Please note that superseded_by has no meaning as a depends, so an installer should probably not automatically install any superseded_by compunits.

excludes

Optional. A hash in which the key is a compilation unit provided by this distribution, and the value is a use string of all compilation units that will be disallowed when attempted to be loaded in the same lexical scope. An example of this would be:

  "excludes" : {
    "JSON::PurePerl" : "JSON::Slow:auth<cpan:*>:ver(1..*)"
  }

So, if a lexical scope loads JSON::PurePerl from this distribution, then attempting to load JSON::Slow will cause a Failure. Please note that this has no meaning for packagers: it is simply a way to provide a better error message if a collision of some sort will occur when both modules are loaded in the same lexical scope.

build-depends

Optional. A list of build-time dependencies, specified as use strings. An example of this would be:

  "build-depends" : [
    "Archive::Zip"
  ]

test-depends

Optional. A list of test-time dependencies, specified as use strings. An example of this would be:

  "test-depends" : [
    "Test:auth<cpan:OVID>"
  ]

resource

Optional. A hash of resource groups, each of them corresponding to a directory in the "resource" directory in the distribution. Each resource group has a name and a list of files that are provided. During installation the installer will install these into a location, and make the files available through the %?RESOURCE hash. So, for example:

  "resource" : {
    "images" : {
      "fido.png"
    }
  }

would assume there is a file resource/images/fido.png. After installation, the path of that file would be available through

  %?RESOURCE<images><fido.png>.path

and a handle could be obtained with:

  %?RESOURCE<images><fido.png>.IO

without there being any guarantee that this path has anything to do with the path as specified in the distribution. Please also note that the installer may mangle filenames of actually installed files.

support

Optional. A hash of key-value pairs regarding support for this distribution. Possible names are: email, mailinglist, bugtracker, source, irc, phone.

email

The email address of the owner of this distribution, if any.

mailinglist

The mailinglist of users of this distribution, if any.

bugtracker

The bugtracker of this distribution, if any.

source

The URL of the source of this distribution, if any.

irc

The URL of the IRC channel where this distribution can be discussed, if any.

phone

A fully qualified phone number (with potential cost indication) that can be used with queries about this distribution.

production

Optional. A Boolean to indicate whether or not this is a distribution intended to be used in production. For instance:

  "production" : 1

By default, a distribution is not ready for production. If a distribution is not ready for production, then it will never be recommended.

Please note that this section is only to be used by installers, giving them the opportunity to decide whether or not to install that distribution. Once a distribution is installed, it can be loaded just like any other distribution.

license

Optional. The URL with the text of the license under which this distribution is available for installation. Or some other way to indicate the license, e.g. inspired by the Perl 5 module Software::License.

  "license" : "http://www.gnu.org/licenses/gpl-1.0.html"  

tags

Optional. A list of general purpose tags. For instance:

  "tags" : [
    "json",
    "perl6"
  ]

It has no meaning other than the meaning you assign to it.

Special directories

A distribution may contain several directories that will be handled specially.

bin

Any file inside this directory, will be installed as a callable shell application.

t

All .t files in this directory, will be tested in alphabatical order, possibly in parallel. Any files in this directory will never be installed.

hooks

All files in this directory should contain executable Perl 6 code, to be executed at various stages of the install process of this distribution.

Installation

Distributions can be installed with an installer. This may be a command-line script, or be some kind of GUI. The installer needs the user to (implicitly) select the CompUnitRepo in which the distribution should be installed, and the recommendation manager that should be used to convert requests for a compilation unit into an identity of a distribution to be downloaded.

Classes

CompUnitRepo

Base class (interface, really) for the object living in the @*INC array. Used both for installing compunits, as well as finding a certain compunit by way of its from, longname, auth and ver information.

new

 my $repo = CompUnitRepo.new( $location );

Create a new CompUnitRepo object, either for inclusion in @*INC, or to install a compilation unit.. The parameter indicates the location in which compunits are supposed to be located for this object. This could be a local directory (as in the case of CompUnitRepo::Local::File and CompUnitRepo::Local::Installation). Or it could be anything that indicates a remote repository, such as a connect string to a database, or a URL to a an authority (such as CPAN or Github). Returns the instantiated object.

install

 my $installed = $repo.install(...);

Install a compilation unit in the appropriate way for this object. May cause a fatal exception if this repository does not support installing. The first parameter contains the actual source-code of the compilation unit to be installed. The named parameters indicate the other meta-information to be associated with the compunit. Returns whether compilation unit was installed.

Of course, any implementation of CompUnitRepo's install interface, may decide to accept additional meta-information and store this and make available for later introspection.

candidates

 my @candidates = $repo.candidates( $longname, $auth?, $ver?, $from? );

Return CompUnit candidates given the matching credentials.

CompUnit

The object that describes a compilation unit.

load

 my $loaded = @candidates[0].load;
[ Top ]   [ Index of Synopses ]