Skip to content

Commit ca92f0d

Browse files
committed
As per comments from @ugexe, I have:
- Removed references to P6C and CPAN - Changed compunit to module where appropriate
1 parent 60e86f5 commit ca92f0d

File tree

5 files changed

+40
-112
lines changed

5 files changed

+40
-112
lines changed

doc/Language/distributions/configuration-structure.rakudoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -222,8 +222,8 @@ In general, the array form will be more than enough for most cases.
222222
The C<README.md> file is a
223223
L<markdown-formatted|https://help.github.com/articles/markdown-basics/>
224224
text file, which will later be automatically rendered as HTML by GitHub/GitLab for modules kept
225-
in those ecosystems or by L<raku.land|https://raku.land> website for modules
226-
kept on L<CPAN|/language/faq#index-entry-CPAN_(FAQ)>.
225+
in those places, or by L<raku.land|https://raku.land> website for modules
226+
accessible with L<zef|/language/faq#Is_there_a_repository_of_third_party_library_modules_for_Raku?>.
227227

228228
=head3 The C<LICENSE> file and key
229229

doc/Language/distributions/introduction.rakudoc

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,30 @@
44

55
=SUBTITLE Distributions and How they Work
66

7+
=head2 Terminology
8+
9+
This is a point in the Raku journey where we need to get specific with some of
10+
the terminology, so here are some of the terms which will be used:
11+
12+
=item1 B<compunit>: A compilation unit, or compunit for short, is a piece of
13+
Raku code that is analyzed and compiled as a single unit. Typically, this
14+
comes from a source file on disk, but what's inside an EVAL also counts as
15+
such.
16+
17+
=item1 B<script>: A script refers to a compilation unit that is provided to
18+
Raku as the entry point for execution. In an invocation like raku foo.raku,
19+
we say that foo.raku is first compiled and then executed. In Rakudo Raku, in
20+
this case, the results of the compilation only exist in memory.
21+
22+
=item1 B<module>: A module refers to a compilation unit that is used by a
23+
script, or by another module used from a script. A module must also be
24+
compiled before it can be made use of. (There is nothing preventing a given
25+
source file serving as both a script and a module depending on how it is used).
26+
27+
=item1 B<distribution>: A distribution is a set of zero or more scripts and
28+
modules that are released together, along with some meta-data and potentially
29+
resources and tests.
30+
731
=head2 Basic structure
832

933
Module distributions (in the I<set of related source files> sense) in Raku
@@ -30,23 +54,23 @@ different files. In addition, when a C<distribution> is published (see
3054
L<Distributing modules|/language/distributions/introduction>) it may be
3155
necessary to provide access to other resources, such as callable utilities.
3256

33-
B<Raku> also allows for a single distribution to provide multiple C<compunit>s
57+
B<Raku> also allows for a single distribution to provide multiple C<module>s
3458
that can be C<use>d (or C<require>d etc). The information about a distribution
3559
is contained in the C<META6.json> file in the distribution's root directory. See
3660
below for more about C<META6.json>. Each entity that the B<distribution> allows
37-
to be C<use>d (or C<require>d etc), also called a C<compunit>, is placed in the
61+
to be C<use>d (or C<require>d etc), also called a C<module>, is placed in the
3862
C<provides> section of the C<META6.json> (as specified below).
3963

4064
It should also be noted that when writing the C<depends> section of the
4165
C<META6.json> file, it is the name of the B<distribution> that is listed, not
42-
the name of the C<compunit> that is desired. Although, for very many entities,
43-
the name of the I<distribution> and the name of the I<compunit> are the same.
66+
the name of the C<module> that is desired. Although, for very many entities,
67+
the name of the I<distribution> and the name of the I<module> are the same.
4468
Another global effect of the C<depends> list in a distribution made available to
45-
the Ecosystem, is that package managers, e.g. C<zef>, can look for C<compunit>
69+
the Ecosystem, is that package managers, e.g. C<zef>, can look for C<module>
4670
names in all distributions available.
4771

4872
Given this arrangement, the B<rakudo> compiler, or a package manager such as
49-
B<zef>, can obtain all the information needed about each C<compunit> from a
73+
B<zef>, can obtain all the information needed about each C<module> from a
5074
C<META6.json> file in a directory.
5175

5276
=head2 Contact information

doc/Language/distributions/testing.rakudoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
=SUBTITLE Testing your distribution of modules
66

77
This also means that a testing program such as B<Perl>'s C<prove> or the B<Raku>
8-
equivalent L<prove6|https://raku.land/cpan:LEONT/App::Prove6> can be
8+
equivalent L<prove6|https://raku.land/zef:leont/App::Prove6> can be
99
run in the root directory of the B<distribution> as, e.g.,
1010

1111
=for code :lang<shell>

doc/Language/distributions/tools.rakudoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ of a distribution of modules.
1515

1616
=item L<App::Mi6|https://raku.land/zef:skaji/App::Mi6> Minimal authoring tool for Raku
1717
=item L<META6|https://raku.land/zef:jonathanstowe/META6> Do things with Raku C<META> files
18-
=item L<rakudoc|https://raku.land/cpan:SOFTMOTH/rakudoc> Generate documentation end-products
18+
=item L<rakudoc|https://raku.land/zef:coke/rakudoc> Generate documentation end-products
1919

2020
=head1 Distribution Testing Tools
2121

doc/Language/distributions/uploading.rakudoc

Lines changed: 6 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,13 @@ If you've written a Raku module and would like to share it with the
88
community, we'd be delighted to have it listed in the
99
L<Raku modules directory|https://raku.land>. C<:)>
1010

