summaryrefslogtreecommitdiff
path: root/BUILD.MSVC.txt
blob: 5c41fb90b54e8f4863616e85ec204843125c4d7d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
OCE MSVC Build Instructions

1) INTRODUCTION
2) PREREQUISITES
  2.1) Cmake
  2.2) External Libraries
    2.2.1) Compile the libs by yourself
    2.2.2) Using OCE - BUNDLE
3) Extracting the sources
4) Configuring
  4.1) Designate a build directory 
  4.2) Run cmake-gui 
  4.3) Select the generator
  4.4) Configuration Options
  4.5) Configuring library paths
    4.5.1) TCL
    4.5.2) OCE bundle
    4.5.3) Using your own compiled libs
  4.6) Generating 
5) Compiling
6) Installing
  6.1) External libs
  6.2) Command line
7) Building for Win64
8) Building for both Win32 and Win64
9) Final Notes
  9.1) Debug libraries
  9.2) Debug symbols 


1) INTRODUCTION

This guide will help you throught recompiling OCE from scratch. Consider downloading 
precompiled binaries if you just want to use it in a supported compiler.

2) PREREQUISITES

  2.1) Cmake
  OCE build system requires CMake 2.8 to function. Download and install it at www.cmake.org

  2.2) External Libraries
    Some modules of OCE require external libraries. These include

    - freetype , required by Visualization
    - FTGL , required by Visualization
    - TCL , required by DRAW
    - gl2ps and FreeImage , optionally required by Visualization
    - TBB , optionally required to to multithreading

    If you use DRAW , we strongly suggest that you install ActiveState TCL for Win32 or Win64. It comes
    with a simple to use installation package and cmake automatically finds it.

    You have two choices to build or use dependency binaries:

    - Compile all the libs by yourself
    - Use OCE-WIN-BUNDLE (see below), to be found at http://www.github.com/QbProg/oce-win-bundle

      2.2.1) Compile the libs by yourself
        
        These libs must be downloaded and compiled separately.
        If you find precompiled binaries, make sure that the compiler version used to compile matches
        exactly the one installed in your system (even the service pack level).
        If you choose build the libraries, make sure you compile them in debug and release.

      2.2.2) Using OCE - BUNDLE
      
        The bundle will let you compile all the libraries required by oce in one simple step.
        You can also download precompiled binaries of the bundle if you use VC2008 or VC2010.

        If you choose to use the bundle, make sure you have extracted or INSTALLed it to a specific folder, one time for 32bit binaries,
        and in a different folder for 64bit binaries (always debug+release). 
        Actually bundle 32/64 binaries are split, and will be provided together in OCE-0.4

        If you want to rebuild the bundle from sources, follow the instructions at 
        http://www.github.com/QbProg/oce-win-bundle
        
        In this example we will extract the precompiled bundle in C:\oce-win-bundle-win32\
  --
    
3) Extracting the sources
    
  - Download oce-x.x.zip and extract it in a folder. Say C:\oce-src

4) Configuring

  We strongly suggest the use of out-of-source CMake builds. This means that the temporary
  compilation projects and objects will not pollute the source folder.

  4.1) Designate a build directory 
    You can use a subdirectory of the source one, or a completely different one. 
    In this case we will use c:\oce-src\Build32\

  4.2) Run cmake-gui 
     This is the GUI front-end to CMake. It will help you to select
     the compilation options and configurations.  

    - In the "Where is the source code" field put the oce source directory : C:\oce-src
    - In the "Where to build the binaries" field put your build folder : C:\oce-src\Build32\
    - Press "Configure"

  4.3) Select the generator 
      The first time you press "Configure", you will have to select the compiler you plan to use. 
      Select one of the "Visual Studio xx" generators, and select the "Win64" ones if you want to do a 64bit compilation
      
  4.4) Configuration Options

    After the first configuration step, you will have to select the options.
    You will find a lot of options: concentrate first on these that begin with OCE_
    Here the most important ones:
      
      - OCE_INSTALL_PREFIX : the destination folder of the INSTALL phase. 
      At the end of the process, you will find there all the includes, binaries, libraries,etc...
      NOTE : This directory is filled only when you compile the INSTALL project.
      In this example we'll set it pointing to C:/oce-bin/
 
      - OCE_USE_MSVC_EXPRESS : enable this if you are using the express edition. 
      - OCE_BUILD_SHARED_LIB : disable this if you want static libraries
      - OCE_WITH_xxx : enable or disable the usage of the xxx external library
      - OCE_xxxxxx : enables or disables a specific component to be built. (i.e. OCE_VISUALIZATION, OCE_DRAW , etc...) 
      - OCE_INSTALL_PDB_FILES : enable this if you want to copy resulting PDB files (debug symbols) in the INSTALL directory

      After you set the required options , press CONFIGURE. You will likely get errors.  To fix those errors, you
      have to tell CMake where to find headers and libraries for dependencies, this is discussed just below.
      
   4.5) Configuring library paths
      Now, depending on the enabled options, it's time to set the external library directories.

    4.5.1) TCL
      If you use ActiveState TCL, CMake will find it automatically. Else, you should set the variables 
      starting with TCL_ and TK (eventually available in the "Advanced" section of cmake-gui)

    4.5.2) OCE bundle
     
      - Enable the OCE_USE_BUNDLE option
      - Press Configure
      - Set OCE_BUNDLE_ROOT_PATH to point to the oce-win-bundle installation directory. For example C:/oce-win-bundle-win32/
      - Configure again
      
      It should automatically set all the library paths. Some of them will appear in red, but the CONFIGURE phase will end successfully at 
      this time. You should check this in the output window at the bottom of cmake-gui
      
    4.5.3) Using your own compiled libs
      For each lib, set the appropriate fields pointing to the include directories or libraries.
      For example, you will have to set FREETYPE_INCLUDE_DIR to C:/freetype-???/include/ and so on...
      Reconfigure until all the errors go away

  4.6) Generating      
    Once you configured everything , press the Generate button. It will create a MSVC solution in C:\oce-src\Build32\OCE.sln
    If you want to change settings, you can return to cmake-gui , reconfigure and regenerate again.

