.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Minilla::Tutorial 3pm" .TH Minilla::Tutorial 3pm "2023-02-21" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Minilla::Tutorial \- Tutorial document for Minilla .SH "The Minilla workflow" .IX Header "The Minilla workflow" .SS "Installing" .IX Subsection "Installing" .Vb 1 \& > cpanm \-\-with\-recommends Minilla .Ve .PP You can install Minilla from \s-1CPAN.\s0 .PP Unlike dzil, you don't need to do any setup. Minilla aggregates user name and e\-mail address from your \f(CW\*(C`~/.gitconfig\*(C'\fR (You already set, isn't it?) .SS "Making new distribution" .IX Subsection "Making new distribution" Now it's time to make a new distribution. .PP .Vb 2 \& > minil new Dist\-Name \& > cd Dist\-Name/ .Ve .PP At this point, you will have a really simple Dist-Name directory that contains your module file with as minimum boilerplate as possible. .PP minil done \f(CW\*(C`git init\*(C'\fR and \f(CW\*(C`git add .\*(C'\fR. You need to commit it \s-1ASAP.\s0 .PP .Vb 1 \& > git commit \-m \*(Aqinitial import\*(Aq .Ve .PP Now start writing your code, edit the docs, tests and manage \s-1CPAN\s0 dependencies with cpanfile. .PP .Vb 1 \& > $EDITOR lib/Dist/Name.pm t/dist\-name.t cpanfile .Ve .SS "Making the first release" .IX Subsection "Making the first release" When you get confident and it's about time to ship to \s-1CPAN,\s0 use the test and release command. Before doing so, make sure your git directory is not dirty i.e. all changes are committed. .PP .Vb 1 \& > git commit \-a \-m "Done initial version" .Ve .PP Minilla assumes you have a git remote setup so that you can push all your changes to. I recommend you to use either hub gem or App::ph to create a new github repository. .PP .Vb 2 \& # Use hub rubygem \& > hub create \& \& # Use App::ph \& > ph import .Ve .PP Alternatively, if you prefer to use GitLab you can create a project in their web interface and follow the instructions it provides to \fIPush an existing Git repository\fR. .PP Now, make sure you have Changes file ready and have a new entry under \f(CW\*(C`{{$NEXT}}\*(C'\fR, which will be expanded to the next version of your module. .PP .Vb 2 \& > $EDITOR Changes \& > minil test .Ve .PP Before you proceed to release step, please ensure the \f(CW\*(C`~/.pause\*(C'\fR file is configured correctly because Minilla uses CPAN::Uploader to upload your distribution to \s-1CPAN.\s0 You can specify the location of \s-1PAUSE\s0 configuration file on \fIminil.toml\fR if you want to. See \*(L"\s-1CONFIGURATION\*(R"\s0 in Minilla for further information. .PP .Vb 1 \& > minil release .Ve .PP And your first release is done. The release is tagged on git and all the changes automatically made are committed to git as well. .PP If this is your first conversion to Minilla and want to make sure you're not going to mess \s-1CPAN\s0 with a bad archive when something goes wrong, you can run the release command with \s-1FAKE_RELEASE\s0 environment variable. This will run all the other release process, except the UploadToCPAN step. .PP .Vb 1 \& > FAKE_RELEASE=1 minil release .Ve .PP Wait for \s-1PAUSE\s0 processing it and your module showing up on MetaCPAN in a few minutes. Congratulations! .SS "Making a maintenance release" .IX Subsection "Making a maintenance release" You have new features, bugs, pull requests and get ready to make a next version of your module. Great, making a new release is equally easy. .PP First, make sure all your code has been committed to git and there's no dirty files in the working directory. .PP Then make sure to edit Changes file and contain entries for the next release under \f(CW\*(C`{{$NEXT}}\*(C'\fR. You don't need to commit the change to the \fIChanges\fR file, yet. .PP Now, make a release! .PP .Vb 2 \& > minil test \& > minil release .Ve .PP The release command will automatically bump the version for you \- if you have 0.10, the next version will be 0.11 by default, but you will be prompted to confirm that version in case you need a major bump. .PP You can annotate any lines for which you would like the automatic version bump to be skipped by appending, `# No BumpVersion`. .PP This will update \f(CW\*(C`Changes\*(C'\fR, \f(CW\*(C`META.json\*(C'\fR and bump \f(CW$VERSION\fR in your main module. These changes made by Minilla will be automatically committed, tagged and pushed to the remote. .SH "MIGRATING" .IX Header "MIGRATING" This section describes how to migrate your current authoring process to Minilla. .ie n .SS "Migrate by ""minil migrate""" .el .SS "Migrate by \f(CWminil migrate\fP" .IX Subsection "Migrate by minil migrate" You just type \f(CW\*(C`minil migrate\*(C'\fR. .PP It can migrate your distribution automatically. If you can't do it, please report to Github issues . .SS "Manually migrating from other build tools" .IX Subsection "Manually migrating from other build tools" \fIModule Dependencies to cpanfile\fR .IX Subsection "Module Dependencies to cpanfile" .PP First, move the prereq declaration from Makefile.PL or Build.PL to cpanfile. .PP The easiest way to convert existing dependencies to cpanfile is to use the command line tool mymeta-cpanfile, which is installed with Module::CPANfile. Run the configuration with Makefile.PL for the one last time, then run the mymeta-cpanfile command: .PP .Vb 3 \& > perl Makefile.PL \& > mymeta\-cpanfile \-\-no\-configure \& requires \*(AqDBI\*(Aq, \*(Aq1.000\*(Aq; \& \& on test => sub { \& requires \*(AqTest::More\*(Aq, \*(Aq0.86\*(Aq; \& } \& \& ... .Ve .PP You can redirect the output to cpanfile if you like. It is important to pass \-\-no\-configure option here, since otherwise modules like ExtUtils::MakeMaker will be included. It is not required with Minilla setup, since Minilla knows which configuration tool (installer) to use and include them in \s-1META\s0 files upon the releases. You can leave that out from the cpanfile. .PP If you decide to manually construct new cpanfile, the format is mostly compatible to Module::Install's requirement \s-1DSL.\s0 .PP .Vb 3 \& # Makefile.PL \& test_requires \*(AqTest::More\*(Aq, 0.90; \& requires \*(AqPlack\*(Aq, \*(Aq1.000\*(Aq; .Ve .PP becomes: .PP .Vb 3 \& # cpanfile \& test_requires \*(AqTest::More\*(Aq, 0.90; \& requires \*(AqPlack\*(Aq, \*(Aq1.000\*(Aq; .Ve .PP which is exactly the same. If you use Module::Build or ExtUtils::MakeMaker, that will be more manual process, but basically the same thing. See cpanfile for the available syntax. .PP \fIRemove boilerplate\fR .IX Subsection "Remove boilerplate" .PP Next, remove unnecessary boilerplate files. .PP .Vb 1 \& > git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit .Ve .PP \fIEdit configurations\fR .IX Subsection "Edit configurations" .PP Edit .gitignore and add the following lines: .PP .Vb 3 \& /Dist\-Name\-* \& /.build \& !META.json .Ve .PP You're almost done, and your directory will look like: .PP .Vb 3 \& cpanfile \& lib/Dist/Name.pm \& t/... .Ve .PP \&\f(CW\*(C`git add\*(C'\fR the newly created files and commit it. .PP \fIMake a new build\fR .IX Subsection "Make a new build" .PP Now you're ready to make the first build. .PP .Vb 1 \& > minil build .Ve .PP and if it was successful, you get a build in a directory called \f(CW\*(C`Dist\-Name\-v0.1.0\*(C'\fR under your current directory. They can be later removed with \f(CW\*(C`minil clean\*(C'\fR command. .PP Also, new \f(CW\*(C`Build.PL\*(C'\fR, \f(CW\*(C`META.json\*(C'\fR and \f(CW\*(C`README.md\*(C'\fR are added in your working directory for git-friendliness. \f(CW\*(C`git add\*(C'\fR them and commit it. .PP .Vb 1 \& > git add Build.PL META.json README.md && git commit \-m "git stuff" .Ve .PP Now you're ready to roll a new release with Minilla. Before doing so, convert your \f(CW\*(C`Changes\*(C'\fR file format a little bit, and make sure you have a following header in the top: .PP .Vb 1 \& {{$NEXT}} \& \& \- Change log entry for the next version .Ve .PP The \f(CW\*(C`{{$NEXT}}\*(C'\fR is a template variable that gets replaced with the version and date string, when you make a next release. This is almost the \fIonly\fR change you're required to make in your code base. .PP Now, run the release command: .PP .Vb 1 \& > minil release .Ve .PP to make a new release, in the same way described above for a new Minilla setup. You can set \f(CW\*(C`FAKE_RELEASE\*(C'\fR environment variable if this is your first conversion and want to double check what happens, before uploading to \s-1CPAN.\s0 .PP When this is not your first release, the version number gets automatically bumped by Minilla, but you will be prompted if that is exactly the version you want, and if you want a major version up, you can specify to do so. .SH "AUTHOR" .IX Header "AUTHOR" Tokuhiro Matsuno .PP Tatsuhiko Miyagawa (Most of documents are taken from Dist::Milla::Tutorial!) .SH "SEE ALSO" .IX Header "SEE ALSO" Minilla, Dist::Milla::Tutorial