VPC Scripts

From Valve Developer Community
Revision as of 17:50, 26 July 2025 by SomeoneTookSeven (talk | contribs) (Created page with "VPC (or Valve Project Creator) is a a command line tool that ships with the Source SDK. This tool is used for constructing Visual Studio projects (<code>.vcproj</code>) with consistent project properties. The Source Engine uses pre-processor definitions to determine what code needs to be compiled in any given file for the target settings. While the SDK does use some pre-defined definitions set by the compiler or operating system, it also uses custom definitions like <co...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

VPC (or Valve Project Creator) is a a command line tool that ships with the Source SDK. This tool is used for constructing Visual Studio projects (.vcproj) with consistent project properties.

The Source Engine uses pre-processor definitions to determine what code needs to be compiled in any given file for the target settings. While the SDK does use some pre-defined definitions set by the compiler or operating system, it also uses custom definitions like CLIENT_DLL and TF_CLIENT_DLL to tell the compiler what is or isn't needed from that file.

This is done for maximum reusability. Every file in the source engine will be functional across all projects and platforms as long as the preprocessors are setup correctly. While extremely useful, it can be un-intuitive at times when read the source code to understand why things were implemented the way they were.

Using VPC

VPC gets really powerful in two distinct ways. First is the command line. VPC offers a quick, consistent, and easy way to generate or modify large source engine projects.

if you have downloaded the SDK and opened it (if you haven't please see a relevant page about that) you would have already used VPC in the form of a .bat file.

When you ran createallprojects.bat you actually ran the code: 

devtools\bin\vpc.exe /hl2mp /tf /define:SOURCESDK +everything /mksln everything.sln

This simplifies the process of creating project files and ensure that those working in teams can all have a consistent setup.

Below is the output of VPC /h. Also known as the help command: 

VPC - Valve Project Creator (Build: Mar  8 2025 19:08:18)
Copyright (c) Valve Corporation. All Rights Reserved.

Source Path: C:\Users\User\Desktop\SDK\source-sdk-2013\src
Target Platform: win64
Generating for Visual Studio 2022.


usage: vpc [options] <+/-/*/@project or group>

  Use +/- to add or remove projects or groups.
  Use *   to add a project and all projects that depend on it.
  Use @   to add a project and all projects that it depends on.

  Use /h spew final target build set ONLY (no .vcproj created).

Examples:

  Single .vcproj generation:
    vpc +client /hl2     <-- Creates a Win32 .vcproj for the HL2 client.
    vpc +shaderapi /x360 <-- Creates a Xbox360 .vcproj for the shaderapi.

  Multiple .vcproj generation - Multiple Projects for Games:
    vpc +client /hl2 /tf     <-- Creates ALL the Win32 .vcprojs for the HL2 and TF client.
    vpc +gamedlls /allgames  <-- Creates ALL the Win32 .vcprojs for client and server for all GAMES.
    vpc +tools -tier0 /win32 <-- Creates ALL the Win32 .vcprojs for the tool projects but not the tier0 project.

  Automatically expand and add projects based on dependencies:
    vpc *tier2 <--- Would expand out to every project that needs tier2. i.e. How do I know what projects are affected for my tier2 change?
    vpc @engine <--- Would expand out to every project that engine requires. i.e. What projects might I need to fully debug engine?

  Creating Solutions:
    vpc /mksln foo.sln *tier2 +bar <--- Builds a foo solution of all tier2 consumers and bar. Sets up solution dependencies as required.
    vpc /mksln foo.sln @engine +bar <--- Builds a foo solution of engine and all the projects it requires and bar. Sets up solution dependencies as required.
    vpc /p4sln checkin.sln 0 <--- Builds a checkin solution with all dependencies based on whatever is in the current p4 client's changelists.

  Further details can be found on Valve Internal Wiki on VPC.

--- OPTIONS ---
[/q]:           Quiet mode (quiet mode is automatically on if the VPC_QUIET environment variable is set)
[/qv]:          Quiet just the CRC valid spew for those projects that are up-to-date.
[/v]:           Verbose
[/f]:           Force rewrite project files, even if they would not change
[/fi]:          Ignore input CRC checks, always consider regenerating projects
[/fc]:          Force build dependency caches
[/dp]:          Decorate project names with platform
[/testmode]:    Override output .vcproj file to be named 'test.vcproj'
[/projsuffix]:  <suffix> - Override output .vcproj file to be named '?????_suffix.vcproj'
[/mirror]:      <path> - Mirror output files to specified path. Used for A:B testing.
[/ninja]:       Use the Ninja build system instead of Makefiles on Linux.
[/2022]:        Generate projects and solutions for Visual Studio 2022
[/2019]:        Generate projects and solutions for Visual Studio 2019
[/2017]:        Generate projects and solutions for Visual Studio 2017
[/2015]:        Generate projects and solutions for Visual Studio 2015
[/2013]:        Generate projects and solutions for Visual Studio 2013
[/2012]:        Generate projects and solutions for Visual Studio 2012
[/2010]:        Generate projects and solutions for Visual Studio 2010
[/2005]:        Generate projects and solutions for Visual Studio 2005

--- Help ---
[/h]:           Help
[/?]:           Help
[/platforms]:   Spew Platforms
[/games]:       Spew Games
[/projects]:    Spew Projects
[/groups]:      Spew Groups
[/properties]:  Spew Properties

--- Reserved Conditionals ---
[/profile]:     Set Reserved $PROFILE=1
[/retail]:      Set Reserved $RETAIL=1
[/callcap]:     Set Reserved $CALLCAP=1
[/fastcap]:     Set Reserved $FASTCAP=1
[/memtest]:     Set Reserved $MEMTEST=1
[/nofpo]:       Set Reserved $NOFPO=1
[/lv]:          Set Reserved $LV=1
[/demo]:        Set Reserved $DEMO=1
[/no_steam]:    Set Reserved $NO_STEAM=1
[/no_scaleform]:    Set Reserved $NO_SCALEFORM=1
[/no_ceg]:      Set Reserved $NO_CEG=1
[/upload_ceg]:  Set Reserved $UPLOAD_CEG=1
[/no_qt]:       Set Reserved $ALLOW_QT=0
[/qtdebug]:     Set Reserved $QTDEBUG=1
[/no_schema]:   Set Reserved $ALLOW_SCHEMA=0
[/unity]:          Set Reserved $ALLOW_UNITY=1
[/forceunity]:  Set Reserved $ALLOW_UNITY=1 and compile writable files in unity files -- needed for buildbot

--- User Custom Conditionals ---
[/define:xxx]:   Enable a custom conditional $XXX as true to use for quick testing in VPC files.
                 (i.e. /define:FOOBAR, sets $FOOBAR=1, otherwise the default is $FOOBAR=0)

--- Solution Generation ---
[/mksln]:        <.sln filename> - make a solution file
[/p4sln]:        <.sln filename> <changelists...> - make a solution file based on
                 the changelist. Changelists can be specific numbers, 0 or "default"
                 for the default changelist, or "all" for all active changelists.
[/slnitems]:     <filename> - adds all files listed in <filename> to generated solutions.
[/slnfolder]:    <folder path with search pattern> - Adds a solution folder
                 containing all the files found in the specified folder path
                 that match the search pattern. Searches all the
                 sub-directories of the specified path as well.
                 (eg. /slnfolder D:\dev\source2\main\src\public\*.h will
                 add all the header files located in the src\public\ folder
                 and its sub-directories to the solution.
                 The path can be absolute or relative to the src dir.
[/showdeps]:     Show an example dependency chain for each project that depends
                 on your p4 change list(s).  Use with /p4sln.
[/shallowdeps]:  Do not treat .lib files as dependencies. Allows building a solution of only files directly affected by source code changes for compile testing.
[/allprojects]:  Do not restrict dependency and solutions to the everything group, allow all known projects.

--- Checking Files ---
[/checkfiles]:         Check for the existence of files in $file commands. For debugging vpc files.
[/nocheckfiles]:       Do not check for the existence of files in $file commands. For debugging vpc files.
[/checkfiles_error]:   Missing files reported as errors.
[/checkfiles_warning]: Missing files reported as warnings.

--- Other ---
[/allgames]:     Enable all conditionals in the game group.
[/noallgames]:   Disable all conditionals in the game group.
[/srcctl]:       Enable source control integration.
[/nosrcctl]:     Disable source control integration.
[/novpcgame]:    Xbox Only. Disable reserved vpc macro $VPCGAME and $VPCGAMECAPS.
                 By default if a single game is specified on command line, then that game
                 name will be used as a value for $VPCGAME and $VPCGAMECAPS macros.
[/clangall]:     Emit .BAT files to parse projects with Clang [WIP]
[/unity_suffix]: Add a '_unity' suffix to $UnityProject-enabled vcxproj files
[/unity_update]  <unityfilelistpath>:   (Used by ValveVSAddin)

However this is not the only way to utilize VPC.

VPC Script Files

VPC can also be written as scripts with the .vpc file extension. These files work in conjunction with the VPC command line to generate the projects. These files is where per-project properties are setup, pre-processor definitions set, what files to include in the given project, and even where the output should be directed to.

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=VPC_Scripts&oldid=485936"