Merge pull request #16 from tpaviot/qb/msvc-build-instructions

Added preliminary installation and build instructions

BUILD.MSVC.txt

@@ -0,0 +1,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.6 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://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://github.com/QbProg/oce-win-bundle
+
+        In this example we will extract the precompiled bundle in C:\oce-win-bundle-win32-0.3\
+  --
+
+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.
+
+   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-0.2/
+      - 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 \bind and \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-0.3\bin and c:\oce-win-bundle-win32-0.3\bind to your c:\oce-bin\Win32\bind and 
+  c:\oce-bin\Win32\bin  folders. 
+
+ 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.
+

INSTALL.MSVC.txt

@@ -0,0 +1,33 @@
+****** STUB *******
+
+If you want to build OCE from sources with MSVC, read BUILD.MSVC.txt
+
+If you have downloaded the PRECOMPILED package, just make sure that you are using the 
+exactly matching compiler version, including service pack level.
+
+To be able to use OCE from MSVC, you have to set various "Project Options"
+
+- C++ Compiler \ Additional include directories 
+  Set these pointing to <oce-install-dir>\inc
+
+- Linker \ Additional Directories 
+  In DEBUG set these point to <oce-install-dir>\Win32\libd
+  In RELEASE set these point to <oce-install-dir>\Win32\lib
+  Eventually change Win32 with Win64 when required
+
+- Linker "Input Libraries"
+  For each toolkit you use , you must add the corresponding .lib files
+  Debug libraries have a "d" suffix.
+  For example, you will have to add TKernel.lib in RELEASE and TKerneld.lib in DEBUG
+  to use the Kernel module.
+  If you get linker errors, you likely forgot to add a .lib file to that list.
+
+- Binary search path
+  When you run the program, the system must be able to find the OCE libraries somewhere. You can add the 
+  <oce-install-dir>\Win32\bind and <oce-install-dir>\Win32\bin to your PATH environment variable or 
+  add it locally to your project (preferred way). Also you can copy all the DLLs to your project binary folder.
+
+  Be careful when adding multiple OCE version in your search PATH, you will likely end up with loader errors.
+
+
+