Maintenance.html

<html><head><title>VCP::Maintenance - VCP code maintenance tips &amp; tricks</title></head><body><h1><a name="NAME">NAME
 
</a></h1><p>VCP::Maintenance - VCP code maintenance tips &amp; tricks
 
<p><hr><h1><a name="SYNOPSIS">SYNOPSIS
 
</a></h1><pre> VCPNODELETE=yes
 
</pre><pre> bin/hexdump.pl
 
</pre><pre> vcp revml: --dtd &lt;dtd file name&gt; --save_dtd &lt;how&gt;
 
</pre><p><hr><h1><a name="DESCRIPTION">DESCRIPTION
 
</a></h1><h2><a name="Teh_distribution_hierarchy">Teh distribution hierarchy
 
</a></h2><p>As untarred, the distribution hierarchy looks like (some files not
show for brevity):
 
<pre>   VCP-x.yy/
   +--- Makefile.PL     ## Generates the Makefile
   +--- MANIFEST        ## what files to ship, built with `make manifest`
   +--- MANIFEST.SKIP   ## what filenames `make manifest` should ignore
   +--- CHANGES         ## A detailed summart of all edits
   +--- TODO            ## Things we can't get to quite yet
   +--- LICENSE
   +--- README
   +--- revml.dtd       ## Defines legal RevML
   +--+ bin/            ## Executable files
   |  +---- vcp         ## The command line interface
   |  +---- gentrevml   ## builds RevML files for the test suite
   |  +---- hexdump.pl  ## dumps files in hex, a debugging aid
   |
   +--+ lib/            ## All modules that comprize VCP itself
   |  +--- VCP.pm       ## Drives the VCP process
   |  +--- *.pod        ## Supplemental documentation
   |  +--- Plugin.pm    ## Base class for all sources &amp; destinations
   |  |
   |  +--- Source.pm    ## Base class for all sources
   |  +--+ Source/
   |  |  +--- foo.pm    ## A backend to read from repo. type &quot;foo&quot;
   |  |
   |  +--- Dest.pm      ## Base class for all destinations
   |  +--+ Dest/
   |  |  +--- foo.pm    ## A backend to write to repo. type &quot;foo&quot;
   |  |
   |  +--+ Utils/
   |  |  +--- foo.pm    ## Routines shared by Source/ and Dest/ foo.pm's
   |  |
   |  +--- Rev.pm       ## VCP's concept of a revision
   |  +--- Revs.pm      ## A collection of VCP::Rev instances
   |  |
   |  +--- RevML/       ## Files defining RevML
   |
   +--+ t/              ## The test suite
      +--- *.t          ## Test scripts
      +--- test-*.revml ## Fodder for test scripts
 
</pre><p>In addition, the following files are created:
 
<pre>   |
   +--- vcp_html        ## By running the `vcp html` command
   +--- pod2htm*        ## Gunk left over from `vcp html`
   +--- blib/           ## By running `make`
 
</pre><h2><a name="Useful_command_line_idioms">Useful command line idioms
 
</a></h2><dl><dt><a name="perl_Ilib_cw_"><strong><p>perl -Ilib -cw %
 
