Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 248 lines (170 sloc) 7.708 kb
be1862e P6 Synopsis : ws changes - to help BOMers, added leading blank line to f...
Darren_Duncan authored
1
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
2 =encoding utf8
3
4 =head1 TITLE
5
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
6 Synopsis 22: Package Format [DRAFT]
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
7
04840a3 [Spec] treat all authors equally
lwall authored
8 =head1 AUTHORS
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
9
10 Jos Boumans <kane@cpan.org>
e5ce913 * I've got a new email address, audreyt@audreyt.org.
audreyt authored
11 Audrey Tang <audreyt@audreyt.org>
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
12 Florian Ragwitz <rafl@debian.org>
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
13 Tim Nelson <wayland@wayland.id.au>
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
14
15 =head1 VERSION
16
04840a3 [Spec] treat all authors equally
lwall authored
17 Created: 3 Nov 2005
18
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
19 Last Modified: 19 Dec 2008
20 Version: 2
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
21
84ecb80 Added some definitions
wayland authored
22 =head1 OVERVIEW
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
23
84ecb80 Added some definitions
wayland authored
24 =head2 Terminology and Scope
25
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
26 I'll start by listing a few terms, and whether this document is supposed to cover them or
27 not.
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
28
29 =over
30
84ecb80 Added some definitions
wayland authored
31 =item * .jib files; this is the source package format, and is specified in this document
32
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
33 =item * CPAN6; this is a piece of software for managing an archive network (such as CPAN).
b5521b3 [S17, S22, S26] Turned URLs into links
wayland authored
34 This is not specified in this document; see L<http://cpan6.org/>
84ecb80 Added some definitions
wayland authored
35
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
36 =item * PAUSE6; this is an actual network based on the cpan6 software (see above). It also
37 is not documented here.
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
38
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
39 =item * CPAN6.pm; this is a piece of software that starts with what it can get on PAUSE6, and
40 attempts to give you an installed perl module (this is a replacement for
84ecb80 Added some definitions
wayland authored
41 CPANPLUS/cpan2dist)
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
42
43 =back
44
45 =head2 Inspirations
46
47 The following can be useful inspirations:
48
49 =over
50
b5521b3 [S17, S22, S26] Turned URLs into links
wayland authored
51 =item * Debian Policy: L<http://www.us.debian.org/doc/debian-policy>
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
52
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
53 =item * Software::Packager::Metadata:
b5521b3 [S17, S22, S26] Turned URLs into links
wayland authored
54 L<http://perlsoftpackmet.svn.sourceforge.net/viewvc/perlsoftpackmet/main/doc/> (click on the
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
55 link in the Rev. column next to Overview)
56
84ecb80 Added some definitions
wayland authored
57 =back
58
59 =head1 PACKAGE LAYOUT
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
60
61 =head2 Project directory
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
62
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
63 Step 1 of the general flow should ideally be done by an automated tool, like
64 p5's current Module::Starter or somesuch. Suffice to say, it should produce
65 a layout something along these lines (note, this is just an example):
66
67 p5-Foo-Bar/
68 lib/
69 Foo/
70 Bar.pm
71 t/
72 00_load.t
73 _jib/
74 META.info
75
76 The files in the _jib dir are part of the package metadata. The most important
77 file is the META.info file that holds all the collected metadata about the
78 package, which ideally gets filled (mostly) by what is described in step 2 of
79 the C<General Flow>. Any pre/posthook files should also go in this directory.
80 This directory should be extensible, so new files can be added to extend
81 functionality.
82 See the section on C< Metadata Spec > for details.
83
c95cf0e Removed stuff about repositories and build and install software.
wayland authored
84 =head2 .jib files
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
85
86 These files are created in step 3 of the C<General Flow>
87
0e9f98e * answer some XXX sections
kane authored
88 C<JIB> is a simple 3 letter combination that's not yet 'taken' as
89 a known extension. It's purposely not perl specific, as there's nothing
023d54b typo fix
sunnavy authored
90 about the C<JIB> specification that's limiting it to perl only.
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
91
92 # XXX - Also C<package> is carrying double meaning in P6 as both namespace
93 and source distribution. Can we remove the former meaning and refer to them
94 as C<module> and C<namespace> from now on?
95
96 C<.jib> files are archives designed to distribute source packages, not
97 installable packages. As we will need to compile things on the client side
98 (things that have C bits or equivalent), and because we can not know the
99 install path before hand, a source package is an obvious choice.
100 A binary, installable package like C<.deb> is therefor no option.
101
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
102 These C<.jib> contain metadata and installable code quite analogous to
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
103 the C<.deb> packages we know, except that the metadata is also used to
104 C<compile> (for the lack of a better term so far) the code on the user side.
105
106 The name of a C<.jib> file is determined as follows:
107
108 <prefix>-<package-name>-<version>-<authority>.<extension>
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
109
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
110 In praxis, this will produce a name along these lines:
111
112 p5-Foo-Bar-1.1-cpan+kane.jib
113
114 The Internal layout is as follows:
115
116 - control.tgz
117 * contains the data in the _jib directory
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
118 - data.tgz
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
119 * contains the following directories the other directories.
120 This may be limited in the future, by say, a manifest.skip
121 like functionality, or by dictating a list of directories/
122 files that will be included
123
124 There is room to ship more files alongside the 2 above mentioned archives.
125 This allows us to ship an extra md5sum, version, signature, anything.
126
84ecb80 Added some definitions
wayland authored
127 =head1 METADATA SPEC
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
128
129 - Define no more than needed to get started for now
130 - Allow for future extensions
131 - Use YAML as metadata format as it's portable and available standard
132 in perl6
133
134 =head2 Supported fields
135
0e9f98e * answer some XXX sections
kane authored
136 - Prefix Package prefix category (p5)
137 - Name Perl module name (Foo-Bar)
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
138 - Version Perl module version (1.2.3)
139 - Authority From S11 (cpan+KANE)
140 - Package Full package name (p5-Foo-Bar-1.2.3-cpan+kane)
0e9f98e * answer some XXX sections
kane authored
141 - Description Description of function (This is what it does)
142 - Author CPAN author id (KANE)
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
143 - Depends Packages it depends on[1][2](p5-Foo)
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
144 - Provides Packages this one provides (p5-Foo-Bar,
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
145 p5-Foo-Bar-cpan+kane)
146
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
147 As the <Prefix>-<Name>-<Version>-<Authority> combination make up the
148 <Package> name, arguably, we can leave the former out.
149 The upside is to make sure all fields contain unique information.
150 The downside is that 3rd party parsers will need to understand the
0e9f98e * answer some XXX sections
kane authored
151 C<Package> syntax.
152
153 Again, arguably, the C<Author> and C<Authority> fields overlap, and
154 C<Authority> can be made to hold both cases.
155
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
156 [1] This is packages, *not* modules. If we need a module -> package
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
157 mapping, this needs to be done when extracting the data from the
158 compiler, and queried against the available packages cache.
159 [2] See the section on L<Dependencies>
160
161 =head2 Suggested fields[3]
162
163 - Build-Depends Packages needed to build this package
164 - Suggests Packages suggested by this package
165 - Recommends Packages recommended by this package
166 - Enhances Packages that are enhanced by this package
167 - Conflicts Packages this one conflicts with
168 - Replaces Packages this one replaces
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
169 - Tags Arbitrary metadata about the package,
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
170 like flickr and debtags
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
171 - Contains List of modules (and scripts?) contained
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
172 in the package
173
174 [3] Steal more tags from debian policy
175
84ecb80 Added some definitions
wayland authored
176 =head1 DEPENDENCIES
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
177
178 =head2 Dependency Notation
179
180 Dependency notation allows you to express the following concepts:
181
182 =over
183
184 =item OR
185
186 Specifies alternatives
187
188 =item AND
189
190 Specifies cumulative requirements
191
192 =item associate VERSION requirement
193
194 Specifies a criteria for the version requirement
195
196 =item grouping
197
198 This allows nesting of the above expressions
199
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
200 =back
201
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
202 =head3 Basic notation:
203
204 a, b # a AND b
205 [a, b] # a OR b
206 { a => "> 2" } # a greater than 2
207 { a => 1 } # shorthand for a greater or equal to 1
208 \[ ... ] # grouping
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
209
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
210 =head3 More complex examples:
211
212 a, [b,c] # a AND (b OR c)
213 { a => 1 }, { a => '< 2' } # a greater or equal to 1 AND smaller than 2
214 [a, \[ b, c ] ] # a OR (b AND c) [1]
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
215
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
216 [1] This is possibly not portable to other languages. Options seem
217 thin as we don't have some /other/ grouping mechanism than [ ], { }
218 and \[ ]; ( ) gets flattened and \( ) == [ ].
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
219 We could abuse { } to create { OR => [ ] } and { AND => [ ] }
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
220 groups, but it would not read very intuitively. It would also mean
221 that the version requirements would have to be in the package naming,
222 ie. 'a > 2' rather than a => '> 2'
223
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
224 =head3 Serialization Examples
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
225
226 # a, b -- AND
227 - a
228 - b
229
230 # [a, b] -- OR
231 -
232 - a
233 - b
234
235 # { a => "> 2" } -- VERSIONED
236 a: > 2
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
237
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
238 # { a => 1 } -- VERSIONED
239 a: 1
92c4265 [docs/Perl6/Spec/CPAN.pod]
agentz authored
240
241
eab6d15 * repo-copy S22 to CPAN.pod
audreyt authored
242 # \[ ... ] -- GROUPING
243 - !perl/ref:
244 =:
245 - ...
246
7746c06 [Synopses] - some formating
mj41 authored
247 =for vim:set expandtab sw=4:
Something went wrong with that request. Please try again.