The modules2 file

This page describes the modules2 file, which provides flexible modules support without the problems that the old modules file has.

Do not attempt to use both a modules and modules2 file at the same time. The results will be undefined if this is attempted.

The format of modules2 is very simple - similar to a Windows .ini file. Each section describes a module, and definitions may be called recursively. Optionally recursion can be switched off for a directory.

The operation of modules2 is transparent to the client so there are no special issues using checkout and/or update.

An example modules2 file is:

  [pets]
  dog
  cat

  [people]
  brother
  sister

  [household]
  pets
  people

Checking out 'household' will create the directory structure:

  household
    pets
      dog
      cat
    people
      brother
      sister

In this example the 'household', 'pets', and 'people' directories don't have any files in them - they're just containers. However let's say we want to put the files listing pet food in the pets directory, above all the pet specific directories.

Modules2 lets you override what goes in the root of a module, to overlay another module in it:

  [pets]
  / = !petfood
  dog
  cat

  [people]
  brother
  sister

  [household]
  pets
  people

Now when we checkout we get the same directory structure as above, but the pets directory contains the contents of 'petfood'. Note also we said that we don't want any subdirectories of petfood, using the '!' prefix. This makes sure that the directory is never recursed into, even during an update -d. We still get the 'dog' and 'cat' directory of course.

You can simply rename an entire directory tree using this method. The following:

  [project1]
  / = myproject

  [project2]
  / = myproject
  junk =
  total_junk =
  project/old_project = myproject/junk

project1 will checkout the entire myproject tree. project2 is the same, except the 'junk' directory is removed, and moved to project/oldproject. The total_junk directory is hidden completely.

You can also mask certain files within a directory, or certain subdirectories using an extended regular expression.

  [project1]
  / = myproject

  [project2]
  / = myproject (*\.cpp$|*\.[ch]$|*/$)
  junk =
  total_junk =
  project/old_project = myproject/junk

Directories are subject to the same filtering, except they have a '/' directory separator after their name. If you just want to filter some files and allow subdirectories then add '|*/$' as an option.

need to be more verbose here

The '+' prefix stops processing, so that entries that would be potentially recursive can be defined to be nonrecursive.
Spaces can be used in the file, delimited by quotes or using backslash escapes. File separators must always be forward slashes.
Comments are on a line beginning '#'