11-
Currently, there are three ways to distribute a module. No matter which method
12-
you choose, your module will be indexed on the L<raku.land|https://raku.land>
13-
and L<raku.land|https://raku.land> websites. The three module
14-
distribution networks, or ecosystems, are:
11+
There have been three ways to distribute a module, but the CPAN and P6C ways
12+
have been deprecated; please use the zef/fez method instead. However, no
13+
matter the method, all modules will be indexed on the L<raku.land|https://raku.land>
14+
L<raku.land|https://raku.land> website.
1515

16-
=item B<zef ecosystem> using the L<C<fez> module uploader|https://raku.land/zef:tony-o/fez>
17-
utility. Use of the C<fez> command is
18-
the newest and perhaps easiest way to distribute your module and is growing in
19-
popularity.
20-
21-
=item B<CPAN>
22-
This is the same ecosystem Perl is using. Modules are uploaded as I<.zip>
23-
or I<.tar.gz> files on L<PAUSE|https://pause.perl.org/>.
24-
25-
=item B<p6c>
26-
Up until recently the only ecosystem. It is based
27-
on Github repositories which are directly accessed. It has only limited
28-
capability for versioning.
16+
The B<zef ecosystem> uses the L<C<fez> module uploader|https://raku.land/zef:tony-o/fez>
17+
utility. Use of the C<fez> command is the way to distribute your module.
2918

3019
The process of sharing your module consists of two steps, preparing the module,
3120
and uploading the module to one of the ecosystems mentioned above.
@@ -72,90 +61,6 @@ one module), only B<one> upload of a distribution per version is permitted. If a
7261
code in a repository, the changes will not be reflected in the C<fez> system. So changes to code must be
7362
accompanied by a bump in the version number and the new version uploaded to C<fez>.
7463

75-
=head1 Upload your module to CPAN
76-
77-
A prerequisite for using CPAN is a L<PAUSE|https://pause.perl.org/>
78-
user account. If you don't have an account already, you can create one
79-
L<here|https://pause.perl.org/pause/query?ACTION=request_id>
80-
The process takes about 5 minutes and some e-mail back and forth.
81-
82-
=begin item
83-
Create a package of your module:
84-
85-
=begin code :lang<shell>
86-
cd your-module-folder
87-
tar czf Vortex-TotalPerspective-0.0.1.tar.gz \
88-
--transform s/^\./Vortex-TotalPerspective-0.0.1/ --exclude-vcs\
89-
--exclude=.[^/]*
90-
=end code
91-
92-
If you use git you can also use the following command to create a package
93-
directly for a given commit.
94-
95-
=begin code :lang<shell>
96-
git archive --prefix=Vortex-TotalPerspective-0.0.1/ \
97-
-o ../Vortex-TotalPerspective-0.0.1.tar.gz HEAD
98-
=end code
99-
100-
=end item
101-
102-
=item Go to L<PAUSE|https://pause.perl.org/>, log in and navigate to
103-
C<Upload a file to CPAN>.
104-
105-
=item Make sure you select C<Perl6> as the I<Target Directory>. For
106-
your first upload, you have to enter the string C<Perl6> in the text field.
107-
On subsequent uploads, you can select the C<Perl6> directory from the
108-
selection box right below the input field.
109-
110-
=begin item
111-
Select your file and click I<Upload>! If everything was fine with your
112-
dist, you should see your module tar file in your C<Perl6> directory along
113-
with both a C<META> and a C<README> file named after your module filename.
114-
115-
I<Make sure you have a META6.json file in your dist and that the dist
116-
version you're uploading is higher than the currently uploaded version.
117-
Those are the most common upload errors.>
118-
119-
=end item
120-
121-
=head2 Upload your module to p6c
122-
123-
The Raku community is migrating to the I<fez> ecosystem (see above). For developers
124-
who have modules on the I<p6c> ecosystem and migrated them to I<fez>, please remove them
125-
from the I<p6c> ecosystem. If you do not have the commit bit, open a pull request or ping someone on IRC
126-
(#raku at libera.chat) to get help.
127-
128-
If you want to use the I<p6c> ecosystem you need to use git for your module's
129-
version control. The instructions herein assume that you have a
130-
L<GitHub|https://github.com> account so that your module can be shared from its
131-
GitHub repository, however another provider such as
132-
L<GitLab|https://about.gitlab.com/> should work as long as it works in a
133-
similar way.
134-
135-
=item Put your project under git version control if you haven't done so
136-
already.
137-
138-
=item Once you're happy with your project, create a repository for it on GitHub.
139-
See L<GitHub's help docs|https://help.github.com/> if necessary. Your
140-
GitHub repository should be named the same as your project directory. Immediately
141-
after creating the GitHub repo, GitHub shows you how to configure your
142-
local repository to know about your GitHub repository.
143-
144-
=item Push your project to GitHub.
145-
146-
=item Consider setting up automated testing.
147-
One option is to use the github workflows functionality, and an example can be found for the
148-
L<Mi6-Helper App|https://github.com/tbrowder/Mi6-Helper/blob/master/.github/workflows>.
149-
150-
=item Create a PR (Pull Request) on L<ecosystem|https://github.com/Raku/ecosystem> adding
151-
your module to META.list, or ping someone on IRC (#raku at libera.chat) to
152-
get help having it added.
153-
154-
=item After the pull request has been accepted, wait for an hour. If
155-
your module doesn't show up on L<https://raku.land/>, please
156-
view the log file to see if it identifies an error with your module or
157-
C<meta> file.
158-
15964
B<That's it! Thanks for contributing to the Raku community!>
16065

16166
If you'd like to try out installing your module, use the X<zef|Reference,zef> module
@@ -174,4 +79,3 @@ C<use Vortex::TotalPerspective>, and your Raku implementation will
17479
know where to look for the module file(s).
17580

17681
=end pod
177-

0 commit comments

Comments
 (0)