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

[sunnavy at bestpractical.com]

Author: sunnavy
Date: Sun Mar 23 15:49:55 2008
New Revision: 11163

Added:
   Shipwright/trunk/lib/Shipwright/Manual/CustomizeBuild.pod
   Shipwright/trunk/lib/Shipwright/Manual/UsingFlags.pod

Log:
added more pods

Added: Shipwright/trunk/lib/Shipwright/Manual/CustomizeBuild.pod
==============================================================================
--- (empty file)
+++ Shipwright/trunk/lib/Shipwright/Manual/CustomizeBuild.pod	Sun Mar 23 15:49:55 2008
@@ -0,0 +1,69 @@
+=head1 NAME
+
+Shipwright::Manual::CustomizeBuild - Customize build way for a dist
+
+=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> ). 
+
+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.
+
+=head2 build.pl
+
+When executing F<build.pl>, the current working dir 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): 
+
+=over 4
+
+=item --install-base=s
+
+you'd be familiar with this :)
+
+e.g. --install-base '/tmp/test-xxxxxx/test'
+
+=item --flags=s
+
+a list of flags, joined by comma.
+
+e.g. --flags default,mysql
+
+=item --skip-test
+
+whether to skip test or not
+
+=item --force
+
+If 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
+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>.
+
+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>
+
+=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.
+
+=item clean
+
+if with C<--clean>, all the cmds won't be executed but this one.
+

Added: Shipwright/trunk/lib/Shipwright/Manual/UsingFlags.pod
==============================================================================
--- (empty file)
+++ Shipwright/trunk/lib/Shipwright/Manual/UsingFlags.pod	Sun Mar 23 15:49:55 2008
@@ -0,0 +1,45 @@
+=head1 NAME
+
+Shipwright::Manual::UsingFlags - Using Flags
+
+=head1 DESCRIPTION
+
+B<Flags> is supported since 1.10.
+
+It's another way to skip some dists, and even more...
+
+Imagining you want to create a project, there're several database types
+you want to support, while for each B<vessel>, you'd like users to choose only 
+one type.( sometimes you have to choose one because some other dists
+will be confused if provided more than one type. e.g. for RT, you have to
+supply the database type when ./configure ).
+
+Well, B<Flags> is right for this.
+
+e.g. you want to support both mysql and postgresql, and you've imported mysql, DBD::mysql( will be named as cpan-DBD-mysql), postgresql and DBD::Pg( cpan-DBD-Pg).
+
+then you need to mark dists with flags, let's say they are C<mysql> and
+C<postgresql>.
+
+    $ shipwright flags set mysql mysql
+    $ shipwright flags set cpan-DBD-mysql mysql
+    $ shipwright flags set postgresql postgresql
+    $ shipwright flags set cpan-DBD-Pg postgresql
+
+B<Flags> related things are stored in F<shipwright/flags.yml>
+
+So when building you can set C<--flags> arg to C<mysql> or C<postgresql> to
+install that type db and related stuff only.
+
+If a dist need this info to configure( RT in our example ), you'll need
+to customize the build script, see L<Shipwright::Manual::CustomizeBuild> for
+more info about that.
+
+Note:
+
+Shipwright will automatically add C<default> to C<--flags> args, and if one dist isn't set flags at all( so no such item in F<shipwright/flags.yml> ), it'll be the same as C<default> so it can be installed by default. 
+
+=head1 SEE ALSO
+
+L<Shipwright::Manual::CustomizeBuild>
+