Minor documentation update.

Docs/GettingStarted.dox

@@ -10,13 +10,13 @@ Although all required third-party libraries are included as source code, there a
 
 - For Windows, the June 2010 DirectX SDK needs to be installed.
 
-- For Linux, the following development packages need to be installed: libx11-dev, libxrandr-dev, libasound2-dev on Debian-based distros; libX11-devel, libXrandr-devel, alsa-lib-devel on RedHat-based distros. Also install the package libgl1-mesa-dev (Debian) or mesa-libGL-devel (RH) if your GPU driver does not include OpenGL headers & libs.  Building as 32-bit on a 64-bit system requires installing also the 32-bit versions of the development libraries.
+- For Linux, the following development packages need to be installed: libx11-dev, libxrandr-dev, libasound2-dev on Debian-based distros; libX11-devel, libXrandr-devel, alsa-lib-devel on RedHat-based distros. Also install the package libgl1-mesa-dev (Debian) or mesa-libGL-devel (RH) if your GPU driver does not include OpenGL headers & libs, but in most of the case it usually does and has better performance than Mesa's OpenGL implementation. Building as 32-bit on a 64-bit system requires installing also the 32-bit versions of the development libraries.
 
 - For Raspberry Pi, the following development packages need to be installed. On Raspbian: libasound2-dev, libudev-dev. On Pidora: alsa-lib-devel, systemd-devel.
 
 - For Mac OS X, the Xcode developer tools package should include everything necessary.
 
-- For Android, the Android SDK and Android NDK (minimum API level 12) need to be installed. Optionally, also install Eclipse ADT plugin for building and deployment via Eclipse.
+- For Android, the Android SDK and Android NDK (minimum API level 12) need to be installed.
 
 To run Urho3D, the minimum system requirements are:
 
@@ -32,15 +32,37 @@ To run Urho3D, the minimum system requirements are:
 
 SSE requirement can be eliminated by disabling the use of SSE instruction set, see URHO3D_SSE build option below.
 
+\section Build_Scripts Build scripts
+
+As this is a cross-platform project, we have provided a number of build scripts for the most common use cases. The shell scripts end with extension *.sh are meant for building Urho3D project in a Unix-like host system (Linux, Mac, and even Raspberry Pi), while the batch files end with *.bat are meant for Windows host system only. They only provide a convenient way to invoke CMake to process our CMakeLists.txt files. Their usage is not a must as you can also invoke CMake to do the same via cmake-gui or via your IDE when your IDE supports that.
+
+The basic usage as follows:
+
+\verbatim
+Usage: <script-name> /path/to/build-tree [build-option] [build-option] ...
+\endverbatim
+
+Where the <script-name> is one of the provided build script. The /path/to/build-tree is where CMake will be generating the build tree for the project. Both out-of-source build tree and non out-of-source build tree path are now supported. The build options are described in detail in the \ref Build_Options "next section" below.
+
+After the build tree has been generated, you can use the build script again to reconfigure it by passing different build options. You can do as the basic usage above; or by first change the working directory to the already generated build tree and use the following syntax:
+
+\verbatim
+Usage: <script-name> [build-option] [build-option] ...
+\endverbatim
+
+Naturally you have to specify a fully qualified path to the build script for this to work. Alternatively, you can add the path to the Urho3D project root to the PATH environment variable in order to make the build scripts available everywhere.
+
+Our CMakeLists.txt files are designed to work with most of the generators supported by CMake: Makefile, Xcode, VS, and even Ninja. Though we do not use the latter in any of our build scripts explicitly. Which build script to use is determined by which CMake generator (and toolchain) you intend to use in your build tree. For native build, you can just use cmake_generic.sh or cmake_generic.bat to let CMake to detect and decide which generator to use automatically. CMake should default to use "Unix Makefiles" generator on Linux and Mac host systems and it should default to use 32-bit "Visual Studio" generator on Windows host system when it is installed.
+
 \section Build_Options Build options
 
