[occt.git] / dox / dev_guides / building / cmake / cmake.md

Building with CMake {#dev_guides__building__cmake}
===================

@tableofcontents

This file describes steps to build OCCT libraries from complete source package
with CMake. CMake is free software that can create GNU Makefiles, KDevelop, 
XCode, and Visual Studio project files. Version 2.6 or above of CMake is 
required.

If you are building OCCT from bare sources (as in Git repository), or do some 
changes affecting CDL files, you need to use WOK to re-generate header files
and build scripts / projects. See \ref dev_guides__building__wok for instructions.

Before building OCCT, you need to install required third-party libraries; see paragraph 1 of 
\ref dev_guides__building for instructions.

## Decide on location of build and install directories.

The build directory is the one where intermediate files will be created (projects / makefiles, objects, binaries).
The install directory is the one where binaries will be installed after build, along with header files and resources required for OCCT use in applications.

OCCT CMake scripts assume use of separate build and one install directories for each configuration (Debug or Release).

It is recommended to separate build and install directories from OCCT source directory, for example:

       /user/home/occt/ - sources
       /user/home/tmp/occt-build-release - intermediate files (release)
       /user/home/occt-install-release - installed binaries (release)

## CMake usage

Run CMake indicating path to OCCT sources ($CASROOT; in previous example CASROOT equal to /user/home/occt in lin case, and d:/occt in win case) and selected build directory (in prev example build directory is /user/home/tmp/occt-build-release). 

It is recommended to use GUI tools provided by CMake: cmake-gui on Windows and Mac, ccmake on Linux.

### Windows:

@image html /dev_guides/building/cmake/images/cmake_image001.png
@image latex /dev_guides/building/cmake/images/cmake_image001.png

* Specify "main" CMakelists.txt meta-project location by clicking Browse Source (e.g., $CASROOT)
* Specify location (build folder) for Cmake generated project files by clicking Browse Build (e.g., d:/occt/build/win32-vc9-debug) (each cmake configuration of the project uses a specific build directory and a specific directory for installed files. It is recommended to compose names of the binary and install directory from system, bitness, compiler and build type.)
* 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)

@image html /dev_guides/building/cmake/images/cmake_image002.png
@image latex /dev_guides/building/cmake/images/cmake_image002.png

### Linux:

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
       > ccmake ~/occt

@image html /dev_guides/building/cmake/images/cmake_image003.png
@image latex /dev_guides/building/cmake/images/cmake_image003.png

Press "c" to configure.

### Mac OS:

Use cmake-gui (Applications -> CMake 2.8-10.app) to generate project files for the chosen build environment (e.g., XCode).

@image html /dev_guides/building/cmake/images/cmake_image004.png
@image latex /dev_guides/building/cmake/images/cmake_image004.png

## OCCT Configuration

The error message which appears at the end of configuration process, informs you about the required variables 
which need to be defined. This error will appear until all required variables are defined correctly.
Note: In cmake-gui there is "grouped" option, which groups variables with a common prefix.

###The variables with BUILD_ prefix:

* BUILD_TYPE - defines build configuration of the future project (Release by default)
* BUILD_<MODULE> - allows including the toolkit set of the specified module to the future project or excluding it from the project.
* BUILD_TOOLKITS - allows including additional specified toolkits (list of items separated by a space or a semicolon) to the common set of the future project.

Check USE_\<PRODUCT\> variable (USE_FREEIMAGE, USE_GL2PS, USE_TBB and USE_OPENCL) if you want to use this 3rd-party product in the future project.

### 3rd-party configuration

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 3rdparty products (some or all). 
At the next configuration 3rd-party product paths stored in 3RDPARTY_\<PRODUCT\>_DIR variable 
will be searched for in 3RDPARTY_DIR directory. If the structure of 3RDPARTY_DIR directory 
is the same as adopted in the OCCT, the directory will contain product dir, lib and header files. 
Press "Configure" ("c" key for ccmake)
Important: The names of searched libraries and header files are hardcoded.
The result of the 3rdparty product search will be recorded in the corresponding variables:

* 3RDPARTY_\<PRODUCT\>_DIR - path to the product directory (with directory name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32)
* 3RDPARTY_\<PRODUCT\>_LIBRARY - path to the .lib libraries (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/lib/tcl85.lib). 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., D:/3rdparty/Tcl-8.5.12.0-32/include including tcl.h)
* 3RDPARTY_\<PRODUCT\>_DLL - path to the .dll/.so/.dylib library  (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/bin/tcl85.dll)

The search process is as follows:

