Part 0: What we've got

  P4/Modules.pm - a P4 module the reads an equivalent to the
		  cvs-modules file for mapping depot directories
		  into client directories or other branch directories.
		  And vice versa.  It's for writing scripts.
		  The public interface is pretty simple right now.

  bin/mkmodules.pl - a script to convert cvs-modules to p4-modules
  bin/mkbranch.pl  - a sample script for generating branch specs
  bin/mkclient.pl  - a sample script for generating client specs
  bin/c2pwhere.pl  - a sample script for mapping CVS directories back
			  into the depot.  Only useful for reference.

  bin/mkconvclient.pl - a script to map all of the branches for
			  all of the modules into a client spec.
			  Now that cvs2p4 supports P4::Modules, this
			  isn't really needed (and it makes for really
			  slow 'p4 where' commands).  Using the p4-modules
                          file from mkmodules.pl is the recommended practice.


Part 1: Getting ready to use P4::Modules


  CREATING A P4 MODULES FILE

To create a p4 modules file, use the mkmodules script.  This takes a
CVS modules file and creates an equivalent one that can be used by
the P4::Modules Perl module.

Obtain the use info with:

    mkmodules.pl -h


For an example of a mapfile, see sample.depotmap.
For an example of a CVS files regexp file, see sample.cvs-files.

The output of mkmodules can be saved and used as the modules definitions
for the other scripts.



  CREATING A CONVERSION CLIENT

To create a Perforce client spec which can be used to map all of the modules
and any branches desired into a Perforce client workspace.  You can import
the client spec into perforce with a command like:

    mkconvclient [ options ] | p4 client -i


Obtain the use info with:

    mkconvclient.pl -h


For an example of a branches file, see sample.branches.
For an example of a modules file, see sample.modules.



Part 2: Using P4::Modules


  CREATING A CLIENT SPEC

Use the mkclient.pl script to generate a Perforce client spec with the P4
modules and branches that you desire.  This script will only give you one
version of each module but you can mix and match which versions of each
module are mapped out of the Perforce depot.

You can import the client spec into perforce with a command like:

    mkclient [ options ] | p4 client -i


Obtain the use info with:

    mkclient.pl -h


For an example of a config file, see sample.mkclient.
For an example of a modules file, see sample.modules.



  CREATING A BRANCH SPEC

Use the mkbranch.pl script to generate a Perforce branch spec with the P4
modules and branches that you desire.  This script will only give you one
version of each module but you can mix and match which versions of each
module are branched to the new branch location.

You can import the branch spec into perforce with a command like:

    mkbranch [ options ] | p4 branch -i


Obtain the use info with:

    mkbranch.pl -h


For an example of a config file, see sample.mkbranch.
For an example of a modules file, see sample.modules.



  DETERMINING WHERE A CVS FILE IS IN THE DEPOT and
  FINDING DUPLICATELY MAPPED DIRECTORIES

Use the c2pwhere.pl script for this.  Given a path (and branch) under
CVSROOT, it will return the location in the depot.  As a side effect,
c2pwhere.pl also warns of conflicting file mappings.


Obtain the use info with:

    c2pwhere.pl -h


Example:

        ./bin/c2pwhere -b 0.5 -f atg.modules /atg/atginstall/lib/...
  or    ./bin/c2pwhere -b 0.5 -f atg.modules /atg/atginstall/lib/somefile

  example output is:

        //products/DAS/0.5/atg/atginstall/lib/...
  or    //products/DAS/0.5/atg/atginstall/lib/somefile

  NOTE: The path argument isn't the full path.  It's relative to CVSROOT.