@need 3200

@node Multi-tree Projects and Configuration Management
@chapter Multi-tree Projects and Configuration Management

You can define @geindex meta-projects
@dfn{meta-projects} which are combinations of individual
projects that are separately tracked by @code{arch}.  This allows you to
divide a large project into smaller, more manageable pieces, each of
which can develop independently of the others, and each of which can
be a part of more than one meta-project.


This is accomplished by writing @geindex config specs
@dfn{config specs}, which define the
contents of the meta-project and how they should be arranged in a
source tree.


For example, @code{arch} itself is a meta-project.  The source tree
contains:

@example
@group
        dists/
          dists/src/
            dists/src/arch/
            dists/src/file-utils/
            dists/src/ftp-utils/
            dists/src/hackerlab/
            dists/src/shell-utils/
@end group
@group
@end group
@end example

Each of those directories is the root of a project tree (contains a
subdirectory named @geindex @{arch@}
@dfn{@{arch@}}).


The topmost directory, @code{dists} also contains a subdirectory named
@code{configs}.  In that subdirectory are the meta-project configuration
files.  For example:

@example
@group
        dists/
          dists/configs/
            dists/configs/regexps.com/  # Tom's configuration files
              dists/configs/regexps.com/devo.arch
              dists/configs/regexps.com/release-template.arch
@end group
@group
@end group
@end example

Here are the contents of @code{devo.arch}:

@example
@group
     # 
     # Check out an arch distribution from the devo branches.  
     # Latest revisions.
     #
@end group
@group
@end group
@end example
@example
@group
     ./src                   lord@@regexps.com--2002/package-framework--devo
     ./src/arch              lord@@regexps.com--2002/arch--devo
     ./src/file-utils        lord@@regexps.com--2002/file-utils--devo
     ./src/ftp-utils         lord@@regexps.com--2002/ftp-utils--devo
     ./src/hackerlab         lord@@regexps.com--2002/hackerlab--devo
     ./src/shell-utils       lord@@regexps.com--2002/shell-utils--devo
     ./src/text-utils        lord@@regexps.com--2002/text-utils--devo
@end group
@group
@end group
@end example

Each (non-blank, non-comment) line in that file has the format:

@example
@group
        LOCATION             CONTENTS
@end group
@group
@end group
@end example

@noindent
which means, to create the meta-project, get the revision indicated by
@code{CONTENTS} and install it at @code{LOCATION}.  The @code{CONTENTS} field can be
a branch (meaning, get the latest revision of the latest version on
that branch), a version (meaning get the latest revision in that
version), or a revision name (meaning get that revision, exactly).


To check out an entire @code{arch} tree, I first check out @code{dists} from
@code{devo}, then use @code{build-config}:

@example
@group
        % larch get dists--devo dists
        [....]
@end group
@group
@end group
@end example
@example
@group
        % cd dists
@end group
@group
@end group
@end example
@example
@group
        % larch build-config regexps.com/dists.devo
        [....]
@end group
@group
@end group
@end example

Once you have a meta-project tree, some other useful commands are:

@example
@group
               update-config : update a multi-project tree
               replay-config : replay a multi-project tree
@end group
@group
@end group
@end example

Those commands recursively @code{update} or @code{replay} the sub-trees in a
meta-project.


One more configuration management command:

@example
@group
        % larch record-config GENERAL-CONFIG SPECIFIC-CONFIG
@end group
@group
@end group
@end example

That reads a config file, the @code{GENERAL-CONFIG}.  It examines the
project tree to see what revisions are actually installed at each of
the @code{LOCATIONs}.  Then it writes a new config file, the
@code{SPECIFIC-CONFIG} that has @code{CONTENTS} which specify those @code{REVISIONS}
precisely.   This is useful, for example, for recording the specific
revisions you are about to turn into a distribution.