1 level:. 3RDPARTY_DIR
  2 level: 3RDPARTY_\<PRODUCT\>_DIR\
    3 level: 3RDPARTY_\<PRODUCT\>_LIBRARY
    3 level: 3RDPARTY_\<PRODUCT\>_INCLUDE
    3 level: 3RDPARTY_\<PRODUCT\>_DLL

If a variable of any level is not defined (empty or \<variable name\>-NOTFOUND) 
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 
doesn't find the required files, it searches in default places also. 

*Note*: Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir 
and after that adds "3RDPARTY_FREETYPE_INCLUDE /freetype2" path to common includes if it exists. 
Important: If BUILD_TYPE or BITNESS 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.
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 
(or clear one of them) and run the configuration process again. 
At this time the search will be performed in the new identified directory 
and the result will be recorded to empty variables (non-empty variables will not be replaced).

For example, (Linux case) 3RDPARTY_FREETYPE_DIR variable 

/PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7

can be changed to 

/PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10

and the related variables: 3RDPARTY_FREETYPE_DLL, 3RDPARTY_FREETYPE_INCLUDE_DIR and  3RDPARTY_FREETYPE_LIBRARY will be cleared.

@image html /dev_guides/building/cmake/images/cmake_image005.png
@image latex /dev_guides/building/cmake/images/cmake_image005.png

During configuration process the cleaned variables will be filled with new found values.

### Install path configuration

Define in INSTALL_DIR variable the path to the installed OCCT files (libraries, executables and headers).
If INSTALL_\<PRODUCT\> 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.

## OCCT Generation

This will create makefiles or project files for your build system.

### Windows

Click Generate button and wait until the generation process is finished. 
Then the project files will appear in the build folder (e.g., d:/occt/build/win32-vc9-release). 

### Linux

When the configuration is complete, start the generation process by pressing "g".

@image html /dev_guides/building/cmake/images/cmake_image006.png
@image latex /dev_guides/building/cmake/images/cmake_image006.png

### Mac OS X

Click Generate button and wait until the generation process is finished. 
Then the project files will appear in the build folder (e.g., /Developer/occt/build/XCode).

## 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.

### Windows (Visual studio)

Go to the build folder, start the Visual Studio solution (OCCT.sln) and build it by clicking Build - Build Solution.
When the building process finished, build the INSTALL project 
(by default the build solution process skips the building of the INSTALL project) to move the above files to INSTALL_DIR. 
For this in the solution explorer right click on the INSTALL project and select Project Only - Build Only INSTALL. 

### Linux (make)
Change directory to binary dir and run make command

       > make 

To copy all libraries, executables and chosen 3rd-party libraries run "make" command with "install" argument

       > make install

This command will move the above files to INSTALL_DIR.

### Mac OS X (XCode)

Go to the build folder, start the XCode solution (OCCT.xcodeproj) 
and build it by clicking Build -> Build. 
Please notice that XCode may have worst responsibility to user actions 
due to sources processing at first start.

When the building process finished, build the INSTALL project 
(by default the build solution process skips the building of the INSTALL project) 
to move the above files to INSTALL_DIR. 
Notice that env.sh (configure PATH and DYLD_LIBRARY_PATH environment variables 
as well as Draw Harness extra variables) and draw.sh (to launch DRAWEXE) will be created in target directory. 

## OCCT project debugging for Visual Studio
Run OCCT.bat from the build directory to start Visual Studio with required environment for debugging.
Commit	Line	Data
e5bd0d98	1	Building with CMake {#dev_guides__building__cmake}
	2	===================
	3
	4	@tableofcontents
	5
	6	This file describes steps to build OCCT libraries from complete source package
	7	with CMake. CMake is free software that can create GNU Makefiles, KDevelop,
	8	XCode, and Visual Studio project files. Version 2.6 or above of CMake is
	9	required.
	10
	11	If you are building OCCT from bare sources (as in Git repository), or do some
	12	changes affecting CDL files, you need to use WOK to re-generate header files
	13	and build scripts / projects. See \ref dev_guides__building__wok for instructions.
	14
79d580f2	15	Before building OCCT, you need to install required third-party libraries; see paragraph 1 of
79d580f2	16	\ref dev_guides__building for instructions.
e5bd0d98	17
	18	## Decide on location of build and install directories.
	19
	20	The build directory is the one where intermediate files will be created (projects / makefiles, objects, binaries).
	21	The install directory is the one where binaries will be installed after build, along with header files and resources required for OCCT use in applications.
	22
	23	OCCT CMake scripts assume use of separate build and one install directories for each configuration (Debug or Release).
	24
	25	It is recommended to separate build and install directories from OCCT source directory, for example:
	26
	27	/user/home/occt/ - sources
	28	/user/home/tmp/occt-build-release - intermediate files (release)
	29	/user/home/occt-install-release - installed binaries (release)
	30
	31	## CMake usage
	32
	33	Run CMake indicating path to OCCT sources ($CASROOT; in previous example CASROOT equal to /user/home/occt in lin case, and d:/occt in win case) and selected build directory (in prev example build directory is /user/home/tmp/occt-build-release).
	34
	35	It is recommended to use GUI tools provided by CMake: cmake-gui on Windows and Mac, ccmake on Linux.
	36
	37	### Windows:
	38
	39	@image html /dev_guides/building/cmake/images/cmake_image001.png
	40	@image latex /dev_guides/building/cmake/images/cmake_image001.png
	41
	42	* Specify "main" CMakelists.txt meta-project location by clicking Browse Source (e.g., $CASROOT)
	43	* Specify location (build folder) for Cmake generated project files by clicking Browse Build (e.g., d:/occt/build/win32-vc9-debug) (each cmake configuration of the project uses a specific build directory and a specific directory for installed files. It is recommended to compose names of the binary and install directory from system, bitness, compiler and build type.)
	44	* 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)
	45
	46	@image html /dev_guides/building/cmake/images/cmake_image002.png
	47	@image latex /dev_guides/building/cmake/images/cmake_image002.png
	48
	49	### Linux:
	50
	51	In the console, change to the build directory and call ccmake with the path to the source directory of the project:
	52
	53	> cd ~/occt/build/debug
