User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
cppdev:gettingstarted [2012-11-09 17:37]
Carsten [Downloading a Compressed Archive]
cppdev:gettingstarted [2017-01-06 11:33] (current)
Carsten [Compiler Setup]
Line 9: Line 9:
 ===== Getting the Source Code ===== ===== Getting the Source Code =====
  
-This section explains how you initially get the Cafu source code+This section explains how you obtain ​the Cafu source code by checking ​it out from its [[https://​bitbucket.org/​cafu/​cafu|Git ​repository]].
-The Cafu source code can be obtained from a compressed archive or by checking out from its Subversion ​repository.+
  
- +Git is a version control system that allows the Cafu developers to work on their copy of the source code independently of each other, and to distribute the latest version of the source code to other developers at any time.
-==== Downloading a Compressed Archive ==== +
- +
-The easiest way to get the Cafu source code is to download a compressed archive for your platform from [[http://​www.cafu.de/​downloads|www.cafu.de/​downloads]]. +
- +
-The contents of the Windows (zip) and Linux (gz, bz2) archives is the same (inclusive end-of-line style), but Linux users should still get the tar.gz or tar.bz2 archive as it properly sets the executable flags that are required for the build scripts. +
- +
-Extract the archive contents into an arbitrary directory and you're ready for the [[#​python_and_scons|next step]]. +
- +
- +
-==== Git Repository Access ==== +
- +
-Alternatively,​ you can also check out the Cafu source code directly from its Git repository. +
-/* (We recently migrated from Subversion to Git, a detailed report is at [[http://​www.cafu.de/​forum/​viewtopic.php?​f=14&​t=1090|Part 1]], [[http://​www.cafu.de/​forum/​viewtopic.php?​f=14&​t=1092|Part 2]].) */ +
- +
-Git is a version control system that allows the Cafu developers to work on their copy of the source code independently of each other, and to distribute the latest version of the source code to users and developers at any time.+
 Moreover, many developers prefer to manage their project independently in their own version control system, but also wish to integrate the latest changes (e.g. bug-fixes and new features) from the official Cafu repository into theirs from time to time: Git makes the synchronization of the projects code with the original Cafu source code as convenient and automatic as possible. Moreover, many developers prefer to manage their project independently in their own version control system, but also wish to integrate the latest changes (e.g. bug-fixes and new features) from the official Cafu repository into theirs from time to time: Git makes the synchronization of the projects code with the original Cafu source code as convenient and automatic as possible.
- 
 If you don't know Git yet, have a look at the [[http://​git-scm.com|Git website]] and the [[http://​git-scm.com/​documentation|Git documentation]]. The "Pro Git" book is very well written and available for free in several languages. If you don't know Git yet, have a look at the [[http://​git-scm.com|Git website]] and the [[http://​git-scm.com/​documentation|Git documentation]]. The "Pro Git" book is very well written and available for free in several languages.
  
-You should prefer getting the source code from the repository over getting it from compressed archive whenever possible: +For Windows and many other systems, you can get Git from the [[http://​git-scm.com/​downloads|Git downloads]] page. Popular Git clients with graphical user interface are available at the Git downloads page as well.
-The code from the repository is always the latest and can easily be updated at any time. +
-There is no better way to get and share new features and bug fixes conveniently and simple.+
  
-Check out the source code at the command-line ​under Windows or Linux with this command:+With most Linux distributions,​ installing Git via the systems package manager is usually preferred. For example, ​under Ubuntu:
 <code bash> <code bash>
-> git clone https://​bitbucket.org/​cafu/​cafu.git Cafu+sudo apt-get install ​git gitk
 </​code>​ </​code>​
  
-This command assumes that you have already installed ​the Git command-line ​client. +Then check out the source code at the command-line ​under Windows or Linux with this command: 
-You can get Git from the [[http://git-scm.com/downloads|Git downloads]] page for Windows, Linux and many other systems+<code bash> 
-Note that with most Linux distributions,​ installing Git via the systems package manager is usually preferred. +> git clone --recursive https://bitbucket.org/cafu/cafu.git Cafu 
-Popular Git clients with a graphical user interface are available at the Git downloads page as well.+</​code>​
  
-Our Git project page is https://​bitbucket.org/​cafu/​cafu,​ where you can browse the repository online, create forks, post pull requests, and find very good related ​help texts.+Note the ''​%%--recursive%%''​ option in the command above: it makes sure that submodules are automatically checked out as well. As we keep the texture images for the DeathMatch example game in a submodule, it is convenient to have them checked out along with the main repository. Be prepared though that this adds approximately 180 MiB to the download volume. 
 + 
 +Our Git project page is https://​bitbucket.org/​cafu/​cafu,​ where you can browse the repository online, create forks, post pull requests, and find additional ​help about Git.
  
  
Line 62: Line 45:
 Under Windows, Under Windows,
   * first get and install Python **2.7** (//not// one of the newer, but backwards-incompatible 3.x editions!) from [[http://​www.python.org/​download/​]],​   * first get and install Python **2.7** (//not// one of the newer, but backwards-incompatible 3.x editions!) from [[http://​www.python.org/​download/​]],​
-  * then get and install SCons **2.0** (or any later version; with VS 2010, you even need version **2.1 (alpha)**) from [[http://​www.scons.org/​download.php]].+  * then get and install SCons **2.3** (or any later version) from [[http://​www.scons.org/​download.php]].
  
-If in doubt, pick the Windows installers for both Python 2.7 and SCons 2.0: they are easy to use, lightweight,​ and automatically setup the proper environment variables.+If in doubt, pick the Windows installers for both Python 2.7 and SCons 2.3: they are easy to use, lightweight,​ and automatically setup the proper environment variables.
  
 Important notes: Important notes:
-  * Pick the **32-bit** edition of Python even on 64-bit systems! (Unfortunately,​ SCons does not yet work with the 64-bit builds of Python.) That is, [[http://​www.python.org/​ftp/​python/​2.7.2/​python-2.7.2.msi|python-2.7.2.msi]] is the right file for all Windows systems. +  * Pick the **32-bit** edition of Python even on 64-bit systems! (Unfortunately,​ SCons does not yet work with the 64-bit builds of Python.) That is, [[http://​www.python.org/​ftp/​python/​2.7.12/​python-2.7.12.msi|python-2.7.12.msi]] is the right file for all Windows systems. 
-  * On Windows ​Vista and Windows 7, run the SCons installer via right-click,​ then select **"Run as administrator"​**.+  * On Windows ​7, 8 and 10, run the SCons installer via right-click,​ then select **"Run as administrator"​**.
  
-That is normally all, but you may wish to check if the Python installer added Pythons ​''​Scripts''​ directory to the ''​PATH''​ environment variable of your system.+That is normally all, but you may wish to check if the Python installer added Python'​s ​''​Scripts''​ directory to the ''​PATH''​ environment variable of your system.
 For example, if Python was installed in ''​C:​\Python27'',​ then ''​PATH''​ should contain both ''​C:​\Python27''​ and ''​C:​\Python27\Scripts''​. For example, if Python was installed in ''​C:​\Python27'',​ then ''​PATH''​ should contain both ''​C:​\Python27''​ and ''​C:​\Python27\Scripts''​.
 Otherwise, you have to add the proper directories manually: See http://​support.microsoft.com/​kb/​310519 and http://​vlaurie.com/​computers2/​Articles/​environment.htm for additional information. Otherwise, you have to add the proper directories manually: See http://​support.microsoft.com/​kb/​310519 and http://​vlaurie.com/​computers2/​Articles/​environment.htm for additional information.
Line 84: Line 67:
 > scons -v > scons -v
 SCons by Steven Knight et al.: SCons by Steven Knight et al.:
-        ​engine: v2.0.0.final.0.r50232010/06/14 22:05:46, by scons on scons-dev +        ​script: v2.3.0, 2013/03/03 09:48:35, by garyo on reepicheep 
-Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation+        engine: v2.3.0, 2013/03/03 09:48:35, by garyo on reepicheep 
 +        engine path: ['​C:​\\Python27\\Scripts\\..\\Lib\\site-packages\\scons-2.3.0\\SCons'​] 
 +Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation
 </​code>​ </​code>​
 The report of the SCons version indicates that both Python and SCons are ready for use. The report of the SCons version indicates that both Python and SCons are ready for use.
-Please make sure that you use SCons version **2.or newer**, older versions don't work!+Please make sure that you use SCons version **2.or newer**, older versions don't work!
  
  
Line 94: Line 79:
  
 Under Linux, just use the systems package manager in order to install SCons. Under Linux, just use the systems package manager in order to install SCons.
-The package manager will automatically install SCons and all software that SCons depends on, such as Python.+The package manager will automatically install SCons and all software that SCons depends on, such as Python. ​For example, under Ubuntu: 
 +<code bash> 
 +> sudo apt-get install scons 
 +</​code>​
  
  
 ===== Linux Packages ===== ===== Linux Packages =====
  
-This section lists additional ​software packages ​that must be installed on a Linux system +Additional ​software packages must be installed on a Linux system before the Cafu source code can be compiled.
-before the Cafu source code can be compiled.+
  
-On a fresh, newly installed ​**Ubuntu ​8.04 (Hardy Heron)** ​system, you'​ll ​additionally ​need the following packages. +On a fresh, newly installed ​Debian or Ubuntu system, you'll need the following packages. 
-This can be done at the command prompt with the ''​apt-get install''​ command, or via the easier ​to use "​Synaptic Package Manager" ​(recommended)+They can be installed ​at the command prompt with the ''​apt-get install''​ command, or via the easy to use "​Synaptic Package Manager"​. 
-Similar packages and package ​management systems ​also exist on RedHat Linux, SuSE, etc., where you can proceed analogously.+Similar packages and package ​managers ​also exist on RedHat Linux, SuSE, etc., where you can proceed analogously.
  
   * A graphics driver with 3D hardware acceleration (the right driver is usually auto-detected and installed by the "​Driver Manager"​).   * A graphics driver with 3D hardware acceleration (the right driver is usually auto-detected and installed by the "​Driver Manager"​).
   * **build-essential** -- The compiler and basic tools required to compile C and C++ programs.   * **build-essential** -- The compiler and basic tools required to compile C and C++ programs.
   * **libgtk2.0-dev** -- Developer files for GTK 2.0, needed for building wxGTK.   * **libgtk2.0-dev** -- Developer files for GTK 2.0, needed for building wxGTK.
-  * **libgl1-mesa-dev** and **libglu1-mesa-dev** -- OpenGL developer files, needed for building wxGTK and the Cafu rendering subsystem. ​On Debian Sarge (3.1), the packages ​**xlibmesa-gl-dev** ​and **xlibmesa-glu-dev** used to serve the same purpose, but on newer systems, they have been replaced by the **libgl(u)1-mesa-dev** packages.+  * **libgl1-mesa-dev** and **libglu1-mesa-dev** -- OpenGL developer files, needed for building wxGTK and the Cafu rendering subsystem. 
 +  ​* **libxxf86vm-dev** -- An interface ​to the XFree86-VidModeExtension extension.
   * **libasound2-dev** -- ALSA developer files, needed for building OpenAL-Soft.   * **libasound2-dev** -- ALSA developer files, needed for building OpenAL-Soft.
  
Line 121: Line 109:
  
 ^ Windows ^ Remarks ^ ^ Windows ^ Remarks ^
-| Visual<​nbsp>​C++<​nbsp>​2010\\ Visual<​nbsp>​C++<​nbsp>​2008 | You can use the free Express Editions with Cafu. They are available at [[http://​www.microsoft.com/​express/​vc/​]] and automatically install the related Microsoft Windows SDK. | +| Visual<​nbsp>​C++<​nbsp>​2015\\ Visual<​nbsp>​C++<​nbsp>​2013\\ Visual<​nbsp>​C++<​nbsp>​2012\\ Visual<​nbsp>​C++<​nbsp>​2010 ​| You can use the free Express Editions with Cafu. They are available at [[http://​www.microsoft.com/​express/​vc/​]] and automatically install the related Microsoft Windows SDK. |
-| Visual C++ 2005 | Also suitable for Cafu in its free Express Edition. However, unlike the newer 2010 or 2008 versions, note that the Microsoft Windows SDK must be installed from a separate download in another step. |+
 | | | | | |
 ^ Linux ^ Remarks ^ ^ Linux ^ Remarks ^
-g++ 4.| The famous ​GNU Compiler Collection with its C++ front-end, ​available on any Linux system. |+GCC 4.4+ | The GNU Compiler Collection with its C++ front-end, ​version 4.4 or any newer version. |
  
-These are just the compilers that we regularly use here at CFS, other compilers should work as well. +The Cafu-specific ​compiler setup is fully automatic:
-As the Cafu source code is very portable, compilers that are sufficiently standards compliant can be employed without further ado. +
- +
-The compiler setup is fully automatic:+
 No action is required in this step, and you can directly proceed to the next. No action is required in this step, and you can directly proceed to the next.
  
Line 138: Line 122:
   - You can edit ''​Cafu/​CompilerSetup.py''​ in order to set the compiler and tools that are used to build Cafu, and to set the target architecture (such as ''​x86''​ or ''​x86_64''​) that it is build for. Each setting is well documented, so you should have no problems to make the desired changes. \\ The default settings automatically determine the latest installed compiler and the current architecture,​ so in most cases the file works out-of-the-box and you have to change nothing at all. Also if you have doubts about the right settings, just continue and use the file as-is.   - You can edit ''​Cafu/​CompilerSetup.py''​ in order to set the compiler and tools that are used to build Cafu, and to set the target architecture (such as ''​x86''​ or ''​x86_64''​) that it is build for. Each setting is well documented, so you should have no problems to make the desired changes. \\ The default settings automatically determine the latest installed compiler and the current architecture,​ so in most cases the file works out-of-the-box and you have to change nothing at all. Also if you have doubts about the right settings, just continue and use the file as-is.
  
-When you do this for the first time, we recommend that you don't bother with ''​Cafu/​CompilerSetup.py''​ at all. Just let the automatisms ​determine the settingsand come back here later if desired or required.+If you do this for the first time, we recommend that you don't bother with ''​Cafu/​CompilerSetup.py''​ at all. Just let the automatism ​determine the settings and come back later if desired or required. 
 + 
 +=== 64-bit Windows with Visual C++ 2010 or 2012 Express Editions ===
  
-=== 64-bit Windows ​with Visual C++ 2010 Express Edition ===+On 64-bit Windows ​systems, SCons tries to find a 64-bit compiler, but Visual C++ 2010 Express Edition ​comes with a 32-bit compiler only. To tell SCons to use the 32-bit compiler instead, please edit file ''​Cafu/​CompilerSetup.py''​ as described [[http://​forum.cafu.de/​viewtopic.php?​p=4360#​p4360|here]].
  
-On 64-bit Windows systems, SCons tries to find a 64-bit compiler, but Visual C++ 2010 Express Edition comes with a 32-bit compiler ​only. To tell SCons to use the 32-bit compiler instead, please edit file ''​Cafu/​CompilerSetup.py''​ as described ​[[http://www.cafu.de/forum/​viewtopic.php?​p=4360#​p4360|here]].+Even though the Visual C++ 2012 Express Edition comes with a 64-bit compiler, at this time the [[http://forum.cafu.de/​viewtopic.php?​p=4360#​p4360|same edits]] must be done for it as well.
  
  
Line 148: Line 134:
  
 You are now ready compile the Cafu source code. You are now ready compile the Cafu source code.
-At the command prompt, change into the top-level ''​Cafu''​ directory (where also the files ''​CompilerSetup.py(.tmpl)''​ and ''​SConstruct''​ are), then type:+At the command prompt, change into the top-level ''​Cafu''​ directory (where also the files ''​CompilerSetup.py(.tmpl)''​ and ''​SConstruct''​ are), then start the compilation with:
 <​code>​ <​code>​
 > scons > scons
 </​code>​ </​code>​
-This will start the compilation. 
 When you do this for the first time, be prepared that it will take a while: When you do this for the first time, be prepared that it will take a while:
 Everything is being built from scratch, once for the debug and once for the release build. Everything is being built from scratch, once for the debug and once for the release build.
-(When you repeat the same command in the future, e.g. after source code changes or updates, only the minimum set of files will be rebuilt and the entire process will complete //much// faster.)+When you repeat the same command in the future, e.g. after source code changes or updates, only the minimum set of files will be rebuilt and the entire process will complete //much// faster.
  
 Under Linux, if you have a multi-core system, you can speed this up by having several build jobs run in parallel: Under Linux, if you have a multi-core system, you can speed this up by having several build jobs run in parallel:
Line 181: Line 166:
 ===== Running the new Programs ===== ===== Running the new Programs =====
  
-When the SCons script has finished, all Cafu programs have been built in several ​//​build ​variants//, namely ''​debug'',​ ''​profile''​ and ''​release''​:+When the SCons script has finished, all Cafu programs have been built in several variants:
   * The ''​debug''​ variant contains additional program information and no code optimizations,​ and is often used during development and for finding and fixing bugs.   * The ''​debug''​ variant contains additional program information and no code optimizations,​ and is often used during development and for finding and fixing bugs.
-  * The ''​release''​ variant has program optimizations enabled in order to maximize the execution speedand it contains no debug information. This variant is usually shipped to end users. +  * The ''​release''​ variant has program optimizations enabled in order to maximize the execution speed and contains no debug information. This variant is usually shipped to end users. 
-  * The ''​profile''​ variant is almost like the ''​release''​ variant, but also contains some debug information in order to make it suitable for use with a performance profiler. This variant is not being built by default, you have to call SCons with the proper parameters or edit the ''​CompilerSetup.py''​ script in order to activate ''​profile''​ builds.+  * The ''​profile''​ variant is not built by default. It is similar to the ''​release''​ variant, but also has debug information in order to make it suitable for use with a performance profiler.
  
 As all variants can be built for each compiler on each platform, the build process organizes the binaries in a directory hierarchy of the form As all variants can be built for each compiler on each platform, the build process organizes the binaries in a directory hierarchy of the form
 <​code>​ build/​$platform/​$compiler/​$variant </​code>​ <​code>​ build/​$platform/​$compiler/​$variant </​code>​
-That is, if your compiler is Visual C++ 2008 (abbreviated as ''​vc9''​) and your platform is Windows (abbreviated as ''​win32''​),​ and you want to run the release variant of the new programs, then the related binaries are relative to the path <​code>​ build/​win32/​vc9/release/ </​code>​+That is, if your compiler is Visual C++ 2015 (abbreviated as ''​vc14''​) and your platform is Windows (abbreviated as ''​win32''​),​ and you want to run the release variant of the new programs, then the related binaries are relative to the path <​code>​ build/​win32/​vc14/release/ </​code>​
  
 Another important consideration is that all programs assume the top-level ''​Cafu''​ directory as their working directory. Another important consideration is that all programs assume the top-level ''​Cafu''​ directory as their working directory.
  
 Combining these facts provides you with several options on how you can run the new programs: Combining these facts provides you with several options on how you can run the new programs:
-  - Copy the programs of the platform, compiler and build variant of your choice from ''​Cafu/​build/​$platform/​$compiler/​$variant/​...''​ directly into the ''​Cafu''​ directory. This is what we do at CFS for the prepackaged binary releases, as end-users can then simply and directly double-click each executable in the Windows Explorer.+  - Copy the programs of the platform, compiler and build variant of your choice from ''​Cafu/​build/​$platform/​$compiler/​$variant/​...''​ directly into the ''​Cafu''​ directory. This is what we do for the prepackaged binary releases, as end-users can then simply and directly double-click each executable in the Windows Explorer.
   - Create a Windows link (''​.lnk''​) or batch (''​.bat''​) file in the proper working directory that calls the desired program in its original location.   - Create a Windows link (''​.lnk''​) or batch (''​.bat''​) file in the proper working directory that calls the desired program in its original location.
-  - For developers, the most flexible and recommended approach is to run the program directly from the command prompt: First change the current working directory to ''​Cafu'',​ then type the relative path to the desired program ([[wp>​Tab_completion|TAB completion]] -- also on Windows -- proves to be a great help here!). \\ For example, running the debug version of CaWE under Windows looks like this (note that the example also shows the current working directory at the left, the actual command follows the ''>''​ character): <​code>​ D:\Cafu> build\win32\vc9\debug\CaWE\CaWE.exe </​code>​ Running the release version of Cafu under Linux looks like this: <​code>​ ~/Cafu> ./​build/​linux2/​g++/​release/​Ca3DE/​Cafu </​code>​+  - For developers, the most flexible and recommended approach is to run the program directly from the command prompt: First change the current working directory to ''​Cafu'',​ then type the relative path to the desired program ([[wp>​Tab_completion|TAB completion]] -- also on Windows -- proves to be a great help here!). \\ For example, running the debug version of CaWE under Windows looks like this (note that the example also shows the current working directory at the left, the actual command follows the ''>''​ character): <​code>​ D:\Cafu> build\win32\vc14\debug\CaWE\CaWE.exe </​code>​ Running the release version of Cafu under Linux looks like this: <​code>​ ~/Cafu> ./​build/​linux2/​g++/​release/​Ca3DE/​Cafu </​code>​
  
 If you have downloaded the binary assets as instructed above, you can now run your self-compiled Cafu engine If you have downloaded the binary assets as instructed above, you can now run your self-compiled Cafu engine
-e.g. at ''​build\win32\vc9\release\Ca3DE\Cafu.exe''​ and enjoy one of the included demo levels! LOL+e.g. at ''​build\win32\vc14\release\Ca3DE\Cafu.exe''​ and try one of the included demo levels! LOL
  
  
Line 217: Line 202:
 Or you just browse the files and folders in the ''​Cafu''​ directory, and start with whatever you feel most attracted to. Or you just browse the files and folders in the ''​Cafu''​ directory, and start with whatever you feel most attracted to.
  
-In any case, if you have questions or comments, or if you need help, write us a message at the [[http://www.cafu.de/forum/|support forums]] at any time!+In any case, if you have questions or comments, or if you need help, post a message at the [[http://forum.cafu.de|support forums]] at any time!
  
cppdev/gettingstarted.1352479038.txt.gz · Last modified: 2013-01-07 12:07 (external edit)