Editing Workspace Resources

Many Helix IPLM workflows rely on using specific IPV releases to build workspaces. In this scenario, you populate your workspace with a known good state and then continue development from that point. However, in some cases, it is more convenient to add and remove IPVs from a workspace directly, without first creating a full release. A typical situation where this makes sense is when there is a need to try out new configurations and IPVs, but it is not yet clear that these investigations should be captured in a release. 

Workspace Edit

IPLM provides the workspace edit command to create local workspace modifications without generating a new release. The following modifications are supported:

1. Add or remove standard IPV resources from any given parent IPV in the workspace
2. Add or remove private IPV resources from any given parent IPV in the workspace
3. Modify project properties on any given IPV in the workspace. See Workspace Configuration for additional information.

Workspace traceability in IPLM requires that every IPV in the workspace has a hierarchy link to the top level IPV in the workspace, so when adding a new IPV, it must be associated with an IPV already in the workspace as a resource. Changes made to the workspace exist only in the workspace (or in snapshots made from the workspace) and not in any IPLM release. Workspace edits can be captured in a new release, either in whole or in part, using the pi release command.

Workspace edits are accomplished through editing a template that includes the above fields:

[IPV] 
# Resources are optional 
# One resource per line (newlines require a leading space) 
resources = tutorial.aes512@1.TRUNK 
 tutorial.clk_mux@1.TRUNK 
 tutorial.cpu@1.TRUNK 
 tutorial.dbuf@1.TRUNK 

# Private resources are only loaded when this IP is the top level of a Workspace. 
# This is useful to prevent subsystem test benches from loading into bigger Workspaces. 
private_resources = 

# Project properties (project_props) are optional 
# One resource per line (newlines require a leading space) 
# A property set on a resource in the top IP overrides the same property 
# set on the resource itself. 
# 
# Format: <ip_identifier> [--path <path>] [--mode local|refer|both] 
#  [--resolve <IPV>] [--unix_group <group>] 
# ip_identifier: the resource IP 
# These wildcards are allowed in resource names: 
# * - refers to all resources. (Default) 
# LIB. - refers to all resources belonging to library LIB. 
# --path: A relative path in the workspace where the IP is placed in. 
# $LIB and $IP are provided as convenience vars with the 
# default location in "$LIB.$IP" of the workspace dir. 
# ex: --path data - IP directory is renamed to "data" 
# --path $IP - IP is placed in a top level dir "$IP" 
# --path dir/$IP - IP is placed in "dir/$IP" 
# --mode: Makes the IP local only, or refer only. If the mode is unset both 
# at the top level and at the resource then the IP can be switched 
# between refer and local. The mode "both" can be used at the top 
# level to override a mode of refer or local set at a resource level. 
# ex: resource IP "SUBSYS" has mode --local set so a workspace with 
# SUBSYS at the top is always in local mode 
# an IP "TOP" that uses SUBSYS as a resource can override that 
# using a mode "both" 
# --resolve: When a conflict between multiple resources occurs, this 
# specifies which one of the resources must be used. The --resolve 
# project property can only be applied to the default * group. All 
# resolutions must be specified in one single --resolve directive 
# eg: --resolve lib1.ip1@1.TRUNK lib2.ip2@ALIAS.LINE ... 
# --unix_group: Group owner of the IP directory in the shared area and 
# workspaces. eg: --unix_group group1 
project_props = * --path blocks/$IP

Workspace Edit Permissions Impact

It is not necessary that a user has write permissions to an IP and line in order to add or remove resources on that IPV in the workspace. However, write permissions are required to actually release the IPV. When a user modifies the resources or project properties of a given IPV without write permissions, those changes will remain in the workspace only, and can't be released. A user must have at least read permissions on an IPV for it to be populated in the workspace, see Workspaces and Permissions for more details.

In order to edit an IPV in the workspace, a user must have, at minimum, Library, IP, and IP Line read permissions on the IPV itself, as well as read permissions on all the IPV's direct resources, including private resources. It is not necessary to have read permissions on the resources of any of the IPV's direct resources. Users must also have at least read permission on any IPVs they attempt to add as resources in the workspace.

Workspace Edit details

The workspace edit command is always targeted at one of the IPs loaded into the workspace, and the template that comes up provides access to adding or removing resources (private or standard) or modifying project properties on the target IP. Once the template is saved and closed, the equivalent of a 'pi update' is run on the target IP, with the modifications entered into the template applied. The target IP can be the top level IPV in the workspace or any resource IP in the workspace.

Adding an IPV resource

If an IPV is added as a resource to a target IP, an update will run on the target as if it has the added IPV resource as one of its released resources. If the added resource did not already exist in the workspace, it will be added to the workspace along with any resources it may have. Standard update modes and conflict resolution will apply to the added resource and its hierarchy.