79d580f2	54	> ccmake ~/occt
e5bd0d98	55
	56	@image html /dev_guides/building/cmake/images/cmake_image003.png
	57	@image latex /dev_guides/building/cmake/images/cmake_image003.png
	58
	59	Press "c" to configure.
	60
	61	### Mac OS:
	62
	63	Use cmake-gui (Applications -> CMake 2.8-10.app) to generate project files for the chosen build environment (e.g., XCode).
	64
	65	@image html /dev_guides/building/cmake/images/cmake_image004.png
	66	@image latex /dev_guides/building/cmake/images/cmake_image004.png
	67
	68	## OCCT Configuration
	69
	70	The error message which appears at the end of configuration process, informs you about the required variables
	71	which need to be defined. This error will appear until all required variables are defined correctly.
	72	Note: In cmake-gui there is "grouped" option, which groups variables with a common prefix.
	73
	74	###The variables with BUILD_ prefix:
	75
	76	* BUILD_TYPE - defines build configuration of the future project (Release by default)
	77	* BUILD_<MODULE> - allows including the toolkit set of the specified module to the future project or excluding it from the project.
	78	* BUILD_TOOLKITS - allows including additional specified toolkits (list of items separated by a space or a semicolon) to the common set of the future project.
	79
	80	Check USE_\<PRODUCT\> variable (USE_FREEIMAGE, USE_GL2PS, USE_TBB and USE_OPENCL) if you want to use this 3rd-party product in the future project.
	81
	82	### 3rd-party configuration
	83
	84	If you have 3rd-party libraries in a non-default location
	85	(e.g., on Windows, binaries downloaded from "http://www.opencascade.org/getocc/download/3rdparty/"),
	86	specify 3RDPARTY_DIR variable that points to the folders of 3rdparty products (some or all).
	87	At the next configuration 3rd-party product paths stored in 3RDPARTY_\<PRODUCT\>_DIR variable
	88	will be searched for in 3RDPARTY_DIR directory. If the structure of 3RDPARTY_DIR directory
	89	is the same as adopted in the OCCT, the directory will contain product dir, lib and header files.
	90	Press "Configure" ("c" key for ccmake)
	91	Important: The names of searched libraries and header files are hardcoded.
	92	The result of the 3rdparty product search will be recorded in the corresponding variables:
	93
	94	* 3RDPARTY_\<PRODUCT\>_DIR - path to the product directory (with directory name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32)
	95	* 3RDPARTY_\<PRODUCT\>_LIBRARY - path to the .lib libraries (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/lib/tcl85.lib). In non-windows case, this variable is the same as 3RDPARTY_\<PRODUCT\>_DLL.
	96	* 3RDPARTY_\<PRODUCT\>_INCLUDE - path to the include directory that contains the required header file (with "include" name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/include including tcl.h)
	97	* 3RDPARTY_\<PRODUCT\>_DLL - path to the .dll/.so/.dylib library (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/bin/tcl85.dll)
	98
	99	The search process is as follows:
	100
	101	1 level:. 3RDPARTY_DIR
	102	2 level: 3RDPARTY_\<PRODUCT\>_DIR\
	103	3 level: 3RDPARTY_\<PRODUCT\>_LIBRARY
	104	3 level: 3RDPARTY_\<PRODUCT\>_INCLUDE
	105	3 level: 3RDPARTY_\<PRODUCT\>_DLL
	106
	107	If a variable of any level is not defined (empty or \<variable name\>-NOTFOUND)
	108	and the upper level variable is defined, the content of the non-defined variable
	109	will be searched for at the next configuration step. If search process in level 3
	110	doesn't find the required files, it searches in default places also.
	111
	112	Note: Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir
	113	and after that adds "3RDPARTY_FREETYPE_INCLUDE /freetype2" path to common includes if it exists.
	114	Important: If BUILD_TYPE or BITNESS variable is changed - at the next configuration
	115	3RDPARTY_ variables will be replaced by the search process result, except for the 3RDPARTY_DIR variable.
	116
	117	Note: CMake will produce an error after the configuration step until all required variables are defined correctly.
	118	If the search result (include path, or library path, or dll path) does not meet your expectations -
