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. You can
export your custom tool definitions to a file from which other P4V users can
import them.
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,
P4PASSWORD 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, check Ignore P4CONFIG files. (For
details about config files, refer to the P4 User's Guide.) If you are
passing arguments to a custom tools, check Ignore P4CONFIG files to ensure
that the server settings used by the custom tool correspond to the values that
are passed.
On Macintosh, 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.
Adding custom tools
To add custom tools to P4V:
- Choose Tools>Manage Custom Tools... The Manage Custom Tools dialog
is displayed.
- Click New and choose Tool.... The Add Custom Tool dialog is
displayed.
- In the Name field, enter the name of the menu item you want to appear
on the Tools menu.
- Use the Placement field to define where you want the tool to appear
in the Tools menu. Check the Add to applicable context menus checkbox
if you want the new tool to be available in P4V context menus.
- 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.)
Important: 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.
On Windows machines, you can specify the command and arguments together
in the Application field, but if you export the resulting definition
to a non-Windows machine, it will not work.
- In the Arguments field, enter command arguments using the specifiers
listed in the following table.
%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 |
Selected submitted changelists. |
%u |
Selected user. |
$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, while 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
".
- 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 specify %f, which uses the directory
of the selected file.(Note: If you specify %f, omit any other values.
For example, %f\temp
is invalid.) If you do not specify a value
in the Start in field, the value of the field depends on whether you
specify other file selection parameters (% parameters) in the Arguments
field, as follows:
- No file selection parameters in the Arguments field: The Start
in field is set to the directory containing the first selected file
at the time the tool is executed. If no files are selected, the root directory
is used.
- %f or %o or %d: The command is run once for each
selected file, with the Start in field set to the directory containing
the file.
- %F or %O or %D: The command is run once regardless
of how many files are selected, and the Start in field is set to
the directory containing the first selected file.
- To execute the application in a terminal window that displays standard input
and output, check Run tool in terminal window.
- To enable users to enter arguments after they choose the custom tool menu
item, check Prompt user for arguments and enter a description of the
required arguments in the Description field. To enable users to browse
when prompted, check Add file browser to prompt dialog.
- To refresh P4V after the tool application finishes running, check Refresh
P4V upon completion.
- To save your entries, click OK.
Importing and exporting tools
You can export the tools you've defined to an XML file that other P4V users can
import. Likewise, you can import tools that other P4V users have created.
To import tools:
- Choose Tools>Manage Custom Tools... The Manage Custom Tools dialog is displayed.
- Click Import tools... P4V displays the Read Custom Tools from
a File dialog.
- Enter the file name or browse to the file and click Open. The Import
Preview dialog is displayed.
- Click Import. The tool definitions are imported..
To export tools:
- Choose Tools>Manage Custom Tools... The Manage Custom Tools dialog is displayed.
- Click Export tools... The Export Preview dialog is displayed.
- Check the tools you want to export and click Export. The Save Custom
Tools to a File dialog is displayed.
- Enter a file name and browse to the location where you want to save the
export file and click OK.
Note: On Windows, if a tool does not run, verify that the files that it
opens have their extensions mapped to the required application.