@@ -423,21 +423,29 @@ If you've written a Perl 6 module and would like to share it with the
423
423
community, we'd be delighted to have it listed in the L < Perl 6 modules
424
424
directory|https://modules.perl6.org > . C < :) >
425
425
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:
428
428
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/ > .
434
432
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:
436
445
437
446
= item Create a project directory named after your module. For
438
447
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 > .
441
449
442
450
= begin item
443
451
Make your project directory look like this:
@@ -447,14 +455,13 @@ Vortex-TotalPerspective/
447
455
|-- lib
448
456
| `-- Vortex
449
457
| `-- TotalPerspective.pm
450
- |-- doc
451
- | `-- Vortex
452
- | `-- TotalPerspective.pod6
453
458
|-- LICENSE
454
459
|-- META6.json
455
460
|-- README.md
456
461
`-- t
457
462
`-- basic.t
463
+
464
+
458
465
= end code
459
466
460
467
If your project contains other modules that help the main module do
@@ -504,15 +511,23 @@ lib
504
511
https://design.perl6.org/S26.html> markup inside your modules. Module
505
512
documentation is most appreciated and will be especially important once
506
513
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
+
508
524
N «
509
525
Note, described above is a minimal project directory. If your project
510
526
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 > ,
516
531
C < TODO > , or other files.
517
532
»
518
533
523
538
{
524
539
"perl" : "6.c",
525
540
"name" : "Vortex::TotalPerspective",
526
- "version" : "0.1.0 ",
541
+ "version" : "0.0.1 ",
527
542
"description" : "Wonderful simulation to get some perspective.",
528
543
"authors" : [ "R < Your Name > " ],
529
544
"license" : "Artistic-2.0",
560
575
C < %?RESOURCES > Hash indexed on the name provided.
561
576
562
577
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.
564
579
565
580
There are more fields described in the L < META design documents |
566
581
https://design.perl6.org/S22.html#META6.json > , but not all of these are
@@ -570,10 +585,70 @@ lib
570
585
571
586
= end item
572
587
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
+
573
648
= item Put your project under git version control if you haven't done so
574
649
already.
575
650
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.
577
652
See L < GitHub's help docs|https://help.github.com/ > if necessary. Your
578
653
GitHub repository should be named the same as your project directory. Immediately
579
654
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).
612
687
You can find a list of modules and tools that aim to improve the experience of
613
688
writing/test modules at L < Modules Extra|/language/modules-extra >
614
689
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
-
635
690
= head2 Contact Information
636
691
637
692
To discuss module development in general, or if your module would
0 commit comments