Previous Table of Contents Index Next
Perforce 2012.3: P4Sandbox User's Guide

Chapter 2
This chapter tells you how to install, configure, and remove P4Sandbox on a workstation.
For details about installing the Perforce Server, see the Perforce System Administrator's Guide.
For more information on p4 and p4sandbox commands discussed in this chapter, see P4Sandbox Command Reference.
Installing P4Sandbox
For hardware and software requirements and platform-specific installation instructions, see the Perforce P4Sandbox Release Notes included with the release package.
P4Sandbox installer and behavior
To install P4Sandbox, download the appropriate installer or installers for your platform and client application from the Perforce downloads page:
When you perform an uninstall or upgrade with active P4Sandboxes running on your machine, the installer may prompt you either to stop all active P4Sandboxes or to reboot your machine to complete the process.
P4Sandbox installation components
The P4Sandbox installation consists of the following components:
p4sandbox: The broker that implements P4Sandbox functionality. All user interactions are managed through this broker.
p4sandbox-p4d: The Perforce Server distribution (p4d)used by P4Sandbox for the local server.
p4sandbox-config: A GUI configuration tool (P4Sandbox Configuration Wizard) for creating and editing servers. Creating a P4Sandbox server also creates a hidden directory and updates a reference file. The location of the these files and directories is dependent upon your platform.
.p4sandbox-list: An XML configuration file that lists your P4Sandbox servers.
.p4sandbox/: Directory containing the p4d databases and archive files.
.p4config file: A text file containing the following three default settings and values. For more information, see p4sandbox init.
P4USER=machine's default user
Verifying the installation directory structure
If you use P4Sandbox with a graphical client application, you must ensure that the P4Sandbox and graphical client application components reside in the same directory. The initial P4Sandbox directory location depends on your platform:
OS X and Linux: The installation process may install P4Sandbox and graphical client application components in different directories.
Windows: The installation process usually installs P4Sandbox in the appropriate subdirectory of the graphical client application directory.
Verify your implementation and confirm that it has the correct directory structure—with all components residing in the same directory—before you create a P4Sandbox.
Creating a P4Sandbox
You can create and configure a connected or standalone P4Sandbox using either p4 or the P4Sandbox Configuration Wizard.
This section discusses important configuration issues for you to consider.
Workspace root clobber issues
For most users, we recommend that you do not create a P4Sandbox in the shared service workspace directory (the workspace root), as this can result in synchronization clobber issues. For more information, see the Usage Notes section of p4sandbox init.
Initial content replication time
The initial content replication from the shared service to the new P4Sandbox may take several minutes (or longer), depending on the number of files to copy and network latency. Subsequent replications should be faster, as the process copies over only those files that have been updated.
Standalone to connected P4Sandbox conversion
If you install P4Sandbox as a private standalone implementation and later decide to connect it to a shared service, you must contact your Perforce Technical Support representative at [email protected] for help with this conversion.
Using p4
Use one of the following three methods to create a P4Sandbox.
p4-only method for a connected P4Sandbox
To create a P4Sandbox in the current directory, type:
p4sandbox init
In the following example, the user:
Example: This example shows how to create a connected P4Sandbox.
p4 set P4CONFIG=.p4config
p4sandbox init
p4 remote -p perforce:1666
p4 merge //remote/depot/stream/... //streams/mirror/...
p4 merge //streams/mirror/... //streams/local/...
Note the following about the above example:
p4 set is a Windows-specific Perforce command. To set the appropriate environmental variables for your platform, see the "Environment Variables" section in the Perforce Command Reference.
You can also exclude specific files from replication by defining P4IGNORE within a P4CONFIG file. For more information, see the "P4IGNORE" and "P4CONFIG" sections in the Perforce Command Reference, and the "Ignoring groups of files" section in the P4 User's Guide.
For lines 4 and 5, note that you can use any of the following commands in place of p4 merge because (in this case) they have similar functionality:
p4-only method to create a standalone P4Sandbox
To create a P4Sandbox in the current directory, type:
p4sandbox init
The command creates a standalone P4Sandbox containing only a .p4config file and .p4sandbox directory.
p4 with wizard method
The p4sandbox-config command launches the P4Sandbox Configuration Wizard to create a P4Sandbox.
For more information, see "Using the configuration wizard."
Using the configuration wizard
When using a graphical client application, you use the P4Sandbox Configuration Wizard to create a connected or standalone P4Sandbox.
Configure P4Sandbox
To use the P4Sandbox Configuration Wizard:
Double-click the Perforce Sandbox Configuration icon.
Mac OS X locations: Applications > Perforce folder
Windows locations: Start Menu or Start Menu > All Programs > Perforce folder
In P4V, click Connection > Configure Sandbox.
From p4, type p4sandbox-config.
Welcome to the Sandbox Setup Wizard
Create a new or edit an existing P4Sandbox.
This page does not appear if you launch the wizard directly from a client application.
Specify Central Server Settings
Specify connection to a central server or P4Sandbox.
The connection setting you specify here determines whether the P4Sandbox is a connected or standalone implementation. Consequently, this selection also affects the Configuration Wizard's subsequent page display.
Specify Port, Server, and User values.
Specify whether to replicate files from a Workspace or Stream, or select None to choose which files to replicate.
Define pulling interval and (optionally) select files to copy from a central server.
This page appears as the initial page when you launch the wizard from P4V. Whether or not you can choose files to replicate depends on the options defined on the previous page.
The Central Server field displays the specified server, user, stream, and in parentheses, the stream root information.
Note: If you do not define a pulling interval, you must manually perform this action. P4Sandbox will prompt you to pull (merge down) changes, as needed, before allowing you to push (copy up) changes.
Because files occupy space on your hard disk and require time to transfer across the network, we suggest you minimize the number of folders you copy to minimize disk and time consumption.
Specify Local Sandbox Server and Workspace Settings
Review connection settings for a P4Sandbox.
Specify the Server, Port, User, Workspace Name, Workspace Root, and Charset (character set) for Unicode Servers fields.
When you change the Port or Workspace name value (or both), the wizard automatically updates the corresponding entry in the Workspace Root path.
Note: The default Workspace Root path differs among platforms as follows:
Linux: $home/sandboxes/sandbox­NNNN/client
Mac OS X: /Users/user name/sand­boxes/sandboxNNNN/client
Windows: \Users\user name\sand­boxes\sandboxNNNN/client
Note: You cannot use the same port number for multiple P4Sandboxes. When you attempt to re-use an existing port number, the following message appears:
The specified port number is already in use by another P4Sandbox.
Review P4Sandbox settings before finalization.
Click Finish to complete the configuration.
For the initial P4Sandbox launch, P4V opens a dialog box indicating that it has launched a P4Sandbox connection window. This dialog box also includes links to P4Sandbox documentation and videos. Click the Don't show again check box to prevent the dialog box from displaying for any subsequent P4Sandboxes that you create.
The figure below shows an initial view of a sample P4Sandbox, prior to any modification with additional task streams. The word Sandbox appears in the title bar. This P4Sandbox includes the default local stream (//streams/local) defined on the Specify Central Server Settings wizard page. The Depot tab view shows the files contained in the local and mirror streams. You can identify the currently active stream by the following:
The active file icons in the local stream (//streams/local/jblack/main).
Verifying the connection
This section discusses how to verify that you have successfully configured a P4Sandbox connection using either the p4 or the graphical client application.
For more information on specifying configuration settings, contact your Perforce Administrator and also see the appropriate guide for your implementation:
P4Eclipse Help, "Configuring Perforce Server Connections and Working Offline"
P4 User's Guide, "Configuring P4"
P4V Online Help, "Connecting to the Perforce Server"
Using IDE Plug-ins, "Basic Concepts: Configuring IDEs with plug-ins"
Using p4
To verify that you have successfully configured a P4Sandbox, type p4 info at the command line.
If your configuration settings are correct and a server is running on the specified host and port, you receive a message similar to the following. The Sandbox broker version: field indicates that a P4Sandbox is running.
User name: jblack
Client name: my_workspace
Client host: win-jblack
Client root: C:\Users\jblack\sandboxes\sandbox1666\client
Client stream: //streams/local
Current directory: c:\Users\jblack\sandboxes\sandbox1666
Client address:
Server address: win-jblack:1667
Server root: c:\Users\jblack\sandboxes\sandbox1666\.p4sandbox
Server date: 2012/01/27 11:43:48 -0800 Pacific Standard Time
Server uptime: 00:47:30
Server version: P4D/NTX86/2012.1.MAIN-TEST_ONLY/400159 (2012/01/10)
Server license: none
Case Handling: insensitive
Sandbox broker version: P4SANDBOX/NTX86/2012.1.MAIN-TEST_ONLY/400282
Sandbox broker port: localhost:1666
If your configuration settings are incorrect, the following error message appears:
Perforce client error:
        Connect to server failed; check $P4PORT.
        TCP connect to <hostname> failed.
        <hostname>: host unknown.
Using a graphical client application
To verify that you have successfully configured P4Sandbox:
Connect to localhost:nnnn where nnnn is the Local Server port that appears on the Settings Summary page of the P4Sandbox Configuration Wizard.
If your configuration settings are incorrect, an error message similar to the following appears:
TCP connect to localhost:1666 failed.
Connect: Connection refused
Removing a P4Sandbox
You must use p4 to delete a P4Sandbox; you cannot delete a P4Sandbox using a graphical client application. Either use the command procedure discussed below or contact your Perforce Administrator for assistance.
Issuing p4sandbox delete
To delete a P4Sandbox:
Example: This example shows how to delete a specific P4Sandbox. After you issue this command, you must enter -y to confirm the deletion.
p4sandbox delete performs the following actions:
Deletes all files located in the .p4sandbox/ directory:
Local p4d database metadata
After you issue the p4sandbox delete command, use the appropriate OS-specific process to remove the remaining files from your machine.
If you want to remove files from your workspace, you must remove them manually; p4sandbox delete does not affect files in your workspace.
You cannot reverse the p4sandbox delete command. However, you can usually restore a P4Sandbox if backups are available. For more information, type p4sandbox help delete.
Uninstalling a P4Sandbox
p4sandbox delete does not uninstall a P4Sandbox. After issuing p4sandbox delete, use the appropriate OS-specific process to remove the program from your machine.
When you perform an uninstall or upgrade with active P4Sandboxes running on your machine, the installer may prompt you either to stop all active P4Sandboxes or to reboot your machine to complete the process.

Previous Table of Contents Index Next

Perforce 2012.3: P4Sandbox User's Guide
Copyright 2012-2013 Perforce Software.