</strong></a><dd>(in your editor's key mapping).
 
<p>Useful to map an editor key to this.  Use whatever path for -I works
given your cwd usage habit, and replace the &quot;%&quot; with whatever macro your
editor replaces with the path to the current file.
 
<dt><a name="make_test_TEST_FILES_t_90foo_t_TEST_VERBOSE_1_"><strong><p>make test TEST_FILES=t/90foo.t TEST_VERBOSE=1
 
</strong></a><dd>Runs just the listed test files (space separated list; use quotes) and
shows STDOUT.
 
<dt><a name="perl_Ilib_bin_vcp_"><strong><p>perl -Ilib bin/vcp ...
 
</strong></a><dd>Run <code>vcp</code> manually without setting PERL5LIB or installing it.
 
<dt><a name="export_PERL5LIB_lib_"><strong><p>export PERL5LIB=lib
 
</strong></a><dd>Allows <code>vcp</code> and <code>gentrevml</code> to be run from command line
 
<dt><a name="make_test_"><strong><p>make test
 
</strong></a><dd>Runs all tests, generating <code>t/test-*.revml</code> if need be.
 
</dl><h2><a name="Environment_Variables">Environment Variables
 
</a></h2><p>Some environment variables that are useful in debugging:
 
<dl><dt><a name="VCPNODELETE_"><strong><p>VCPNODELETE
 
</strong></a><dd>Set this to <code>yes</code> to tell <code>vcp</code> <i>not</i> to delete it's working
directories.  This allows you to take a look at them and see what
the source and dest command lines saw.
 
<dt><a name="IPCRUNDEBUG_"><strong><p>IPCRUNDEBUG
 
</strong></a><dd>Set this to some number from 0..10 to see how <code>vcp</code> (via <a>IPC::Run</a>)
is treating it's subprocesses.
 
<dt><a name="VCPDEBUG_"><strong><p>VCPDEBUG
 
</strong></a><dd>Set this to a regular expression to control what modules within <code>VCP::*</code>
emit debugging messages.
 
<p>See also <a>VCP::Debug</a> for more details.
 
</dl><p>In addition, both CVS and Perforce backends pay attention to the relevant
environment variables.
 
<h2><a name="hexdump_pl"><code>hexdump.pl</code>
 
</a></h2><p><code>bin/hexdump.pl</code> is useful for debugging issues involving line endings,
embedded control code (esp. ^Z on Win32 and NULL on every platform, since most
C programs die when encountering NULL in a text file).
 
<h2><a name="The_tests">The tests
 
</a></h2><p>The t/*.t files in the source distribution contain a large number of
tests.  The tests begin with a two digit number that orders them so that
more primitive tests run first, followed by higher level &quot;end-to-end&quot;
tests in <code>t/90*.t</code>.
 
<p>The more primitive tests are pretty standard fare for Perl test suites.
Where things get interesting is the <code>t/90*.t</code> tests.  These tests use the
command-line <code>vcp</code> interface to move reasonably sized chunks of RevML
(up to about 65k currently; pretty small in comparison to &quot;real&quot;
exports) in to, out of, and between various repositories.
 
<p>The RevML extracted from the repositories is compared to the RevML that
was fed in to them, after sanitizing both of data that is known to not
make it through ok.
 
<p>The module <a>VCP::TestUtils</a> contains support routines
for initializing repositories and shutting them down (when a server is
needed).  Existing repositories are not used in the test suite; they'd
be useless and in danger if we did.
 
<p>The file <code>bin/gentrevml</code> is used to generate the RevML files
(<code>t/test*.revml</code>) from scratch using hand written code instead of
<a href="Dest/revml.html">VCP::Dest::revml</a> in order to reduce the chances of a bug in
VCP::Dest::revml causing false positives in the test results.
 
<p>It's highly likely that new back ends will require new test RevML files.
<code>bin/gentrevml</code> should be hacked up to generate these and new rules
should be added to the <code>Makefile</code> by editing <code>Makefile.PL</code>.
 
<h3><a name="The_structure_of_a_test_script_">The structure of a test script.
 
</a></h3><p>The t/*.t scripts generally all follow the same structure.
 
<p>First, they import all necessary modules and init themselves.
 
<p>Then they build a
 
<pre>   my @tests = (
   sub {
       ...
   },
   );
   
</pre><p>array that contain the actual tests.  Each
test is a single anonymous <code>sub {...}</code>, every once in a while a single
<code>sub {...}</code> will contain two tests; it is preceded by an empty (or nearly
empty) <code>sub {}</code> in these cases.
 
<p>At the bottom, some final checks are run to see if all tests should be
skipped, then
 
<pre>   plan tests =&gt; scalar @tests;
 
</pre><p>emits how many tests are to be run, and
 
<pre>   $_-&gt;() for @tests;
 
</pre><p>runs the tests.
 
<p>This structure is used for several reasons:
 
<dl><dt><a name="1_No_counting_tests_"><strong><p>1. No counting tests
 
</strong></a><dd>Tests are counted automatically for you this way, the <code>scalar @tests</code>
does this.  Otherwise you end up having to remember to manually fudge
this every time a test is adding or removed.
 
<dt><a name="2_Clear_demarcation_"><strong><p>2. Clear demarcation
 
</strong></a><dd>Tests tend to use local variables a lot; this structure keeps them from
&quot;leaking&quot; from one test to another.  Things that are shared between
tests are usually declared right above the <code>my @tests =</code> line and are
pretty obvious.
 
<dt><a name="3_Commenting_out_tests_"><strong><p>3. Commenting out tests
 
</strong></a><dd>In situations where you want to focus on one or a few tests, just put a
line like:
 
<pre>    ); @tests = (
 
</pre><p>before the first test <code>sub</code> you want to run, and a line like
 
<pre>   sub { last },
 
</pre><p>after the last one.  This is especially important
 
<dt><a name="4_Test_line_numbers_"><strong><p>4. Test line numbers
 
</strong></a><dd>Failing tests, when run with <code>TEST_VERBOSE=1</code> as shown above, will
report their line numbers.  This is the fastest way to find out what's
failing.  The list-of-subs approach is used even when <code>@tests</code> could
actually contain just test vectors and the <code>for @tests </code> loop could
check the vectors because we want line numbers to tell us where to look.
If we used test vectors, then the call to <code>ok()</code> would report some line
number in the <code>for @tests</code> loop, not the line number of the test.
 
<dt><a name="5_"><strong><p>5.
 
</strong></a><dd>If you want to enable <code>vcp</code> or <a>IPC::Run</a> debugging (see
<a>VCP::Debug</a>, too), you can put a
 
<pre>   local $ENV{VCPDEBUG} = '.*';
 
</pre><p>or
 
<pre>   local $ENV{IPCRUNDEBUG} = 1;  ## 1..10
 
</pre><p>in the appropriate <code>sub {...}</code> and it won't cause all the other tests
to spew a lot of noise.
 
</dl><h2><a name="Developing_a_new_backend">Developing a new backend
 
</a></h2><p>In general, backends are created in pairs so that a <code>t/90foo.t</code> can be
written to import the RevML files in to the backend repository, extract
new RevML from it, and compare the two.
 
<p>A backend usually consists of 3 Perl classes: VCP::Source::foo,
VCP::Dest::foo, and VCP::Utils::foo.  The reason for the lowercase
final name is so that the <code>vcp</code> command can translate from the scheme
name (<code>cvs:</code>) to a source or destination module name trivially.
 
<p>The VCP::Source::foo generally contains a parser to extract metadata
from repository log reports and a routine to drive the copying process.
The <a>VCP</a> module (<code>/lib/VCP.pm</code>)
 
<h2><a name="Updating_the_RevML_DTD">Updating the RevML DTD
 
</a></h2><p>There is one command used for maintainance: <code>save_dtd</code>. This should not be
necessary in the normal course of events; it's only needed if the RevML DTD has
changed.  Here's how it looks:
 
<p>This outputs the DTD to stdout if <code>&lt;how&gt;</code> is <code>-</code>, or to a file named
like <code>v0_28.pm</code> if <code>&lt;how&gt;</code> looks like a version number (0.28 in this
case), or in a module named <code>&lt;how&gt;</code> if <code>&lt;how&gt;</code> contains '::'.
 
<p>The generated file is placed in <code>./lib/RevML/Doctype/</code> or <code>./RevML/Doctype/</code>
or <code>./</code>, whichever is found first.  No directories will be created.
 
<p>This does not update the <a href="Source/revml.html">VCP::Source::revml</a> or
<a href="Dest/revml.html">VCP::Dest::revml</a> drivers to match the DTD, nor does
it affect <code>bin/gentrevml</code>, which is used by the test suite to build the
RevML files used for testing.
 
<p><hr><h1><a name="AUTHOR">AUTHOR
 
</a></h1><p>Barrie Slaymaker &lt;barries@slaysys.com&gt;
 
<p><hr><h1><a name="COPYRIGHT">COPYRIGHT
 
</a></h1><p>Copyright (c) 2000, 2001, Perforce Software, Inc.
All rights reserved.
 
<p>See <a href="License.html">VCP::License</a> (<code>vcp help license</code>) for the terms of use.
 
<p><hr><i><font size="-1">Last updated: Fri Nov  8 13:07:23 2002</font></i></body></html>
#	Change	User	Description	Committed
#1	4311	alan_teague	Initial versions of productization files and scripts. All are draft quality submi...tted for review. «	21 years ago