Release Notes for
P4Sandbox, Using Perforce in a Distributed Environment
Version 2012.3
Introduction
P4Sandbox provides connection independent versioning, private local
branching, and task branching for individual users. This tool allows
you to create a local branch from your central server and merge/copy
changes back and forth between your local server and the central
server. P4Sandbox enforces a strict merge-down/copy-up work flow.
P4Sandbox can also be used as a purely local server without a connection
to a central server. This allows you to jump right into development
using Perforce.
Perforce numbers releases YYYY.R/CCCCCC, for example, 2012.1/40716.
YYYY is the year; R is the release of that year; CCCCCC is the
bug fix change level. Each bug fix in these release notes is
marked by its change number. Any build includes (1) all bug fixes
of all previous releases and (2) all bug fixes of the current
release up to the bug fix change level.
Please send all feedback to support@perforce.com
Requirements
* Central Perforce server at Release 2010.2 or higher.
- Any intermediary brokers must be 2011.1 or higher
- Any intermediary proxies must be 2011.1 or higher
* Supported Platforms:
* Windows XP SP2, 2003, Vista, 7, 2008 Intel (x86, x86_64)
* Linux 2.6 Intel (x86, x86_64)
* Mac OS X 10.6, 10.7 (Mac/Carbon)
* All client programs must be 2010.1 or later.
* Streams support is not required for basic add/edit/delete
operations. Streams support is not required but recommended for
merging down and copying up changes between a central server and
P4Sandbox.
* The P4Sandbox server and all central servers must all have the
same unicode setting: all enabled or all disabled.
Documentation
p4sandbox help Lists help associated with the p4sandbox executable
p4 help sandbox Lists help for P4Sandbox extensions. This requires
being connected to a running P4Sandbox server.
Installation
All:
* Make sure that the p4, p4sandbox, and p4sandbox-p4d executable
files are in your PATH
Windows:
* Run the installer for P4Sandbox
Linux:
* Untar the distribution for P4Sandbox
* For use with P4V, move the contents of the p4sandbox directory into
the p4v directory
Mac OS X:
* Drag the 'p4sandbox-config' application into your Applications
* For command-line use:
Drag the p4, p4sandbox, and p4sandbox-p4d executable files into
some directory which is in your PATH, or create a new directory
for them and then add this new directory to your PATH
environment variable.
Installed Components
The P4Sandbox installation consists of the following:
* p4sandbox The broker which implements P4Sandbox
functionality. All user interactions go through
this broker.
* p4sandbox-p4d The p4d distribution used by P4Sandbox for the
local server.
* p4sandbox-config The GUI configuration tool for creating and
editing P4Sandbox servers.
When you create a P4Sandbox server, a directory and a file are created.
* .p4sandbox/ Directory containing p4d database and archive files.
* .p4sandbox-list A list of P4Sandbox servers.
Important Concepts
Think of P4Sandbox as a distributed branch of your central server.
In concept, this would be as if you could run the following
non-existent command:
p4 integ //depot/core/... mymachine://streams/mirror/...
The central server is accessed through the //streams/mirror stream.
If you are connected and the central server is accessible, merging
from mirror into your development stream copies the latest changes
from the central server into mirror prior to running the merge.
Copying, then submitting to mirror also submits those changes to the
central server. These two general rules are good guidelines for
understanding this process:
* Submitting on mirror is submitting to the central server.
* Merging from mirror is merging from the central server.
Quick Start - Overview
The following assumes a simple configuration where your P4Sandbox
server is connected to a single central server.
The key parts created are:
//remote/... is the remote depot which defines the
central server. Most interactions with
//remote are internal to P4Sandbox; you do
not directly access this depot.
//streams/mirror/... is the mainline stream which acts as a
bridge between your P4Sandbox server and
the central server. You copy/merge changes
to/from this stream to send or retrieve
changes.
//streams/local/... is your development stream which is where
you do most of your work.
Quick Start - P4V
1. Open connection to central server.
2. Select 'Connection->Configure Sandbox...'.
3. Complete the wizard.
4. Start using the resulting connection window to your P4Sandbox server.
These steps create and configure P4Sandbox and then open a new P4V
window to your local P4Sandbox server.
The central server client you specify in this tool is used only to
pre-check items to be replicated. That client is not used by P4Sandbox
for any other purposes.
The initial copy of content from the central server to your new
P4Sandbox server may take several minutes or longer depending on the
number of files selected and network latency. Subsequent copies
bring over only updated files and complete faster.
Quick Start - Command-line
$ export P4CONFIG=.p4config <<- Change this for your environment
$ p4sandbox init
$ p4 remote -p perforce:1666
$ p4 merge //remote/depot/project/... //streams/mirror/project/...
$ p4 merge //streams/mirror/... //streams/local/...
These commands create a local P4Sandbox server, connect it to a
central server, branch the 'project' contents to your P4Sandbox
server, and then create a 'local' development area for you to work
in. See Helpful Hints below.
Creating a Task Branch - P4V
From within P4V when connected to your P4Sandbox server, use the
Stream Graph to bring up the context menu on the Mirror stream.
Select the 'Create new stream from 'mirror'' menu item. Type in the
name for the task (e.g., fixGui). Click 'OK'.
Creating a Task Branch - Comand Line
p4 merge //streams/mirror/... //streams/fixGui/...
This automatically creates the new stream 'fixGui', populates it,
and switches your workspace to 'fixGui'.
Updating from Central Server
To merge the most recent central server changes into your work,
merge the mirror stream to your current local stream:
p4 mergedown
This automates steps that you can perform manually if you require
more control:
p4 merge -r -S //streams/local
... resolve conflicts ...
p4 submit
To copy recent central server changes to your mirror stream, but not
yet merge to any local stream:
p4 pull
Copying to Central Server
To copy your work to the central server, copy from your local stream
to the mirror stream:
p4 copyup
p4 submit
This automates a copy that you can perform manually:
p4 copy -S //streams/local
p4 submit
'p4 submit' stores the files in both the mirror stream and the
central server.
'p4 shelve' instead of 'p4 submit' shelves the files to both the
mirror stream and the central server.
Administration
Start/Stop P4Sandbox Server:
* 'p4sandbox start' starts the P4Sandbox server
* 'p4sandbox stop' stops the P4Sandbox server
These two commands can be used in startup/shutdown scripts on your machine.
See 'p4sandbox help start stop' for more details.
See P4Sandbox User's Guide for checkpoint, journals, backup and restoration.
Uninstalling P4Sandbox
Prior to using your OS specific process for removing software, if
you do not want to keep the local server data, run 'p4sandbox
delete' on each of your local P4Sandbox servers. You can not undo
'p4sandbox delete'.
Removing P4Sandbox Servers
'p4sandbox delete' removes the local p4d databases, archive data and
the entry from the .p4sandbox-list file. Workspace files are left
untouched.
You cannot undo 'p4sandbox delete', although the server could be
restored if you have backups.
Helpful Hints
To create a local P4Sandbox server in your current directory, either
invoke the Sandbox Configuration tool using 'p4sandbox-config' or
run 'p4sandbox init'.
Set P4CONFIG=.p4config before running 'p4sandbox init': P4Sandbox
creates a .p4config file with appropriate settings.
Use the new 'p4 merge' and 'p4 copy' commands instead of 'p4 integ'.
These commands are faster and focus better on propagating content
changes in P4Sandbox's strict merge-down/copy-up world. Use 'p4
mergedown' and 'p4 copyup' for less typing and more automation.
'p4sandbox init -r root -R workspace' separates P4Sandbox's internal
files from your development workspace.
Run 'p4 login' before running 'p4 remote'.
A Perforce proxy's cache does not help P4Sandbox's file access; if
possible, directly connect the P4Sandbox server to the central
server.
Known Limitations and Behaviors
All Platforms:
* Move actions from the central server are propagated as add/delete
actions
* There may be problems with some SSO installations
* P4V's Revision Graph may report errors for content within the
//remote/... depots.
* If central server requires SSL, enter the "ssl:" prefix in
P4Sandbox-Config UI's "Server" field, not in the "Port" field.
* If a case-insensitive P4Sandbox connects to a case-sensitive
central server, then files or directories whose pathnames differ
only by case will not be copied to the mirror stream.
* If both a proxy and a broker are between P4Sandbox and a central
server then the broker must be at least version 2012.1/438660.
* The audit log contents are always encoded using the UTF-8 character
set regardless of the values of P4CHARSET or P4CMDCHARSET, and
so must be viewed with an editor that supports UTF-8; some
characters in the log may display incorrectly if viewed using
another character set.
* You should not set the configurable "net.maxwait" on a central
server, and you especially should not set it to a low value. If it
is set then some operations (e.g., a large integrate from the central
server to P4Sandbox) may complete successfully and then print an
error message: "Partner exited unexpectedly.", and other operations
executed after a long idle period might also produce the same error
message. This is because "net.maxwait" is intended to be set for a
client; when set for a server then connections that are idle for more
than "net.maxwait" seconds will generate this error when they are
next used. This is true even for non-P4Sandbox clients; you will get
the same error if you run "p4 client" directly on such a p4d server,
leave the editor idle for longer than "net.maxwait" seconds, and then
save the form and quit the editor.
Windows:
* Windows junctions are not supported for the root directory of a
P4Sandbox server
* P4Sandbox does not run as a service. It exits when you close the
command window or logoff.
* p4sandbox start and p4sandbox stop generate no console output.
Redirect to a file to see the minimal information generated
* Symlinks are not supported
Mac OS X:
* The deprecated 'apple' and 'resource' filetypes are not supported
-------------------------------------------
Minor new functionality in 2012.3
* upgraded dependent library
-------------------------------------------
Major new functionality in 2012.1
* Connection Independent Versioning
- All work other than pulling/pushing changes from the central
server occurs locally. Network connectivity is not required.
* Private Local Branching
- Changes made in a P4Sandbox remain private until copied to a
central server.
- P4Sandbox servers are single-user, local access only.
* Task Branching
- Creation of development streams off of the branched code is simple
with P4Sandbox creating and maintaining all of the necessary
infrastructure.
Bugs fixed in 2012.1
#605262 (Bug #64219)
Remote depots using SSL now work.
#600387 (Bug #64017)
Add Japanese message translations.
#491854 (Bug #57848)
The name of the command character set variable in the P4CONFIG file
is now P4COMMANDCHARSET rather than the previous P4CMDCHARSET, in
order to match the name used by p4d.
#488386 (Bug #48684) *
"p4 switch" now honors the "-ztag" option and outputs non-translated
key-value pairs rather than localized text; previously it ignored
this option.
#483810 (Bug #54670) *
"p4 copy -S" a file of type ktext in a local stream, followed by a
"p4 submit", no longer produces a spurious error message about the
file not existing underneath the "p4sandbox-client" directory.
#471743 (Bug #56101) *
In addition to ASCII and Unicode (UTF-8, etc), the following character
sets are now supported (matching the character sets supported by P4D):
P4CHARSET Standard name or Description
value code page number
--------- ------------------ -----------
iso8859-5 ISO-8859-5 Latin/Cyrillic
iso8859-15 ISO-8859-15 Latin/Western European [revised]
eucjp EUC-JP Japanese
winoem code page 437 WinOEM
shiftjis code page 932 Japanese [Shift JIS]
cp936 code page 936 Simplified Chinese
cp949 code page 949 Korean
cp950 code page 950 Traditional Chinese
cp1251 code page 1251 Cyrillic
winansi code page 1252 WinANSI
koi8-r code page 20866 Russian [KOI8-R]
Run "p4 help charset" for more information.
#467926 (Bug #55970) *
"p4 help" now works even if the client and P4Sandbox have different
unicode settings.
#467918 (Bug #52776) *
"p4sandbox start", "p4sandbox delete", and "p4sandbox list" now ignore
case in P4ROOT on case-insensitive filesystems.
#457554 (Bug #54777) * **
Initial integrations from a central server to a new mirror stream are
now much faster over a network, especially over a network that has high
latency.
#453301 (Bug #55542) *
P4Sandbox no longer checks for case-conflicts if p4sandbox/p4d and the
central server have the same case sensitivity, as case-conflicts cannot
arise in this case. The new counter "p4sandbox_force_case_check" allows
overriding this behavior: set it to "true" to force case-checking
or to "false" to prevent it.
#453095 (Bug #54905) *
The background pull thread now works when pulling from a Unicode server.
#479627 (Bug #056843) *
During the integration from a central server to a new mirror stream,
if the filesystem for the local p4d does not have enough free disk space
then P4Sandbox used to report that the remote depot was not accessible.
It now reports the correct error, noting the available and required free
disk space.
OpenSSL:
This product includes software and cryptographic software written by Eric Young (eay@cryptsoft.com).
This product includes software written by Tim Hudson (tjh@cryptsoft.com).
OpenSSL License
---------------
/* ====================================================================
* Copyright (c) 1998-2011 The OpenSSL Project. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. All advertising materials mentioning features or use of this
* software must display the following acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
* endorse or promote products derived from this software without
* prior written permission. For written permission, please contact
* openssl-core@openssl.org.
*
* 5. Products derived from this software may not be called "OpenSSL"
* nor may "OpenSSL" appear in their names without prior written
* permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
* acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit (http://www.openssl.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* ====================================================================
*
* This product includes cryptographic software written by Eric Young
* (eay@cryptsoft.com). This product includes software written by Tim
* Hudson (tjh@cryptsoft.com).
*
*/
Original SSLeay License
-----------------------
/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
* All rights reserved.
*
* This package is an SSL implementation written
* by Eric Young (eay@cryptsoft.com).
* The implementation was written so as to conform with Netscapes SSL.
*
* This library is free for commercial and non-commercial use as long as
* the following conditions are adhered to. The following conditions
* apply to all code found in this distribution, be it the RC4, RSA,
* lhash, DES, etc., code; not just the SSL code. The SSL documentation
* included with this distribution is covered by the same copyright terms
* except that the holder is Tim Hudson (tjh@cryptsoft.com).
*
* Copyright remains Eric Young's, and as such any Copyright notices in
* the code are not to be removed.
* If this package is used in a product, Eric Young should be given attribution
* as the author of the parts of the library used.
* This can be in the form of a textual message at program startup or
* in documentation (online or textual) provided with the package.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. All advertising materials mentioning features or use of this software
* must display the following acknowledgement:
* "This product includes cryptographic software written by
* Eric Young (eay@cryptsoft.com)"
* The word 'cryptographic' can be left out if the routines from the library
* being used are not cryptographic related :-).
* 4. If you include any Windows specific code (or a derivative thereof) from
* the apps directory (application code) you must include an acknowledgement:
* "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
*
* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* The licence and distribution terms for any publicly available version or
* derivative of this code cannot be changed. i.e. this code cannot simply be
* copied and put under another distribution licence
* [including the GNU Public Licence.]
*/