If the added IPV already exists in the workspace (because it is a resource of another IPV in the workspace) it will be updated with the selected update mode (default promote) passed in to the pi ws edit command.

Modifications of the private resource field of an IP in the workspace may or may not have any effect on the workspace - depending on whether the edit is to the top level IPV or not. Private resources are only populated when they are resources of the top level IPV in the workspace.

Adding an IPV that is present at another version elsewhere in the workspace will result in an update of the target IPV as if it had the added IPV as a resource. All standard update modes and conflict resolution will apply. See Updating the Workspace for details on how updates are applied to a workspace.

Removing an IPV resource

If an IPV is removed as a resource from a target IP, it may or may not be fully removed from the workspace, depending on whether another IPV in the workspace has that IPV as a resource. A subsequent release of the target IPV will capture that the removed IPV is no longer a resource of the target IP. 

All Standard updated modes and conflict resolution will apply to removing the IPV from the workspace. If the removed IPV has resources that don't occur elsewhere in the workspace, they too will be removed from the workspace.

Modifying the Version/Line of an IP 

Performing a pi ws edit to move an IPV in the workspace to a new version and/or line is equivalent to running a 'pi update' of that IPV to a new version and/or line. Standard update modes and conflict resolution applies.

Modifying Project Properties

Modifying Project Properties (see Workspace Configuration for details) with pi ws edit results in the equivalent of a 'pi update' of the target IP as if it had the modified project property values. A subsequent release of the IP with modified project property values will capture them as part of the new release. Note that only edits to either the top level IPV or the leaf level IPVs in the workspace will have any effect on the current workspaces. See the Workspace Configuration page for details on how Project Properties are applied.

Snapshots and edited Workspaces

Snapshots of workspaces that have resource or project property modifications capture those modifications. Any workspaces subsequently built from those snapshots will also retain the modifications of the original workspace.

Releasing a Modified IPV in a Workspace

The 'pi release' command will by default restrict creating a new release from an IPV in a workspace edited with the pi workspace edit command. To bypass this restriction use the 'pi release --allow-modified' option, see Making Workspace Releases for more details.

Command Line

Workspace edits are performed in the workspace with the 'pi workspace edit' command.

> pi ws edit -h
Usage: pi workspace edit [-h] [--wsdir WSDIR] [--template TEMPLATE] 
                         [--force] [--keep-local] [--promote]
                         [--unload <unload_mode>] [discard] [ip]

Description: Edit the Workspace IP. The command puts the Workspace IP
specification into a temporary file and invokes the editor specified by the
EDITOR environment variable. Saving the file updates the Workspace IP.

Positional arguments:
  ip	            The IP to update. By default, the top IP of the
                   Workspace will be used.

Optional arguments:
  --discard	    Do not back up unmanaged files in IPVs removed from workspace. 
  --force, -f      Update a Workspace to precisely reflect the template.
                   All resources are updated to the version in the
                   template.
  --keep-local, -k Update the Workspace to the template, while retaining
                   changes that had already been made to files and
                   resources.
  --promote, -p    Update the Workspace to the template, unless the
                   Workspace already has a version of a resource that is
                   greater than the version in the template. In that
                   case, the version of the resource already in the
                   Workspace. This is the default behavior.
  --template TEMPLATE, -t TEMPLATE
                   Use the specified template to edit the Workspace IP.
                   The template is an ASCII file that defines the
                   Workspace IP. This can be used to edit Workspace IP
                   with a script and avoid the interactive editor. To
                   read the template from STDIN, set TEMPLATE='-'.
  --unload MODE    Specify handling of IPVs that will be unloaded from the workspace. 
	            MODE is integer 0-2:
			0 (default) - block unload for open files,
			1 - block unload for open+modified files (unmodified files will be reverted),			
			2 - same as 1 but unopened modified files will be backed up to BACKUP_DIR. 	
			Higher mode number gives lower performance 
  --wsdir WSDIR, -ws WSDIR
                   The Workspace directory. If not specified, the current
                   directory should be a Workspace directory.
  -h, --help Show this help message and exit

Update Mode Options

Update modes are explained on the Updating the Workspace page. They control how (or if) local changes in the workspace are retained during changes from a pi workspace edit (or pi update) command. Update modes come into play when resources are added or removed from a workspace and may affect both the directly modified target IPV as well as its resources. 

Specifying the Workspace Directory

Unload Mode

Unload mode is a perforce IP specific function, the unload mode is specified as a number 0-2, with lower mode numbers resulting in higher performance, and higher unload mode numbers resulting in more careful and conservative checking and preservation of file modifications when an IP is unloaded from the workspace.