Project configuration project.cfg file format

Date: 2009/11/28
Version: "Subprojects for real"

File project.cfg has an ini-style format with several sections/subsections with key = value content. ConfigObj library is used to parse project.cfg file. The file content is utf-8 encoded.

All reserved words, section and key names are uppercase to avoid name clashes with user variables. So user should use only lowercase names for your own variables/keys.

There is no mandatory sections, everything is optional.

Nevertheless one could use several optional sections:

Every component and subproject should be described in additional named sections.

Skeleton of the file:

[PROJECT]
## Optional project description
NAME =
DESCRIPTION =
## VCS used for project components.
## Every component can override this parameter.
VCS = bzr
## Optional space-separated list of known components
# COMPONENTS =

[ALTS]
## describe project variations here in the form
## variation_name = component1:branchA component2:branchB

[SUBSETS]
## describe predefined partial subsets of project here
## as space separated lists of visible components:
## subset_name = component1 component2 ...

[COMPONENTS]
## describe some component templates, which will be used unless it is
## overridden in the component section
# RELPATH =  ## available template variable {COMPONENT}
# BRANCH_URL =  ## available template variables {COMPONENT}, {BRANCH}, {RELPATH}
## List of the default public branches for components, e.g. BRANCHES = trunk
## This list can be overriden in component section.
# BRANCHES =
## Optional default format for components
# FORMAT =
## Optional default VCS for components
# VCS =

## describe each component in subsequent sections
# [component "name"]
# ## Optional component description
# DESCRIPTION =
# ## Mapping of component directory to project tree
# RELPATH =
# ## Optionally specify VCS used for this component (default is bzr)
# VCS =
# ## Optionally specify repo/branch format used for this component
# FORMAT =
# ## Optionally specify read-only mode for component (True/False)
# READONLY =
# ## Space separated list of known public branches for this component;
# ## by default branches names used as relative paths for component
# ## repo url.
# BRANCHES =
# ## Optional URL to branch (template, see notes from COMPONENTS section)
# BRANCH_URL =
# ## To provide detailed info about each public branch use subsequent subsections
#     [[branch "name"]]
#     ## Optionally specify VCS used for this branch (default is bzr)
#     VCS =
#     ## Optionally specify branch format used for this branch
#     FORMAT =
#     ## Optional URL to this branch
#     BRANCH_URL =
#     ## Optional revision info to checkout this branch
#     REVISION =
#     ## Optionally specify read-only mode for branch (True/False)
#     READONLY =

## describe each subproject in subsequent sections
# [subproject "name"]
# ## Mapping of subproject root directory to project tree
# RELPATH =
# ## URL of subproject location
# SUBPROJECT_URL =

See detailed explanation below.

PROJECT Section

To provide a optional project description you can use these keys:

You should specify a default vcs used for component branches with the following key:

Optionally you can provide the space-separated list of known components with COMPONENTS key (see below Components Sections).

ALTS Section

In this section you can declare a set of your project variants. Every alt is the space-separated list of items:

<component name> <:> <component branch name>

E.g., foo:bar, spam:trunk.

There is one predefined alt named DEFAULT, by default it is equal to the first branch of every component (in the known branches list for component). But you can override this default behavior either by specifying your own list, or to make a link to another alt; a link is marked with a @ prefix, e.g.:

[ALTS]
DEFAULT = @eggs
eggs = foo:bar

It is possible to define a default branch name per alt, and also to override this default for specific cases, eg:

[ALTS]
dev = {COMPONENT}:trunk
qa = {COMPONENT}:qa non-standard-component:bar

In this instance for the dev alt it would use the trunk branch for all components. For the qa alt it would use the qa branch for all components except for non-standard-component where it will use bar.

SUBSETS Section

This section is similar to the ALTS section, but you only specify a list of visible components for every subset. There is three predefined subsets: DEFAULT, FULL and NULL.

Subset FULL enables all components.

Subset NULL disables all components.

DEFAULT subset by default enables all components. But you can override this default behavior either by specifying your own list, or by making a link to another subset; a link is marked with a @ prefix, e.g.:

[SUBSETS]
DEFAULT = @fish
fish = foo spam

