=head1 NAME

Shipwright::Manual::CustomizeBuild - Customize the build method for a source


=head1 DESCRIPTION

There are currently two ways to build a source: through a perl script
(F<scripts/foo/build.pl>) which allows for heavy customization, or using a list
of tagged commands (F<scripts/foo/build>), which is simpler but less
customizable.

F<scripts/foo/build.pl> has higher precedence, so if both
F<scripts/foo/build.pl> and F<scripts/foo/build> exist, the former will be used.

=head2 build.pl

When executing F<build.pl> for the source I<foo>, the current working directory
will be F<dists/foo>

The script will be run with a list of arguments (the format is designed
to be easily extracted with L<Getopt::Long>): 

=over 4

=item --install-base=s

The base directory where the vessel is to be built to.

e.g. C<--install-base '/tmp/test-xxxxxx/test'>

=item --flags=s

A list of flags, joined by comma. (See L<Shipwright::Manual::UsingFlags> for
more information.)

e.g. C<--flags default,mysql>

=item --skip-test

Whether to skip running tests or not.

=item --force

If any test fails, whether to go on or just die.

=item --clean

If run with this argument, the script should do the C<clean> work instead of
the C<install> work.

=back

=head2 build

This is a text file; each line should be either blank or use the format
C<type: command>. The command will be executed line by line, and the current
working directory for building the source I<foo> will be F<dists/foo>.

In a normal build script, the following types of commands are specified:
configure, make, install, clean, and sometimes test. Their functions should be
self-explanatory for anyone familiar with building perl modules.

Four template substitutions are available for use in the command:
C<%%PERL%%>, C<%%PERL_ARCHNAME%%>, C<%%INSTALL_BASE%%> and C<%%MAKE%%>.
These can be used in cases where the path to perl, the perl archname (e.g.
'i486-linux-gnu-thread-multi'), the base install path or make command 
are needed, since they are not known beforehand or need to choose one later.

There are two special types: C<test> and C<clean>.

=over 4

=item test

If executed with C<--skip-test>, this command won't be executed.
If executed with C<--force>, even if this command fails the build will continue.

=item clean

If executed with C<--clean>, all commands will be skipped except this one.

=back

=head1 SEE ALSO

L<Shipwright>, L<Shipwright::Manual>

=head1 AUTHORS

sunnavy  C<< <sunnavy@bestpractical.com> >>

=head1 LICENCE AND COPYRIGHT

Shipwright is Copyright 2007-2012 Best Practical Solutions, LLC.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.