--
5) Compiling

 You can just open c:/oce-src/Build32/OCE.sln and compile as usual from the IDE.
 You must compile the Debug configuration and one of the Release ones. 
 RelWithDebInfo is good because it generates debug symbols while being optimized.
 
 If you use MSVC2010 , you can build from the commandline using a Visual Studio 2010 prompt.
 
 cd \oce-src\Build32
 msbuild OCE.sln /p:Configuration=Debug
 msbuild OCE.sln /p:Configuration=RelWithDebInfo
 
 The process could take hours, depending on the system. If you have a multicore machine and MSVC 2010, BEFORE running these commands you can run
 
 SET cl=/MP
 
 the compiler will then use all your cores to compile.
 
 If you get compilation errors, it is likely that you did something wrong in the configure phase. Go back there and make sure that all the libraries
 are found.
 
6) Installing
  
 In CMake+MSVC, INSTALLing means copying just the required files to a designed folder, set by OCE_INSTALL_PREFIX.
 This include header files, libs, binaries and data files.
 Object files will be left in the BUILD directory. This means that you can distribute your INSTALL folder and other will be able to use
 it to compile programs dependent by OCE.
  
 Once compiled, from the IDE explicitly compile the "INSTALL" project. 
 You do this by right-clicking on the project and selecting "Compile".
 
 IMPORTANT : do this once for each Configuration you compiled : Debug and RelWithDebInfo
 
 After the INSTALL phase, we'll find the result in c:\oce-bin\Win32
 
 6.1) External libs
  We miss just one piece : unless you have these in your path, copy all the external DLLs in the \bin folder of the installation directory.
  (remember tcl85.dll too)

  If you used oce-win-bundle, copy the dlls from c:\oce-win-bundle-win32\bin and c:\oce-win-bundle-win32\bind to your c:\oce-bin\Win32\bin forlder.
 
 6.2) Command line
   Again, in MSVC2010 command prompt you can run
    
   msbuild INSTALL.vcxproj /p:Configuration=Debug 
   msbuild INSTALL.vcxproj /p:Configuration=RelWithDebInfo 
   
   and you will get the same effect.

7) Building for Win64
  
  You should do exactly the same step as before, except that 
   - Use a "Win64" generator in the Configure phase
   - Use the "win64" oce-win-bundle packages
   - Install TCL for 64 bit and all your libs compiled for 64bits
   - Use a Build64 folder in the CMake configuration phase
   - Installation files will go in OCE_INSTALL_PREFIX/Win64
   
8) Building for both Win32 and Win64

  First of all, let's make this clear: CMake doesn't support mixing 32bit and 64bit compilation. 
  You will have to do all the steps two times, one for win32, one for win64. 
  Just use a Build32 and Build64 folder, and configure *exactly* in the same way the two projects.

  You CAN use the same OCE_INSTALL_PREFIX, if you configure the two build in the same way. 
  Otherwise it is better to use different installation folders.
  You will find the binaries in the OCE_INSTALL_PREFIX/Win32 and OCE_INSTALL_PREFIX/Win64 directories.

9) Final Notes

  9.1) Debug libraries
    You can avoid to build the debug libraries , but then you won't be able to build projects using oce in debug mode. It is *UNSUPPORTED* and 
    really not working to link release libraries in debug configurations.
  9.2) Debug symbols 
    If you include them in the INSTALL directory, you will be able to see OCE call stacks and local variables. The INSTALL dir will grow in size
    of about 200MB.