Using Workspace Views
Workspace views enable populating only the workspace data that is relevant to a user and/or putting files at a different revisions than those specified in the IPV. Workspace views can be applied at the time of workspace load, or added and removed as needed after workspace load. Only one view can be applied at a time.
What is a Workspace View?
Workspace Views are Perforce IPLM database objects containing a set of patterns identifying IPs, IP paths, and IP managed files that will receive special treatment when loading and updating workspaces. Views are specified in a similar syntax to Perforce view specs used in Perforce clients.
When a 'pi ip load' or a 'pi update' is run to either create or update a workspace, the file versions captured in the released IP Hierarchy can be overridden by a workspace view. Views can be used to:
- Omit files or IP sub-directories in certain IPs in the workspace
- Include some files from otherwise omitted IP sub-directories in certain IPs in the workspace
- Automatically update certain files or sub-directories in certain IPs to a specified version (Currently only @HEAD is supported).
For example, a layout engineer doesn't care about RTL or testbench data and so can use a Workspace View to prevent that data from being loaded or updated into their workspace. A layout engineer might also want to see only the latest committed layout data, and so could request that data to be automatically loaded and updated to @HEAD, even though they are working in a fixed release IPV that might otherwise be updated to earlier versions of those files.
A view can be specified when a workspace is created, and the active view in an existing workspace can be changed or removed. A default view can be defined in piclient.conf (workspace_view) or with the environment variable MDX_WORKSPACE_VIEW. The active view on a workspace is displayed in 'pi ws st' and optionally in 'pi ws ls'.
Notes:
- Views are supported in P4 IPVs only.
- Views are applicable only to Local IPVs. Refer IPVs are always populated in full at the released version.
- At most one View can be active in a workspace.
- Currently the only supported revision is @HEAD
- In case of overlapping or conflicting patterns, later patterns take precedence
Workspace Views and IP Diff
If a view is active in a workspace, the 'pi ip diff' command will only compare files that are present in the workspace (it ignores any that are omitted from the workspace due to a view specification). Any revision patterns in the view will not affect the operation of 'pi ip diff', these files will still be compared. See the Comparing IPs in the System section for details.
Workspace Views and Workspace Status
If a view is active in a workspace the 'pi ws status' command will ignore files excluded by the workspace view pattern, and not report a 'Modified' or similar state because of the excluded files. Any files affected by revision patterns will be compared normally. See Viewing Workspace Modifications for more information.
Workspace Views and Releases
If a release is made from a workspace with an active view, there are three cases to consider:
| Case | Behavior |
|---|---|
| Files included in the workspace | Capture the workspace version of the files in the new release |
| Files excluded from the workspace by the view | Capture the server version of the excluded files in the new release |
| Files specified at revision patterns by the view | Capture the workspace version of the files in the new release |
Workspace Views and Workspace Updates
If a view is active in a workspace and a 'pi update' is run on IPs that are covered by the view, the affected files or directory paths will be updated according to what is specified in the view, other unaffected files and directory paths will be updated according to the incoming target IPV hierarchy.
Command Line
Workspace views are managed with the pi view set of commands:
> pi view -h
Usage: pi view [-h] SUBCOMMAND ...
Description: Commands related to Views. These subcommands are used to add,
edit, delete and list information about Views.
Optional arguments:
-h, --help Show this help message and exit
Available sub-commands:
SUBCOMMAND
add Create a new View.
delete (del, remove, rm)
Delete an existing View.
edit Edit an existing View.
list (ls) List all matching Views.
Creating a New View
Views are created with the pi view add command:
> pi view add -h
Usage: pi view add [-h] [--template TEMPLATE] [identifier]
Description: Create a new View. The command puts the View specification into a
temporary file and invokes the editor specified by the EDITOR environment
variable. Saving the file adds the View.
Positional arguments:
identifier The name of the View being created.
Optional arguments:
--template TEMPLATE, -t TEMPLATE
Use the specified template to add the View. The
template is an ASCII file that defines the View. This
can be used to add Views using a script and avoid the
interactive editor.
-h, --help Show this help message and exit
> pi view add layout_head [VIEW] # The name of the View may be any Unicode string and is required. name = layout_head # An optional description of the View. description = # A list of include, exclude or revision patterns in p4 format, one pattern per line # A pattern is an optional IP Identifier and a file pattern, separated by a colon # Include patterns define file(s) that should appear in the workspace # Exclude patterns define file(s) that should not appear in the workspace # Revision patterns define file(s) to be at a particular revision in the workspace # If patterns overlap or conflict, later mappings take precedence # Examples: # Include pattern for a named IP: lib1.ip1:.../cds/... # Include pattern for all IPs (implicit): .../cds/... # Include pattern for all IPs (explicit): *:.../cds/... # Exclude pattern for a named IP: -lib1.ip1:.../layout*/... # Revision pattern for all IPs: *:.../schematic/...@HEAD patterns =
View patterns are specified one per line, lines after the first need to have at least some whitespace at the beginning, the first should be on the same line as 'patterns =':
patterns = *:.../layout/...@HEAD -tutorial.top:rtl/...
Defining a View
The View definition patterns consist of two parts, the first before the colon ':' is the library.ip name of the IP the pattern should apply to. An asterix '*' can be used to match all IPs in the system.
The second part of the View definition pattern is in Perforce File Specification format. The pattern defined here is combined with the repo path of the IP specified to the left of the colon to form a full pattern that is included in the p4 client spec for the workspace. The overall format of the View definition pattern is:
library.ip:<file pattern>
Some important notes on the View definition pattern:
| Expression | Meaning |
|---|---|
| ... | Matches any string including path separators |
| * | Matches any string excluding path separators |
| - | (beginning of pattern) Indicates an exclude pattern |
| @HEAD | (end of pattern) Indicates files matching the pattern should be loaded at the HEAD revision |
| : | Separator between IP specification and the file pattern |
Types of View Patterns
| Pattern | Meaning |
|---|---|
| Include | Lines without a leading '-' and without an @HEAD specification are Include type patterns. By default all data underneath an IP is included in the workspace when it is populated so an include type pattern only makes sense when coupled with an exclude pattern, i.e. you exclude a directory under all IPs and then re-include the directory under one specific IP in a subsequent include pattern. |
| Exclude | Lines with a leading '-' and no @HEAD specification are exclude patterns, the specified path in the specified IP will be removed from the IP when it is populated on disk |
| Revision | Patterns with the @HEAD specification will cause files matching the specified pattern to be loaded in the workspace @HEAD regardless of what version the rest of the IP is loaded at. |
Example View Specifications
| View Specification | Description |
|---|---|
lib1.ip1:.../cds/... |
In Library 'lib1', IP 'ip1' include all files within directories underneath a 'cds' directory. The cds directory can be at any folder depth under the IP repo path. |
.../cds/... |
Same as above but for all IPs. Omitting the IP specification portion implies the pattern applies to all IPs. |
*:.../cds/... |
Same as above, but explicitly showing that the pattern applies to all IPs with the asterix wildcard. |
-lib1.ip1:.../layout*/... |
Exclude anything in the 'lib1.ip1' IP under any directory with a name that begins with 'layout'. The directory beginning with 'layout' can be at any folder depth under the IP repo path. |
*:.../schematic/...@HEAD |
For any IP load any files under a schematic directory at the perforce HEAD version. The schematic directory can be at any folder depth under the IP repo path. |
Editing an Existing View
A view cannot be modified if it is being used in any workspace.
Views are modified with the pi view edit command:
> pi view edit -h
Usage: pi view edit [-h] [--template TEMPLATE] identifier
Description: Edit an existing View. The command puts the View specification
into a temporary file and invokes the editor specified by the EDITOR
environment variable. Saving the file edits the View.
Positional arguments:
identifier The name of the View being edited.
Optional arguments:
--template TEMPLATE, -t TEMPLATE
Use the specified template to edit the View. The
template is an ASCII file that defines the View. This
can be used to edit Views using a script and avoid the
interactive editor.
-h, --help Show this help message and exit
Running pi view edit:
> pi view edit layout_head
Running pi view edit brings up the View specification, which can be edited as described in the following section.
Deleting a View
If a Workspace View is used in any workspaces, it cannot be deleted, it must first be cleared from all workspaces using pi ws view --clear. Alternatively if all workspaces that are using the View are deleted the View itself can then be deleted.
Views are deleted with the pi view delete command:
> pi view delete -h Usage: pi view delete [-h] identifier Description: Delete an existing View. This command will mark a View as inactive. Positional arguments: identifier The name of the View to delete. Optional arguments: -h, --help Show this help message and exit
Listing Workspace Views
The Workspace Views defined in the system can be listed with the pi view list command:
> pi view list -h
Usage: pi view list [-h] [--format {csv,json,long,table,template} | --verbose]
[--model MODEL]
[identifier [identifier ...]]
Description: List all matching Views. A variety of format and filtering
options are supported.
Positional arguments:
identifier Filter Views by name.
Optional arguments:
--format {csv,json,long,table,template}
Return the results using the specified data structure.
The template format produces files that can be used by
the pi add|edit commands with the --template option.
--model MODEL Use the specified report model (table report only).
--verbose, -v Alias for --format long.
-h, --help Show this help message and exit
Working with Views in Workspaces
The pi ws view command can be used to show, remove and apply a view to an existing workspace:
pi workspace view [-h] [--clear] [view]
Applying a View on Workspace Load
Workspace views can be applied at workspace load via the pi ip load command:
> pi ip load tutorial.tutorial ws1 --view layout_head
Applying a View to an Existing Workspace
To apply the view layout_head to an existing workspace use (from within the workspace):
> pi workspace view layout_head
Show the Current View on a Workspace
To see the current view on a workspace, run pi workspace view from inside the workspace:
> pi workspace view
The current view is also shown in the output of pi ws st
Removing a View From a Workspace
To remove the applied view from an existing workspace use (from within the workspace):
> pi workspace view --clear