1package Dist::Zilla::App::Command::build 6.024;
2# ABSTRACT: build your dist
3
4# BEGIN BOILERPLATE
5use v5.20.0;
6use warnings;
7use utf8;
8no feature 'switch';
9use experimental qw(postderef postderef_qq); # This experiment gets mainlined.
10# END BOILERPLATE
11
12use Dist::Zilla::App -command;
13
14#pod =head1 SYNOPSIS
15#pod
16#pod   dzil build [ --trial ] [ --tgz | --no-tgz ] [ --in /path/to/build/dir ]
17#pod
18#pod =head1 DESCRIPTION
19#pod
20#pod This command is a very thin layer over the Dist::Zilla C<build> method, which
21#pod does all the things required to build your distribution.  By default, it will
22#pod also archive your distribution and leave you with a complete, ready-to-release
23#pod distribution tarball.
24#pod
25#pod To go a bit further in depth, the C<build> command will do two things:
26#pod
27#pod =over
28#pod
29#pod =item
30#pod
31#pod Generate a directory containing your module, C<Foo-0.100>. This directory is
32#pod complete. You could create a gzipped tarball from this directory and upload it
33#pod directly to C<PAUSE> if you so desired. You could C<cd> into this directory and
34#pod test your module on Perl installations where you don't have C<Dist::Zilla>, for
35#pod example.
36#pod
37#pod This is a default behavior of the C<build> command. You can alter where it puts
38#pod the directory with C<--in /path/to/build/dir>.
39#pod
40#pod =item
41#pod
42#pod Generate a gzipped tarball of your module, C<Foo-0.100.tar.gz>. This file
43#pod could be uploaded directly to C<PAUSE> to make a release of your module if you
44#pod wanted. Or, you can test your module: C<cpanm --test-only Foo-0.100.tar.gz>.
45#pod This is the same thing you would get if you compressed the directory described
46#pod above.
47#pod
48#pod The gzipped tarball is generated by default, but if you don't want it to be
49#pod generated, you can pass the C<--no-tgz> option. In that case, it would only
50#pod generate the directory described above.
51#pod
52#pod =back
53#pod
54#pod Once you're done testing or publishing your build, you can clean up everything
55#pod with a C<dzil clean>.
56#pod
57#pod =cut
58
59sub abstract { 'build your dist' }
60
61#pod =head1 EXAMPLE
62#pod
63#pod   $ dzil build
64#pod   $ dzil build --no-tgz
65#pod   $ dzil build --in /path/to/build/dir
66#pod
67#pod =cut
68
69sub opt_spec {
70  [ 'trial'  => 'build a trial release that PAUSE will not index'      ],
71  [ 'tgz!'   => 'build a tarball (default behavior)', { default => 1 } ],
72  [ 'in=s'   => 'the directory in which to build the distribution'     ]
73}
74
75#pod =head1 OPTIONS
76#pod
77#pod =head2 --trial
78#pod
79#pod This will build a trial distribution.  Among other things, it will generally
80#pod mean that the built tarball's basename ends in F<-TRIAL>.
81#pod
82#pod =head2 --tgz | --no-tgz
83#pod
84#pod Builds a .tar.gz in your project directory after building the distribution.
85#pod
86#pod --tgz behaviour is by default, use --no-tgz to disable building an archive.
87#pod
88#pod =head2 --in
89#pod
90#pod Specifies the directory into which the distribution should be built.  If
91#pod necessary, the directory will be created.  An archive will not be created.
92#pod
93#pod =cut
94
95sub execute {
96  my ($self, $opt, $args) = @_;
97
98  if ($opt->in) {
99    require Path::Tiny;
100    die qq{using "--in ." would destroy your working directory!\n}
101      if Path::Tiny::path($opt->in)->absolute eq Path::Tiny::path('.')->absolute;
102
103    $self->zilla->build_in($opt->in);
104  } else {
105    my $method = $opt->tgz ? 'build_archive' : 'build';
106    my $zilla;
107    {
108      # isolate changes to RELEASE_STATUS to zilla construction
109      local $ENV{RELEASE_STATUS} = $ENV{RELEASE_STATUS};
110      $ENV{RELEASE_STATUS} = 'testing' if $opt->trial;
111      $zilla  = $self->zilla;
112    }
113    $zilla->$method;
114  }
115
116  $self->zilla->log('built in ' . $self->zilla->built_in);
117}
118
1191;
120
121__END__
122
123=pod
124
125=encoding UTF-8
126
127=head1 NAME
128
129Dist::Zilla::App::Command::build - build your dist
130
131=head1 VERSION
132
133version 6.024
134
135=head1 SYNOPSIS
136
137  dzil build [ --trial ] [ --tgz | --no-tgz ] [ --in /path/to/build/dir ]
138
139=head1 DESCRIPTION
140
141This command is a very thin layer over the Dist::Zilla C<build> method, which
142does all the things required to build your distribution.  By default, it will
143also archive your distribution and leave you with a complete, ready-to-release
144distribution tarball.
145
146To go a bit further in depth, the C<build> command will do two things:
147
148=over
149
150=item
151
152Generate a directory containing your module, C<Foo-0.100>. This directory is
153complete. You could create a gzipped tarball from this directory and upload it
154directly to C<PAUSE> if you so desired. You could C<cd> into this directory and
155test your module on Perl installations where you don't have C<Dist::Zilla>, for
156example.
157
158This is a default behavior of the C<build> command. You can alter where it puts
159the directory with C<--in /path/to/build/dir>.
160
161=item
162
163Generate a gzipped tarball of your module, C<Foo-0.100.tar.gz>. This file
164could be uploaded directly to C<PAUSE> to make a release of your module if you
165wanted. Or, you can test your module: C<cpanm --test-only Foo-0.100.tar.gz>.
166This is the same thing you would get if you compressed the directory described
167above.
168
169The gzipped tarball is generated by default, but if you don't want it to be
170generated, you can pass the C<--no-tgz> option. In that case, it would only
171generate the directory described above.
172
173=back
174
175Once you're done testing or publishing your build, you can clean up everything
176with a C<dzil clean>.
177
178=head1 PERL VERSION
179
180This module should work on any version of perl still receiving updates from
181the Perl 5 Porters.  This means it should work on any version of perl released
182in the last two to three years.  (That is, if the most recently released
183version is v5.40, then this module should work on both v5.40 and v5.38.)
184
185Although it may work on older versions of perl, no guarantee is made that the
186minimum required version will not be increased.  The version may be increased
187for any reason, and there is no promise that patches will be accepted to lower
188the minimum required perl.
189
190=head1 EXAMPLE
191
192  $ dzil build
193  $ dzil build --no-tgz
194  $ dzil build --in /path/to/build/dir
195
196=head1 OPTIONS
197
198=head2 --trial
199
200This will build a trial distribution.  Among other things, it will generally
201mean that the built tarball's basename ends in F<-TRIAL>.
202
203=head2 --tgz | --no-tgz
204
205Builds a .tar.gz in your project directory after building the distribution.
206
207--tgz behaviour is by default, use --no-tgz to disable building an archive.
208
209=head2 --in
210
211Specifies the directory into which the distribution should be built.  If
212necessary, the directory will be created.  An archive will not be created.
213
214=head1 AUTHOR
215
216Ricardo SIGNES �� <rjbs@semiotic.systems>
217
218=head1 COPYRIGHT AND LICENSE
219
220This software is copyright (c) 2021 by Ricardo SIGNES.
221
222This is free software; you can redistribute it and/or modify it under
223the same terms as the Perl 5 programming language system itself.
224
225=cut
226