You cannot override FULL or NULL subsets.

COMPONENTS Section

This section is for specifying some component templates, which will be used unless it is overridden in the component section. e.g.:

[PROJECT]
COMPONENTS = foo

[COMPONENTS]
RELPATH = {COMPONENT}

[foo]
# RELPATH = foo

In this section you can declare the following two templates:

In addition you can provide default set of public branches for components using option BRANCHES, e.g.:

BRANCHES = trunk dev

For the RELPATH template, you may only use the {COMPONENT} template parameter, for which the component name will be substituted. In this case you don't need to specify the the RELPATH for the foo component as it is already defined by the template.

For the BRANCH_URL template you may use template variables: {COMPONENT} (component name), {BRANCH} (branch name), and {RELPATH}.

In this section user also can provide default values for FORMAT and VCS used for components branches.

Components Sections

Specify components list for the project

User can specify the list of project components either via COMPONENTS option in the PROJECT section, or simply by declaring components sections.

COMPONENTS option in the PROJECT section should be space-separated list of component names. This list can be used alone without dedicated sections for the components. In this case user should provide mandatory component options (RELPATH and BRANCH_URL) via templates in COMPONENTS section.

In the case COMPONENTS list is used with dedicated component sections, this list should be superset of components sections set.

Dedicated component section

To describe a component user need to use dedicated section in the config. Section header should be as following:

[component "name"]

Where:

  • component -- reserved keyword to specify component section
  • name -- the name of component. Double quotes around the name are optional.

Main info for component

For every component you should specify mandatory info and could specify some optional info.

Mandatory component info:

  • RELPATH -- mapping of component directory to project tree
  • BRANCH_URL -- URL to the branch (can be a template)

Optional component info:

  • DESCRIPTION -- more or less verbose description of component
  • VCS -- main vcs used for component branches
  • FORMAT -- vcs repository format of component branches (this option could be very important to bzr and its zoo of formats)
  • READONLY -- you can use this option to prohibit local changes to component files (useful when using vendor branches)

Specifying component branches

When project used only one alt then there is only one branch for every component.

But when the project need several alts then some components will have several branches. User could specify set of component branches explicitly or implicitly.

To specify explicitly list of component branches user should use BRANCHES option in the component section (or in the COMPONENTS template section). The value of BRANCHES should be space-separated list of known branches names. Branch names can be used in the templates then (as {BRANCH}).

Another way to specify set of branches for component implicitly is to using special subsections for every branch.

Component branches info subsections

Branch subsections header should be as following:

[[branch "name"]]

Where:

  • branch -- reserved keyword to specify component branch subsection
  • name -- the name of branch. Double quotes around the name are optional.

Branches subsections for component are optional, and they could provide following optional info:

  • BRANCH_URL -- full URL to the branch
  • REVISION -- explicit revision info used to checkout branch
  • VCS -- vcs used for this branch
  • FORMAT -- vcs repository format for this branch
  • READONLY -- you can use this option to prohibit local changes to branch files (useful when using vendor branch)

Examples

  • The project contains 2 components named foo and bar. User should specify them in the config as 2 sections:

    [PROJECT]
VCS = bzr

[component "foo"]
RELPATH = docs
BRANCH_URL = http://example.com/foo

[component "bar"]
RELPATH = src
BRANCH_URL = http://example.com/bar

  • User can specify branch URL via templates in COMPONENTS section (see above) or in the dedicated branch section:

    [COMPONENTS]
BRANCH_URL = http://example.com/{COMPONENT}

[component "foo"]
RELPATH = some/path

[component "bar"]
RELPATH = some/another/path

    [[branch "baz"]]
    BRANCH_URL = http://example.com/boo/{BRANCH}

    Then for "foo" component will be used http://example.com/foo URL.

Subprojects sections

To describe a subproject you should use dedicated section in the config. Section header should be as following:

[subproject "name"]

Where:

For every subproject you should specify mandatory info and could specify some optional info.

Mandatory subproject info:

Example:

[subproject "cats"]
RELPATH = meow
SUBPROJECT_URL = http://www.cats.net/fluffy