Release Notes for P4Sandbox, Using Perforce in a Distributed Environment Version 2012.1 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 ------------------------------------------- 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.] */