119	you can change 3RDPARTY_\<PRODUCT\>_DIR variable, clear (if they are not empty)
120	3RDPARTY_\<PRODUCT\>_DLL, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR and 3RDPARTY_\<PRODUCT\>_LIBRARY variables
121	(or clear one of them) and run the configuration process again.
122	At this time the search will be performed in the new identified directory
123	and the result will be recorded to empty variables (non-empty variables will not be replaced).
124
125	For example, (Linux case) 3RDPARTY_FREETYPE_DIR variable
126
127	/PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7
128
129	can be changed to
130
131	/PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
132
133	and the related variables: 3RDPARTY_FREETYPE_DLL, 3RDPARTY_FREETYPE_INCLUDE_DIR and 3RDPARTY_FREETYPE_LIBRARY will be cleared.
134
135	@image html /dev_guides/building/cmake/images/cmake_image005.png
136	@image latex /dev_guides/building/cmake/images/cmake_image005.png
137
138	During configuration process the cleaned variables will be filled with new found values.
139
140	### Install path configuration
141
142	Define in INSTALL_DIR variable the path to the installed OCCT files (libraries, executables and headers).
143	If INSTALL_\<PRODUCT\> variable is checked - 3rd-party products will be copied to the install directory.
144	At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
145
146	## OCCT Generation
147
148	This will create makefiles or project files for your build system.
149
150	### Windows
151
152	Click Generate button and wait until the generation process is finished.
153	Then the project files will appear in the build folder (e.g., d:/occt/build/win32-vc9-release).
154
155	### Linux
156
157	When the configuration is complete, start the generation process by pressing "g".
158
159	@image html /dev_guides/building/cmake/images/cmake_image006.png
160	@image latex /dev_guides/building/cmake/images/cmake_image006.png
161
162	### Mac OS X
163
164	Click Generate button and wait until the generation process is finished.
165	Then the project files will appear in the build folder (e.g., /Developer/occt/build/XCode).
166
167	## OCCT Building
168
169	The install folder contains bin, inc, lib and res folders and a script to run DRAWEXE (draw.bat or draw.sh).
170	"bin" contains executables, DLL (Windows) style shared libraries and pdb-files in OCCT debug version,.
171	"lib" contains the import parts of DLL libraries.
172	"inc" contains header files.
173	"res" contains all required source files for OCCT.
174
175	### Windows (Visual studio)
176
177	Go to the build folder, start the Visual Studio solution (OCCT.sln) and build it by clicking Build - Build Solution.
178	When the building process finished, build the INSTALL project
179	(by default the build solution process skips the building of the INSTALL project) to move the above files to INSTALL_DIR.
180	For this in the solution explorer right click on the INSTALL project and select Project Only - Build Only INSTALL.
181
182	### Linux (make)
183	Change directory to binary dir and run make command
184
185	> make
186
187	To copy all libraries, executables and chosen 3rd-party libraries run "make" command with "install" argument
188
189	> make install
190
191	This command will move the above files to INSTALL_DIR.
192
193	### Mac OS X (XCode)
194
195	Go to the build folder, start the XCode solution (OCCT.xcodeproj)
196	and build it by clicking Build -> Build.
197	Please notice that XCode may have worst responsibility to user actions
198	due to sources processing at first start.
199
200	When the building process finished, build the INSTALL project
201	(by default the build solution process skips the building of the INSTALL project)
202	to move the above files to INSTALL_DIR.
203	Notice that env.sh (configure PATH and DYLD_LIBRARY_PATH environment variables
204	as well as Draw Harness extra variables) and draw.sh (to launch DRAWEXE) will be created in target directory.
205
206	## OCCT project debugging for Visual Studio
207	Run OCCT.bat from the build directory to start Visual Studio with required environment for debugging.