Source

Mogre / Documentation / Build instructions by Manski.txt


--- Foreword ---

This instruction file was created by user Manski in August(?) 2010 
related to Mogre 1.7.

It was the first comprehensive documentation, which was written at all. 
This was hard reverse-engineering work, because there was not much 
information before and the very few "wrapping specialists" became inactive. 

Note:
Have a look to the MogreBuilder.
By this tool you can do the building/wrapping process very easy.
http://www.ogre3d.org/tikiwiki/MogreBuilder

So, this was my "foreword". (Written by Beauty in April 2012.)






Step by step instructions to build Mogre/Ogre with Visual Studio
================================================================

Repository information
----------------------
The repositories for MOGRE and OGRE are based on the official repositories. 
They've slightly modified to fix certain bugs not (yet) fixed in the official
sources. They also aim to the goal to provide an easier way of build MOGRE.

By cloning the MOGRE repository, the other two repositories are cloned as well
automatically (as sub repositories). The can be found here:

  /                               - MOGRE repository: http://bitbucket.org/manski/mymogre/
  /Main/OgreSrc/ogre              - OGRE repository: http://bitbucket.org/manski/myogre
  /Main/OgreSrc/ogre/Dependencies - OGRE dependencies repository: http://bitbucket.org/manski/myogredependencies/

Custom changes the MOGRE and the OGRE repository are placed in their own named
branch. The branches of the original repository remain unchanged to allow easier
pulling of changes in the original repositories. The named branches are:

  MOGRE: mymogre
  OGRE: mogre-patched
  Dependencies: default (since there is no official repository for them)
  
To clone the MOGRE repository, use:

 $ hg clone -u mymogre http://bitbucket.org/manski/mymogre
  

Necessary Software
------------------
You need to have the following pieces of software installed on your computer
to build MOGRE:

 * Microsoft Visual Studio 2008 or 2010 (Express Edition should do; you need Visual C++)
     http://www.microsoft.com/express/Windows/
     
 * .NET framework 2.0 or higher (should usually be installed together with
   Visual Studio)
     
 * CMake for generating the project files for OGRE (tested with CMake 2.8.2)
     http://www.cmake.org/
     
 * A mercurial client for cloning the repository (TortoiseHg will work nicely)
     http://mercurial.selenic.com/
     http://tortoisehg.bitbucket.org/
     
 * The DirectX SDK (tested with DirectX SDK June 2010)
     http://msdn.microsoft.com/en-us/directx/
     
  
Building MOGRE
--------------
The following instructions can be used to build this MOGRE repository. Note that
most auto-generated code is already included in the repository. For more 
information about the auto-generaed code and its regeneration, see below.

