Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Restart S22, move appropriate stuff in from S11
  • Loading branch information
@lizmat
lizmat committed Mar 15, 2014
1 parent f901166 commit 3d55709
Show file tree
Hide file tree
Showing 2 changed files with 351 additions and 207 deletions.
208 changes: 1 addition & 207 deletions S11-modules.pod
View file
Expand Up @@ -2,7 +2,7 @@

=head1 TITLE

Synopsis 11: Units, Modules and Distributions
Synopsis 11: Compilation Units

=head1 AUTHORS

Expand Down Expand Up @@ -760,210 +760,4 @@ The object that describes a compilation unit.

my $loaded = @candidates[0].load;

=head1 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)).

=head2 META6.json

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

Please note that there is B<no> C<author> information in the meta information.
The author information is stored from the credentials used when uploading to
a repository.

=head3 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.

=head3 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" : "Dog"

=head3 version

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

"version" : "v1.0"

=head3 description

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

"description" : "Adding bite to your programs"

=head3 provides

Optional. A list of module - filename pairs that this distribution makes
available to be C<use>d. For example:

"provides" : {
"Dog" : "lib/Dog.pm6"
}

=head3 depends

Optional. A list of run-time dependencies, specified as C<use> strings. An
example of this would be:

"depends" : [
"Canine:auth<cpan:*>:ver(1..*)"
]

An installer has the option to automatically install any dependencies, if the
use has so indicated.

=head3 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" : {
"Dog" : "Wolf:auth<cpan:JRANDOM>:ver<1.0>"
}

If then later, a program would say:

use Wolf:auth<cpan:JRANDOM>:ver<1.0>;

it would in fact load the C<Dog> compunit, but make it appear as a C<Wolf>
compunit, but only if there was no "real" C<Wolf> compunit installed that would
match the C<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.

=head3 supersedes

Optional. Has the same meaning as "emulates" for the L<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 L<superseded_by>.

=head3 superseded_by

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

"superseded_by" : {
"Dog" : "SuperDog:ver(v1.0 .. *)"
}

it would mean that if a program attempts to load the C<Dog> compunit of this
distribution, it should instead use any C<SuperDog> 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
C<supersedes> and C<superseded_by> pair in its collection of distributions to
be packaged, the packager may decide to only supply the distribution providing
the C<superseded_by> compilation unit.

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

=head3 excludes

Optional. A list of modules to be disallowed, specified as C<use> strings.
An example of this would be:

"excludes" : [
"Tiger:auth<cpan:*>:ver(1..*)"
]

Trying to load a module that matches the C<use> string, will cause a failure.

=head3 build-depends

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

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

=head3 test-depends

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

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

=head3 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 C<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

=head3 support

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

=head3 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.

=head2 Special directories

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

=head3 bin

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

=head3 t

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

=for vim:set expandtab sw=4:

0 comments on commit 3d55709

Please sign in to comment.