[Bps-public-commit] r12849 - Shipwright/trunk/lib/Shipwright/Manual

[spang at bestpractical.com]

Author: spang
Date: Tue Jun  3 14:24:18 2008
New Revision: 12849

Modified:
   Shipwright/trunk/lib/Shipwright/Manual/CustomizeBuild.pod

Log:
Initial update and polishing of CustomizeBuild.pod; the section on build
scripts still needs work.

Modified: Shipwright/trunk/lib/Shipwright/Manual/CustomizeBuild.pod
==============================================================================
--- Shipwright/trunk/lib/Shipwright/Manual/CustomizeBuild.pod	(original)
+++ Shipwright/trunk/lib/Shipwright/Manual/CustomizeBuild.pod	Tue Jun  3 14:24:18 2008
@@ -1,69 +1,74 @@
 =head1 NAME
 
-Shipwright::Manual::CustomizeBuild - Customize build way for a dist
+Shipwright::Manual::CustomizeBuild - Customize the build method for a
+distribution
 
 =head1 DESCRIPTION
 
-Now we support two ways to build a dist: a perl script (F<dists/foo/build.pl>) and a list of tagged commands(  F<dists/foo/build> ). 
+There are currently two ways to build a dist: through a perl script
+(F<dists/foo/build.pl>), or using a list of tagged commands (F<dists/foo/build>).
 
-F<dists/foo/build.pl> has higher precedence, so if there're both
-F<dists/foo/build.pl> and F<dists/foo/build>, the latter will be omitted.
+The script F<dists/foo/build.pl> has higher precedence, so if both
+F<dists/foo/build.pl> and F<dists/foo/build> exist, the former will be used.
 
 =head2 build.pl
 
-When executing F<build.pl>, the current working dir will be F<dists/foo>
+When executing F<build.pl> for the dist I<foo>, the current working directory
+will be F<dists/foo>
 
-The script will be ran with a list of arguments( the format is designed well
-to be extracted with L<Getopt::Long> easily): 
+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
 
-you'd be familiar with this :)
+The base directory where the vessel is to be built to.
 
-e.g. --install-base '/tmp/test-xxxxxx/test'
+e.g. C<--install-base '/tmp/test-xxxxxx/test'>
 
 =item --flags=s
 
-a list of flags, joined by comma.
+A list of flags, joined by comma.
 
-e.g. --flags default,mysql
+e.g. C<--flags default,mysql>
 
 =item --skip-test
 
-whether to skip test or not
+Whether to skip running tests or not.
 
 =item --force
 
-If test fails, whether to go on or just die.
+If any test fails, whether to go on or just die.
 
 =item --clean
 
-if provided with this arg, the script should do the C<clean> work instead of
+If provided with this arg, the script should do the C<clean> work instead of
 C<install> work.
 
 =back
 
 =head2 build
 
-This is a plain file, each line should be either blank or the format of 
-C<type: cmd>, the command will be executed line by line, and the current
-working dir will be F<dists/foo>.
+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 dist I<foo> will be F<dists/foo>.
+
+Three template substitutions are available for use in the command:
+%%PERL%%, %%PERL_ARCHNAME%% and %%INSTALL_BASE%%. These can be used in cases
+%where the path to perl, the perl archname (e.g.
+'i486-linux-gnu-thread-multi'), or the base install path are needed, since they
+are not known beforehand.
 
-Now we support three templates in cmd, %%PERL%%, %%PERL_ARCHNAME%% and
-%%INSTALL_BASE%%, so we don't need to set it until we know.
-
-There're two special types: C<test> and C<clean>
+There are two special types: C<test> and C<clean>.
 
 =over 4
 
 =item test
 
-- if with C<--skip-test>, this cmd won't be executed. 
-- if with C<--force>, even if the test cmd fails, we'll still go on building.
+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 with C<--clean>, all the cmds won't be executed but this one.
-
+If executed with C<--clean>, all commands will be skipped except this one.