                             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.]
 */
