0024888: Refactoring of OCCT CMake meta-project

user sees just dirs of libs, shared libs and headers of 3rdparty products
documentation updated

3rdparty search priority was fixed: 1. user paths; 2. system paths
3rdparty debug usage fixed
vtk search introduced
occt information, generated by wok, was divided onto two files: occt_toolkits.cmake and occt_inc_toolkits.cmake
additional behavior of cmake search for freetype 2.5.1 and above

CMake (version < 3.0) don't know about new place of config/ftheader.h in freetype 2.5.1. There are cases when cmake seeks config/ftheader.h in defined place (3RDPARTY_FREETYPE_DIR variable), doesn't find it and start new search in system places. If system has own freetype header- cmake will find it and 3RDPARTY_FREETYPE* variables will point to different places. This situation is avoided

tcl, freetype, vtk are checked before usage of it (CSF variables usage)
tbb search mechanism was refactored
freetype search is processed by default cmake mechanism
tcl search is processed by default cmake mechanism

3rdparty macro seeks debug libraries (and release if debug ones aren't found); 3rdparty dll is sought in win case only

ADD_SUBDIRECTORY preferred to SUBDIRS

gendoc.bat search for tclsh.exe in user's system

0025141: CMake / MinGW: link recipe fails due to long command

0025146: Porting to Android

OCCT documentation updated. "Building with CMake and ADT for Android" article added

[CMAKE] custom.sh.in uses library variables instead unused dll ones.

-DDEBUG remove from CMAKE_CXX_FLAGS_DEBUG and CMAKE_C_FLAGS_DEBUG

hide unused 3rdparty in android case

also messages of freetype search mechanism slightly updated

dox/dev_guides/building/android/android.md

@@ -0,0 +1,71 @@
+Building with CMake and ADT for Android {#occt_dev_guides__building_android}
+===================
+
+@tableofcontents
+
+This file describes the steps to build OCCT libraries from a complete source package
+with following tools:
+  - Generation of eclipse project files
+    - CMake v3.0+ http://www.cmake.org/cmake/resources/software.html
+    - Cross-compilation toolchain for CMake https://github.com/taka-no-me/android-cmake
+    - Android NDK rev.10+ https://developer.android.com/tools/sdk/ndk/index.html
+    - Make: MinGW v4.82+ for Windows, GNU Make vXX for Linux. http://sourceforge.net/projects/mingw/files/
+  - Building eclipse project files of OCCT
+    - Android Developer Tools (ADT) v22+ https://developer.android.com/sdk/index.html
+
+## Generation of eclipse project files
+Run GUI tool provided by CMake: cmake-gui
+
+### Tools configuration
+   - Specify the root folder of OCCT (<i>$CASROOT</i>, which contains *CMakelists.txt* file) by clicking **Browse Source**.
+  - Specify the location (build folder) for Cmake generated project files by clicking **Browse Build**.
+
+@figure{/dev_guides/building/android/images/android_image001.png}
+
+Click **Configure** button. It opens the window with a drop-down list of generators supported by CMake project. - 
+
+Select "Eclipse CDT4 - MinGW MakeFiles" item from the list
+  - Choose "Specify toolchain file for cross-compiling"
+  - Click "Next"
+@figure{/dev_guides/building/android/images/android_image002.png}
+  - Specify the Toolchain file at next dialog by android.toolchain.cmake is contained by cross-compilation toolchain for CMake
+  - Click "Finish"
+@figure{/dev_guides/building/android/images/android_image003.png}
+
+Add cache entry ANDROID_NDK - path (entry type is PATH) to the NDK folder ("Add Entry" button)
+@figure{/dev_guides/building/android/images/android_image004.png}
+
+if there is message "CMake Error: CMake was unable to find a build program corresponding to "MinGW Makefiles".  CMAKE_MAKE_PROGRAM is not set.  You probably need to select a different build tool."  
+Define CMAKE_MAKE_PROGRAM variable with the file path to mingw32-make executable. 
+@figure{/dev_guides/building/android/images/android_image005.png}
+
+### OCCT Configuration
+
+How to configure OCCT, see "OCCT Configuration" section of @ref occt_dev_guides__building_cmake "Building with CMake"
+taking into account the specific configuration variables for android:
+  - ANDROID_ABI = armeabi-v7a
+  - ANDROID_NATIVE_API_LEVEL = 15
+  - ANDROID_NDK_LAYOUT is equal to BUILD_CONFIGURATION variable 
+  - CMAKE_ECLIPSE_VERSION is equal to installed eclipse version (e.g., 4.2)
+
+Configure parallel building:
+  - CMAKE_ECLIPSE_MAKE_ARGUMENTS = -jN where N = your numbers of CPU cores (threads)
+
+@figure{/dev_guides/building/android/images/android_image006.png}
+
+### Generation of eclipse projects files
+
+Click **Generate** button and wait until the generation process is finished. 
+Then the eclipse project files will appear in the build folder (e.g. <i> D:/android-build-eclipse-api-15 </i>).
+
+## Building eclipse project files of OCCT
+
+  - Open eclipse (downloaded ADT bundle contains it)
+  @figure{/dev_guides/building/android/images/android_image007.png}
+  - Import "Existing project into Workspace"
+  @figure{/dev_guides/building/android/images/android_image008.png}
+  @figure{/dev_guides/building/android/images/android_image009.png}
+  - Build ALL
+  @figure{/dev_guides/building/android/images/android_image010.png}
+  
+When the building process has finished, libraries are located in \<build folder\>/out (e.g. <i> D:/android-build-eclipse-api-15/out </i>).

dox/dev_guides/building/building.md

@@ -24,6 +24,7 @@ you need to:
 3. Build using your preferred build tool.
    - \subpage occt_dev_guides__building_automake "Building on Linux with Autotools"
    - \subpage occt_dev_guides__building_cmake "Building with CMake (cross-platform)"
+   - \subpage occt_dev_guides__building_android "Building with CMake and ADT for Android (cross-platform)"
    - \subpage occt_dev_guides__building_code_blocks "Building on Mac OS X with Code::Blocks"
    - \subpage occt_dev_guides__building_msvc "Building on Windows with MS Visual Studio"
    - \subpage occt_dev_guides__building_xcode "Building on Mac OS X with Xcode"

dox/dev_guides/building/cmake/cmake.md

@@ -5,7 +5,7 @@ Building with CMake {#occt_dev_guides__building_cmake}
 
 This file describes the steps to build OCCT libraries from a complete source package
 with **CMake**. CMake is free software that can create GNU Makefiles, KDevelop, 
-XCode, and Visual Studio project files. **CMake** version 2.6 or above is 
+XCode, Eclipse and Visual Studio project files. **CMake** version 3.0 or above is 
 required.
 
 If you build OCCT from bare sources (as in Git repository) or make some 
@@ -32,7 +32,7 @@ It is recommended to separate build and install directories from OCCT source dir
 
 Run CMake indicating the path to OCCT sources <i>($CASROOT)</i> and selected build directory.
 
-It is recommended to use GUI tools provided by CMake: *cmake-gui* on Windows and Mac, *ccmake* or *cmake-gui* on Linux.
+It is recommended to use GUI tools provided by CMake: *cmake-gui* on Windows, Mac and Linux (*ccmake* also can be used on Linux).
 
 ### Windows:
 
@@ -100,69 +100,65 @@ library.
 
 If you have 3rd-party libraries in a non-default location 
 (e.g., on Windows, binaries downloaded from http://www.opencascade.org/getocc/download/3rdparty/") 
-specify *3RDPARTY_DIR* variable that points to the folders of 3rd-party libraries (some or all). 
+*3RDPARTY_DIR* variable should be specified with the path to the folders where required 3rd-party libraries will be sought
 
-At the next configuration step the 3rd-party libraries will be searched for in *3RDPARTY_DIR* directory, and stored in *3RDPARTY_\<LIBRARY\>_DIR* variables.
+The results of search for 3rd-party directories will be stored in *3RDPARTY_\<LIBRARY\>_DIR* variables. If *3RDPARTY_DIR* directory is defined, required libraries are sought in *3RDPARTY_DIR* location.
 
-The procedure expects to find binary and header files of each 3rd-party library in its own sub-directory, separated by sub-directories *bin*, *lib*, and *include*.
+The procedure expects to find binary and header files of each 3rd-party library in its own sub-directory: *bin*, *lib* and *include*.
 
 Press **Configure** (**c** key for ccmake).
 
-The result of the 3rdparty product search will be recorded in the corresponding variables:
+The result of the search are recorded in the corresponding variables:
 
-* *3RDPARTY_\<PRODUCT\>_DIR* - path to the product directory (with directory name) (e.g. <i>D:/3rdparty/Tcl-8.5.12.0-32</i>)
-* *3RDPARTY_\<PRODUCT\>_LIBRARY* - path to .lib libraries (with the library name) (e.g. <i>D:/3rdparty/Tcl-8.5.12.0-32/lib/tcl85.lib</i>). 
-  In non-windows case, this variable is the same as *3RDPARTY_\<PRODUCT\>_DLL*.
-* *3RDPARTY_\<PRODUCT\>_INCLUDE* - path to the include directory that contains the required header file (with "include" name) (e.g., <i>D:/3rdparty/Tcl-8.5.12.0-32/include including tcl.h</i>)
-* *3RDPARTY_\<PRODUCT\>_DLL* - path to  <i>.dll/.so/.dylib</i> library  (with the library name) (e.g., <i>D:/3rdparty/Tcl-8.5.12.0-32/bin/tcl85.dll</i>)
+* *3RDPARTY_\<PRODUCT\>_DIR* - path to the 3rdparty directory (with directory name) (e.g. <i>D:/3rdparty/tcltk-86-32</i>)
+* *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR* - path to directory containing a library (e.g. <i>D:/3rdparty/tcltk-86-32/lib</i>). 
+* *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* - path to the directory containing a header file (e.g., <i>D:/3rdparty/tcltk-86-32/include</i>)
+* *3RDPARTY_\<PRODUCT\>_DLL_DIR* - path to the directory containing a shared library (e.g., <i>D:/3rdparty/tcltk-86-32/bin</i>) This variable is able just in windows case
+
+
+Note: a libraries and include directories should be the children of product directory if the last one is defined.
 
 The search process is as follows:
 
 1. Common path: *3RDPARTY_DIR*
 2. Path to a particular 3rd-party library: *3RDPARTY_\<PRODUCT\>_DIR*
 3. Paths to headers and binaries:
-   1. *3RDPARTY_\<PRODUCT\>_INCLUDE*
-   2. *3RDPARTY_\<PRODUCT\>_LIBRARY*
-   3. *3RDPARTY_\<PRODUCT\>_DLL*
+   1. *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR*
+   2. *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR*
+   3. *3RDPARTY_\<PRODUCT\>_DLL_DIR*
 
 If a variable of any level is not defined (empty or <i> \<variable name\>-NOTFOUND </i>) 
 and the upper level variable is defined, the content of the non-defined variable 
-will be searched for at the next configuration step. If search process in level 3 
-does not find the required files, it searches in default places also.
-
-**Note**: the names of searched libraries and header files are hard-coded.
-Freetype search process tries to find *ft2build.h* file in *3RDPARTY_FREETYPE INCLUDE* directory 
-and after that adds *3RDPARTY_FREETYPE_INCLUDE /freetype2* path to common includes if it exists. 
+will be sought at the next configuration step. If search process at level 3 does not find the required files, it seeks in default places.
 
 Important: If *BUILD_CONFIGURATION* variable is changed, at the next configuration 
 *3RDPARTY_ variables* will be replaced by the search process result, except for the *3RDPARTY_DIR* variable.
 
-*Note* : CMake will produce an error after the configuration step until all required variables are defined correctly.
+**Note** : CMake will produce an error after the configuration step until all required variables are defined correctly.
 If the search result (include path, or library path, or dll path) does not meet your expectations, 
-you can  change *3RDPARTY_\<PRODUCT\>_DIR variable*, clear (if they are not empty) 
-*3RDPARTY_\<PRODUCT\>_DLL, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* and 3RDPARTY_\<PRODUCT\>_LIBRARY variables 
+you can  change *3RDPARTY_\<PRODUCT\>_*_DIR variable*, clear (if they are not empty) 
+*3RDPARTY_\<PRODUCT\>_DLL_DIR, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* and 3RDPARTY_\<PRODUCT\>_LIBRARY_DIR variables 
 (or clear one of them) and run the configuration process again. 
 
 At this time the search will be performed in the newly identified directory 
-and the result will be recorded to empty variables (non-empty variables will not be replaced).
+and the result will be recorded to corresponding variables (replace old value if it is necessary).
 
 For example, (Linux case) *3RDPARTY_FREETYPE_DIR* variable 
 
-    /PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7
+    /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
 
 can be changed to 
 
-    /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
+    /PRODUCTS/maintenance/Mandriva2010/freetype-2.5.3
 
-and the related variables *3RDPARTY_FREETYPE_DLL, 3RDPARTY_FREETYPE_INCLUDE_DIR* and  *3RDPARTY_FREETYPE_LIBRARY* will be cleared.
+During the configuration process and the related variables (*3RDPARTY_FREETYPE_DLL_DIR*, *3RDPARTY_FREETYPE_INCLUDE_DIR* and *3RDPARTY_FREETYPE_LIBRARY_DIR*) will be filled with new found values
 
-@figure{/dev_guides/building/cmake/images/cmake_image005.png}
-
-During the configuration process the cleaned variables will be filled with new found values.
+**Note**: The names of searched libraries and header files are hard-coded. If there is the need to change their names,
+change appropriate cmake variables (edit CMakeCache.txt file or edit in cmake-gui in advance mode) without reconfiguration: *3RDPARTY_\<PRODUCT\>_INCLUDE* for include, *3RDPARTY_\<PRODUCT\>_LIB* for library and *3RDPARTY_\<PRODUCT\>_DLL* for shared library.
 
 ###The variables with INSTALL_ prefix:
 
-Define in *INSTALL_DIR* variable the path, where the built OCCT files (libraries, executables and headers) will be placed.
+Define *INSTALL_DIR* variable as the path will be contain the built OCCT files (libraries, executables and headers)
 If <i>INSTALL_\<PRODUCT\></i> variable is checked, 3rd-party products will be copied to the install directory.
 
 At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
@@ -178,9 +174,7 @@ Then the project files will appear in the build folder (e.g. <i> d:/occt/build/w
 
 ### Linux
 
-When the configuration is complete, start the generation process by pressing **g**.
-
-@figure{/dev_guides/building/cmake/images/cmake_image006.png}
+Click **Generate** button (if you use cmake-gui) or press **g** (for ccmake) to start the generation process.
 
 ### Mac OS X
 
@@ -189,11 +183,14 @@ Then the project files will appear in the build folder (e.g. <i> /Developer/occt
 
 ## OCCT Building
 
-The install folder contains *bin, inc, lib* and *res* folders and a script to run *DRAWEXE* (*draw.bat* or *draw.sh*).
-* **bin** contains executables, DLL (Windows) style shared libraries and pdb-files in OCCT debug version.
-* **lib** contains the import parts of DLL libraries.
-* **inc** contains header files.
-* **res** contains all required source files for OCCT.
+The install folder contains the scripts to run *DRAWEXE* (*draw.bat* or *draw.sh*) and samples (if its were built; (see below **MFC samples**)); the directory structure is follow:
+* **data**    - data files for OCCT (brep, iges, stp)
+* **inc**     - header files
+* **samples** - tcl sample files
+* **src**     - all required source files for OCCT
+* **tests**   - OCCT test suite
+* **win32/vc10/bind**> - example relative directory tree of binary files (3rdparty and occt) (the abstract one is <system with bitness>/<compiler>/bin<build type>)
+* **win32/vc9/lib**>   - example relative directory tree of libraries (3rdparty and occt) (the abstract one is <system with bitness>/<compiler>/lib<build type>)
 
 ### Windows (Visual studio)