Skip to content

Commit de1d46d

Browse files
author
Patrick Sebastian Zimmermann
committed
Update ecosystem upload docs (CPAN).
As explained here: https://rakudo.party/post/CPAN6-Is-Here
1 parent b5a674d commit de1d46d

File tree

1 file changed

+97
-42
lines changed

1 file changed

+97
-42
lines changed

doc/Language/modules.pod6

Lines changed: 97 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -423,21 +423,29 @@ If you've written a Perl 6 module and would like to share it with the
423423
community, we'd be delighted to have it listed in the L<Perl 6 modules
424424
directory|https://modules.perl6.org>. C<:)>
425425
426-
For now, the process requires that you use git for your module's version
427-
control.
426+
Currently there are two different module ecosystems (module distribution
427+
networks) available:
428428
429-
The instructions herein assume that you have a
430-
L<GitHub|https://github.com> account so that your module can be
431-
shared from its GitHub repository, however another provider such as
432-
L<GitLab|https://about.gitlab.com/> should work as long as it works in
433-
a similar way.
429+
=item B<CPAN>
430+
This is the same ecosystem Perl5 is using. Modules are uploaded as I<.zip>
431+
or I<.tar.gz> files on L<PAUSE|https://pause.perl.org/>.
434432
435-
To share your module, do the following:
433+
=item B<p6c>
434+
Up until recently the only ecosystem, but soon to be deprecated. It is based
435+
on Github repositories which are directly accessed. It has only limited
436+
capability for versioning.
437+
438+
The process of sharing your module consists of two steps, preparing the module
439+
and uploading the module to one of the ecosystems.
440+
441+
=head2 Preparing the Module
442+
443+
For a module to work in any of the ecosystems, it needs to follow a certain
444+
structure. Here is how to do that:
436445
437446
=item Create a project directory named after your module. For
438447
example, if your module is C<Vortex::TotalPerspective>, then create a
439-
project directory named C<Vortex-TotalPerspective>. This project
440-
directory name will also be used as the GitHub repository name.
448+
project directory named C<Vortex-TotalPerspective>.
441449
442450
=begin item
443451
Make your project directory look like this:
@@ -447,14 +455,13 @@ Vortex-TotalPerspective/
447455
|-- lib
448456
| `-- Vortex
449457
| `-- TotalPerspective.pm
450-
|-- doc
451-
| `-- Vortex
452-
| `-- TotalPerspective.pod6
453458
|-- LICENSE
454459
|-- META6.json
455460
|-- README.md
456461
`-- t
457462
`-- basic.t
463+
464+
458465
=end code
459466
460467
If your project contains other modules that help the main module do
@@ -504,15 +511,23 @@ lib
504511
https://design.perl6.org/S26.html> markup inside your modules. Module
505512
documentation is most appreciated and will be especially important once
506513
the Perl 6 module directory (or some other site) begins rendering Pod docs
507-
as HTML for easy browsing.
514+
as HTML for easy browsing. If you have extra docs (in addition to the
515+
Pod docs in your module(s)), create a C<doc> directory for them. Follow
516+
the same folder structure as the C<lib> directory like so:
517+
518+
=begin code :skip-test
519+
doc
520+
`-- Vortex
521+
`-- TotalPerspective.pod6
522+
=end code
523+
508524
N«
509525
Note, described above is a minimal project directory. If your project
510526
contains scripts that you'd like distributed along with your module(s),
511-
put them in a C<bin> directory. If you have extra docs (in addition to the
512-
Pod docs in your module(s)), create a C<doc> directory for them. If you'd
513-
like a graphical logo to appear next to your module at the module
514-
directory, create a C<logotype> directory and put into it a C<logo_32x32.png>
515-
file. At some point, you might also consider adding C<CONTRIBUTORS>, C<NEWS>,
527+
put them in a C<bin> directory. If you'd like a graphical logo to
528+
appear next to your module at the module directory, create a
529+
C<logotype> directory and put into it a C<logo_32x32.png> file. At some
530+
point, you might also consider adding C<CONTRIBUTORS>, C<NEWS>,
516531
C<TODO>, or other files.
517532
»
518533
@@ -523,7 +538,7 @@ lib
523538
{
524539
"perl" : "6.c",
525540
"name" : "Vortex::TotalPerspective",
526-
"version" : "0.1.0",
541+
"version" : "0.0.1",
527542
"description" : "Wonderful simulation to get some perspective.",
528543
"authors" : [ "R<Your Name>" ],
529544
"license" : "Artistic-2.0",
@@ -560,7 +575,7 @@ lib
560575
C<%?RESOURCES> Hash indexed on the name provided.
561576
562577
The L<Test::META module | https://github.com/jonathanstowe/Test-META/>
563-
can help you check the correctness of the META.info file.
578+
can help you check the correctness of the META6.json file.
564579
565580
There are more fields described in the L<META design documents |
566581
https://design.perl6.org/S22.html#META6.json>, but not all of these are
@@ -570,10 +585,70 @@ lib
570585
571586
=end item
572587
588+
=begin item
589+
To test your module you can use the following command to install the
590+
module directly from the module folder you just created.
591+
592+
=for code :lang<shell>
593+
zef install ./your-module-folder
594+
595+
=end item
596+
597+
=head2 Upload your Module to CPAN
598+
599+
Uploading a module to CPAN requires having a L<PAUSE|https://pause.perl.org/>
600+
user account. If you don't have an account already go there and apply for an
601+
account. The process takes about 5 minutes and some e-mail back and forth.
602+
603+
=begin item
604+
Create a package of your module:
605+
606+
=begin code :lang<shell>
607+
cd your-module-folder
608+
tar czf Vortex-TotalPerspective-0.0.1.tar.gz --transform s/^\./Vortex-TotalPerspective-0.0.1/ --exclude-vcs --exclude=.[^/]*
609+
=end code
610+
611+
If you use git you can also use the following command to create a package directly for a given commit.
612+
613+
=for code :lang<shell>
614+
git archive --prefix=Vortex-TotalPerspective-0.0.1/ -o ../Vortex-TotalPerspective-0.0.1.tar.gz HEAD
615+
616+
=end item
617+
618+
=item Go to L<PAUSE|https://pause.perl.org/>, login and click on
619+
L<Upload a file to CPAN|https://pause.perl.org/pause/authenquery?ACTION=add_uri>.
620+
621+
=item Make sure you select C<Perl6> in the select input box.
622+
623+
=begin item
624+
Select your file and click I<Upload>!
625+
626+
N«
627+
Make sure you have a META6.json file in your dist and that the dist
628+
version you're uploading is higher than the currently uploaded version.
629+
Those are the most common upload errors.
630+
»
631+
632+
=end item
633+
634+
=head2 Upload your Module to p6c
635+
636+
N«
637+
The I<p6c> ecosystem is soon to be deprecated, so you should consider
638+
using the I<CPAN> ecosystem instead.
639+
»
640+
641+
If you want to use the I<p6c> ecosystem you need to use git for your module's
642+
version control. The instructions herein assume that you have a
643+
L<GitHub|https://github.com> account so that your module can be shared from its
644+
GitHub repository, however another provider such as
645+
L<GitLab|https://about.gitlab.com/> should work as long as it works in a
646+
similar way.
647+
573648
=item Put your project under git version control if you haven't done so
574649
already.
575650
576-
=item Once you're happy with your project, create a repository for it at GitHub.
651+
=item Once you're happy with your project, create a repository for it on GitHub.
577652
See L<GitHub's help docs|https://help.github.com/> if necessary. Your
578653
GitHub repository should be named the same as your project directory. Immediately
579654
after creating the GitHub repo, GitHub shows you how to configure your
@@ -612,26 +687,6 @@ know where to look for the module file(s).
612687
You can find a list of modules and tools that aim to improve the experience of
613688
writing/test modules at L<Modules Extra|/language/modules-extra>
614689
615-
=head1 The Future of the Ecosystem
616-
617-
L<https://modules.perl6.org> and github-based infrastructure is temporary. The
618-
plan is to establish something similar to Perl 5's PAUSE/CPAN/MetaCPAN
619-
infrastructure. B<Volunteers needed!>
620-
621-
The rough plan is:
622-
623-
=for code :skip-test<should be numbered items>
624-
1. fix EVAL precomp bug (nine)
625-
2. get Repository API straight
626-
3. get zef up to speed
627-
4. continue with the metacpan fork for perl6 (jdv79)
628-
629-
The repository with jdv's fork can be found at L<https://github.com/jdv/metacpan-web>
630-
631-
You can also already upload your Perl 6 modules to
632-
L<Perl 5's PAUSE|https://pause.perl.org/>, selecting `Perl6` directory during the
633-
upload. That will ensure your module is indexed in Perl 6's space and not Perl 5's.
634-
635690
=head2 Contact Information
636691
637692
To discuss module development in general, or if your module would

0 commit comments

Comments
 (0)