Difference between revisions of "Installing and Debugging the Source Code"

From Valve Developer Community
Jump to: navigation, search
m (Links)
 
(50 intermediate revisions by 28 users not shown)
Line 1: Line 1:
[[Category:Programming]][[Category:Modding]]
+
{{otherlang2|
 +
| jp = Installing and Debugging the Source Code:jp
 +
| es = Installing and Debugging the Source Code:es
 +
| fr = Installing and Debugging the Source Code:fr
 +
| it = Installing and Debugging the Source Code:it
 +
| ru = Installing and Debugging the Source Code:ru
 +
| pl = Installing and Debugging the Source Code:pl
 +
| zh-cn = Installing and Debugging the Source Code:zh-cn}}
  
=Overview=
+
== Installing ==
  
The general steps to installing and debugging the source code are:
+
# Run the [[Source SDK]] and choose ''Create a Mod''. See [[Create a Mod]] for details about the process.
 +
# [[Compiler Choices|Choose a compiler]]
 +
# Go! Get started with [[Your First Entity]].
  
# Run the '''[[Create a Mod]]''' tool in the SDK to install the source code.
+
To compile your code on Linux, see [[Compiling under Linux]]. To get the latest code, see [https://github.com/ValveSoftware GitHub].
# Use Microsoft Visual Studio .NET 2003 to compile the source code.
 
# Setup debugging parameters.
 
# Run in the debugger.
 
  
=Step By Step=
+
== Debugging ==
  
===Run the Create a Mod wizard===
+
'''Debugging''' is the process of a human examining closely the inner workings of a program. It can reveal the causes of crashes and other bugs.
  
* Run the Source SDK from Steam and choose the '''[[Create a Mod]]''' link.
+
=== Windows ===
* You can normally choose any type of mod here, but for the purposes of this tutorial, choose the '''Modify Half-Life 2 Single Player''' option and click '''Next'''.
 
* In the top edit control of the next dialog, enter a directory where you would like to create a mod. This tutorial will assume you entered '''C:\MyMod'''.
 
* In the bottom edit control, enter any name for your mod. This will become a subdirectory under your '''''SteamInstallPath'''\SteamApps\SourceMods'' folder. This example will assume you entered '''MyMod''' here.
 
* Click the '''Next''' button and the source code will be installed on your hard drive.
 
* Wait for the mod wizard to finish.
 
  
===Compile the Source Code===
+
# Make sure you are working in the Debug configuration, not Release.
 +
# In the Solution Explorer (Microsoft Visual C++), right-click on the active project (the one in bold) and choose ''Properties''. It doesn't matter whether you're working with the server or client.
 +
# In the window that appears, choose ''Debugging'' from the left-hand list.
 +
# Change ''Command'' to the path to the .exe file you want to launch (the same on that runs when you play the game/mod in question, e.g. <code>C:\Steam\SteamApps\common\source sdk base 2007\hl2.exe</code>).
 +
# Change ''Command Arguments'' to read something like <code>-allowdebug -dev -sw -game "C:\Steam\SteamApps\SourceMods\MyMod"</code>
 +
# Change ''Working Directory'' to the folder containing the .exe you chose for Command e.g. <code>C:\Steam\SteamApps\common\source sdk base 2007</code>.
 +
# Before debug you need to unpack all game resources to your mod folder or sdk base (at least for 2006). Otherwise you will get white screen, then pink console and other glitches! It's very important. You need to unpack shaders (white screen bug) from <code>Source SDK Base\vpks</code>, then <code>resources\</code> to <code>Source SDK Base\hl2\</code> (will fix menu strings) and finally <code>Source SDK Base\platform</code> (pink console), don't forget <code>expressions\</code>, otherwise npc won't move their lips and other stuff like models, materials, etc... don't try to use different source engine models except from your engine base, otherwise you will get glitches.
  
* Open Microsoft Visual Studio .NET 2003.
+
You can now press F5 at any time to start debugging. (If you really do want to debug in Release mode, repeat the above for that configuration. But don't expect the results to be very useful).
* Choose ''Open Project'' from the ''File'' menu.
 
* Navigate to the directory where you installed the source code. In our example, it would be '''C:\MyMod\Src'''.
 
* Open the '''game_sdk.sln''' file.
 
* Choose ''Rebuild Solution'' from the ''Build'' menu.
 
* Wait for the source code to build. You should now have two DLLs in your ''C:\Steam\SteamApps\SourceMods\MyMod\bin'' folder (depending on where your Steam is installed and what name you entered for your mod in the ''Create a Mod'' dialog). One is called '''client.dll''' and the other is called '''server.dll'''.
 
  
=== Setup debugging parameters ===
+
The paths will be unique to the version of the SDK being used. For example, with Source SDK 2013, the settings for a single player mod might be:
  
* In the '''Solution Explorer''' window, right-click on the current project (the one in bold) and choose '''Properties'''.
+
    Command:          C:\Program Files (x86)\Steam\steamapps\common\Source SDK Base 2013 Singleplayer\hl2.exe
* In the Property Pages dialog that appears, choose the Debugging item on the left-hand side.
+
    Command Arguments: -allowdebug -dev -sw -condebug -console -toconsole -game "C:\My_Mod\source-sdk-2013\sp\game\mod_hl2" +map my_map
* On the right-hand side, in the text control next to '''Command''', enter <code>C:\Steam\SteamApps\'''Username'''\Half-Life 2\hl2.exe</code> (adjusting the folder names given here to reflect your own Steam installation).
+
    Working Directory: C:\Program Files (x86)\Steam\steamapps\common\Source SDK Base 2013 Singleplayer\
* Next to '''Command Arguments''', enter <code>-dev -sw -game "C:\Steam\SteamApps\SourceMods\MyMod"</code> (where '''MyMod''' is the name of your mod you entered in the ''Create a Mod'' dialog).
 
* Next to '''Working Directory''', enter <code>C:\Steam\SteamApps\'''Username'''\Half-Life 2</code> (adjusting the folder names given here to reflect your own Steam installation).
 
* Click the '''OK''' button.
 
  
=== Run in the debugger ===
+
{{note|You will be told that symbols could not be found for <whatever>.exe - this is normal, as you don't have that source code. Ignore the warning.}}
  
* ''Important: after an SDK update, you must make sure to run whatever game you're editing'' '''through Steam''' ''once (only one time is necessary) before running in the debugger. If you don't, you may get Steam errors when running through the debugger.''
+
==== Run-time attachment ====
* Right-click on the same project you were editing the properties for, and choose Debug->Start New Instance.
 
* If you get a warning that <code>hl2.exe</code> has no debugging information, ignore it.
 
* It should now launch Half-Life 2 and run your code. You can make modifications to the code now, rebuild, and rerun the game with your changes!
 
  
=Editing other games=
+
If you want to debug a process that is already running, choose ''Debug > Attach to Process...'' and select it from the list.
  
For a ''Half-Life 2 Multiplayer'' mod, the only difference is that you must use <code>C:\Steam\SteamApps\'''Username'''\Half-Life 2 deathmatch\hl2.exe</code> as the value for the '''Command''' field, and use <code>C:\Steam\SteamApps\'''Username'''\Half-Life 2 deathmatch</code> as the value for the '''Working Directory''' field.
+
=== Linux ===
  
If you chose ''Start a mod from scratch'' from the ''Create a Mod'' dialog, then everything works the same.
+
# Disable OPTFLAGS in the root makefile
 +
# Uncomment DEBUG in your project's makefile. {{confirm|Change it to read <code>-O0 -g -ggdb3</code>.}}
 +
# Make and Install
 +
# Open a terminal window and cd to the location of the executable you are running
 +
<!-- not needed, and bad? # Perform <code>export LD_LIBRARY_PATH=".:bin:$LD_LIBRARY_PATH"</code> -->
 +
# Perform <code>gdb srcds_linux</code> (or whatever the name is)
 +
# Perform <code>run <parameters></code> to start the program
  
=Links=
+
* On a crash ("segfault"), do <code>bt</code> ("backtrace") to see the callstack.
 +
* To break into the debugger, press {{key|Ctrl+C}}; to continue afterwards perform <code>cont</code>.
 +
* To set a breakpoint, do <code>break <function></code>. See <code>help breakpoint</code> for more details.
 +
* To print an expression, do <code>print <expr></code>.
  
A good next step after mastering this document is to look at the [[My First Entity]] document, in which you will make changes to some of the source code.
 
  
If you plan to integrate code updates from Valve, and if you want code backups and revision history, take a look at the [[Using Source Control with the Source SDK]] document.
+
[[Category:Programming]]
{{otherlang:en}} {{otherlang:en:jp|Installing and Debugging the Source Code:jp}}
+
[[Category:Modding]]

Latest revision as of 13:54, 1 December 2019

Español Français Italiano Polski Русский 日本語 简体中文

Installing

  1. Run the Source SDK and choose Create a Mod. See Create a Mod for details about the process.
  2. Choose a compiler
  3. Go! Get started with Your First Entity.

To compile your code on Linux, see Compiling under Linux. To get the latest code, see GitHub.

Debugging

Debugging is the process of a human examining closely the inner workings of a program. It can reveal the causes of crashes and other bugs.

Windows

  1. Make sure you are working in the Debug configuration, not Release.
  2. In the Solution Explorer (Microsoft Visual C++), right-click on the active project (the one in bold) and choose Properties. It doesn't matter whether you're working with the server or client.
  3. In the window that appears, choose Debugging from the left-hand list.
  4. Change Command to the path to the .exe file you want to launch (the same on that runs when you play the game/mod in question, e.g. C:\Steam\SteamApps\common\source sdk base 2007\hl2.exe).
  5. Change Command Arguments to read something like -allowdebug -dev -sw -game "C:\Steam\SteamApps\SourceMods\MyMod"
  6. Change Working Directory to the folder containing the .exe you chose for Command e.g. C:\Steam\SteamApps\common\source sdk base 2007.
  7. Before debug you need to unpack all game resources to your mod folder or sdk base (at least for 2006). Otherwise you will get white screen, then pink console and other glitches! It's very important. You need to unpack shaders (white screen bug) from Source SDK Base\vpks, then resources\ to Source SDK Base\hl2\ (will fix menu strings) and finally Source SDK Base\platform (pink console), don't forget expressions\, otherwise npc won't move their lips and other stuff like models, materials, etc... don't try to use different source engine models except from your engine base, otherwise you will get glitches.

You can now press F5 at any time to start debugging. (If you really do want to debug in Release mode, repeat the above for that configuration. But don't expect the results to be very useful).

The paths will be unique to the version of the SDK being used. For example, with Source SDK 2013, the settings for a single player mod might be:

   Command:           C:\Program Files (x86)\Steam\steamapps\common\Source SDK Base 2013 Singleplayer\hl2.exe
   Command Arguments: -allowdebug -dev -sw -condebug -console -toconsole -game "C:\My_Mod\source-sdk-2013\sp\game\mod_hl2" +map my_map
   Working Directory: C:\Program Files (x86)\Steam\steamapps\common\Source SDK Base 2013 Singleplayer\
Note:You will be told that symbols could not be found for <whatever>.exe - this is normal, as you don't have that source code. Ignore the warning.

Run-time attachment

If you want to debug a process that is already running, choose Debug > Attach to Process... and select it from the list.

Linux

  1. Disable OPTFLAGS in the root makefile
  2. Uncomment DEBUG in your project's makefile.
    Confirm:Change it to read -O0 -g -ggdb3.
  3. Make and Install
  4. Open a terminal window and cd to the location of the executable you are running
  5. Perform gdb srcds_linux (or whatever the name is)
  6. Perform run <parameters> to start the program
  • On a crash ("segfault"), do bt ("backtrace") to see the callstack.
  • To break into the debugger, press Ctrl+C; to continue afterwards perform cont.
  • To set a breakpoint, do break <function>. See help breakpoint for more details.
  • To print an expression, do print <expr>.