-A number of build options can be defined explicitly when invoking the above cmake_xxxx batch files or shell scripts or when configurating the project interactively using cmake-gui. To use one of these build options on the command line interface, pass it in this format "-DOPTION=VALUE" without the quotes.\n
+A number of build options can be defined when invoking the build scripts or when configurating the project interactively using cmake-gui. To use one of these build options on the command line interface, pass it in this format "-DOPTION=VALUE" without the quotes.\n
 |Build Option         |V|Description          |
 |---------------------|-|---------------------|
 |ANDROID              |0|Configure project using Android cross-compiler toolchain (cmake_generic.bat and cmake_generic.sh only)|
 |RPI                  |0|Configure project using Raspberry Pi cross-compiler toolchain (cmake_generic.sh only)|
-|WIN32                |0|Configure project using MinGW cross-compiler toolchain (cmake_generic.sh only)|
-|IOS                  |0|Configure project for targeting iOS platform (cmake_generic.sh and cmake-gui only); use cmake_ios.sh as shortcut|
+|WIN32                |0|Configure project using MinGW cross-compiler toolchain (cmake_generic.sh only); also applicable when cross-compiling 64-bit Windows platform|
+|IOS                  |0|Configure project for targeting iOS platform (cmake_generic.sh and cmake-gui only)|
 |URHO3D_64BIT         |*|Enable 64bit build, on MSVC default to 0, on other compilers the default is set based on the 64-bit capability of the chosen toolchain on host system|
 |URHO3D_ANGELSCRIPT   |1|Enable AngelScript scripting support|
 |URHO3D_LUA           |0|Enable Lua scripting support|
@@ -67,8 +89,8 @@ A number of build options can be defined explicitly when invoking the above cmak
 |URHO3D_STATIC_RUNTIME|0|Use static C/C++ runtime libraries and eliminate the need for runtime DLLs installation (VS only)|
 |URHO3D_LIB_TYPE      |*|Specify Urho3D library type, possible values are STATIC (\*default) and SHARED|
 |URHO3D_SCP_TO_TARGET |-|Use scp to transfer executables to target system (non-Android cross-compiling build only), SSH digital key must be setup first for this to work, typical value has a pattern of usr@tgt:remote-loc|
-|URHO3D_USE_LIB64_RPM |0|Enable 64-bit RPM CPack generator using /usr/lib64 and disable all other generators (Debian-based host only)|
-|URHO3D_USE_LIB_DEB   |0|Enable 64-bit DEB CPack generator using /usr/lib and disable all other generators (Redhat-based host only)|
+|URHO3D_USE_LIB64_RPM |0|Enable 64-bit RPM CPack generator using /usr/lib64 and disable all other generators (Debian-based host only, which uses /usr/lib by default)|
+|URHO3D_USE_LIB_DEB   |0|Enable 64-bit DEB CPack generator using /usr/lib and disable all other generators (Redhat-based host only, which uses /usr/lib64 by default)|
 |URHO3D_HOME          |-|Path to Urho3D build tree or SDK installation location (external project only)|
 |CMAKE_BUILD_TYPE     |*|Specify CMake build configuration (single-configuration generator only), possible values are Release (\*default), RelWithDebInfo, and Debug|
 |CMAKE_INSTALL_PREFIX |*|Install path prefix, prepended onto install directories; default to 'c:/Program Files/Urho3D' on Windows host and '/usr/local' on all other non-Windows hosts|
@@ -82,7 +104,7 @@ A number of build options can be defined explicitly when invoking the above cmak
 |RPI_PREFIX           |-|Prefix path to Raspberry Pi cross-compiler tools (RPI cross-compiling build only)|
 |RPI_SYSROOT          |-|Path to Raspberry Pi system root (RPI cross-compiling build only)|
 
-Note that the specified build option values are cached by CMake. The cached values will be used by CMake in the subsequent invocation. That is, the same build options are not required to be specified again and again. But once a non-default build option value is being cached, it can only be reverted back to its default value by explicitly resetting it. That is, simply by not passing the corresponding build option would not work. One way to revert all the build options to their default values is by clearing the CMake cache by calling cmake_clean.bat or cmake_clean.sh.
+Note that the specified build option values are cached by CMake after the initial configuration step. The cached values will be used by CMake in the subsequent configuration. The same build options are not required to be specified again and again. But once a non-default build option value is being cached, it can only be reverted back to its default value by explicitly resetting it. That is, simply by not passing the corresponding build option would not revert it back to its default. One way to revert all the build options to their default values is by clearing the CMake cache by calling cmake_clean.bat or cmake_clean.sh.
 
 \section Building_Native Native build process
 
