windows_compile_guide/index.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4   <head>
   5     <title>Compiling GtkRadiant on Windows</title>
   6     <style type="text/css">
   7       body
   8       {
   9         color: black;
  10         background-color: white;
  11         font-family: sans-serif;
  12         margin: 1em 1em 1em 1em;
  13       }
  14       a { color: blue; text-decoration: underline; }
  15       a:hover { color: red; text-decoration: underline; }
  16       .error { color: #dd0000; }
  17     </style>
  18   </head>
  19   <body>
  20     <div style="left:0px; top:0px; width:88px; height:31px; position:absolute">
  21       <a href="http://validator.w3.org/check?uri=referer">
  22         <img src="http://www.w3.org/Icons/valid-xhtml10"
  23              style="border-style:none"
  24              alt="Valid XHTML 1.0!" height="31" width="88" />
  25       </a>
  26     </div>
  27     <br />
  28     <center><h1>Compiling GtkRadiant on Windows</h1></center>
  29     <hr />
  30     <p>This guide explains how to compile GtkRadiant 1.6.x from source code on Windows operating systems.
  31       The source code is obtained from
  32       id Software's official GtkRadiant SVN repository, which is open to the public (details follow).
  33       These instructions are aimed at developers wanting to test changes to GtkRadiant source code.
  34       The instructions below have been executed successfully on
  35       Windows XP 32 bit (some late service pack) and on Windows 7 Ultimate 32 bit.  Since 64 bit systems have not been tested by me, I cannot
  36       give any advice on how to complete these instructions on those systems.  (Also, I'm an advanced UNIX user but a complete Windows nub.)</p>
  37     <p>This guide is divided into the following main sections.  I choose to use MSYS instead of Cygwin in this
  38       tutorial because using MinGW/MSYS is the documented and supported way to compile ioquake3.  The need for MinGW/MSYS is
  39       really only to execute a single SCons build target; you could presumably execute those needed steps by
  40       hand if you really don't want to bother with installing MSYS (but you're on your own if you choose that route).
  41     </p>
  42     <ul>
  43       <li><h3><a href="#mingw">Section 1: Installing MinGW</a></h3></li>
  44       <li><h3><a href="#msys">Section 2: Installing MSYS</a></h3></li>
  45       <li><h3><a href="#python">Section 3: Installing Python</a></h3></li>
  46       <li><h3><a href="#scons">Section 4: Installing SCons</a></h3></li>
  47       <li><h3><a href="#svn">Section 5: Installing SVN</a></h3></li>
  48       <li><h3><a href="#vcpp">Section 6: Installing Visual C++</a></h3></li>
  49       <li><h3><a href="#sources">Section 7: Obtaining Source Code, Game Paks, and Libs</a></h3></li>
  50       <li><h3><a href="#compile">Section 8: Compiling GtkRadiant</a></h3></li>
  51       <li><h3><a href="#run">Section 9: Running GtkRadiant</a></h3></li>
  52     </ul>
  53     <hr />
  54     <br />
  55     <a name="mingw"></a>
  56     <h2>Section 1: Installing MinGW</h2>
  57     <p>The following URL can be used as a coarse guide for installing MinGW:
  58       <a href="http://www.mingw.org/wiki/Getting_Started">http://www.mingw.org/wiki/Getting_Started</a>.
  59       The needed steps are reproduced below.
  60     </p>
  61     <h3>Step A: Download</h3>
  62     <p>Download the <tt>mingw-get</tt> program.  We're going to use <tt>mingw-get</tt>
  63       as opposed to the graphical installer <tt>mingw-get-inst</tt> .  You can download the most
  64       recent version of <tt>mingw-get</tt> from
  65       <a href="http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/mingw-get/">this SourceForge page</a>.
  66       (That page also contains a <tt>readme.txt</tt> file that has very useful information on how to use
  67       <tt>mingw-get</tt> , for your reading pleasure.)  Download the binary zip file version;
  68       the downloaded file should have a name along the lines of <tt>mingw-get-0.1-mingw32-alpha-5-bin.zip</tt> .
  69     </p>
  70     <h3>Step B: Extract</h3>
  71     <p>
  72       Extract the zip file you just downloaded to <tt>C:\MinGW</tt> .  I would use that exact location; I will be referring to
  73       that location in the rest of the instructions.  <font color="#ff0000">If you choose a different location, make sure that there is no space in
  74       the path.</font>  After extraction, double check that there exists a file
  75       <tt>C:\MinGW\bin\mingw-get.exe</tt> .  If such a file does not exist, you extracted at an incorrect level or you downloaded
  76       the wrong zip archive.
  77     </p>
  78     <h3>Step C: Set <tt>PATH</tt></h3>
  79     <p>
  80       You need to add <tt>C:\MinGW\bin</tt> to your <tt>PATH</tt> system environment variable.  Don't forget that the semicolon
  81       character is the separator for the elements in <tt>PATH</tt> .  The steps to find where <tt>PATH</tt> can be edited are roughly
  82       as follows on Windows XP:
  83     </p>
  84     <ol>
  85       <li>Go to Control Panel (usually in Start menu).</li>
  86       <li>In Control Panel, go to System.</li>
  87       <li>Hit "Advanced" tab.</li>
  88       <li>Hit "Environment Variables" button.</li>
  89       <li>Near the bottom, under "System variables", highlight "Path" and click "Edit".</li>
  90       <li>Tack on the string "C:\MinGW\bin" to the end, making sure to use a semicolon to separate the existing <tt>PATH</tt> from
  91         your new entry.</li>
  92       <li>Reboot? (I don't know if it's necessary.)</li>
  93     </ol>
  94     <h3>Step D: Update/Upgrade</h3>
  95     <p>
  96       We're going to update the <tt>mingw-get</tt> program with the latest version and pull in the latest distribution manifest.
  97       Open up Command Prompt.  Execute the following commands:
  98     </p>
  99     <blockquote>
 100       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">C:\MinGW> <b>mingw-get update</b>
 101 C:\MinGW> <b>mingw-get upgrade mingw-get</b>
 102 </pre>
 103     </blockquote>
 104     <p>
 105       The above commands can be executed from any directory; <tt>C:\MinGW</tt> happened to be the currect directory in my case.
 106     </p>
 107     <p>
 108       Note: If you execute <tt>mingw-get</tt> without any arguments, you might get an unpleasant-looking error.
 109       This is normal.
 110     </p>
 111     <p>
 112       We're all done installing the base of the MinGW system.  You don't need to install any additional <tt>mingw-*</tt> packages
 113       to get GtkRadiant to compile (because we're using different software to actually compile GtkRadiant).
 114     </p>
 115     <hr />
 116     <br />
 117     <a name="msys"></a>
 118     <h2>Section 2: Installing MSYS</h2>
 119     <p>We're now going to install MSYS, which sits on top of MinGW.</p>
 120     <h3>Step A: Install <tt>msys-base</tt></h3>
 121     <p>
 122       Open up Command Prompt.  Execute the following command:
 123     </p>
 124     <blockquote>
 125       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">C:\MinGW> <b>mingw-get install msys-base</b>
 126 </pre>
 127     </blockquote>
 128     <p>You can now close the Command Prompt.  You won't have to use it again!</p>
 129     <h3>Step B: Fire Up MSYS</h3>
 130     <p>
 131       In your native file exploring application in Windows, navigate to <tt>C:\MinGW\msys\1.0</tt> .  Here you will find
 132       a file <tt>msys.bat</tt> .  This script is what launches MSYS.  You can make a shortcut to this file and place the shortcut
 133       in a convenient location such as your Desktop.  You can also use the provided icon <tt>msys.ico</tt> (in the same
 134       directory) for your shortcut icon.
 135     </p>
 136     <p>
 137       Now start MSYS by double-clicking <tt>msys.bat</tt> (or your shortcut).  We will use MSYS to install some remaining packages that are needed.
 138       In case you are completely new to MSYS, I'd like to point out that it's much like a UNIX shell.
 139       In fact you can access the <tt>C:</tt> Windows drive in MSYS via the <tt>/c</tt> path.
 140     </p>
 141     <h3>Step C: Install MSYS Additions</h3>
 142     <p>
 143       There are many MinGW/MSYS packages you can install; you may even choose to install all of them.
 144       However, for the purposes of compiling GtkRadiant, you will need only the following.  Execute this
 145       from your MSYS shell:
 146     </p>
 147     <blockquote>
 148       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">$ <b>mingw-get install msys-wget</b>
 149 $ <b>mingw-get install msys-unzip</b>
 150 </pre>
 151     </blockquote>
 152     <p>You should now have the two commands <tt>wget</tt> and <tt>unzip</tt> at your disposal in the MSYS shell.
 153       We will be needing these commands to successfully execute the SCons build target later on.</p>
 154     <p>You can leave your MSYS shell open because we will use it again in a little while.</p>
 155     <p>Side Note: The <tt>msys-openssh</tt> package comes with traditional <tt>scp</tt> and <tt>ssh</tt> commands that work
 156       orders of magnitude faster than WinSCP or PuTTY.</p>
 157     <hr />
 158     <br />
 159     <a name="python"></a>
 160     <h2>Section 3: Installing Python</h2>
 161     <p>We will now install the Python programming language, which is needed for SCons to work.</p>
 162     <p>
 163       The homepage for Python is <a href="http://www.python.org/download">www.python.org</a>.  You should download and install
 164       a version of Python suitable for your version of Windows.  I would strongly recommend sticking to a version of Python
 165       that is 2.x.x, <i>not</i> 3.x.x.  This is because lots of legacy software that uses Python is known to work correctly
 166       with 2.x.x, but might not necessarily work with 3.x.x.  At the time of writing this tutorial, the preferred version of Python
 167       was 2.7.1.  For purposes of this tutorial, Python is installed to <tt>C:\Python27</tt> .  All of the default
 168       options for installing Python should be fine.
 169     </p>
 170     <p>
 171       The following step is needed since we're going to be calling SCons in such a way that requires the <tt>python</tt>
 172       command to be in our <tt>PATH</tt> in MSYS.  In your MSYS shell, execute this:
 173     </p>
 174     <blockquote>
 175       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">$ <b>mkdir -p /usr/local/bin</b>
 176 $ <b>ln -s /c/Python27/python.exe /usr/local/bin/python</b>
 177 </pre>
 178     </blockquote>
 179     <p>You should now have the <tt>python</tt> command at your disposal in your MSYS shell.</p>
 180     <hr />
 181     <br />
 182     <a name="scons"></a>
 183     <h2>Section 4: Installing SCons</h2>
 184     <p>We will now install SCons, which is a multi-platform substitute for traditional Make.</p>
 185     <p>
 186       The homepage for SCons is <a href="http://www.scons.org/download.php">www.scons.org</a>.  You should download and install the
 187       latest production release.  During the install procedure you will be asked to confirm the location of your Python
 188       installation.
 189     </p>
 190     <p>
 191       SCons gets installed into <tt>C:\Python27\Scripts</tt> because it's basically a Python script.
 192       You would normally invoke SCons by using the <tt>scons.bat</tt> script
 193       in this directory.  However, since we will be invoking SCons from MSYS (which is UNIX-like), we're actually going to call the UNIX script version
 194       of SCons, which is the plain-old file <tt>scons</tt> in this same directory.  Furthermore, we're going to make sure that the <tt>scons</tt>
 195       command is available under MSYS.  Execute these commands in your MSYS shell:
 196     </p>
 197     <blockquote>
 198       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">$ <b>mkdir -p /usr/local/bin</b>
 199 $ <b>ln -s /c/Python27/Scripts/scons /usr/local/bin/scons</b>
 200 </pre>
 201     </blockquote>
 202     <p>
 203       You now have the <tt>scons</tt> command at your disposal in the MSYS shell.
 204     </p>
 205     <hr />
 206     <br />
 207     <a name="svn"></a>
 208     <h2>Section 5: Installing SVN</h2>
 209     <p>
 210       We're now going to install a command-line version of the SVN client that we can use from MSYS.  We don't need no
 211       stinkin' GUI.  Anyhow, command-line SVN is required to perform the SCons build target later on.
 212       In fact, you don't need to touch TortoiseSVN or any other GUI-based SVN client for any part of this entire tutorial.
 213       (I wouldn't touch a GUI-based SVN client with a 10 foot pole given the opportunity to use command-line SVN instead.)
 214     </p>
 215     <p>
 216       The preferred download site for SVN client for Windows is <a href="http://www.collab.net/downloads/subversion/">CollabNet</a>.
 217       You should download and install CollabNet Subversion Command-Line Client,
 218       <i>not</i> CollabNet Subversion Edge or something of any other nature.  Unfortunately you'll have to create an account with CollabNet
 219       to download this software, but everything is free.  You can use all defaults when installing SVN.
 220     </p>
 221     <p>
 222       The CollabNet version of SVN client for Windows should automatically modify your <tt>PATH</tt> , and you should be able to
 223       execute the <tt>svn</tt> command in MSYS after closing MSYS and starting it again.  If this is not the case for some strange
 224       reason, you'll have to tweak your environment to ensure that you can execute the <tt>svn</tt> command from MSYS.
 225     </p>
 226     <hr />
 227     <br />
 228     <a name="vcpp"></a>
 229     <h2>Section 6: Installing Visual C++</h2>
 230     <p>
 231       The GtkRadiant developers are currently using Microsoft Visual C++ 2008 to compile GtkRadiant.  Even though Visual C++ 2010 is a newer
 232       version, don't use it [unless you want to be on your own].  You can download Visual C++ 2008 Express Edition from
 233       <a href="http://www.microsoft.com/express/Downloads/#Visual_Studio_2008_Express_Downloads">this Microsoft webpage</a>.
 234     </p>
 235     <p>
 236       When you install Visual C++ 2008 Express Edition, you can install the bare minimum application <i>without</i> any extras such as
 237       Microsoft Silverlight Runtime or Microsoft SQL Server 2008 Express Edition.  For the rest of the install options, the
 238       defaults can be chosen.
 239     </p>
 240     <hr />
 241     <br />
 242     <a name="sources"></a>
 243     <h2>Section 7: Obtaining Source Code, Game Paks, and Libs</h2>
 244     <p>We are now ready to get the source code for GtkRadiant.</p>
 245     <h3>Step A: Get Base Project</h3>
 246     <p>
 247       Open an MSYS shell.  When you start the shell, you will be in what is called your "home directory".  You can execute the
 248       <tt>pwd</tt> command in MSYS to find out which directory you are currently in.  For example, when I start MSYS, my
 249       current directory is <tt>/home/rambetter</tt> .  In reality, this path is relative to the MSYS install root.
 250       For example, in the Windows operating system, my home directory is actually <tt>C:\MinGw\msys\1.0\home\rambetter</tt> .
 251     </p>
 252     <p>
 253       In any case, we need to create ourselves a work area for purposes of downloading files and compiling software.  I would recommend
 254       creating a directory <tt>radiant-work</tt> in your home directory.  So:
 255     </p>
 256     <blockquote>
 257       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">$ <b>mkdir radiant-work</b>
 258 </pre>
 259     </blockquote>
 260     <p>Now, we're going to change to that directory and get the base GtkRadiant project:</p>
 261     <blockquote>
 262       <pre width="88" style="background: #CCCCCC; padding: 2mm; border-style: ridge">$ <b>cd radiant-work</b>
 263 $ <b>svn checkout https://zerowing.idsoftware.com/svn/radiant/GtkRadiant/trunk ./GtkRadiant</b>
 264 </pre>
 265     </blockquote>
 266     <p>We created the extra <tt>radiant-work</tt> parent directory of <tt>GtkRadiant</tt> because the following step will
 267       place many files into the project's parent directory, and we don't want to litter our home directory with these files.</p>
 268     <h3>Step B: Execute SCons Build Target</h3>
 269     <p>
 270       Remember all the work we did earlier in order to install SCons?  Well, thanks to all that work we did,
 271       obtaining the remaining things we need for compiling is really really easy:
 272     </p>
 273     <blockquote>
 274       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">$ <b>cd GtkRadiant</b>
 275 $ <b>scons target=setup</b>
 276 </pre>
 277     </blockquote>
 278     <p>This SCons build target performs several actions:</p>
 279     <ul>
 280       <li>Downloads "install paks" for several games such as Quake III Arena and Urban Terror.</li>
 281       <li>Downloads library dependencies (such as GTK+) for building and running GtkRadiant.</li>
 282       <li>Places library dependencies in proper locations.</li>
 283       <li>Performs any other actions needed prior to compiling GtkRadiant.</li>
 284     </ul>
 285     <hr />
 286     <br />
 287     <a name="compile"></a>
 288     <h2>Section 8: Compiling GtkRadiant</h2>
 289     <p>We are now finally going to compile GtkRadiant using Microsoft Visual C++.</p>
 290     <p>
 291       Start Microsoft Visual C++.  From the "File" menu, choose "Open" -> "Project/Solution...".
 292       Navigate to your <tt>GtkRadiant</tt> directory (in my case <tt>C:\MinGW\msys\1.0\home\rambetter\radiant-work\GtkRadiant</tt>).
 293       Choose the project file <tt>radiant.sln</tt> from this directory.
 294     </p>
 295     <p>
 296       You now have the GtkRadiant project loaded in Visual C++.  You can poke around if you like, e.g. open up some source code
 297       files and edit them.
 298     </p>
 299     <p>
 300       Before you build the project, you might want to select the "Release" target (as pictured below).
 301     </p>
 302     <table border="0" cellpadding="0" cellspacing="0">
 303       <tr>
 304         <td width="20">&nbsp;</td>
 305         <td><img src="vc-radiant-release.png" alt="vc-radiant-release.png"></img></td>
 306       </tr>
 307     </table>
 308     <p>
 309       To build GtkRadiant, choose "Build Solution" from the "Build" menu.  The build will take
 310       about 10 minutes [on a Pentium 4 with HTT], so this would be a good time to go get a cup of tea.
 311     </p>
 312     <p>If the build completes successfully, you will get a message similar to the following in the output
 313       of Visual C++:</p>
 314     <blockquote>
 315       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">radiant - 0 error(s), 0 warning(s)
 316 ========== Build: 37 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
 317 </pre>
 318     </blockquote>
 319     <hr />
 320     <br />
 321     <a name="run"></a>
 322     <h2>Section 9: Running GtkRadiant</h2>
 323     <p>All of the files needed to run GtkRadiant are going to be in the folder <tt>radiant-work\GtkRadiant\install</tt> [relative
 324       to your home directory in MSYS].  You can copy the entire <tt>install</tt> folder to some place such as your Desktop
 325       and you can rename this folder to <tt>ZeroRadiant</tt> for example.
 326       Then, you will use <tt>radiant.exe</tt> in that directory to launch the application.
 327     </p>
 328     <p>
 329       There is one little bit of optional cleanup you can perform on your installation folder.  You can remove all SVN-related
 330       files since they are no longer needed and only take up disk space.  Let's say that you renamed your installation folder
 331       to <tt>ZeroRadiant</tt> (as the previous paragraph suggests), and let's say that you're in the MSYS shell, and that your current
 332       working directory is the parent directory of <tt>ZeroRadiant</tt>.  Then, in your MSYS shell, you can execute this command to
 333       delete all SVN-related files (all <tt>.svn</tt> directories):
 334     </p>
 335     <blockquote>
 336       <pre width="80" style="background: #CCCCCC; padding: 2mm; border-style: ridge">$ <b>find ZeroRadiant/ -type d -name '\.svn' -print0 | xargs -0 rm -rf</b>
 337 </pre>
 338     </blockquote>
 339     <p>
 340       That's it!  Good luck and thanks for reading my tutorial!  If you have comments or suggestions please email me at nlandys@gmail.com .
 341       More information about GtkRadiant is on <a href="http://www.qeradiant.com/cgi-bin/trac.cgi">www.qeradiant.com</a>.
 342     </p>
 343     <br />
 344     <br />
 345   </body>
 346 </html>