This instructions assume that you've already cloned the MOGRE repository. If 
not, run the command from the previous section to do so. The directory in which
you've clone the repository will be represented by "$REPOS" in the instructions.

 * Building the dependencies:
   * Open the solution file apropriate for your Visual Studio version (e.g.
     "OgreDependencies.VS2010.sln" for Visual Studio 2010) from:
      $REPOS\Main\OgreSrc\ogre\Dependencies\src\
        
   * Build both the DEBUG and the RELEASE versions! (Both version are needed for
     CMake.)
   
 * Create OGRE's project files:
   * Open the cmake-gui (a link should have been created in your start menu when
     you installed CMake)
     
   * Under "Where is the source code" select this folder:
     $REPOS\Main\OgreSrc\ogre
   
   * Under "Where to build the binaries" select this folder (may not yet exist)
     $REPOS\Main\OgreSrc\build
     
   * Click "Configure". If you run configure for the first time, you need to 
     select your IDE (e.g. Visual Studio 2010). Leave all options (except for
     the IDE selection) like they are, unless you know what you're doing.
   
   * Change the following build properties (you need to switch to "Advanced" mode):
     * OGRE_CONFIG_ENABLE_PVRTC = on
     * OGRE_CONFIG_CONTAINERS_USE_CUSTOM_ALLOCATOR = off
     * OGRE_BUILD_SAMPLES = off  (optional; speeds up the build process by excluding example projects)
     
   * Click "Configure" again
   
   * Click "Generate" to generate the project files; they will be placed in the
     "binaries" directory specified above.
  
 * Build OGRE:
   * Open the solution file for OGRE:
     $REPOS\Main\OgreSrc\build\Ogre.sln
     
   * Add the following files to the project "OgreMain". (You can do this by
     expanding the project "OgreMain", right clicking on "Source Files"/
     "Header Files" and choosing "Add" -> "Existing item...")
     * Source Files:
        $REPOS\Main\Ogre\CLRHandle.cpp
        $REPOS\Main\Ogre\CLRObject.cpp
     * Header Files (optional; just for easier editing):
        $REPOS\Main\Ogre\CLRConfig.h
        $REPOS\Main\Ogre\CLRHandle.h
        $REPOS\Main\Ogre\CLRObject.h
        $REPOS\Main\include\auto\CLRObjects.inc
     
   * Unfortunately MOGRE and OGRE depend on each other (dependency cycle). So, 
     if this is the first time you build MOGRE (i.e. if the file
     $REPOS\Main\lib\Debug,Release\mogre.lib doesn't exist), you need to break
     this cycle once.
     * To do so open the file "CLRConfig.h" in the "OgreMain" project and change
       "LINK_TO_MOGRE" to "0":
     
         #define LINK_TO_MOGRE 0
     
       This avoids a linker error. We will revert this change in a later step.
       If you already have a "mogre.lib" file, you should skip this step.
     
   * Build the whole solution. You can build both DEBUG and RELEASE 
     version or just the one you want to use together with MOGRE (e.g. OGRE 
     Debug with MOGRE Debug).
   
 * Build MOGRE:
   * Open the solution file for MOGRE (according to your Visual Studio version)
     located in this folder:
     $REPOS\Main  (e.g. Mogre_vx2010.sln)
     
   * Build MOGRE.
   
 * If you've set "LINK_TO_MOGRE" to "0" in the steps above, change it again to
   "1" and then build the OGRE solution again (just a regular build, no rebuild
   necessary).


The build results can be found here:
 * For Debug: "$REPOS\Main\lib\Debug" and "$REPOS\Main\OgreSrc\build\lib\Debug"
 * For Release: "$REPOS\Main\lib\Release" and "$REPOS\Main\OgreSrc\build\lib\Release".

  
Manually generate sources
-------------------------
Most of MOGRE's source code is auto-generated. This repository already contains
all auto-generated sources. However, if you need to re-auto-generate the sources
for some reason (for example when a new version of OGRE is released; see next
section), here is how this works.

IMPORTANT: Make sure that fixes that were applied to the sources are applied
  again (or at least not overwritten). Check the changelog of the repository
  for applied patches.

Prerequisite: You need to compile the "AutoWrap" project found here:
  "$REPOS\Codegen\AutoWrap". Also you need to have a Java runtime (JRE) 
  installed on your system to be able to run "cpp2java".

Execute the following steps to generate MOGRE's sources from OGRE's sources:

 * First the OGRE sources may need to be patched (depending on the grade of 
   change) to prepare them for use together with the .NET runtime (CLR). The
   patch to do this can be found here:
   $REPOS\Main\Ogre Patches
   
   The "easiest" way to patch the sources is to install "patch" via Cygwin 
   (found under "Utils/Patch" in the installer). Then execute in a command 
   prompt:
   $ cd $REPOS\Main\OgreSrc\ogre
   $ c:\cygwin\bin\patch.exe --no-backup-if-mismatch -p0 <"..\..\..\Ogre Patches\mogre.patch"

 * Execute "build.bat" (preferably in a command prompt) inside the folder:
   $REPOS\Codegen\cpp2java
   
 * Run "AutoWrap" from $REPOS\Codegen\AutoWrap and click on "Produce".
 
The auto-generated files are placed here:
  
  * Headers: $REPOS\Main\include\auto
  * Sources: $REPOS\Main\src\auto

  
Updating
--------
This section is for maintenance only and describes how to update the OGRE and
the MOGRE sources. For ease-of-use reasons the steps will use TortoiseHg (but
should be easily adaptable to any other Mercurial client).

Updating MOGRE and OGRE requires the same steps but on different repositories
and branches. (The paths of the custom repositories "myOgre" and "myMogre" are
described at the top of this file.)

 1. Pull newest changes from the original repository into custom repository.
    For this use the "Synchronize" dialog. Make sure you've added to original
    repository to the repository settings (as non-default).
    
    Original Repositories:
    * OGRE: http://bitbucket.org/sinbad/ogre
    * MOGRE: http://bitbucket.org/mogre/mogre    
    
 2. Merge changes into custom branch. Use the "Repository Explorer" for this.
 
    "original branch"/"custom branch":
    * OGRE: "v1-7"/"mogre-patched"
    * MOGRE: "Mogre17"/"mymogre"
    
    a. Make sure to have checked out the revision you want to merge with 
       (usually the tip of the "custom branch")
    b. Select the "original branch" (like "v1-7" for OGRE) from the 
       "Branches..." dropdown field.
    c. Check which changes can be safely merged into the working copy.
    d. Right-click the latest, safe revision and choose "Merge with...". Then
       click "Merge". This will merge the changes into the working copy.
    e. Resolve any conflicts and commit the changes to the "custom branch".
       IMPORTANT: Make sure you commit to the right branch (selectable in the 
         "Commit" window).

 3. Changes to the source may make it necessary to regenerate the MOGRE's 
    sources. See above how to do this.
    IMPORTANT: Regenerating may overwrite certain code changes in the 
      auto-generated source. Make sure to add these changes again after 
      re-generating the sources.
  
 4. Push the changes back to bitbucket (using the "Synchronization" dialog).
  

For "myOgreDependencies" see "[Repos]/Main/OgreSrc/ogre/Dependencies/build.txt"


This is what cmake printed out for me as project configuration summary
======================================================================

----------------------------------------------------------------------------
  FEATURE SUMMARY
----------------------------------------------------------------------------

Building components:
  + Paging
  + Terrain
  + RTShader System
  + RTShader System Core Shaders
  + RTShader System Extensions Shaders
Building plugins:
  + BSP scene manager
  + Cg program manager
  + Octree scene manager
  + Portal connected zone scene manager
  + Particle FX
Building rendersystems:
  + Direct3D 9
  + OpenGL
Building executables:
  + Samples
  + Tools
Building core features:
  + DDS image codec
  + PVRTC image codec
  + FreeImage codec
  + ZIP archives

Build type:                      dynamic
Threading support:               none
Use double precision:            disabled
Allocator type:                  nedmalloc (pooling)
STL containers use allocator:    disabled
Strings use allocator:           disabled
Memory tracker (debug):          disabled
Memory tracker (release):        disabled
Use new script compilers:        enabled
Use Boost:                       disabled