Difference between revisions of "Using Source Control with the Source SDK"

From Valve Developer Community
Jump to: navigation, search
(Overview)
 
(41 intermediate revisions by 21 users not shown)
Line 1: Line 1:
[[Category:Programming]]
+
{{otherlang2
===Overview===
+
| ru = Using Source Control with the Source SDK:ru
 +
}} {{toc-right}}
  
test
+
This article describes how to use [[Wikipedia:Revision control|source control]] with the Source SDK. You will want to use source control even if you're working alone, as it largely automates the process of merging code updates released on Steam – without it, you'll be in a world of hurt every time!
  
This document describes how to use source control with the Source SDK. By using a source control system with the SDK, you will have the ability to easily integrate the latest optimizations and fixes from Valve into your mod's code. In addition, you get all the benefits of source control like revision history, backups, multiuser support, branches, and labels.  
+
This document discusses [http://www.perforce.com/ Perforce], the source control system used internally by Valve. It's free for up to 20 users. Other alternatives include [[Wikipedia: Subversion (software)|Subversion]] or [[Wikipedia:Concurrent Versions System|CVS]]. Since all version control systems work with the same high-level processes, this article should still be useful. (Nevertheless, there are specific articles for [[Using Subversion for Source Control with the Source SDK|Subversion]] and [[Using Git for Source Control with the Source SDK|Git]].)
  
'''Note:''' This document refers to Perforce as the source control system because that is what Valve uses internally for all of its source (and content). There is a free 2-user version of Perforce that can be downloaded on the [http://www.perforce.com Perforce web site]. Most other source control systems (like [http://www.cvshome.org CVS]) should be able to support the process that we describe here.
+
== Before you begin ==
  
The high-level steps that you want to use to keep your code in sync with updates from Valve are.
+
If you have started programming without source control, '''STOP!''' Source control needs to be set up at the earliest opportunity, especially since every time a Steam update is released older versions of the base SDK code are lost.
  
# Create a codeline (codeline A) that contains the latest code from Valve.
+
If you're reading this as you try to apply an update that's already out to your unversioned code, it is too late, and you must merge the changes the hard way. Tools like [http://www.scootersoftware.com Beyond Compare] can make this process easier, and if you follow this tutorial after finishing it should be the last time you ever have to endure it.
# Create a codeline (codeline B) that contains your modified version of the code - you work out of this codeline.
 
# Integrate the latest changes from Valve into your code.
 
  
[[Image:Source_control_flowchart.gif]]
+
=== Get Perforce ===
  
<h3>Integrating Source Code Changes</h3>
+
With that out of the way, [http://www.perforce.com/perforce/downloads/ it's time to get Perforce]. You want both the '''visual client''' (which includes the command-line client anyway) and the '''server'''. Take care when installing to leave the network server configuration alone unless you are actually going to connect somewhere remote.
  
The high-level steps to integrate the latest source changes from Valve into your existing source code are:
+
If you are using Visual Studio (as opposed to Visual C++ Express) you should also consider downloading the [http://www.perforce.com/perforce/products/p4scc.html SCC plugin], which integrates Perforce into the IDE.
  
# Open all files in Codeline A for edit, copy all the latest Valve source into it, and revert unchanged files.
+
{{tip|[http://www.perforce.com/perforce/technical.html Perforce provide documentation of their own] which you may want to consult. It isn't as specific as this guide, however.}}
# Submit all the changes in Codeline A.
 
# Submit any pending changes in Codeline B.
 
# Integrate from Codeline A to Codeline B. At this point, any changes that happened to Valve's source code since the latest time codeline A was integrated into Codeline B will be integrated into your source code.
 
# Check the differences in Codeline B to make sure you want the changes in your code.
 
# Submit the change. At this point, you are up to date with the latest code from Valve.
 
  
==Step By Step==
+
{{tip|If you make a mistake while following this tutorial and need to reset Perforce's database, execute this from the command prompt: <code>p4 obliterate –y //depot/...</code>. DON'T do this on a database that's already up and running!}}
  
This section walks through the entire process of setting up your mod to use source control.
+
== Overview ==
  
 +
We will make a fresh install of Valve's SDK code and submit it to the Perforce server. We will then 'branch' that submitted code to a second location, which allows you to work with the code as you see fit while retaining the ability to easily 'integrate' future SDK updates from Valve into your project.
  
<h3>Prerequisites</h3>
+
This means that you will have two 'codelines' on your Perforce server. Valve's, which will only change with SDK updates, and your own, which will change both whenever you decide to submit your work to it, and whenever you decide to integrate SDK updates from Valve.
  
 +
== Setting up source control ==
  
If you already have installed the SDK source code and modified it, and you want to use the process described in this document, then you must follow the steps in this section before proceeding.
+
Valve's base SDK code will form the 'trunk' of your codebase, from which your mod code will 'branch'. Get Valve's code with the [[Create a Mod]] wizard, choosing the "source code only" option and installing to a location in your user dir like <code>C:\Users\You\Mods\valvesrc</code>. Making a <code>\Mods</code> folder is important, as you will discover later.
  
# First, backup the source code that you have.
+
{{tip|If you're using Windows Vista or later it's a good idea to remove the \Mods folder from the search index. Use the Indexing Options tool, which is in the start menu, to do this. You'll need admin privileges.}}
# Double check that you just backed up your source code.
 
# Next, you must get yourself in sync with the latest version of Valve's SDK code. This must be done manually by clicking <code>Create a Mod</code> from the SDK launcher, installing the source code somewhere, and merging your own code into it by hand or vice-versa. Tools like [http://www.scootersoftware.com Beyond Compare] can make this process easier, and this should be the last time you ever have to do this process painfully.
 
  
 +
=== Create a workspace ===
  
<h3>Download and install Perforce</h3>
+
Now we'll start using Perforce. Start P4V, the visual client. You will be greeted by the "Open Connection" dialogue.
  
To download Perforce, go to [http://www.perforce.com www.perforce.com], go to the '''downloads''' page, and get the most recent version. Note that you want to download the '''Core Perforce Windows Installer''' because that includes the Perforce server as well as the front end.
+
[[Image:P4 openconnection.png|center|Perforce open connection dialogue]]
  
# Run the installer, and choose "Administrator - Typical" as the type of install. You can install to any directory, but this document will assume you've installed it into <code>C:\Perforce</code>. Click '''Next'''.
+
Unless you are actually connecting to a network server you can ignore all of the options it gives you except Workspace. Click 'new', to the right, and name the workspace 'mods' (or whatever you please - but the rest of this guide assumes it's called mods).
# Accept the default options at the next screen and click '''Next'''.
 
# Click '''Install'''.
 
# Perforce may mention that installation won't be complete until the system is restarted. If it mentions this, restart your system before proceeding.
 
  
 +
Workspaces link folders containing your files with the location(s) on the Perforce server where they are archived. Earlier versions of this guide suggested that one workspace be created per codeline, but this is unnecessary. We're going to create just one that will encompass all of the SDK projects on your computer, which is why creating a \Mods folder was recommended above.
  
<h3>Creating Your First Client Workspace</h3>
+
Most of the fields in the New Workspace dialogue should be self-explanatory, and you only need to worry about two anyway:
  
In this section, you will create a <code>client workspace</code> that will hold Valve's source code only.
+
* '''Root''' should point to your Source projects folder - <code>C:\Users\You\Mods\</code> if you followed the instructions above precisely.
 +
* '''View''' contains two locations, separated by whitespace:
 +
*# A location on the Perforce server
 +
*# The location that it should correspond to in the workspace
  
Briefly, a client workspace describes where to place a <code>codeline</code> on a user's hard drive. It is similar to mapping a network drive - Perforce has its own internal file system that has a root called <code>//depot</code> (and you're going to place Valve's source code in <code>//depot/ValveSDKCode</code>), and the <code>client workspace</code> is what tells Perforce to store the contents of <code>//depot/ValveSDKCode</code> on your hard drive in <code>C:\ValveSDKCode</code>.
+
Unless you've deviated from this tutorial, the running Perforce server is called 'depot' and your workspace is called 'mods'. We aren't doing anything complex, so View should tie the depot root to the workspace root:
  
For example, as described above, you will have a codeline called &quot;Codeline A&quot;, which will hold Valve's latest source code. This codeline exists inside Perforce and cannot be edited directly. To edit it, each user must have a copy of the codeline on his or her hard drive. They edit that copy, then '''Submit''' their changes to Perforce, in effect saying, "Take the source code on my hard drive and put it up on the Perforce server so other users can get my changes".
+
//depot/sourcemods/... //mods/...
  
For more details on <code>client workspaces</code>, visit the [http://www.perforce.com/perforce/doc.042/manuals/p4guide/04_details.html#1040395 Perforce documentation here].
+
The <code>/sourcemods</code> subfolder will keep your mod projects separate from any other workspaces you create in the future. If you're absolutely sure that this server will only be used with one workspace you can use the root <code>//depot/...</code> path instead.
  
* The first time you run Perforce, it will bring up the '''Client Workspace Wizard''' dialog. We need to enter some advanced options, so click '''Cancel'''.
+
=== Submit the trunk source code ===
* Select the '''ClientSpec''' menu and choose '''New'''.
 
* At the next dialog, enter ValveSDKCode and click '''OK'''.
 
  
[[Image:Source_control_clientspec_name.gif]]
+
We now have a workspace filled with Valve's base SDK code, but the Perforce server is still empty. We need to get our files up there. To do that we'll be using the main P4V interface, which having created a workspace should currently be in front of you.
  
* At the next dialog, make these changes (and leave the other fields as they are):
+
<div style="padding:1em; background-color: #2B2B2B;border:1px solid #000;">[[Image:P4 interfaceoverview.png|center|P4V interface overview]]
* Set '''Root''' to <code>C:\ValveSDKCode</code> (or wherever you want to put Valve's source code on your machine - you will never edit the code in here directly).
 
* Add <code>ValveSDKCode</code> after the <code>//depot</code> in the '''View''' section, so it reads:
 
<code>//depot/'''ValveSDKCode/'''... //ValveSDKCode/... </code>
 
  
* Click '''Update'''.
+
{{tip|You can also get an overview of the interface from <code>Help > Getting Started with P4V</code>.}}
* A dialog will come up asking if you want to '''Sync To Head''' (i.e. copy the latest files from the codeline to your hard drive). Since there are no files in the codeline yet, click '''Dont Sync.'''
 
  
[[Image:Source_control_clientspec.gif]]
+
# ''Workspace/depot view (left pane).'' Click on the tabs at the bottom to change between the two. Workspace is your local copy, depot is the server's master copy.
 +
# ''Task tabs (right pane).'' The tabs along the bottom of this pane allow you to switch between different tasks. They are opened as needed from the main menu buttons. We will be using Pending, Workspaces and Branches.
 +
# ''Log.'' Errors will appear in bold text.
 +
# ''Main menu.'' Most of the options here are available elsewhere in the interface, but it's useful to have them in one place too.</div>
  
<h3>Populating Codeline A</h3>
+
Bring up the workspace view and we'll submit the code. It's a two-step process:
  
In the previous step, we created a <em>client workspace</em> to hold Valve's source code. It is still empty - we haven't added any files to the Perforce server, so now we want to add all of Valve's source code to the codeline (in <code>//depot/ValveSDKCode</code>).  
+
# Mark the files for addition. We want to add everything, so select the whole \valvesrc folder and click 'Mark for Add'. You can find the Add button on the main menu or in the context menu; it's the file icon with a plus over it. There are a lot of files in the SDK, so it might take a while for the operation to complete. When it's finished, all of the files in the workspace view will have changed appearance to reflect that they are now being version controlled.
 +
# Submit the changelist. Move to the 'Pending' tab (the red, upwards arrow) and you'll see that there's an item called 'default' that contains all of the files you just added. Submit it with a double-click (or {{key|Ctrl+S}}). You'll need to enter a brief description of what the changes are.
  
* Run the Source SDK and choose <code>Create a Mod</code>.
+
Once the process has finished, you'll be able to browse to the newly-populated depot view. Congratulations! You can now safely delete the <code>\valvesrc</code> folder.
* Choose the '''Source code only''' option and click '''Next'''.
 
  
[[Image:Source_control_create_mod.gif]]
+
=== Create and execute the branch ===
  
* Enter in the directory name you chose above to hold the Valve code (<code>C:\ValveSDKCode</code>).
+
{{note|You can't properly branch to a location that's already populated. If you've already made changes to the code that you want to keep, back the files you've changed up somewhere before deleting the rest of the old source folder. You'll have to manually add everything back later.}}
* Click '''Next'''.
 
* All the latest source code will be copied into <code>C:\ValveSDKCode</code>.
 
  
[[Image:Source_control_mod_info.gif]]
+
Choose ''File > New > Branch Specification...'' to create a new 'branch'. A branch operation tells Perforce to copy code to a separate location while remembering where it came from, and when &mdash; vital information when it comes to integrating SDK updates.
  
* Now, to add all the files, open a command prompt and <code>cd</code> to <code>C:\ValveSDKCode</code>.
+
The view field of a branch is slightly different to that of a workspace: ''both'' halves refer to locations on the server. Yours should read something like this:
  
* To tell Perforce which client workspace you're adding the files to, type:
+
//depot/valvesrc/... //depot/mymod/...
  
<code>set p4client=ValveSDKCode</code>
+
Although we've just specified a destination on the server, the new branch will actually be created in the workspace. This is so that you can examine how the integration turned out before committing to anything: polite behaviour that isn't terribly useful at this point, since we are "integrating" with an empty folder!
  
* Then type the following command to add all the files to the depot:
+
{{note|To see the newly created branch in the workspace, use the Branch Mappings tab. You can Enable it by way of ''View > Branch Mappings...'' or {{key|Ctrl+3}}}}
  
<code>for /R %i in (*.*) do @p4 add "%i"</code>
+
{{tip|The confusing error "No target file(s) in both client and branch view" means that one or both paths in the View are pointing to the wrong location. Don't forget to include any subfolders you made.}}
   
 
* You will see Perforce adding all the files. It will be scrolling lines like this:
 
  
<code>//depot/ValveSDKCode/dlls/nav_generate.cpp#1 - opened for add</code>
+
A good name for the branch is <code>valve_to_mymod</code>. Hit OK and it will be created: now we just need to execute it. Right-click on your new branch and select the 'Integrate Using' option. You should be able to start the process without changing anything.
  
[[Image:Source_control_command_prompt.gif]]
+
[[Image:P4 integrate.png|center|Preparing to execute a branch in Perforce]]
  
* At this point, we've told Perforce that we want to add all the Valve SDK code to Codeline A. All that remains is to <em>submit</em> the change to the Perforce server.
+
You now have the 'mymod' branch of valvesrc registered on the server, and its files sitting in your workspace. Submit them in the same way as you did the trunk code.
* Alt+TAB back to Perforce and hit '''F5'''. Under '''Pending Perforce Changelists''', you should see an item called '''Default'''.
 
* Right-click on the '''Default''' item and choose '''Submit'''.
 
  
[[Image:Source_control_perforce_submit.gif]]
+
=== Check out ===
  
* In the dialog that comes up, the only thing you need to change is the '''Description''' field.
+
All version-controlled files in your workspace are read-only unless you have them 'checked out' of the server. This is useful when you're working with a team of programmers, as it makes developers aware of which files they are each working on, but can still help to keep things organised when you are working alone.
* Fill in the '''Descrpition''' field as shown in the image below, and click the '''Submit''' button.
 
  
[[Image:Source_control_perforce_submit2.gif]]
+
To check a file or folder out, select it and hit {{key|Ctrl+E}} or use the context menu.
  
 +
If you are working alone you might think it logical to check out the entire workspace, and this is a perfectly valid option. However, it will help you keep track of your changes between submissions if you only check out those files that you need to modify.
  
To recap: At this point, we have created Codeline A and populated it with the most latest version of Valve's SDK code. From now on, the only time Codeline A will ever be modified is when you want to integrate a newer version of Valve's SDK code into your mod's codebase.
+
{{warning|Resist the temptation to manually remove the read-only flag from your versioned files. This desynchronizes Perforce and may confuse it (and you) later on.}}
  
We need two more things to complete the source control setup:
+
== Integrating SDK updates ==
  
# We need a codeline for your mod's source code to live in (Codeline B).
+
We've now got source control up and running for your mod. It might have seemed complex, but the steps above only need to be performed once and this stuff will soon become grist for the mill anyway.
# We need Perforce to know that Codeline A and Codeline B are related, so when you update Codeline A with Valve's latest SDK code, Perforce will do all the dirty work of merging the changes into your mod's code (in Codeline B).
 
  
<h3>Populating Codeline B</h3>
+
You can use source control as an ongoing backup, to compare code with what came before or after it, to revert changes, share code with others and contribute collaboratively, and, of course, to integrate trunk updates, which is what we'll be doing in this section.
  
Populating Codeline B is going to be similar to populating Codeline A, with a few key differences. The main difference is that we're going to '''branch''' the code in Codeline A into Codeline B. This means we're making a copy of Codeline A, but Perforce is going to remember that the files in the two codelines are linked, so it can easily merge changes between the two copies of the files (which is the main reason we want to use source control in the first place).
+
=== Submit pending branch changes ===
  
* In Perforce, click the '''ClientSpec''' menu and choose '''New'''.
+
You already know how to submit, but this is an appropriate time to remind you that newly-created files aren't automatically added to version control.
* Enter <code>LocalModCode</code> in the dialog and click '''OK'''.
 
  
[[Image:Source_control_clientspec_name_local_mod.gif]]
+
P4V only supports adding files individually, which is fiddly, or by folder, which will pick up all the huge binary files generated by Visual Studio that you definitely don't want on the server. To add files with a wildcard search, we must turn to the [[command line]].
  
* At the next dialog, make these changes (and leave the other fields as they are):
+
Open CMD and execute these commands ('client' is another word for workspace):
  
<blockquote>
+
set p4client mods
# Set '''Root''' to <code>C:\LocalModCode</code>. Important: This must be a directory that does not currently exist on your hard drive. If you want to store and edit your source code somewhere else (and you probably will), you can change this later - we'll show you how.
+
p4 add //mods/game/....cpp
# Add <code>LocalModCode</code> after the <code>//depot</code> in the '''View''' section, so it reads:
+
p4 add //mods/game/....h
<code>//depot/'''LocalModCode/'''... //LocalModCode/... </code>
 
</blockquote>
 
  
* Click '''Update'''.
+
Of course, if you've added files outside the <code>\game</code> folder and/or that aren't .cpp or .h, you'll need to perform extra commands to pick them up.
             
 
           
 
* A dialog will come up asking if you want to '''Sync To Head''' (i.e. copy the latest files from the codeline to your hard drive). Since there are no files in the codeline yet, click '''Dont Sync'''.
 
  
[[Image:Source_control_clientspec_local_mod.gif]]
+
Right-click on your branch root and hit the "Revert Unchanged Files" option, then submit the changelist and we'll move on.
  
* Click on the '''BranchSpec''' menu and choose '''New'''.
+
{{tip|If you do end up with VS's binary files in the depot, you can delete them from the database with these console commands (which are given without the confirming <code>-y</code> switch):
* At the next dialog, make these changes (and leave the other fields as they are):
 
  
# Set '''Branch''' to <code>valve_to_mod</code>.
+
p4 obliterate //....ncb
# Change the '''View''' section to read like this:
+
p4 obliterate //....sdf
<code>//depot/ValveSDKCode/... //depot/LocalModCode/... </code>
+
p4 obliterate //....ipch
</blockquote>
+
p4 obliterate //....obj
 +
p4 obliterate //....pdb
 +
p4 obliterate //....pch
 +
}}
  
* Click '''Update'''.
+
=== Submit trunk update ===
* We just told Perforce that we want to map the files from Codeline A (<code>//depot/ValveSDKCode</code>) into Codeline B (<code>//depot/LocalModCode</code>). All we have to do now is branch the files over.
 
  
[[Image:Source_control_branchspec.gif]]
+
The 'trunk' contains Valve's unmodified SDK code, which now needs updating too. Delete any workspace files from your \valvesrc folder then [[Create a Mod|install the new code]] there with the Create a Mod wizard's 'Source code only' option.
  
* Hit '''F10''' to flip back to the ClientSpec view.
+
Now switch to workspace view in P4V and right-click on the \valvesrc folder. Choose 'Reconcile Offline Work', which is in the same section as Submit and Revert. Leave all the checkboxes in the window that opens active and click 'Reconcile'. Then submit the changes.
* On the left-hand side of the Perforce window, you should see a tree control with <code>//depot</code> at the root.  Right-click on <code>//depot</code>, and choose '''Integrate Using''', then choose '''Branchspec''' in the popup menu.
 
  
[[Image:Source_control_integrate_branchspec.gif]]
+
=== Integrate ===
  
* The <code>valve_to_mod</code> BranchSpec that we just created should be selected.
+
We've got the latest code for both projects in the depot, so it's time to integrate them. To do this, execute your <code>valve_to_mymod</code> branch again.
* Click '''Next'''.
 
  
[[Image:Source_control_perforce_branches.gif]]
+
The difference this time is that you'll need to resolve files that have changed between the versions. Since Perforce knows the point at which your mod code branched it can make a very good guess as to what version of a file should take precedence in most cases. You'll only have to manually inspect changes if there's a conflict that can't be resolved automatically.
  
* In this dialog, the only thing you need to change is the radio buttons next to the '''File Specifications - Integrate''' area in the middle.
+
Remember that a) you don't have to submit the integrated code until you're happy and b) you can always revert to the earlier, unmerged version of a file if the process later turns out to have gone wrong.
* Check the '''To''' button, as shown in the image below.
 
* Click '''Finish'''.
 
* Perforce will spit out a lot of messages like this:
 
  
<code>//depot/LocalModCode/dlls/particle_light.h#1 - branch/sync from //depot/ValveSDKCode/dlls/particle_light.h#1</code>
+
For more details on merging, open P4Merge's help tool.
 
* When Perforce is done branching all the files from the previous step, you can proceed to the next step.
 
  
[[Image:Source_control_final_integrate.gif]]
+
{{tip|If Perforce queries a .lib file, always accept Valve's.}}
  
* At this point, Perforce has a big list of all the files it wants to branch from Codeline A into Codeline B. All that remains is to '''Submit''' the change.
+
=== Test the new code ===
* Hit '''F6''' to bring up the '''Change List''' pane in Perforce.
 
* In the right-hand panel, there will be a tree control that says '''Pending Changelists''', and right under there, '''Default'''.
 
* Right-click on '''Default''', and choose '''Submit'''.
 
  
[[Image:Source_control_about_to_submit_branched_code.gif]]
+
At this point, you should do a pass of the code to fix any compile errors that may have been introduced by the code merge. You could also do this pass before submitting the merged code changelist, but it tends to be easier to make changes starting with an empty changelist rather than one full of code merges.
  
* In this dialog, enter anything you want into the '''Description''' field and click '''Submit'''.
+
And you're done!
  
[[Image:Source_control_submit_branched_code.gif]]
+
== Conclusion ==
  
At this point, you have Codeline A and Codeline B setup on the Perforce server.
+
Working with a source control introduces some concepts that take getting used to, but it pays dividends. It saves time, helps teams work together on the same product, and provides access to the whole history of a project.  
  
<h3>Copying Your Code Into Codeline B</h3>
+
Keep in mind that, while this document has a lot of steps, this stuff is all trivial once you're familiar with Perforce. Once you know how this all works, all these integrations and merges can be done in a matter of minutes. Valve recommend that you jump back to the "overview" section of this document to review the high-level process that is involved, and see how all the detailed steps fit into that simple high-level process.
  
If, before embarking on this document, you already had source code for a mod you were working on, you should follow the instructions in this section. Otherwise (i.e. if you are starting a new set of mod source code right now), you should skip over this section and start reading at "Moving Codeline B's Directory" below.  
+
Internally, Valve uses source control in a similar fashion to that described in this document. The main difference is that ALL files for Valve games go in Perforce, including content source .TGA artwork, .VMT files, executables, scripts, documents, etc. They recommend doing this while developing a mod as well, bandwidth limits and disc space allowing, because you can instantly restore any version of the mod that ever existed.
  
* In Perforce, hit '''F10''' to go to your ClientSpecs list.
+
Valve also uses a multitude of codelines (whereas there are just two in this document). For example, they have a main codeline that about 20 programmers submit code into. Often programmers need to stay sheltered from other people's changes (which may happen as many as 19 times per day!), so each programmer has their own set of personal codelines that are branched off the main codeline. This way, the programmers can choose when they want to integrate their colleague's changes into their personal codeline (just like you now have the choice about when you want to integrate Valve's SDK updates into your own codeline).
* If the <code>LocalModCode</code> ClientSpec doesn't have a green arrow next to it (i.e. it is not the active ClientSpec), right-click on it and choose '''Switch to LocalModCode'''.
 
  
[[Image:Source_control_switch_to_local_mod_code.gif]]
+
== See also ==
  
* On the left-hand side, right-click on <code>//depot</code> and choose '''Open For Edit'''.
+
* [[Using Subversion for Source Control with the Source SDK]]
* Answer '''Yes''' to the dialog asking if you want to proceed with the edit.
+
* [http://www.perforce.com/perforce/technical.html Official Perforce documentation]
 +
* [http://public.perforce.com/public/perforce/faq/beginner.html Perforce Beginner's FAQ]
 +
* [http://www.perforce.com/perforce/technotes/note064.html Integrating Perforce with Visual Studio] (Visual C++ Express does not support this)
 +
* [http://www.perforce.com/perforce/doc.092/manuals/p4sag/02_backup.html Backing up and restoring your server]
  
[[Image:Source_control_open_for_edit.gif]]
+
[[Category:Programming]]
 
+
[[Category:Tutorials]]
* Now, either in Windows explorer or in a command prompt, copy the source tree from your mod into <code>C:\LocalModCode</code>. For example, if you installed your mod into <code>C:\MyMod</code>, the command line would be:
 
<code> xcopy C:\MyMod\src C:\LocalModCode /e </code>
 
 
 
* We also need to make sure that any extra files files in your mod's code are added to Perforce.
 
* Open a command prompt and <code>cd</code> to <code>C:\LocalModCode</code>.
 
* To tell Perforce which client workspace you're adding the files to, type:
 
 
 
<code> set p4client=LocalModCode</code>
 
 
 
* Then type the following command to add all the files to the depot:
 
 
 
<code> for /R %i in (*.*) do @p4 add "%i"</code>
 
 
 
* Perforce will be scrolling lines like this:
 
 
 
<code>//depot/LocalModCode/vgui2/controls/controls.cpp - can't add existing file</code>
 
 
 
* This just means that Perforce already has most of the files on its server, so now we'll check to see if there were any new ones.
 
 
 
 
 
[[Image:Source_control_add_files_to_localmodcode.gif]]
 
 
 
* Hit '''F6''' to bring up the 'Change List' pane in Perforce.
 
* In the right-hand panel, there will be a tree control that says '''Pending Changelists''', and right under there, '''Default'''.
 
* Right-click on '''Default''', and choose '''Revert Unchanged Files'''
 
* Perforce will work for a few minutes gathering the file list.
 
 
 
[[Image:Source_control_revert_unchanged.gif]]
 
 
 
* When this dialog appears listing the files to Revert, click '''Revert Files'''.
 
 
 
[[Image:Source_control_revert_unchanged_final.gif]]
 
 
 
* Hit '''F6''' to bring up the 'Change List' area in Perforce.
 
* In the right-hand pane, there will be a tree control that says '''Pending Changelists''', and right under there, '''Default'''.
 
* Right-click on '''Default''', and choose '''Submit'''
 
 
 
[[Image:Source_control_about_to_submit_branched_code.gif]]
 
 
 
* In this dialog, enter anything you want into the '''Description''' field, then click '''Submit'''.
 
 
 
[[Image:Source_control_submit_branched_code.gif]]
 
 
 
 
 
<h3>Moving Codeline B's Directory</h3>
 
 
 
At this point, the Perforce server has your mod's latest code in Codeline B. The only problem now is that you've got Codeline B in <code>C:\LocalModCode</code>, and you may want it elsewhere (like in <code>C:\MyMod\src</code> if you installed your mod into <code>C:\MyMod</code>). To move where Codeline B is stored on your hard drive, follow the steps below.
 
 
 
First, if you want Codeline B to sit in the same directory where you had your source code previously (if you were already working on a mod), then go rename that directory to something else for now. '''Note: '''You should have already copied your source code into Codeline B in the "Copying Your Code Into Codeline B" section, so we're just going to tell Perforce that we want Codeline B's code in the directory you copied from.
 
 
For example, if you already were working on a mod, and its source code was in <code>C:\MyMod\src</code>, then in the "Copying Your Code Into Codeline B" section, you would have copied from <code>C:\MyMod\src</code> into <code>C:\LocalModCode</code>. Now, you would rename the <code>C:\MyMod\src</code> directory to something else, and we'll tell Perforce to put Codeline B's source code in <code>C:\MyMod\src</code>.
 
 
 
* In Perforce, hit '''F10''' to go to your ClientSpecs list.
 
* If the '''LocalModCode''' ClientSpec doesn't have a green arrow next to it (i.e. it is not the active ClientSpec), right-click on it and choose '''Switch to LocalModCode'''.
 
 
 
[[Image:Source_control_switch_to_local_mod_code.gif]]
 
 
 
* Right-click on '''LocalModCode''' and choose the '''Edit LocalModCode''' option from the popup menu.
 
 
 
[[Image:Source_control_edit_local_mod_spec.gif]]
 
 
 
* In this dialog, edit the '''Root''' field to point to where you want Codeline B's source code on your hard drive. '''Note:''' <code>C:\MyMod\src</code> is just an example. What you enter here depends on where you want to work on your mod.
 
 
 
[[Image:Source_control_change_local_mod_dir.gif]]
 
 
 
* Click '''Yes''' in this dialog.
 
 
 
[[Image:Source_control_confirm_change_root.gif]]
 
 
 
* Now we need to have Perforce copy the latest source code for Codeline B back into the directory you just specified, so you can edit it.
 
* In the left-hand pane, there should be a tree control with <code>//depot</code> at the root.
 
* Right-click on it, go to '''Sync''', then select the '''Force sync to Head Revision''' option from the sub-menu.
 
* Perforce will now copy all the source code into the directory you specified earlier.
 
 
 
[[Image:Source_control_force_sync.gif]]
 
 
 
 
 
==Editing Your Source Code In Perforce==
 
 
At this point, you should be all set to continue with development of your mod. The main thing to be aware of is that Perforce needs to know about any changes to the source code you are making. What you do is build a <em>changelist</em> of the files that you've edited, and you <em>Submit</em> the changelist to Perforce. For a complete description of how to use Perforce, see the [http://www.perforce.com/perforce/doc.042/manuals/p4guide/index.html Perforce Documentation].
 
 
 
 
 
<h3>Editing Files</h3>
 
 
 
* In Perforce, hit '''F10''' to go to your ClientSpecs list.
 
* If the '''LocalModCode''' ClientSpec doesn't have a green arrow next to it (i.e. it is not the active ClientSpec),
 
right-click on it and choose '''Switch to LocalModCode'''.
 
 
 
[[Image:Source_control_switch_to_local_mod_code.gif]]
 
 
 
* On the left-hand side, there should be a tree control with <code>//depot</code> at the root.
 
* Navigate  the tree control by clicking the &quot;+&quot; next to folders, to the file you want to edit. Then right-click the file and choose '''Open for Edit'''.
 
* Now you can edit the file on your local hard drive (but don't forget to submit the changelist when you are done).
 
 
 
[[Image:Source_control_open_file_for_edit.gif]]
 
 
 
 
 
<h3>Adding Files</h3>
 
 
 
This section describes how to add a new source code file to Perforce.
 
 
 
* In Perforce, hit '''F10''' to go to your ClientSpecs list.
 
* If the '''LocalModCode''' ClientSpec doesn't have a green arrow next to it (i.e. it is not the active ClientSpec), right-click on it and choose '''Switch to LocalModCode'''.
 
 
 
[[Image:Source_control_switch_to_local_mod_code.gif]]
 
 
 
* Go to the '''File''' menu and choose '''Add to Source Control'''.
 
* Find the file you want to add and double-click on it.
 
* At the following dialog, make sure that the files listed are the files you want to add, then click the '''Add Files''' button.
 
 
 
[[Image:Source_control_add_file.gif]]
 
 
 
 
 
<h3>Submitting Changelists</h3>
 
 
 
As you add and edit files, they sit in a temporary area waiting to be <em>Submitted</em> to Perforce. The nice thing about this is that you can revert your changes at any time, in case you decide to back up and start over on them. Once you have a set of changes that you do want to commit to Perforce (which will give you the ability to restore that version and to make it available to other users), follow the steps below to submit the change.
 
 
 
* In Perforce, hit '''F10''' to switch the right pane to your ClientSpecs list.
 
* If the '''LocalModCode''' ClientSpec doesn't have a green arrow next to it (ie: it is not the active ClientSpec), right-click on it and choose '''Switch to LocalModCode'''.
 
 
 
[[Image:Source_control_switch_to_local_mod_code.gif]]
 
 
 
* Hit '''F6''' to bring up the '''Change List''' pane in Perforce.
 
* In the right-hand pane, there will be a tree control that says '''Pending Changelists''', and right under there, '''Default'''.
 
* Right-click on '''Default''', and choose '''Submit'''.
 
 
 
[[Image:Source_control_about_to_submit_branched_code.gif]]
 
 
 
* In this dialog, enter anything you want into the '''Description''' field, and then click '''Submit'''.
 
 
 
[[Image:Source_control_submit_branched_code.gif]]
 
 
 
 
 
==Integrating SDK Code Into Your Mod==
 
 
 
This section assumes you've setup the codelines as described above. When new code from Valve comes out, you can use the steps here to merge it into your code. First, make sure that you have submitted any changelists in your '''LocalModCode''' client workspace.
 
 
 
* In Perforce, hit '''F10''' to go to your ClientSpecs list.
 
* If the '''ValveSDKCode''' ClientSpec doesn't have a green arrow next to it (ie: it is not the active ClientSpec), right-click on it and choose '''Switch to ValveSDKCode'''.
 
 
 
[[Image:Source_control_switch_to_valvesdkcode.gif]]
 
 
 
* On the left-hand side, right-click on <code>//depot</code> and choose '''Open For Edit'''.
 
* Answer '''Yes''' to the dialog asking if you want to proceed with the edit.
 
 
 
[[Image:Source_control_open_for_edit.gif]]
 
 
 
* Run the Source SDK and choose '''Create a Mod'''.
 
* Choose the '''Source code only''' option and click '''Next'''.
 
 
 
[[Image:Source_control_create_mod.gif]]
 
 
 
* Enter in the directory name you chose above to hold the Valve code (<code>C:\ValveSDKCode</code>).
 
* Click '''Next'''.
 
* All the latest source code will be copied into the directory (<code>C:\ValveSDKCode</code>, in this example).
 
 
 
[[Image:Source_control_mod_info.gif]]
 
 
 
* We don't want to merge in the .vcproj files, because they are difficult to merge. It's easier to just add and remove any changes in your '''LocalModCode''' codeline.
 
* Open a command prompt and <code>cd</code> into the <code>C:\ValveSDKCode</code> directory.
 
* Next type:
 
<code> set p4client=ValveSDKCode</code>
 
* And then:
 
<code>for /R %i in (*.vcproj) do @p4 revert "%i"</code>
 
 
 
[[Image:Source_control_revert_vcproj.gif]]
 
 
 
* Hit '''F6''' to bring up the 'Change List' area in Perforce.
 
* In the right-hand pane, there will be a tree control that says '''Pending Changelists''', and right under there, '''Default'''.
 
* Right-click on '''Default''', and choose '''Revert Unchanged Files.'''
 
* Perforce will work for a few minutes.
 
 
 
[[Image:Source_control_revert_unchanged.gif]]
 
 
 
* When this dialog appears, click '''Revert Files'''.
 
 
 
[[Image:Source_control_revert_unchanged_final.gif]]
 
 
 
* In the right-hand panel, there will be a tree control that says '''Pending Changelists''', and right under there, '''Default'''.
 
* Right-click on '''Default''', and choose '''Submit'''.
 
 
 
[[Image:Source_control_about_to_submit_branched_code.gif]]
 
 
 
* In this dialog, enter anything you want into the '''Description''' field and click '''Submit'''.
 
* At this point, Perforce now has the latest Valve code in Codeline A (<code>ValveSDKCode</code>). What remains to be done  is to tell Perforce to integrate the changes that just happened in Codeline A into Codeline B. Perforce will automatically detect which files changed, and it will move those changes into your MOD's code.
 
 
 
[[Image:Source_control_submit_branched_code.gif]]
 
 
 
* In Perforce, hit '''F10''' to go to your ClientSpecs list.
 
* If the '''LocalModCode''' ClientSpec doesn't have a green arrow next to it (i.e. it is not the active ClientSpec), right-click on it and choose '''Switch to LocalModCode'''.
 
 
 
[[Image:Source_control_switch_to_local_mod_code.gif]]
 
 
 
* On the left-hand pane of the Perforce window, you should see a tree control with <code>//depot</code> at the root. Right-click on <code>//depot</code>, and choose '''Integrate Using''', then choose '''Branchspec''' in the sub-menu.
 
 
 
[[Image:Source_control_integrate_branchspec.gif]]
 
 
 
* The <code>valve_to_mod</code> BranchSpec that we just created should be selected.
 
* Click '''Next'''.
 
 
 
[[Image:Source_control_perforce_branches.gif]]
 
 
 
* In this dialog, the only thing you need to change is the radio buttons next to the '''File Specifications - Integrate''' area in the middle.
 
* Select the '''To''' button, as shown in the image to the right.
 
* Click '''Finish'''.
 
 
 
[[Image:Source_control_final_integrate.gif]]
 
 
 
* Hit '''F6''' to bring up the changelists pane on the right.
 
* There should be a tree control that says, '''Pending Changelists (client 'LocalModCode')''' with a bunch of files in the tree (when you expand the tree).
 
* Right-click on any file and choose '''Resolve''', then '''Auto resolve...''' from the sub-menu.
 
 
 
[[Image:Source_control_auto_resolve.gif]]
 
 
 
* In this dialog, the only thing you need to change is to make sure the '''All open files requiring resolution''' option is checked.
 
* Then click the '''OK''' button.
 
 
 
[[Image:Source_control_auto_resolve_dialog.gif]]
 
 
 
* Now, look over all the files in the tree control, and if there are any with a yellow exclamation point next to them, it means that they couldn't be automatically resolved by Perforce (see example in this image). This means that changes you have made in your '''LocalModCode''' codeline are conflicting with changes Valve has made, and you will have to resolve them manually. If there are no yellow exclamation points, then you can skip to the last step of this section where you submit the change.
 
 
 
[[Image:Source_control_yellow_exclamation.gif]]
 
 
 
* First, if there are any library (.LIB) files with yellow exclamation marks, you want to use Valve's version of the .LIB file.
 
* Select all the .LIB files with yellow exclamation marks.
 
* Right-click, and choose '''Resolve''', then '''Auto Resolve''' from the sub-menu.
 
 
 
[[Image:Source_control_resolve_libs.gif]]
 
 
 
* In the dialog that comes up, make sure that the '''Accept Theirs''' option is selected.
 
* Click the '''OK''' button.
 
 
 
[[Image:Source_control_accept_theirs.gif]]
 
 
 
* For all other files (ones that aren't .LIB files), you must resolve them manually.
 
* For each file, right-click on it and choose '''Resolve''', then ''' Interactively''' from the sub-menu.
 
* Perforce will bring up a 3-way merge application that lets you merge Valve's changes into your code.
 
 
 
[[Image:Source_control_resolve_interactively.gif]]
 
 
 
* Click on the '''Run Merge Utility''' button on this dialog.
 
 
 
[[Image:Source_control_resolve_interactively_dialog.gif]]
 
 
 
* Here is a brief description of how to use Perforce's default 3-way merge utility.
 
 
 
<blockquote>
 
* The top-left window pane contains Valve's version of the file.
 
* The top-right window pane has your version of the file.
 
* The bottom window pane has the merged version of the file.
 
</blockquote>
 
 
 
* Use the green button in the toolbar on the top to go to each difference.
 
* At each difference, pick which of the top windows you want to keep the source from, and double-click on the section of code that you want to move into the bottom window.
 
* You can also right-click in the bottom window to edit the source code directly.
 
 
 
[[Image:Source_control_interactive_merge_window.gif]]
 
 
 
* Now, finally, you can submit the merged version.
 
* In the right-hand panel, there will be a tree control that says '''Pending Changelists''', and right under there, '''Default'''.
 
* Right-click on '''Default''', and choose '''Submit'''.
 
 
 
[[Image:Source_control_about_to_submit_branched_code.gif]]
 
 
 
* In this dialog, enter anything you want into the '''Description''' field and click '''Submit'''.
 
 
 
[[Image:Source_control_submit_branched_code.gif]]
 
 
 
At this point, you should do a fixup pass on the code to fix any compile errors that may have been introduced by the code merge. You could also do this pass right before submitting the merged code changelist, but it tends to be easier to make changes starting with an empty changelist rather than one full of code merges.
 
 
 
 
 
==Further Investigations==
 
 
 
We highly recommend that you read the [http://public.perforce.com/public/perforce/faq/beginner.html Perforce Beginner's FAQ] and look at the [http://www.perforce.com/perforce/doc.042/manuals/p4guide/index.html Perforce Documentation] if necessary, and get acquainted with:
 
 
 
* Codelines
 
* Client workspaces
 
* Changelists
 
* Branches
 
* Integrations
 
 
 
 
 
Working with a source control introduces some concepts that take getting used to, but it pays dividends. It saves time, helps teams work together on the same product, and provides access to the whole history of a project.
 
 
 
Keep in mind that, while this document has a lot of steps, this stuff is all trivial once you're familiar with Perforce. Once you know how this all works, all these integrations and merges can be done in a matter of minutes. We recommend that you jump back to the "overview" section of this document to review the high-level process that is involved, and see how all the detailed steps fit into that simple high-level process.
 
 
 
Internally, Valve uses source control in a similar fashion to that described in this document. The main difference is that ALL files for Valve games go in Perforce, including content source .TGA artwork, .VMT files, executables, scripts, documents, etc. We recommend doing this while developing a mod as well, because you can instantly restore any version of the mod that ever existed.
 
 
 
Valve also uses a multitude of codelines (whereas there are just two in this document). For example, we have a main codeline that about 20 programmers submit code into. Oftentimes, programmers need to stay sheltered from other people's changes (which may happen as many as 20 times per day), so each programmer has their own set of personal codelines that are branched off the main codeline. This way, they can choose when they want to integrate all the changes from other programmers into their personal codeline (just like you now have the choice about when you want to integrate Valve's source code into your mod's source code).
 
 
 
Happy coding!
 

Latest revision as of 22:38, 28 August 2012

Русский

This article describes how to use source control with the Source SDK. You will want to use source control even if you're working alone, as it largely automates the process of merging code updates released on Steam – without it, you'll be in a world of hurt every time!

This document discusses Perforce, the source control system used internally by Valve. It's free for up to 20 users. Other alternatives include Subversion or CVS. Since all version control systems work with the same high-level processes, this article should still be useful. (Nevertheless, there are specific articles for Subversion and Git.)

Before you begin

If you have started programming without source control, STOP! Source control needs to be set up at the earliest opportunity, especially since every time a Steam update is released older versions of the base SDK code are lost.

If you're reading this as you try to apply an update that's already out to your unversioned code, it is too late, and you must merge the changes the hard way. Tools like Beyond Compare can make this process easier, and if you follow this tutorial after finishing it should be the last time you ever have to endure it.

Get Perforce

With that out of the way, it's time to get Perforce. You want both the visual client (which includes the command-line client anyway) and the server. Take care when installing to leave the network server configuration alone unless you are actually going to connect somewhere remote.

If you are using Visual Studio (as opposed to Visual C++ Express) you should also consider downloading the SCC plugin, which integrates Perforce into the IDE.

Tip.png Tip: Perforce provide documentation of their own which you may want to consult. It isn't as specific as this guide, however.
Tip.png Tip: If you make a mistake while following this tutorial and need to reset Perforce's database, execute this from the command prompt: p4 obliterate –y //depot/.... DON'T do this on a database that's already up and running!

Overview

We will make a fresh install of Valve's SDK code and submit it to the Perforce server. We will then 'branch' that submitted code to a second location, which allows you to work with the code as you see fit while retaining the ability to easily 'integrate' future SDK updates from Valve into your project.

This means that you will have two 'codelines' on your Perforce server. Valve's, which will only change with SDK updates, and your own, which will change both whenever you decide to submit your work to it, and whenever you decide to integrate SDK updates from Valve.

Setting up source control

Valve's base SDK code will form the 'trunk' of your codebase, from which your mod code will 'branch'. Get Valve's code with the Create a Mod wizard, choosing the "source code only" option and installing to a location in your user dir like C:\Users\You\Mods\valvesrc. Making a \Mods folder is important, as you will discover later.

Tip.png Tip: If you're using Windows Vista or later it's a good idea to remove the \Mods folder from the search index. Use the Indexing Options tool, which is in the start menu, to do this. You'll need admin privileges.

Create a workspace

Now we'll start using Perforce. Start P4V, the visual client. You will be greeted by the "Open Connection" dialogue.

Perforce open connection dialogue

Unless you are actually connecting to a network server you can ignore all of the options it gives you except Workspace. Click 'new', to the right, and name the workspace 'mods' (or whatever you please - but the rest of this guide assumes it's called mods).

Workspaces link folders containing your files with the location(s) on the Perforce server where they are archived. Earlier versions of this guide suggested that one workspace be created per codeline, but this is unnecessary. We're going to create just one that will encompass all of the SDK projects on your computer, which is why creating a \Mods folder was recommended above.

Most of the fields in the New Workspace dialogue should be self-explanatory, and you only need to worry about two anyway:

  • Root should point to your Source projects folder - C:\Users\You\Mods\ if you followed the instructions above precisely.
  • View contains two locations, separated by whitespace:
    1. A location on the Perforce server
    2. The location that it should correspond to in the workspace

Unless you've deviated from this tutorial, the running Perforce server is called 'depot' and your workspace is called 'mods'. We aren't doing anything complex, so View should tie the depot root to the workspace root:

//depot/sourcemods/... //mods/...

The /sourcemods subfolder will keep your mod projects separate from any other workspaces you create in the future. If you're absolutely sure that this server will only be used with one workspace you can use the root //depot/... path instead.

Submit the trunk source code

We now have a workspace filled with Valve's base SDK code, but the Perforce server is still empty. We need to get our files up there. To do that we'll be using the main P4V interface, which having created a workspace should currently be in front of you.

P4V interface overview
Tip.png Tip: You can also get an overview of the interface from Help > Getting Started with P4V.
  1. Workspace/depot view (left pane). Click on the tabs at the bottom to change between the two. Workspace is your local copy, depot is the server's master copy.
  2. Task tabs (right pane). The tabs along the bottom of this pane allow you to switch between different tasks. They are opened as needed from the main menu buttons. We will be using Pending, Workspaces and Branches.
  3. Log. Errors will appear in bold text.
  4. Main menu. Most of the options here are available elsewhere in the interface, but it's useful to have them in one place too.

Bring up the workspace view and we'll submit the code. It's a two-step process:

  1. Mark the files for addition. We want to add everything, so select the whole \valvesrc folder and click 'Mark for Add'. You can find the Add button on the main menu or in the context menu; it's the file icon with a plus over it. There are a lot of files in the SDK, so it might take a while for the operation to complete. When it's finished, all of the files in the workspace view will have changed appearance to reflect that they are now being version controlled.
  2. Submit the changelist. Move to the 'Pending' tab (the red, upwards arrow) and you'll see that there's an item called 'default' that contains all of the files you just added. Submit it with a double-click (or Ctrl+S). You'll need to enter a brief description of what the changes are.

Once the process has finished, you'll be able to browse to the newly-populated depot view. Congratulations! You can now safely delete the \valvesrc folder.

Create and execute the branch

Note.png Note: You can't properly branch to a location that's already populated. If you've already made changes to the code that you want to keep, back the files you've changed up somewhere before deleting the rest of the old source folder. You'll have to manually add everything back later.

Choose File > New > Branch Specification... to create a new 'branch'. A branch operation tells Perforce to copy code to a separate location while remembering where it came from, and when — vital information when it comes to integrating SDK updates.

The view field of a branch is slightly different to that of a workspace: both halves refer to locations on the server. Yours should read something like this:

//depot/valvesrc/... //depot/mymod/...

Although we've just specified a destination on the server, the new branch will actually be created in the workspace. This is so that you can examine how the integration turned out before committing to anything: polite behaviour that isn't terribly useful at this point, since we are "integrating" with an empty folder!

Note.png Note: To see the newly created branch in the workspace, use the Branch Mappings tab. You can Enable it by way of View > Branch Mappings... or Ctrl+3
Tip.png Tip: The confusing error "No target file(s) in both client and branch view" means that one or both paths in the View are pointing to the wrong location. Don't forget to include any subfolders you made.

A good name for the branch is valve_to_mymod. Hit OK and it will be created: now we just need to execute it. Right-click on your new branch and select the 'Integrate Using' option. You should be able to start the process without changing anything.

Preparing to execute a branch in Perforce

You now have the 'mymod' branch of valvesrc registered on the server, and its files sitting in your workspace. Submit them in the same way as you did the trunk code.

Check out

All version-controlled files in your workspace are read-only unless you have them 'checked out' of the server. This is useful when you're working with a team of programmers, as it makes developers aware of which files they are each working on, but can still help to keep things organised when you are working alone.

To check a file or folder out, select it and hit Ctrl+E or use the context menu.

If you are working alone you might think it logical to check out the entire workspace, and this is a perfectly valid option. However, it will help you keep track of your changes between submissions if you only check out those files that you need to modify.

Warning.png Warning: Resist the temptation to manually remove the read-only flag from your versioned files. This desynchronizes Perforce and may confuse it (and you) later on.

Integrating SDK updates

We've now got source control up and running for your mod. It might have seemed complex, but the steps above only need to be performed once and this stuff will soon become grist for the mill anyway.

You can use source control as an ongoing backup, to compare code with what came before or after it, to revert changes, share code with others and contribute collaboratively, and, of course, to integrate trunk updates, which is what we'll be doing in this section.

Submit pending branch changes

You already know how to submit, but this is an appropriate time to remind you that newly-created files aren't automatically added to version control.

P4V only supports adding files individually, which is fiddly, or by folder, which will pick up all the huge binary files generated by Visual Studio that you definitely don't want on the server. To add files with a wildcard search, we must turn to the command line.

Open CMD and execute these commands ('client' is another word for workspace):

set p4client mods
p4 add //mods/game/....cpp
p4 add //mods/game/....h

Of course, if you've added files outside the \game folder and/or that aren't .cpp or .h, you'll need to perform extra commands to pick them up.

Right-click on your branch root and hit the "Revert Unchanged Files" option, then submit the changelist and we'll move on.

Tip.png Tip: If you do end up with VS's binary files in the depot, you can delete them from the database with these console commands (which are given without the confirming -y switch):
p4 obliterate //....ncb
p4 obliterate //....sdf
p4 obliterate //....ipch
p4 obliterate //....obj
p4 obliterate //....pdb
p4 obliterate //....pch

Submit trunk update

The 'trunk' contains Valve's unmodified SDK code, which now needs updating too. Delete any workspace files from your \valvesrc folder then install the new code there with the Create a Mod wizard's 'Source code only' option.

Now switch to workspace view in P4V and right-click on the \valvesrc folder. Choose 'Reconcile Offline Work', which is in the same section as Submit and Revert. Leave all the checkboxes in the window that opens active and click 'Reconcile'. Then submit the changes.

Integrate

We've got the latest code for both projects in the depot, so it's time to integrate them. To do this, execute your valve_to_mymod branch again.

The difference this time is that you'll need to resolve files that have changed between the versions. Since Perforce knows the point at which your mod code branched it can make a very good guess as to what version of a file should take precedence in most cases. You'll only have to manually inspect changes if there's a conflict that can't be resolved automatically.

Remember that a) you don't have to submit the integrated code until you're happy and b) you can always revert to the earlier, unmerged version of a file if the process later turns out to have gone wrong.

For more details on merging, open P4Merge's help tool.

Tip.png Tip: If Perforce queries a .lib file, always accept Valve's.

Test the new code

At this point, you should do a pass of the code to fix any compile errors that may have been introduced by the code merge. You could also do this pass before submitting the merged code changelist, but it tends to be easier to make changes starting with an empty changelist rather than one full of code merges.

And you're done!

Conclusion

Working with a source control introduces some concepts that take getting used to, but it pays dividends. It saves time, helps teams work together on the same product, and provides access to the whole history of a project.

Keep in mind that, while this document has a lot of steps, this stuff is all trivial once you're familiar with Perforce. Once you know how this all works, all these integrations and merges can be done in a matter of minutes. Valve recommend that you jump back to the "overview" section of this document to review the high-level process that is involved, and see how all the detailed steps fit into that simple high-level process.

Internally, Valve uses source control in a similar fashion to that described in this document. The main difference is that ALL files for Valve games go in Perforce, including content source .TGA artwork, .VMT files, executables, scripts, documents, etc. They recommend doing this while developing a mod as well, bandwidth limits and disc space allowing, because you can instantly restore any version of the mod that ever existed.

Valve also uses a multitude of codelines (whereas there are just two in this document). For example, they have a main codeline that about 20 programmers submit code into. Often programmers need to stay sheltered from other people's changes (which may happen as many as 19 times per day!), so each programmer has their own set of personal codelines that are branched off the main codeline. This way, the programmers can choose when they want to integrate their colleague's changes into their personal codeline (just like you now have the choice about when you want to integrate Valve's SDK updates into your own codeline).

See also