  *** IMPORTANT BUILD INSTRUCTIONS ***

Homeworld SDL - Source Installation Instructions 
 Version 0.5 alpha? (still?)
 Subversion repository: http://www.homeworldsdl.org
 Current Subversion revision as of this update: 391

Homeworld SDL maintainer: 
 Laurence Passmore <lmop@homeworldsdl.org> 
 
---------------------------------------------------------------------

Homeworld copyright 1999-2000 Sierra On-Line, Inc.  All Rights Reserved. 
Homeworld is a registered trademark, and Sierra and Sierra Studios
are registered trademarks of Sierra On-Line, Inc.  Relic is a
trademark of Relic Entertainment, Inc. 
 
 ---------------------------------------------------------------------

 Please read through the following instructions if you plan to build
and run Homeworld SDL: 
 
Contents:
	-Note-
	-System requirements-
	-Compiling the source code-	
	-Important Build Options-
	-Usage and placement of the game data files-
	-Starting the game-
	-Troubleshooting-
	-Kdevelop IDE-

 -Note-

 Homeworld SDL is still in development, and as such the code is somewhat of a mess right now.  Since Homeworld was not designed to be compiled and installed using the typical "configure/make/make install" process found with most open source Unix software, you'll need to keep a few things in mind while trying to get the game running. 
 
 -System requirements-

 SDL 1.2.11 
 GCC 3.3 or later.

GCC 3.x versions prior to 3.3 have problems compiling various sections of the Homeworld code and will crash upon the attempt.  GCC 2.95.x does not provide support for SSE/SSE2 instructions and will not work. 
 
GCC 4.x is now working after resolving cast and compile issues, and removing the requirement to use -fwritable strings.

There is a strong sentiment among many people to rewrite the codebase to modern standards, and even talk of aiming for a 64-bit branch as well, but it will take time. 
 
 -Compiling the source code-

You need to have at least the following packages installed:

 * SDL development files (version 1.2.11 or later) see *1
   - you may get a linkage error against X symbols on earlier ones.
     This can probably be repaired by adding -lX11 -lXext on src/Makefile.am.
 * flex (any recent version will do)
 * bison (any recent version will do)
 * autotools set: autoconf, automake (1.9), libtool
 * YACC (any recent version will do)

	* See also: -If you're compiling libsdl-

The build process itself is relatively straightforward. Running the bootstrap script found in this directory with "./bootstrap" will set up the files needed and then doing "../configure" (that's "period period slash configure") followed by "make" will build the required files and then the binary. Type "../configure --help" for more information on build options.

 ./bootstrap
 ../configure 
 make

If "make" is successful then the "homeworld' binary will be located in the "src" directory created just now within the "Linux" directory. 

If you're inclined to install the game then

 make install

should do the trick. 

 -Usage and placement of the game data files-

 Once you have successfully compiled the source you will still need the Homeworld CD and the Homeworld 1.05 version patch for some data files before you can play. The game requires these files. They have not been provided with the source code or with the SDL port as they are not freely available, You can find the patch at http://www.relicnews.com, and you can also find the patch, and other downloads as well at http://homesource.nekomimicon.net 
 
 You will need at least 
 - Homeworld.big 
 - Update.big 

Homeworld.big comes from the game CD, and the Update.big file has to be the updated version from the 1.05 patch.

Unfortunately the only way to extract Homeworld.big and accompanying data files from the Windows installer is to run it natively in Windows or use an emulator/compatibility layer like Wine. (Alternatively, if someone cares to work on it, a native installer could be created based on the public domain "HWUN" (Heuristic WISE Unpacker) program. This is known to work with HWSetup.exe but unfortunately uses VirtualPascal and its accompanying Windows libraries. There are similar programs to HWUN (e.g. e_wise (Pascal) and exwise (C)) but they don't work with HWSetup.exe as-is.)

The files from the patch are simpler to get at: just open the patch .exe in any zip file program and extract the Update.big files from it.
 
 You can place the game data files in the 'src' directory created within the Linux directory where the "homeworld' binary you just compiled is located. 
 
 Even though the main data files are present now, you will still need to have the Homeworld CD in your CD-ROM drive AND mounted. The game will check that the CD is mounted on "/mnt/cdrom", but if you use a different mount point, you will need to specify it using the "HW_CDROM" environment variable. 
 
 To avoid this you can copy the audio data files 'HW_Comp.vce' and 'HW_Music.wxd' from the Homeworld CD to the 'src' directory alongside the other data files. These archives hold the voice + subtitle files and the music data files respectively... and then you can get along without the CD in the drive. However, the audio data files will take up 155 MB of space.

 -Starting the game-

Go to the projects 'src' directory. "./homeworld". 

 For those who installed the game, instead of running it from the project directory, efforts have been made to set everything up such that "make install" will work, but you will still need to do a few things before running. Specifically, if you installed the game using 'make install' the binary will be able to find the game data in one of two ways: 
 
    -The environment variable "HW_Data" (case-sensitive, without quotes) can be set to the path where the game data is located. For example, if you put the data in /usr/local/share/homeworld, you could run the game by typing the following from the command line: 
 
    HW_Data=/usr/local/share/homeworld homeworld 
 
    - If the "HW_Data" environment variable is not set, or the path specified by it cannot be found, the game will check the current directory.  For example, if you put the game data in a directory called "hw", you would only need to change to that directory and run "homeworld" without specifying anything for "HW_Data", and the executable should be able to find the data without any problem. 
 
 NOW you should be able to start the game...but wait!  There's one last thing you need to know! 
 
 When Homeworld first starts up, it uses the software renderer. Unfortunately, the porting of the software renderer is not yet complete (filled 3D textures do not seem to render currently), so you will need to switch to the OpenGL renderer.  To do so, perform the following steps: 
 
    - Select "Options" from the main game menu. 
    - Select "Video" from the available options sub-menus listed on
      the right side of the screen. 
    - Select "(GL) Default OpenGL" from the "Rendering System" box. 
    - Choose a resolution from the "Resolution" box (any resolution
      you choose will do fine). 
    - Click on the "Accept!" button in the bottom-right corner of the screen. 
 
 The game will now attempt to switch to the OpenGL renderer.  
 If everything goes okay, you should be presented with a confirmation that the settings you requested were changed.  Select "Yes", and you should be ready to go!
 
 The settings you choose will also be saved when you quit, so you don't have to reselect the OpenGL renderer every time. 

 -Important Build Options-

 * If you find some problematic bug in HWSDL Linux, you could try reconfiguring with 
 ./configure --enable-linuxfixme && make
 This will activate all bug work arounds in place for Linux (if any) which may fix your problems.


 -Troubleshooting-

 * if you get this error while compiling HWSDL: "wgl.c:9:27: X11/Xutil.h: No such file or directory"
try installing "libx11-dev".

 ------------------------------------------------------------------------------ 
 
 *** UPGRADING FROM HOMEWORLD SDL 0.2? *** 
 
 As of Homeworld SDL 0.3, the location of saved games has moved. Saved games are now stored within the ".homeworld" directory in your home directory.  To use your old saved games, just move the "SavedGames" directory from the game directory to "~/.homeworld". Note that saved games from the Windows version of Homeworld and Homeworld SDL versions prior to 0.2 still do not work with recent versions of Homeworld SDL.  Also, the game directory no longer needs to be writable for users who want to run the game. 
 
 ------------------------------------------------------------------------------ 
 
 *** A NOTE ABOUT OPTIMIZATION *** 
 
 Various parts of the Homeworld source code do not play particularly well when compiler optimization is enabled (i.e. using the "-O" or "-O[123]" flags with GCC).  The source files containing such problem areas have been pinpointed in the game code, and steps have been made to disable optimization for these files until the code can be altered such that enabling optimization won't thrash the output.  On the other hand, there are issues with the software renderer that affect 2D drawing (such as the menus) which have not been pinpointed yet.  For the time being, the software renderer cannot be built with compiler optimizations, so optimization has been disabled for ALL of the rgl library code. 
 
 Also of note is that the "-fomit-frame-pointer" flag should not be used, as Homeworld uses various assembly techniques that rely on the frame pointer for many functions.  While the original Windows version uses "#pragma" statements to force this on a per-function basis, GCC only provides the "-fno-omit-frame-pointer" flag to force the frame pointer on a per-file basis. Because of this, most of the game will be compiled with support for the frame pointer regardless of the optimization level.  In the future, the functions that rely on the frame pointer may be separated from the rest of the code such that the game can benefit from the potential speed increase provided by the "-fomit-frame-pointer" flag. 


 ----------------------------------------------------------------------------------
  -If you're compiling libsdl-

Before compiling your libsdl, make sure you have these packages installed:
 * libxt-dev
 * mesa-common-dev, libglu1-mesa-dev, libgl1-mesa-dev

 -------------------------------------------------------------------------------------
 	-Kdevelop IDE-

A kdevelop project file is in Linux/
it uses the custom makefile that ./configure generates.

you should run the project file inside Linux/ , else, change the project directory from ../ to something else.

by default the filelist isn't populated, so kdevelop will prompt you, do allow it to populate the list.

if you don't want kdevelop compiling HWSDL just after you compiled it manually or whatever, then do this:
project options > run options > turn off 'automatically compile before execution'
so kdevelop won't want to compile each time you want to debug.

	-------------------------------------------------------------------------------------



*1: use of SDL 1.2.10 is not recommended.
- HWSDL won't exit properly and will lock your mouse.
- librgl*.so won't be found unless put in /usr/lib