original_docs:building_homeworld
Wednesday, October 24, 2001
Luke Moloney
\
Homeworld was build using a command-line make utility (Watcom Make). This utility is provided in tools/bin. Most engineers used 4nt (www.jpsoft.com) as a command-line shell as it very flexible if you actually have to do any work from the command-line. However, you can still use cmd.exe. Once the program is built using the command-line build utility, you will want to open Homeworld.exe in the debugger (MSDev) to debug it. All these steps are described in more detail following.
Homeworld uses a single directory which can be anywhere on your local system. As some tools use batch files and Perl scripts, I suggest that the path have no spaces in the name. I don’t know if that will cause problems, however. For the sake of the following examples, let’s assume our tree is in d:\Homeworld. The CD(s) provided are in a format they such that they can be copied into d:\Homeworld.
A note about environment variables: if you are unused to building from a command-line, you should note that environment variables are local to a particular command shell and often to an application. So, if you change your environment variables using your control panel, you will have to restart your command shell for these settings to take effect.
\
Conversely, if you change your environment variables within a command shell (using set HW_Level=HW_Debug), the change will not be permanent and will not affect other command shells. While this can be confusing, it can also be quite useful.
\
It’s a good idea to restart your debugger (MSDev) whenever you are changing environment variables.
\
The following environment variables are used:
Name
Required
Typical value(s)
Notes
HW_Root
yes
D:\Homeworld
Root of directory structure mentioned above
HW_Data
yes
D:\Homeworld\Data
Where the game finds the data, and where the tools operate on data
HW_Level
yes
HW_Debug
HW_Interim
HW_Release
Control optimization and error checking in compile.
HW_PDB
no
HW_YESPDB
HW_NOPDB
Control location of debug info: in .exe(default) or in .pdb(for vtune)
USERNAME
yes
lmoloney
Created by the OS, is passed in to the preprocessor to control compilation of user-specific code.
HW_Demo
no
Downloadable
OEM
CGW
Passed to preprocessor to control compilation of the 3 various demo versions we made. Perhaps you could build one of these to make the download smaller.
\
You will also have to have the following paths in you existing environment variables:
Variable
Path
Notes
PATH
%HW_Root%\Tools\Bin
All sorts of tools required for building binaries.
PATH
%HW_Root%\Tools\Batch
Batch files and Perl scripts
Include
[path to intel header files]
Interim and release builds use intel compiler.
Include
[path to VC5 header files]
All versions use VC5. Do not use VC6.
Lib
[path to intel .lib files]
Interim and release builds use intel compiler.
Lib
[Path to VC5 .lib files]
All versions use VC5. Do not use VC6.
Because we are using a command-line, you should be able to have VC 5 and VC 6 co-exist on your machine. In fact, you should be able to copy the bin, include and lib directories from an existing installation. This is what I have on my machine right now.
\
All of this command-line stuff may be confusing. To simplify it, there is a batch file in Tools/Bin called SetVC5.bat. You can change the first few lines to match your directories and it will take care of the rest. I’ve copied it here for reference:
\
rem root paths
\
set HW_VC5=d:\vc5
set HW_Intel=d:\IntelCompiler
set HW_Root=d:\homeworld
\
rem set Homeworld variables
set HW_Data=%HW_Root%\data
set HW_Level=HW_Debug
\
rem set compilers into paths
\
set path=%HW_Intel%\bin;%HW_VC5%\bin;%HW_VC5%\sharedide\bin;%HW_Root%\tools\batch;%HW_Root%\tools\bin;%path%
set lib=%HW_Intel%\lib;%HW_VC5%\lib;%lib%
set include=%HW_Intel%\include;%HW_VC5%\include;%include%
\
The following build types are available. Select these build types by changing the HW_Level environment variable:
Build type
Compiler used
Debug info
Debug checking
Enviroment variable
Debug
MS
Yes
Full
HW_Debug
Interim
Intel/MS
Yes
None
HW_Interim
Release
Intel/MS
No
None
HW_Release
\
As you can see, the HW_Interim build is basically a HW_Release build with debug info. This makes debugging release-build specific bugs easier.
In your command prompt:
-
cd d:\Homeworld\src\win32
-
Create 3 empty files named Debug.depend, Interim.depend and Release.depend.
-
type wmake depend
-
wmake
\
When the compile is complete, there will be a. EXE and several .DLL files in d:\Homeworld\exe. This is where the game should be run. Any debugging log files will be put here and will not pollute the Data directory. The data files file will be loaded from HW_Data.
\
Note that the debug exe is almost 12 MB. This is because of all the debugging information. The release build will be much smaller.
There are 3 relevant batch files in Tools/Batch:
-
GetSound.bat
-
BigGet.bat
-
GetMovies.bat
\
These files copy the pertinent data files from “the network” to your data directory. I say “the network” here because while we were developing Homeworld, we used z:\Homeworld as “the network” where we stored all files that are too big for SourceSafe. In these batch files, I’ve changed it to H:\. You can map a network drive to H:\ or change this path in the batch files.
\
Both of these files are dependent upon the setting of HW_Level. Thus, you could try building one of the demo versions of Homeworld.
\
The Sound files are a few small .lut and .bnk files and two large files:
-
HW_Music.wxd – All Homeworld music in custom compressed format.
-
HW_Comp.vce – All Homeworld speech in custom compressed format.
\
These files can reside on the CD or on the local hard-drive, depending on how Homeworld is installed on the end-user’s machine.
\
BigGet.bat gets a .big file that is a collection of all the files in the data directory packed into a single file to make file access quicker and to keep the data directory clean. The files in this .big file are arranged in the order that they are most likely to be loaded, thus cutting down on file seeks.
\
GetMovies.bat gets the movies needed for the full release of the game into the data directory.
If you are adding any new code, you will want to run Homeworld in the debugger. Also, you will probably want to run Homeworld with some of its diagnostic command-line options. So, you should create a shortcut that will run your debugger (you can debug with either VC5 or 6) and load Homeworld.exe with the appropriate command-line options. For a list of valid command-line options, run Homeworld with the -? Command-line option or look in main.c for a list of valid command-line options.
The previous told you how to build and run a debug build. To build a release or interim build, set HW_Level=HW_Release or HW_Interim, respectively. After changing the HW_Level variable, type wmake depend and wmake.
\
You can also build several different demo versions of Homeworld: OEM, CGW and Downloadable. These versions have much smaller movie, data and sound requirements so would probably be better for internet deployment. They differ from the full version in varying ways. None of them support internet play (which your version wouldn’t because of the authentication), not all of them support LAN play and all have less missions, sound, music and movies.
The game uses Wise Install Builder to create the install program. Due to lots of publisher-specific requirements, the install programs are fairly complex. As you won’t be using these programs (and I don’t care to dig up the rather convoluted instructions), I will not describe them here.
\
However, I will describe how Homeworld is meant to be distributed. Basically, you should “clean out” your exe directory and copy it into the data directory. You should delete any debugging files that are dumped into the .exe directory. This is any file that is NOT one of the following:
-
*.exe
-
*.dll
-
*.dat
The remaining files are copied into the root of the HW_Data directory. Thus, the data directory is the root of the finally installed product.
In the data directory, most files are duplicated in the .big file. If there is a version of a file in the .big file and on your hard drive, the version on your hard drive will be built instead. This way you can modify any data files on your hard drive without having to constantly build the .big file. For release, you would want to delete any files that are in the .big file. You can find what files these are by looking at the install programs: any file that is explicitly installed is not in the .big file.