Created compiling_intro (markdown)

compiling_intro.md

@@ -0,0 +1,126 @@
+# Introduction to Godot Build System
+
+### Scons
+
+Godot uses [Scons](http://www.scons.org) to build. We love it, we are not changing it for anything else. We are not even sure other build systems are up to the task of building Godot. We constantly get requests to move the build system to CMake, or Visual Studio, but this is not going to happen. There are many reasons why we have chosen SCons over other alternatives and are listed as follows:
+
+* Godot can be compiled for a dozen different platforms. All PC platforms, all mobile platforms, many consoles, and many web-based platforms (such as HTML5 and Chrome PNACL).
+* Developers often need to compile for several of the platforms **at the same time**, or even different targets of the same platform. They can't afford reconfiguring and rebuilding the project each time. SCons can do this with no sweat, without breaking the builds.
+* SCons will *never* break a build no matter how many changes, configurations, additions, removals etc. You have more chances to die struck by lightning than needing to clean and rebuild in SCons.
+* Godot build process is not simple. Several files are generated by code (binders), others are parsed (shaders), and others need to offer customization (plugins). This requires complex logic which is easier to write in an actual programming language (like Python) rather than using a mostly macro-based language only meant for building.
+* Godot build process makes heavy use of cross compiling tools. Each platform has a specific detection process, and all these must be handled as specific cases with special code written for each.
+
+So, please get at least a little familiar with it if you are planning to build Godot yourself.
+
+### Platform Selection
+
+Godot's build system will begin by detecting the platforms it can build for. If not detected, the platform will simply not appear on the list of available platforms. The build requirements for each platform are described in the rest of this tutorial section.
+
+Scons is invoked by just calling "scons".
+
+```
+
+scons
+
+```
+
+However, this will do nothing except list the available platforms, for example:
+
+```
+user@host:~/godot$ scons
+scons: Reading SConscript files ...
+No valid target platform selected.
+The following were detected:
+	android
+	server
+	javascript
+	windows
+	x11
+
+Please run scons again with argument: platform=<string>
+scons: done reading SConscript files.
+scons: Building targets ...
+scons: `.' is up to date.
+scons: done building targets.
+```
+
+To build a platform (for example, x11), run with the platform= (or just p= to make it short) argument:
+
+```
+user@host:~/godot$ scons platform=x11
+```
+
+
+This will start the build process, which will take a while. If you want scons to build faster, use the -j <cores> parameter to specify how many cores will be used for the build. Or just leave it using one core, so you can use your computer for something else :)
+
+Example for using 4 processes:
+
+```
+user@host:~/godot$ scons platform=x11 -j 4
+```
+
+### Resulting Binary
+
+The resulting binaries will be placed in the bin/ subdirectory, generally with this naming convention:
+```
+godot.<platform>.[opt].[tools/debug].<extension>.<architecture>
+```
+
+For the previous build attempt the result would look like this:
+
+```
+user@host:~/godot$ ls bin
+bin/godot.x11.tools.64
+```
+
+This means that the binary is for x11, is not optimized, has tools (the whole editor) compiled-in, and is meant for 64 bits.
+
+A Windows binary with the same configuration will look like this.
+
+```
+C:\GODOT> DIR BIN/
+godot.windows.tools.64.exe
+```
+
+Just copy that binary to wherever you like, as it self-contains the project manager, editor and all means to execute the game. However, it lacks the data to export it to the different platforms. For that the export templates are needed (which can be either downloaded from http://www.godotengine.org, or you can build them yourself).
+
+Aside from that, there are a few standard options that can be set in all build targets, and will be explained as follows.
+
+### Tools
+
+Tools are enabled by default in al PC targets (Linux, Windows, OSX), disabled for everything else. Disabling tools produces a binary that can run projects but that does not include the editor or the project manager.
+
+```
+scons platform=<platform> tools=yes/no
+```
+
+### Target
+
+Target controls optimization and debug flags. Each mode means:
+
+*  **debug**: Build with C++ debugging symbols, runtime checks (performs checks and reports error) and none to little optimization.
+*  **release_debug**: Build without C++ debugging symbols and optimization, but keep the runtime checks (performs checks and reports errors). Official binaries use this configuration.
+*  **release**: Build without symbols, with optimization and with little to no runtime checks. This target can't be used together with tools=yes, as the tools require some debug functionality and run-time checks to run.
+
+
+```
+scons platform=<platform> target=debug/release_debug/release
+```
+
+This flag appends ".debug" suffix (for debug), or ".tools" (for debug with tools enable). When optimization is enabled (release) it appends the ".opt" suffix.
+
+### Bits
+
+Bits is meant to control the CPU or OS version intended to run the binaries. It works mostly on desktop platforms and ignored everywhere else. 
+
+*  **32**: Build binaries for 32 bits platform.
+*  **64**: Build binaries for  C++ debugging symbols and optimization, but keep the runtime checks (performs checks and reports errors). Official binaries use this configuration.
+*  **default**: Built whatever the build system feels is best. On Linux this depends on the host platform (if not cross compiling), while on Windows and Mac it defaults to produce 32 bits binaries unless specified. 
+
+
+```
+scons platform=<platform> bits=default/32/64
+```
+
+This flag appends ".32" or ".64" suffixes to resulting binaries when relevant.
+