0022827: Make non-CPP source files (CDLs, headers) to appear in MS VS project files...
[occt.git] / dox / dev_guides / building / cmake / cmake.md
index 5e6e93e..58acfbf 100644 (file)
@@ -17,16 +17,16 @@ instructions for your platform in @ref occt_dev_guides__building.
 
 ## Define the location of build and install directories.
 
-The build directory is where intermediate files (projects / makefiles, objects, binaries) will be created. Each built configuration should have its own build directory.
+The build directory is where intermediate files (projects / makefiles, objects, binaries) will be created.
 
 The install directory is where binaries will be installed after build, along with header files and resources required for OCCT use in applications. 
 It is possible to install several configurations of OCCT (differentiated by platform, bitness, compiler, and build type) into the same directory.
 
 It is recommended to separate build and install directories from OCCT source directory, for example:
 
-       /user/home/occt/                           - sources
-       /user/home/tmp/occt-build-vc10-x64-release - intermediate files
-       /user/home/occt-install                    - installed binaries
+       /user/home/occt/                   - sources
+       /user/home/tmp/occt-build-vc10-x64 - intermediate files
+       /user/home/occt-install            - installed binaries
 
 ## CMake usage
 
@@ -42,7 +42,7 @@ Specify the root folder of OCCT (<i>$CASROOT</i>, which contains *CMakelists.txt
 
 Specify the location (build folder) for Cmake generated project files by clicking **Browse Build**.
 
-Each configuration of the project should be built in its own directory. When building multiple configurations it is recommended to indicate in the name of build directories the system, bitness, compiler, and build type (e.g., <i>d:/occt/build/win32-vc9-debug</i> ).
+Each configuration of the project should be built in its own directory. When building multiple configurations it is recommended to indicate in the name of build directories the system, bitness, compiler, and build type (e.g., <i>d:/occt/build/win32-vc9</i> ).
 
 **Configure** opens the window with a drop-down list of generators supported by CMake project. Select the required generator (e.g., Visual Studio 2008) and click **Finish**.
 
@@ -52,7 +52,7 @@ Each configuration of the project should be built in its own directory. When bui
 
 In the console, change to the build directory and call *ccmake* with the path to the source directory of the project:
 
-       > cd ~/occt/build/debug
+       > cd ~/occt/build
        > ccmake ~/occt
 
 @figure{/dev_guides/building/cmake/images/cmake_image003.png}
@@ -74,26 +74,29 @@ which need to be defined. This error will appear until all required variables ar
 
 Note: In *cmake-gui* there is "grouped" option, which groups variables with a common prefix.
 
+**Note**: If a single-configuration generator is chosen (such as make), there is the need to specify *CMAKE_BUILD_TYPE* variable
+with the value of further build type: Debug, Release or RelWithDebInfo.
+
 ### Selection of the components to be built
 
 The variables with <i>BUILD_</i> prefix allow specifying OCCT components and
 configuration to be built:
 
-* *BUILD_CONFIGURATION* - defines configuration to be built (Release by default).
-* <i>BUILD_<MODULE></i>      - specifies whether the corresponding OCCT module should be 
-                        built (all toolkits). Note that even if the whole module is not 
-                        selected for build, its toolkits used by other toolkits 
-                        selected for build will be included automatically.
-* *BUILD_TOOLKITS*      - allows including additional toolkits from non-selected 
-                        modules (should be list of toolkit names separated by a 
-                        space or a semicolon).
-* *BUILD_SAMPLES*       - specifies whether OCCT MFC samples should be built.
-* *BUILD_PATCH_DIR*     - optionally specifies additional folder containing patched OCCT source files.
-                        The patch may contain arbitrary subset of OCCT source files (including CMake scripts, templates, etc.), organized in the same structure of folders as OCCT.
-                        The projects generated by CMake will use files found in the patch folder instead of the corresponding files of OCCT.
-
-Check variables with <i>USE_</i> prefix (<i>USE_FREEIMAGE, USE_GL2PS, USE_TBB,</i> and 
-<i>USE_OPENCL</i>) if you want to enable use of the corresponding optional 3rd-party 
+* *BUILD_LIBRARY_TYPE*     - specifies whether static or shared libraries should be built.
+* <i>BUILD_<MODULE></i>    - specifies whether the corresponding OCCT module should be 
+                             built (all toolkits). Note that even if the whole module is not 
+                             selected for build, its toolkits used by other toolkits 
+                             selected for build will be included automatically.
+* *BUILD_TOOLKITS*         - allows including additional toolkits from non-selected 
+                             modules (should be list of toolkit names separated by a 
+                             space or a semicolon).
+* *BUILD_MFC_SAMPLES*      - specifies whether OCCT MFC samples should be built.
+* *BUILD_OCCT_OVERVIEW*    - specifies whether OCCT overview documentation should be generated.
+* *BUILD_PATCH_DIR*        - optionally specifies additional folder containing patched OCCT source files.
+                             The patch may contain arbitrary subset of OCCT source files (including CMake scripts, templates, etc.), organized in the same structure of folders as OCCT.
+                             The projects generated by CMake will use files found in the patch folder instead of the corresponding files of OCCT.
+
+Check variables with <i>USE_</i> prefix (<i>USE_FREEIMAGE, USE_GL2PS, USE_TBB,</i>) if there is the need to enable use of the corresponding optional 3rd-party 
 library.
 
 ### 3rd-party configuration (The variables with <i>3RDPARTY_</i> prefix)
@@ -116,7 +119,7 @@ The result of the search are recorded in the corresponding variables:
 * *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.
+Note: each library and include directory should be the children of product directory if the last one is defined.
 
 The search process is as follows:
 
@@ -161,6 +164,11 @@ change appropriate cmake variables (edit CMakeCache.txt file or edit in cmake-gu
 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.
 
+Additional INSTALL_ variables:
+
+* INSTALL_SAMPLES       - copy all OCCT samples into the install folder
+* INSTALL_OCCT_OVERVIEW - copy generated OCCT overview documentation into the install folder
+
 At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
 
 ## OCCT Generation