@@ -177,7 +199,7 @@ As of V1.31, the build process first builds the Urho3D library target (either st
 
 To install the Urho3D library as an SDK, use the usual 'make install' command. There is an equivalent built-in target called "install" in Visual Studio solution and Xcode project to perform the SDK installation. This could be useful when you want your application to always link against a 'stable' installed version of the Urho3D library, while keeping your Urho3D project root tree in sync with origin/master; or when you want other users in the same host system to use the installed Urho3D SDK instead of them building from source again.
 
-The default install prefix is 'c:/Program Files/Urho3D' on Windows host and '/usr/local' on all other non-Windows hosts. You can use the CMAKE_INSTALL_PREFIX build option to alter this prefix path. However, when cross-compiling you may actually want to alter the final installation destination by supplying DESDIR environment variable instead of altering the CMAKE_INSTALL_PREFIX variable directly, especially when using Urho3D library as shared library type because the installed executables have their RPATH adjusted relative to CMAKE_INSTALL_PREFIX. The DESTDIR environment variable is not applicable for installation on Window host, i.e. it can only use CMAKE_INSTALL_PREFIX variable to alter the final installation destination. There is no RPATH adjustment for Windows platform but as the result the Urho3D.dll will be installed in a same directory as the installed executables.
+The default install prefix is 'c:/Program Files/Urho3D' on Windows host and '/usr/local' on all other non-Windows hosts. You can use the CMAKE_INSTALL_PREFIX build option to alter this prefix path. However, when cross-compiling you may actually want to alter the final installation destination by supplying DESDIR environment variable instead of altering the CMAKE_INSTALL_PREFIX variable directly, especially when using Urho3D library as shared library type because the installed executables have their RPATH adjusted relative to CMAKE_INSTALL_PREFIX. The DESTDIR environment variable is not applicable for installation on Windows host, i.e. it can only use CMAKE_INSTALL_PREFIX variable to alter the final installation destination. This is not a lost, however, because there is no RPATH adjustment for Windows platform, but as the result the Urho3D.dll will be installed in a same directory as the installed executables.
 
 If the Urho3D SDK is installed to a system-wide default location then the Urho3D library can be found by FindUrho3D CMake module automatically without the help of URHO3D_HOME environment variable or build option. When cross-compiling, the system-wide default location is usually in the system root of the cross-compiling target. To get a corresponding system root path for a cross-compiling build tree, you can use SYSROOT internal variable stored in the CMake cache. You can then use the system root path to set the DESTDIR environment variable in order to stage the Urho3D SDK installation in the corresponding system root. For example:
 
@@ -339,29 +361,29 @@ F2          Toggle debug HUD
 
 \page UsingLibrary Using Urho3D as external library
 
-This page shows how to create a new C++ project linking against Urho3D library as external library. There are two approaches to do this. The first approach uses Urho3D library directly from the Urho3D project build tree. The second approach uses Urho3D SDK installation. It is imperative to clean the CMake cache when changing from one approach to the other. In fact, you also need to clean the cache when any of the environment variables required by the CMake build script below change its value.
+This page shows how to create a new C++ project linking against Urho3D library as external library. There are two approaches to do this. The first approach uses Urho3D library directly from the Urho3D project build tree. The second approach uses Urho3D SDK installation. It is imperative to clean the CMake cache when changing from one approach to the other. In fact, you also need to clean the cache when you change the path in the URHO3D_HOME environment variable.
 
-First of all, structure your project similar to Urho3D project as below, although this is not mandatory now:
+First of all, structure your project similar to Urho3D project as below, although this is not mandatory:
 
 \code
 PROJECT_ROOT/
- ┝ Android/             if you target Android platform as well
- ┝ Bin/
- ╎  ┝ Data/
- ╎  ┕ CoreData/
- ┝ CMake/
- ╎  ┝ Modules/
- ╎  ┕ Toolchains/
- ┝ Docs/                if you do documentation at all
- ┝ Source/              if you have large project with sources arranged in hierarchy
- ┝ CMakeListst.txt
- ┝ *.cpp and *.h
- ┕ *.bat or *.sh
+ ├ Android/ (for Android platform)
+ ├ Bin/
+ │  ├ Data/
+ │  └ CoreData/
+ ├ CMake/
+ │  ├ Modules/
+ │  └ Toolchains/
+ ├ Docs/ (for documentation)
+ ├ Source/ (for large project)
+ ├ CMakeListst.txt
+ ├ *.cpp and *.h
+ └ *.bat or *.sh
 \endcode
 
-The physical project root directory is also now the logical project source tree in CMake terminology where your project main CMakeLists.txt should reside. The Bin directory should contain the Data and CoreData resource subdirs. Unless you intend to configure to use your project root directory as your project build tree as well, all the executables will not be actually generated in this Bin directory. The executables will always be generated in the Bin directory of the project build tree (which is now fully user defined). Therefore, in order to run the executable in the build tree's Bin directory, you need to copy (or symlink) the resource directories (Data and CoreData) from your source tree to your build tree. Alternatively, you can use URHO3D_PREFIX_PATH environment variable to point to a prefix path containing the resource dirs. Urho3D engine automatically uses this prefix path when obtaining resources. By default the engine uses the program executable path.
+The physical project root directory is also the logical project source tree in CMake terminology where your project main CMakeLists.txt should reside. The Bin directory should contain the Data and CoreData resource subdirs. Unless you intend to configure to use your project root directory as your project build tree as well, all the executables will not be actually generated in this Bin directory. The executables will always be generated in the Bin directory of the project build tree (which is now fully user defined). Therefore, in order to run the executable in the build tree's Bin directory, you need to copy (or symlink) the resource directories (Data and CoreData) from your source tree to your build tree. Alternatively, you can use URHO3D_PREFIX_PATH environment variable to point to a prefix path containing the resource dirs. Urho3D engine automatically uses this prefix path when obtaining resources. By default the engine uses the program executable path.
 
-You may also want to copy (or symlink) the batch files or shell script files from Urho3D project root directory (or from Urho3D SDK installation) to your project root directory. The *.bat or *.sh scripts work together with the Urho3D CMake module to configure and generate your initial project build tree. Both out-of-source build tree (recommended) and non out-of-source build tree are now supported. Note that when you invoke one the *.bat or *.sh script for your project, you can also pass most of the \ref Build_Options "build options" supported by Urho3D project. In fact, you probably have to pass the similar build options that you use when building the Urho3D library to avoid any conflict.
+You may also want to copy (or symlink) the batch files or shell script files from Urho3D project root directory (or from Urho3D SDK installation) to your project root directory. The build scripts work together with the Urho3D CMake module to configure and generate your initial project build tree. Both out-of-source build tree (recommended) and non out-of-source build tree are now supported. Note that when you invoke one the build scripts for your project, you can also pass most of the \ref Build_Options "build options" supported by Urho3D project. In fact, you probably have to pass the similar build options that you use when building the Urho3D library to avoid any conflict.
 
 In your own project root directory, create a main CMakeLists.txt file and add the following lines: (replace MyProjectName and MyExecutableName with the actual names you want)
 
@@ -460,10 +482,11 @@ With [Rake](https://rubygems.org/gems/rake) ruby gem installed, you can quickly
 Usage: rake scaffolding dir=/path/to/new/project/root [project=Scaffolding] [target=Main]
 \endverbatim
 
-As its name implies, this task just creates a basic project structure for your new project. You may also pass optional "project" and "target" parameters besides the "dir" parameter. Otherwise, you will get the default project name (Scaffolding) and target name (Main) in the main CMakeLists.txt. This task copies the Urho3DPlayer.cpp and Urho3DPlayer.h as placeholders for the source files. Normally, you should replace these two files with your own project source files before invoking one of the CMake *.bat or *.sh script.
+As its name implies, this task just creates a basic project structure for your new project. You may also pass optional "project" and "target" parameters besides the "dir" parameter. Otherwise, you will get the default project name (Scaffolding) and target name (Main) in the main CMakeLists.txt. This task copies the Urho3DPlayer.cpp and Urho3DPlayer.h as placeholders for the source files. Normally, you should replace these two files with your own project source files before invoking one of the build scripts.
 
 On Windows host system, this task requires privilege to create symlinks by using mklink command. The task would fail when the Windows user account does not have that privilege. We strongly advise you not to use "Administrator" account just for this purpose. Instead, grant your "normal" user account to have the privilege correctly.
 
+WARNING: As of this writing, this rake scaffolding task does not yet create a complete new project suitable for Android platform. You need to supply the missing bits manually yourself for now.
 
 \page Structure Overall structure