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: