Configure custom tools

You can add commands and folders to the Tools menu. The tools can then be accessed from the Tools menu in P4V and optionally from context menus. For each custom tool, you can also create a shortcut.

You can export tools from Custom Tools to a file that other P4V users can import. Depending on how P4V is configured, tools can also be available from Server Tools and Shared Tools.

Environment considerations

P4V launches the specified custom tool in an external process. Perforce settings are exported to the external process as follows: the P4PORT, P4USER, P4CLIENT and P4CHARSET settings in effect for the P4V connection are exported to the external process, plus any other Perforce settings present in the environment in which P4V is running, including command-line arguments specified when P4V was launched and global settings (on Windows machines, settings configured using the p4 set -s command).

If the P4CONFIG environment variable is set, the tool recognizes any P4CONFIG files present in the file hierarchy on which it is operating. Settings in P4CONFIG files override settings in the environment. To ensure that P4CONFIG settings do not override environment settings, select Ignore P4CONFIG files. (For details about config files, refer to the P4 User’s Guide.) If you are passing arguments to a custom tool, select Ignore P4CONFIG files to ensure that the server settings used by the custom tool correspond to the values that are passed.

On a Mac, custom tools are not launched from a shell by default. For tools that must recognize P4CONFIG settings, create a script that launches a shell before invoking the tool, or define P4CONFIG globally (for example, in /etc/profile, /etc/profile.local, or /etc/csh.login). To spawn a shell using Bourne shell, issue the #!/bin/sh command. For the C shell, issue the #!/bin/tcsh command.

If you need to keep a tool running or launch another application, run it in the background and exit the shell or process that was launched by the custom tool. This approach ensures that you do not block another tool and that the application will remain open when you exit P4V.

Understand tool sources

Custom Tools and HTML Window Tools can come from one or more of the following sources:

• My Custom Tools or My HTML Windows: tools that you create and manage in P4V.

• Server Tools: tools published through the P4 Server.

• Shared Tools: tools loaded from shared XML files.

  Shared tool files are loaded from fixed shared folders in the P4V configuration directory. Custom Tools are loaded from CustomToolsShared/ and HTML Window Tools are loaded from HTMLWindowToolsShared/. These locations are predefined and cannot be changed in P4V preferences.

When tools are available from more than one source, P4V groups them by source in:

• Manage Custom Tools

• Manage HTML Windows

• Insert Menu Item

• Tools menu

Published and shared tool definition files can optionally define a custom display name. If the root element includes a non-empty displayName attribute, P4V uses that value as the group label instead of the default source name. As a result, you might see labels such as Developer, ABC Developer, or Rob's Utilities instead of Server Tools or Shared Tools.

If only your own tools exist, P4V displays tools exactly as in previous releases and no source grouping is shown.

If one shared XML file is available, P4V displays Shared Tools.

If multiple shared XML files are available, P4V displays a separate group for each file using the format Shared Tools (file-name).

A published or shared tool definition file can override these default labels by specifying a displayName attribute in the root element. For example:

<CustomToolDefList 
       varName="customtooldeflist" 
	displayName="Developer">

When displayName is present and non-empty, P4V uses that value as the group label in the management dialogs and the Tools menu. If displayName is not specified or is empty, the default naming rules apply.

Add custom tools

You can create and manage tools in My Custom Tools. You can view and run tools from Server Tools and Shared Tools, but you cannot modify them in P4V.

To add custom tools to P4V:

1. Choose Tools > Manage Tools​.

   The Manage Custom Tools dialog box is displayed.

2. Click New and choose Tool…​.

   The Add Custom Tool dialog box is displayed. (In P4 Admin, the Add Local Tool dialog box is displayed.)

3. In the Name field, enter the name of the menu item you want to appear on the Tools menu.
4. Use the Placement field to define where you want the tool to appear in the Tools menu. Select the Add to applicable context menus check box if you want the new tool to be available in P4V context menus.

5. Specify the application that you want to associate with this command in the Application field. To browse to the application, click Browse. (You can drag and drop the application from an Explorer or Finder window to the Application field.)

   To define tools that issue p4 commands, specify p4 in the Application field and the command and desired arguments (for example, fix -c %c job000001) in the Arguments field. Specify the application and arguments separately in the fields provided.

6. In the Arguments field, enter command arguments using the specifiers listed in the following table.

   Some arguments have an uppercase and lowercase form. To run the tool once, submitting all values together, specify the uppercase argument. To run the tool once for each value, specify the lowercase form.

   Argument	Description
   %a	Selected label
   %b	Selected branch
   %C, %c	Selected changelists
   %D, %d	Selected files or folders (depot syntax used for depot files)
   %F, %f	Selected files (workspace syntax used for depot files)
   %i	Selected workspace specifications
   %J, %j	Selected jobs
   %O, %o	Depends on which pane has focus: When left pane has focus, selected checked out files. When right pane has focus, all checked out files.
   %P, %p	Selected pending changelists
   %S, %s	Selected submitted changelists
   %t	Selected stream
   %u	Selected user
   %v	Selected file revision (depot path with revision number)
   $c	Current workspace specification
   $p	Current port
   $r	Current client workspace root
   $u	Current user
   $D	Arguments from prompt dialog
   $%	Literal '%' character
   $$	Literal '$' character

   Notes about arguments:

   • Arguments must be separated by white space.

   • To specify values containing spaces, double-quote them. For example:

     "C:\Program Files\scripts\changelistreport.pl" %p

   • You can specify only one % argument per tool definition.

   • Uppercase specifiers send values to the command as a group. Lowercase specifiers run the command once for each value.

     For example: mycommand %F runs mycommand arg1 arg2 arg3 and mycommand %f runs mycommand arg1; mycommand arg2; mycommand arg3.

   • If your custom tool includes arguments from a prompt dialog ($D), you must warn users to avoid the "&" character when they enter a string value in your custom tool prompt. The "&" value is a special character.

7. In the Start in field, specify the directory where you want the command to execute. You can specify the directory using:

   • operating system syntax (for example: C:\tmp, or /tmp), or
   • %f, which uses the directory of the selected file.
     If you specify %f, omit any other values. For example, %f\temp is invalid.
8. To execute the application in a terminal window that displays standard input and output, select Run tool in terminal window.
9. To enable users to enter arguments after they choose the custom tool menu item, select Prompt user for arguments and enter a description of the required arguments in the Description field. To enable users to browse when prompted, select Add file browser to prompt dialog.
10. To refresh P4V after the tool application finishes running, select Refresh P4V upon completion.
11. To save your entries, click OK.

12. To add a shortcut for the tool, double-click the Shortcut column and enter the desired key combination.

    If a shortcut is reserved or already in use, P4V displays a warning message.

    When tools from multiple sources use the same shortcut, only one shortcut can be active. P4V applies the following precedence:

    1. Server Tools

    2. My Custom Tools

    3. Shared Tools

    If a tool loses a shortcut conflict, the shortcut remains visible but is marked as inactive. A tooltip identifies the tool and source currently using the shortcut.

13. To exit the Manage Custom Tools dialog box, click OK.

Use tools from multiple sources

When more than one source is available, the Tools menu displays source-based submenus.

For example:

• My Custom Tools

• Server Tools

• Shared Tools

If a published or shared tool definition file specifies a custom displayName value, that name is displayed instead of the default Server Tools or Shared Tools label.

All tools remain available from the Tools menu, even when a shortcut has been overridden by a higher-priority source.

A tool whose shortcut is inactive can still be run from the Tools menu or a context menu.

Import and export tools

You can export tools from My Custom Tools to an XML file that other P4V users can import. Likewise, you can import tools that other P4V users have created.

Tools provided through Server Tools and Shared Tools appear automatically and do not require import.

To make tools available through Shared Tools, place the XML definition files in the appropriate shared folder (CustomToolsShared/ for Custom Tools or HTMLWindowToolsShared/ for HTML Window Tools) in the P4V configuration directory.

To import tools:

1. Choose Tools > Manage Custom Tools…​

   The Manage Custom Tools dialog box is displayed.

2. Click Import tools…​

   P4V displays the Read Custom Tools from a File dialog box.

3. Enter the file name or browse to the file and click Open.

   The Import Preview dialog box is displayed.

4. Click Import.

   The tool definitions are imported.

Imported tools are added to My Custom Tools. Server Tools and Shared Tools cannot be imported into or exported from My Custom Tools.

To export tools:

1. Choose Tools > Manage Custom Tools…​

   The Manage Custom Tools dialog box is displayed.

2. Click Export tools…​

   The Export Preview dialog box is displayed.

3. Select the tools you want to export and click Export.

   The Save Custom Tools to a File dialog box is displayed.

4. Enter a file name and browse to the location where you want to save the export file and click OK.

You can export only tools that belong to My Custom Tools. Tools from Server Tools and Shared Tools cannot be exported.