README.md

   1 # NAME
   2
   3 Distar - Additions to ExtUtils::MakeMaker for dist authors
   4
   5 # SYNOPSIS
   6
   7 `Makefile.PL`:
   8
   9     use ExtUtils::MakeMaker;
  10     (do './maint/Makefile.PL.include' or die $@) unless -f 'META.yml';
  11
  12     WriteMakefile(...);
  13
  14 `maint/Makefile.PL.include`:
  15
  16     BEGIN { -e 'Distar' or system qw(git clone https://github.com/p5sagit/Distar.git) }
  17     use lib 'Distar/lib';
  18     use Distar 0.001;
  19
  20     author 'A. U. Thor <author@cpan.org>';
  21
  22     manifest_include t => 'test-helper.pl';
  23     manifest_include corpus => '.txt';
  24
  25 make commmands:
  26
  27     $ perl Makefile.PL
  28     $ make bump             # bump version
  29     $ make bump V=2.000000  # bump to specific version
  30     $ make bumpminor        # bump minor version component
  31     $ make bumpmajor        # bump major version component
  32     $ make nextrelease      # add version heading to Changes file
  33     $ make releasetest      # build dist and test (with xt/ and RELEASE_TESTING=1)
  34     $ make preflight        # check that repo and file state is release ready
  35     $ make release          # check releasetest and preflight, commits and tags,
  36                             # builds and uploads to CPAN, and pushes commits and
  37                             # tag
  38     $ make release FAKE_RELEASE=1
  39                             # builds a release INCLUDING committing and tagging,
  40                             # but does not upload to cpan or push anything to git
  41
  42 # DESCRIPTION
  43
  44 [ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils%3A%3AMakeMaker) works well enough as development tool for
  45 builting and testing, but using it to release is annoying and error prone.
  46 Distar adds just enough to [ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils%3A%3AMakeMaker) for it to be a usable dist
  47 author tool.  This includes extra commands for releasing and safety checks, and
  48 automatic generation of some files.  It doesn't require any non-core modules and
  49 is compatible with old versions of perl.
  50
  51 # FUNCTIONS
  52
  53 ## author( $author )
  54
  55 Set the author to include in generated META files.  Can be a single entry, or
  56 an arrayref.
  57
  58 ## manifest\_include( $dir, $pattern )
  59
  60 Add a pattern to include files in the MANIFEST file, and thus in the generated
  61 dist files.
  62
  63 The pattern can be either a regex, or a path suffix.  It will be applied to the
  64 full path past the directory specified.
  65
  66 The default files that are always included are: `.pm` and `.pod` files in
  67 `lib`, `.t` files in `t` and `xt`, `.pm` files in `t/lib` and `xt/lib`,
  68 `Changes`, `MANIFEST`, `README`, `LICENSE`, `META.yml`, and `.PL` files in
  69 the dist root, and all files in `maint`.
  70
  71 # AUTOGENERATED FILES
  72
  73 - `MANIFEST.SKIP`
  74
  75     The `MANIFEST.SKIP` will be automatically generated to exclude any files not
  76     explicitly allowed via `manifest_include` or the included defaults.  It will be
  77     created (or updated) at `perl Makefile.PL` time.
  78
  79 - `README`
  80
  81     The `README` file will be generated at dist generation time, inside the built
  82     dist.  It will be generated using `pod2text` on the main module.
  83
  84     If a `README` file exists in the repo, it will be used directly instead of
  85     generating the file.
  86
  87 # MAKE COMMMANDS
  88
  89 ## test
  90
  91 test will be adjusted to include `xt/` tests by default.  This will only apply
  92 for authors, not users installing from CPAN.
  93
  94 ## release
  95
  96 Releases the dist.  Before releasing, checks will be done on the dist using the
  97 `preflight` and `releasetest` commands.
  98
  99 Releasing will generate a dist tarball and upload it to CPAN using cpan-upload.
 100 It will also create a git tag for the release, and push the tag and branch.
 101
 102 ### FAKE\_RELEASE
 103
 104 If release is run with FAKE\_RELEASE=1 set, it will skip uploading to CPAN and
 105 pushing to git.  A release commit will still be created and tagged locally.
 106
 107 ## preflight
 108
 109 Performs a number of checks on the files and repository, ensuring it is in a
 110 sane state to do a release.  The checks are:
 111
 112 - All version numbers match
 113 - The `MANIFEST` file is up to date
 114 - The branch is correct
 115 - There is no existing tag for the version
 116 - There are no unmerged upstream changes
 117 - There are no outstanding local changes
 118 - There is an appropriate staged Changes heading
 119 - cpan-upload is available
 120
 121 ## releasetest
 122
 123 Test the dist preparing for a release.  This generates a dist dir and runs the
 124 tests from inside it.  This ensures all appropriate files are included inside
 125 the dist.  `RELEASE_TESTING` will be set in the environment.
 126
 127 ## nextrelease
 128
 129 Adds an appropriate changelog heading for the release, and prompts to stage the
 130 change.
 131
 132 ## bump
 133
 134 Bumps the version number.  This will try to preserve the length and format of
 135 the version number.  The least significant digit will be incremented.  Versions
 136 with underscores will preserve the underscore in the same position.
 137
 138 Optionally accepts a `V` option to set the version to a specific value.
 139
 140 The version changes will automatically be committed.  Unstaged modifications to
 141 the files will be left untouched.
 142
 143 ### V
 144
 145 The V option will be passed along to the version bumping script.  It can accept
 146 a space separated list of options, including an explicit version number.
 147
 148 Options:
 149
 150 - --force
 151
 152     Updates version numbers even if they do not match the current expected version
 153     number.
 154
 155 - --stable
 156
 157     Attempts to convert the updated version to a stable version, removing any
 158     underscore.
 159
 160 - --alpha
 161
 162     Attempts to convert the updated version to an alpha version, adding an
 163     underscore in an appropriate place.
 164
 165 ## bumpminor
 166
 167 Like bump, but increments the minor segment of the version.  This will treat
 168 numeric versions as x.yyyzzz format, incrementing the yyy segment.
 169
 170 ## bumpmajor
 171
 172 Like bumpminor, but bumping the major segment.
 173
 174 ## refresh
 175
 176 Updates Distar and re-runs `perl Makefile.PL`
 177
 178 # SUPPORT
 179
 180 IRC: #web-simple on irc.perl.org
 181
 182 Git repository: [git://git.shadowcat.co.uk/p5sagit/Distar](git://git.shadowcat.co.uk/p5sagit/Distar)
 183
 184 Git browser: [http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Distar.git;a=summary](http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Distar.git;a=summary)
 185
 186 # AUTHOR
 187
 188 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 189
 190 # CONTRIBUTORS
 191
 192 haarg - Graham Knop (cpan:HAARG) <haarg@cpan.org>
 193
 194 ether - Karen Etheridge (cpan:ETHER) <ether@cpan.org>
 195
 196 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
 197
 198 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
 199
 200 # COPYRIGHT
 201
 202 Copyright (c) 2011-2015 the Distar ["AUTHOR"](#author) and ["CONTRIBUTORS"](#contributors)
 203 as listed above.
 204
 205 # LICENSE
 206
 207 This library is free software and may be distributed under the same terms
 208 as perl itself. See [http://dev.perl.org/licenses/](http://dev.perl.org/licenses/).