@need 3200

@node Multi-Tree Projects
@chapter Multi-Tree Projects

Large projects are often most naturally divided into a number of
independently maintained sub-projects.  For example, @code{arch} itself
consists of six separate projects:

@example
@group
        ./src
                A generic top-level source file for combining
                projects.
@end group
@group
@end group
@end example
@example
@group
        ./src/arch
                arch itself.  That is, the `arch' command and all of
                the shell scripts that implement it.
@end group
@group
@end group
@end example
@example
@group
        ./src/file-utils
                Generic utilities for operating on files and
                directories.
@end group
@group
@end group
@end example
@example
@group
        ./src/ftp-utils
                A scriptable FTP client.
@end group
@group
@end group
@end example
@example
@group
        ./src/hackerlab
                The hackerlab C library.
@end group
@group
@end group
@end example
@example
@group
        ./src/text-utils
                Generic utilities for operating on text files.
@end group
@group
@end group
@end example

In an @code{arch} source tree, each of those sub-directories is a separate
project tree (each has its own @code{@{arch@}} subdirectory;  each was
initialized by the command @code{larch init-tree};  each is in a separate
category in the repository).


To put all the pieces together, use the @code{arch} @geindex configuration
commands
@dfn{configuration
commands}:


(TO BE DOCUMENTED:)


Config file format, e.g.:

@example
@group
    ./configs/regexps.com/devo.arch:
@end group
@group
@end group
@end example
@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

@noindent
and

@example
@group
  % larch build-config --help
  instantiate a multi-project tree
  usage: build-config [options] config-name
@end group
@group
@end group
@end example
@example
@group
   -V --version                  print version info
   -h --help                     display help
@end group
@group
@end group
@end example
@example
@group
   --silent                      no output (except odd errors)
   --quiet                       brief output
   --report                      default output
   --verbose                     maximal output
   --debug                       debugging output
   -d --dir DIR                  cd to DIR first
@end group
@group
@end group
@end example
@example
@group
  Build the named configuration based on the specification
  in the "configs" subdirectory at the root of the project
  tree.
@end group
@group
@end group
@end example

@noindent
and

@example
@group
  % larch update-config --help 
@end group
@group
@end group
@end example
@example
@group
  update a multi-project tree
  usage: update-config [options] config-name
@end group
@group
@end group
@end example
@example
@group
   -V --version                  print version info
   -h --help                     display help
@end group
@group
@end group
@end example
@example
@group
   --silent                      no output (except odd errors)
   --quiet                       brief output
   --report                      default output
   --verbose                     maximal output
   --debug                       debugging output
@end group
@group
@end group
@end example
@example
@group
   -d --dir DIR                  cd to DIR first
@end group
@group
@end group
@end example
@example
@group
   --force                       pass the --force flag to update
@end group
@group
@end group
@end example
@example
@group
  Update the named configuration based on the specification
  in the "configs" subdirectory at the root of the project
  tree.
@end group
@group
@end group
@end example

@noindent
and

@example
@group
    % larch replay-config --help
@end group
@group
@end group
@end example
@example
@group
    replay a multi-project tree
    usage: replay-config [options] config-name
@end group
@group
@end group
@end example
@example
@group
     -V --version                  print version info
     -h --help                     display help
@end group
@group
@end group
@end example
@example
@group
     --silent                      no output (except odd errors)
     --quiet                       brief output
     --report                      default output
     --verbose                     maximal output
     --debug                       debugging output
@end group
@group
@end group
@end example
@example
@group
     -d --dir DIR                  cd to DIR first
@end group
@group
@end group
@end example
@example
@group
    Update the named configuration based on the specification
    in the "configs" subdirectory at the root of the project
    tree.
@end group
@group
@end group
@end example

@noindent
and

@example
@group
    % larch record-config --help
@end group
@group
@end group
@end example
@example
@group
    record a revision-specific configuration
    usage: record-config [options] config-name new-config-name
@end group
@group
@end group
@end example
@example
@group
     -V --version                  print version info
     -h --help                     display help
@end group
@group
@end group
@end example
@example
@group
     --silent                      no output (except odd errors)
     --quiet                       brief output
     --report                      default output
     --verbose                     maximal output
     --debug                       debugging output
@end group
@group
@end group
@end example
@example
@group
     -d --dir DIR                  cd to DIR first
@end group
@group
@end group
@end example
@example
@group
     -f --force                    overwrite an existing config
@end group
@group
@end group
@end example
@example
@group
    Update the named configuration based on the specification
    in the "configs" subdirectory at the root of the project
    tree.
@end group
@group
@end group
@end example

@noindent
and

@example
@group
    % larch show-config --help
@end group
@group
@end group
@end example
@example
@group
    show the revision frontier of a configuration
    usage: show-config [options] config-name
@end group
@group
@end group
@end example
@example
@group
     -V --version                  print version info
     -h --help                     display help
@end group
@group
@end group
@end example
@example
@group
     --silent                      no output (except odd errors)
     --quiet                       brief output
     --report                      default output
     --verbose                     maximal output
     --debug                       debugging output
@end group
@group
@end group
@end example
@example
@group
     -d --dir DIR                  cd to DIR first
@end group
@group
@end group
@end example
@example
@group
    Print the revision frontier specified by the named configuration
    in the "configs" subdirectory at the root of the project
    tree.
@end group
@group
@end group
@end example



