clustertoc

- cluster table of contents description file

Description

The cluster table of contents file, .clustertoc, is an ASCII file that
describes a hierarchical view of a software product. A .clustertoc file is
required for the base OS product. The file resides in the top-level
directory containing the product.

The hierarchy described by .clustertoc can be of arbitrary depth, although the
initial system installation programs assume that it has three levels. The hierarchy
is described bottom-up, with the packages described in .packagetoc at the lowest
layer. The next layer is the cluster layer which collects packages into functional
units. The highest layer is the meta-cluster layer which collects packages and
clusters together into typical configurations.

The hierarchy exists to facilitate the selection or deselection of software for
installation at varying levels of granularity. Interacting at the package level gives
the finest level of control over what software is to be installed.

Each entry in the .clustertoc file is a line that establishes the
value of a parameter in the following form:

PARAM=value

A line starting with a pound-sign, ``#'', is considered a comment and
is ignored.

Parameters are grouped by cluster or meta-cluster. The start of a cluster
description is defined by a line of the form:

CLUSTER=value

The start of a meta-cluster description is defined by a line of
the form:

METACLUSTER=value

There is no order implied or assumed for specifying the parameters for
a (meta-)cluster with the exception of the CLUSTER or METACLUSTER parameter, which
must appear first and the END parameter which must appear last.

The following parameters are mandatory:

CLUSTER

The cluster identifier (for example, SUNWCacc). The identifier specified must be unique within the package and cluster identifier namespace defined by a product's .packagetoc and .clustertoc files. The identifiers used are subject to the same constraints as those for package identifiers. These constraints are (from pkginfo(4)):

All characters in the abbreviation must be alphanumeric and the first may not be numeric. The abbreviation is limited to a maximum length of nine characters. install, new, and all are reserved abbreviations.

A cluster must be described before another cluster or meta-cluster may refer to it.

DESC

An informative textual description of the (meta-)cluster's contents. The length of the description supplied may not exceed 256 characters. The text should contain no newlines.

METACLUSTER

The metacluster identifier (for example, SUNWCprog). The identifier specified must be unique within the package and cluster identifier namespace defined by a product's .packagetoc and .clustertoc files. The identifiers used are subject to the same constraints as those for package identifiers. These constraints are (from pkginfo(4)):

All characters in the abbreviation must be alphanumeric and the first may not be numeric. The abbreviation is limited to a maximum length of nine characters. install, new, and all are reserved abbreviations.

Meta-clusters can not contain references to other meta-clusters.

NAME

The full name of the (meta-)cluster. The length of the name string supplied may not exceed 256 characters.

SUNW_CSRMEMBER

Indicates that the package or cluster is a part of the (meta-) cluster currently being described. The value specified is the identifier of the package or cluster. There may be an arbitrary number of SUNW_CSRMEMBER parameters per (meta-)cluster.

VENDOR

The name of the (meta-)cluster's vendor. The length of the vendor string supplied may not exceed 256 characters.

VERSION

The version of the (meta-)cluster. The length of the version string supplied may not exceed 256 characters.

The following parameters are optional:

DEFAULT

Specifies which metacluster within a .clustertoc file should be selected or installed by default. Only one metacluster can be the default.

HIDDEN

Specifies whether a metacluster should be hidden by applications. A hidden metacluster cannot be DEFAULT.

REQUIRED

Specifies which metacluster is required. A required metacluster implies that all of its cluster and package members are not de-selectable (must be installed).

SUNW_CSRMBRIFF

Indicates that the package is to be included dynamically in the (meta-)cluster currently being described. The value of this parameter must follow the following format:

SUNW_CSRMBRIFF=(testtest_arc)package

This line is converted into a SUNW_CSRMEMBER entry at media installation time if the test provided matches the platform on which the media is being installed. There may be zero or more SUNW_CSRMBRIFF parameters per (meta-)cluster.

SUNW_CSRMBRIFF=(testvalue)package

where the test is either the builtin test of "platform" or a shell script which returns shell true (0) or shell false (1) depending on the tests being performed in the script. value is passed to the test as the first argument and can be used to create a script that tests for multiple hardware objects. Finally package is the package that is included in the final .clustertoc file as a SUNW_CSRMEMBER. See parse_dynamic_clustertoc(1M) for more information about the scripts.

Examples

Example 1 A Cluster Description

The following is an example of a cluster description in a .clustertoc
file.