Stream Components

A stream component is similar to an import template path because both allow the stream client to have access to files outside of the current stream. An advantage of a stream component is that it avoids the maintenance issues associated with keeping template paths up to date.

Stream Components allow stream client views to include other stream views. Any stream can become a component by being referenced in another stream view.

Components can be nested to arbitrary levels. For example, stream A references component stream B, which references component stream C, which references component stream D, and so on.

Note

A stream cannot reference itself as a component, either directly or indirectly through other referenced component streams.

Defining stream components

A stream component is defined with this syntax:

component_type component_folder component_stream[@[change | automatic_label]]

such as

readonly dirB //streams/B

where

component_type component_folder component_stream[@[change | automatic_label]]

is readonly, so component files can be synced, but not submitted

Specifies a directory prefix for each component view file.

The specified directory is directly under the workspace root directory.

Specifies the name and path of the component stream, which can be pinned to a change or automatic label.

If @change or @automatic_label is specified,

  • the version of the component stream specification at or before the change or label is used

  • any files synced will be at revisions at or before the change or label.

Note

If neither @change nor @automatic_label is specified, the view is not pinned to any change number but instead defaults to the current revision.

Examples of stream components

For example, given three streams, //streams/A, //streams/B, and //streams/C,

and //streams/A has a component definition

readonly dirB //streams/B

and //streams/B has a component definition

readonly dirC //streams/C

a client of //streams/A therefore has the views

//streams/A/...  //clientname/...
//streams/B/...  //clientname/dirB/...
//streams/C/...  //clientname/dirB/dirC/...

and a client of //streams/B therefore has the views

//streams/B/...  //clientname/...
//streams/C/...  //clientname/dirC/...

In this example, the client of /streams/A does not need to maintain template paths for //streams/B and //streams/C. Therefore, if //streams/C upgrades its path for a new library version, all the stream views that consume the //streams/C component automatically have access to that new library version.

Tip

For security, the p4 protect protections table remains in force. For example, if a user has //clientname/dirB/dirC/... in the component view, but lacks the read protection for that directory, that user cannot read those files.

inheritance and noinherit

Component views are inherited by descendants of the defining stream, unless a descendant has a noinherit ParentView. For example, if a mainline stream consumes two components, the development stream that is a child of that mainline stream also consumes those same two components.

If a descendant stream is converted to have a noinherit ParentView, the component definition is copied to the descendant. In this way, a noinherit ParentView child stream can consume the same components directly as it did by inheritance from its parent prior to conversion.

Note

A stream component only affects client views. Branch views are not affected by stream components, so integrations between parent and child are unaffected by component definitions.

enabling stream components

By default, the stream components feature is not enabled. To enable this feature, set the dm.stream.components configurable to 1.

additional information

See also the p4 help stream command-line output.