1:The Vulcan Build System
   2:=======================
   3:
   4:Contents
   5:--------
   6:
   7:o Overview
   8:o Getting Help
   9:o Preparing the build environment
  10:o Building Vulcan
  11:o Useful Options
  12:o Architecture of the build system
  13:o Updating the MBC
  14:o Platform Specific issues
  15:o Known Problems
  16:
  17:
  18:Overview
  19:--------
  20:Builds are driven from builds/$platform/masterbuildscript. The name of this
  21:master build script will differ from platform to platform. Functionally,
  22:however, each script behaves similarly. This document will use the
  23:really_make_all.bat from windows as an example.
  24:
  25:
  26:Getting Help
  27:------------
  28:
  29:Something like:
  30:
  31:  really_make_all.bat HELP
  32:
  33:will generate a help screen outlining your options.
  34:
  35:
  36:Preparing the build environment
  37:-------------------------------
  38:
  39:Each master build script checks your build environment and reports any problems
  40:found. If a required component is missing you will soon find out.
  41:
  42:
  43:Building Vulcan
  44:---------------
  45:
  46:Running the master script without options will do a fully automated build.
  47:An option will be added later to automate creating the install kits after the
  48:build completes.
  49:
  50:
  51:Useful Options
  52:--------------
  53:
  54:CLEAN      - will clear out debris from a previous build.
  55:
  56:DEBUG      - will create a debug build. This option is intended for engine
  57:             developers. You don't need this if all you want to do is step
  58:             through the source code while running the server in the debugger.
  59:
  60:PREPAREGUI - (Win) will prepare the build environment and open the vulcan
  61:             solution in Visual Studio.
  62:
  63:PREPCLIENT - (Win) will prepare a secondary gui build environment. It is
  64:             intended for testing and debugging problems from the client side
  65:             while simultaneously working with a server running in the
  66:             environment created by PREPAREGUI.
  67:
  68:
  69:Architecture of the build system
  70:--------------------------------
  71:
  72:(The vulcan build system is yet another attempt to resolve the age old conundrum
  73:- how do we keep windows and posix builds in sync. In this case windows (and in
  74:particular Visual Studio) have been chosen as the driver of this process. Time
  75:will tell whether this approach is successful.)
  76:
  77:Build configurations are stored in builds/MasterBuildConfig (MBC). These files
  78:are intended to be platform and build environment neutral. They are in XML
  79:format. They are not intended to be used to build Vulcan directly.
  80:
  81:Each platform has a master build script which configures its build environment.
  82:Part of this process includes building and running a utility called VSRelo. This
  83:generates the correct xml files for the specific build environment. In practice
  84:it just copies the vcproj files and alters the relative paths. For example this:
  85:
  86:  ..\..\..\install\bin
  87:
  88:will become this:
  89:
  90:  ..\..\..\..\install\bin
  91:
  92:when VSRelo copies a project file for building with MSVC7. This is because
  93:'builds\win32\MSVC7' is one level deeper than 'builds\MasterBuildConfig'.
  94:
  95:Platforms that use the gnu toolchain require another step after running VSRElo.
  96:A separate tool 'buildgen' must be built and executed. This tool generates
  97:makefiles from vcproj files.
  98:
  99:
 100:Updating the MBC
 101:----------------
 102:
 103:Changes to the MBC files need to be made by an appropriate XML editor that
 104:understands the config file format. The only known editor is in fact the MS
 105:Visual Studio IDE for VS2003. No tests have yet been made with VS2005, but it
 106:is anticipated that is will work.
 107:
 108:DO NOT UPDATE THE MBC DIRECTLY unless you know what you are doing. Generate the
 109:a windows build environment and edit and test that. Then use
 110:
 111:  build_vsrelo.bat MAPBACK
 112:
 113:to write your changes back to the MBC.
 114:
 115:Before committing these changes it would be wise to verify them via a cvs diff.
 116:Unfortunately VSRelo removes the carriage returns and linefeeds. These need to
 117:be put back by opening the solution in the MBC and saving each project. This
 118:process can be speeded up with the macro in SaveProjects.vb.
 119:
 120:Platform Specific issues
 121:========================
 122:
 123:Windows
 124:-------
 125:o There are currently two solution file templates available in the
 126:  MBC\Vulcan directory. They are automatically copied into the build dir
 127:  and renamed.
 128:
 129:  o Vulcan.sln
 130:    This contains all the projects required to build the engine.
 131:    It makes sense to build the contents as a solution.
 132:
 133:  o Devtools.sln
 134:    This is just a ragbag collection of everything else.
 135:    It doesn't make much sense to build these projects as a solution.
 136:
 137:o Windows builds rely on tools from the GnuWin32 project. You are
 138:  recommended to download the whole toolchain, but if time or diskspace
 139:  is at a premium you should be able to get away with downloading the
 140:  following:
 141:    - coreutils
 142:    - bison
 143:    - sed
 144:
 145:o cygwin is unsupported and untested. If you have cygwin installed and it
 146:  appears earlier on your path than 'native' win32 tools then the results
 147:  may be unexpected.
 148:
 149:
 150:
 151:Posix
 152:-----
 153:
 154:(To be written)
 155:
 156:
 157:Mac OSX
 158:-------
 159:
 160:(To be written)
 161:
 162:
 163:Known Problems
 164:==============
 165:
 166:Windows
 167:-------
 168:
 169:o devenv not found.
 170:
 171:  Well, we will assume you have installed Visual Studio. You probably need to
 172:  run a batch file named like this (for VS7):
 173:
 174:    "%VS71COMNTOOLS%vsvars32.bat"
 175:
 176:  This will set up your environment correctly for the particular version of VS
 177:  that you wish to run.
 178:
 179:  Note - MS tend to be a bit loose in the name of this file. VS6 called it
 180:  vcvars32.bat and the VS7 version refers to itself with the file as
 181:  vcvars32.bat.
 182:
 183:o Visual Studio Express installed
 184:  This free compiler from Microsoft does have a few limitations. One of
 185:  them is that it doesn't include a devenv executable. Currently you will
 186:  need to open the VSRelo.vcproj in MBC and build it manually before
 187:  then running 'really_make_all.bat PREPAREGUI'
 188:
 189:  The build process will be updated in due course to detect VSExpress.
 190:
 191:o Visual Studio 2005 (aka VS8) installed
 192:  No tests have been made with this environment yet. It _should_ work.
 193:
 194:o Windows.h not found
 195:
 196:  This probably means that the %INCLUDE% environment variable doesn't contain
 197:  a path like this:
 198:    C:\Program Files\Microsoft Visual Studio .NET 2003\VC7\PlatformSDK\include;
 199:  You need to search for Windows.h on your system and update your environment
 200:  accordingly.
 201:
 202:o sed fails to process jrd.vcproj correctly (and jrd.vcproj has 0 bytes as a
 203:  consequence of this.)
 204:
 205:  Upgrade your Gnu toolchain from sourceforge. See:
 206:
 207:    http://gnuwin32.sourceforge.net/packages.html
 208:
 209:
 210:Posix
 211:-----
 212:
 213:The new build process is partially broken - building libfbdbc fails
 214:(as of 22-Mar-2006).
 215:
 216:
 217:Mac OSX
 218:-------
 219:
 220:Build process has not been updated to use the MBC.
 221:
 222:
 223: