Hexen II: Hammer of Thyrion (uHexen2) - v1.5.9

Instructions for Compiling:
===========================

To compile the your own binaries, you need a unix build environment.
The makefiles also present several build options, please read them.
Makefiles rely on some scripts residing in the scripts directory. You
may be able to modify them to meet your needs, if necessary, but the
defaults should work just fine.

By editing the makefiles, you can change some compile time options.
Other than the makefiles, we have gathered most, if not all, of our
compile time options in the header file named "h2config.h".  You can
edit it with care too, if necessary.

Here is the recommended software for building:


Tools needed:
========================================

Make	:	The GNU make utility.
		Versions 3.79.1 and newer are recommended.  The minimum
		version required is 3.78.

binutils:	A GNU collection of binary utilities.
		Tested with versions 2.11.9x and newer. Recent versions
		are recommended.

NASM	:	Netwide Assembler. An x86 assembler.
		Minimum version required is 0.98.38 or 0.98.39 from the
		old series. Versions 2.09.10 or 2.13.02 from the new 2.x
		series are recommended.

		YASM, a re-write of NASM, is also supported:  yasm-0.5.0
		and newer can compile our asm.  Versions 1.1.0, 1.2.0 or
		1.3.0 are recommended.

		The assemblers nasm or yasm are required for compiling
		hexen2 and hexenworld clients for 32 bit x86 machines.
		The makefiles present an option to not use x86 assembly,
		in that case nasm or yasm will not be necessary.

GCC	:	GNU C Compiler.

		Minimum version required is GCC 2.95.  GCC versions in
		the 2.95/2.96, 3.x and 4.x series up to 7.x are tested
		and work fine.

		As for archaic gcc versions:  gcc-2.91.66 (egcs-1.1.2),
		gcc-2.7.2, and gcc-2.8.1 still do work.
		NOTE THOUGH:  The gcc-2.xx series may need tweaking the
		CFLAGS: -fomit-frame-pointer, in particular, can result
		in a broken build, especially in combination with some
		other switches such as -ffast-math.

		Avoid buggy versions: for example, gcc-4.1.0/4.1.1 has a
		nasty bug which is fixed in gcc-4.1.2 and later:
		http://gcc.gnu.org/bugzilla/show_bug.cgi?id=26719
		Although those buggy versions seem to compile our source
		correctly, avoiding them would be safer.

CLANG	:	a C language family frontend for LLVM

		As an alternative to gcc, clang versions 3.0 to 4.0 are
		tested to compile all uhexen2 sources correctly.


Libraries needed for various platforms:
========================================

General Unix requirements:
--------------------------

SDL	:	Simple DirectMedia Layer libraries.
		Required for compiling hexen2 and hexenworld clients on
		most unix platforms. Minimum version required is 1.2.4.
		As of this writing, the latest version is 1.2.15, which
		is recommended.

Linux requirements	:
-------------------------

GLIBC	:	C libraries. Any glibc >= 2.1 should be fine. Not tested
		with anything older.

ALSA	:	Advanced Linux Sound Architecture libraries.
		Necessary, if you want to support ALSA sound on Linux.
		Minimum version required is 1.0.1. (v0.9.8 might work,
		but not tested.)  v1.0.7 or newer are recommended at
		runtime.
		The makefiles present an option for disabling ALSA audio
		support, in that case this library won't be necessary.

Windows requirements	:
-------------------------

MSVCRT.DLL:	Windows exe files depend on msvcrt.dll, the microsoft C
		runtime library. Any sane windows installation already
		has it unless it's a very ancient windows version, e.g.
		win95.  In case you need, here is a download link from
		the MS site:  http://support.microsoft.com/kb/259403
		or:  http://support.microsoft.com/?scid=kb;en-us;259403

Mac OS X requirements	:
-------------------------

Xcode, SDKs:	Install the free Xcode suite from developer.apple.com.

Additional requirements	:
-------------------------

libogg and either of libvorbis or libtremor:
		Required if you want Ogg/Vorbis music playback.
libmad or libmpg123:
		Required if you want MP3 music playback.
libogg, opus, and opusfile:
		Required if you want Opus music playback.
libFLAC :	Required if you want FLAC music playback.
libmikmod:	Required if you want tracker music playback.


Compiling for Windows:
========================================

a. On Linux, using MinGW cross compiler:
----------------------------------------
To compile for Win32 (x86), the mingw cross compilers can be used under
linux. We provide mingw cross compilers on our downloads page, too: see
under the support files section if you need one.
Run the  build_cross_win32.sh scripts residing in all directories in
order to compile. Read the scripts and edit them as necessary. Settings
for the build_cross_win32.sh scripts are in the  scripts/cross_defs.w32
file: edit it to meet your needs/setup, if necessary.

To compile for Win64 (X64), mingw-w64 cross compilers can be used under
linux.  We provide mingw-w64 cross compilers on our downloads page, too:
see under the support files section if you need one. To compile, use the
"build_cross_win64.sh" scripts residing in all the directories. Read the
scripts and edit them as necessary.  Settings for build_cross_win64.sh
scripts are in the  scripts/cross_defs.w64  file:  edit it to meet your
needs, if necessary.


b. On Windows, using win32-native MinGW compiler:
-------------------------------------------------
Download a prebuilt MinGW installer and install it to C:\MinGW .  Then
download MSys and install it to c:\msys
As x86 assembler, download nasm version 2.09.10, put nasm.exe into the
C:\MinGW\bin directory. Adding the mingw directory to your PATH may be
a good idea, too.  MinGW-5.1.4 comes with gcc-3.4.5 and is recommended.

Open a console window, cd into \msys and type "msys sh.exe". You will be
in a unixish sh environment.  The rest is like doing things in linux:
cd into your fake "home directory", extract uhexen2 tarball, then change
into into each subdirectory you want to build and normally use the make
commands to compile.

Note that "make" may be named "mingw32-make". In that case, you may want
to try "mingw32-make" if "make" command itself fails to run. Remember to
do a make clean between each different build.

c. On Windows, using Visual Studio 2005/2008 or 2010/2017:
----------------------------------------------------------
MS Visual Studio versions 2005 through 2017 have been tested to compile
all uhexen2 code successfully.  The VisualStudio2005.zip files contain
the *.vcproj project files and *.sln solution files: unzipping them and
double-clicking on them should start visual studio and you will be ready
to go.  The VS2005 project files import perfectly into VS2008, therefore
VS2008 owners can use the VS2005 project files.  For your convenience,
VS2010 project files are provided for hexen2 and hexenworld, which work
fine with vs2017 too.  All of the projects are adjusted for Win32 (x86)
and x64 targets.  Note that older MSVC versions such as Visual Studio 6
aren't supported: parts of our code make use of a few C99 features such
as variadic macros which require Visual Studio 2005 or newer versions.


Compiling for Mac OS X:
========================================

The Xcode project file is in source tarball: look at the hexen2/MacOSX
folder. Currently, project files are adjusted to generate hexen2 and
glhexen2 (universal) binaries for all Mac OS X versions, ppc part tuned
for older g3's for better performance for these slower cpu's.

Double click on hexen2.xcodeproj. At the Xcode main window, on the left
side look at "Targets" in the Groups & Files. Expand "Targets". You'll
see both glhexen2 and hexen2 targets and one of them selected. You can
press the hammer icon at the toolbar and start building, or you can
select "Project/Set Active Target/<glhexen2 or hexen2> to change the
build target to glhexen2 or hexen2.

For building for older Mac OS X sdk's (probably you don't need to),
double click on the little icon at the left of "Architectures" and
select only "ppc"; then double click on the "SDK Path" value and
delete "/Developer/SDKs/MacOSX10.4u.sdk" from there, build as usual.

Cross compiling for OSX on linux is also possible.  To create a cross-
toolchain, you can follow the instructions from the OpenTTD project,
here:	http://devs.openttd.org/~truebrain/compile-farm/
which basically boils down to compiling odcctools, downloading xcode
v3.1.x from the Apple website (you need an account) and extracting the
sdk from it, and compiling a gcc source capable of targeting osx, e.g.
gcc-4.0 from:	http://www.opensource.apple.com/tarballs/
To create an x86_64-capable cross-toolchain with gcc-4.2, I followed
the instructions from https://github.com/Tatsh/xchain/ as guidelines.


Compiling for DOS:
========================================

You need DJGPP. Tested compilation and functionality using djgpp v2.03
and v2.05 using gcc-3.3.6, 3.4.6 and 4.4.7.  I compile on linux using
cross toolchains: see the tiny build_cross_dos.sh script to understand
how I do it.  Settings for the build_cross_dos.sh scripts are in the
scripts/cross_defs.dj file: edit it to meet your needs/setup, if needed.
We provide djgpp cross compilers on our downloads page: see under the
support files section if you need one.

Compiling in a native DOS/DJGPP environment is possible *if* you have
long file names (LFN) support. Remember adding DOSBUILD=1 to your
environment. For example, in order to compile the dos version of hexen2
on native dos:
	set DOSBUILD=1
	make h2

Cross-compiling for DOS on Windows in a command console or under MSYS
should be possible too: remember adding DOSBUILD=1 to your environment,
like above.

Compilers other than djgpp, such as Open Watcom, won't work and need
specifically porting to.

CWSDPMI.EXE is needed at runtime: use the "0.90+ r5" or a newer version.
I've been successfully using the R5 "2008 refresh" (21 Aug.2008) as well
as the R7 (07 Jan. 2010) versions for quite some time.


Compiling for OS/2:
========================================

You need Open Watcom: The latest official release is 1.9.0 which is the
version I used myself.  Newer watcom snapshots or the unofficial V2 fork
work just as well.  You also need nasm in order to build the x86 asm
sources (yasm won't work.)  Change into the relevant directory and run:
	wmake -f Makefile.os2

The Watcom makefiles work both when using on OS/2 natively and also when
cross compiling on linux.  The source builds and runs with EMX/GCC too.


Compiling for Amiga variants:
========================================

For MorphOS, any SDK should work.

For AROS, only ABIv0 is tested: we build against AROS snapshot from
2014-07-26, i.e. the ABI_V0 branch at aros svn:
https://trac.aros.org/trac/browser/AROS/branches/ABI_V0
or https://gitorious.org/aros/aros.git

For AmigaOS 3.x (m68k-amigaos), you can use gcc or vbcc.  We tested
using the following cross-toolchains:
https://github.com/cahirwpz/amigaos-cross-toolchain.git
https://github.com/sezero/amigaos-cross-toolchain.git
- gcc:  gcc-2.95.3 and gcc-2.95.4 were tested.  Builds against libnix
  were found to be broken (stdio issues): build against clib2, instead.
- vbcc: vbcc 0.9f patch1, vasm 1.8a, and vlink 0.16a are tested.


Links:
------
SDL homepage		: http://www.libsdl.org/
Ogg/Vorbis homepage	: http://xiph.org/
Opus homepage		: http://opus-codec.org/
libmad homepage		: http://www.underbit.com/products/mad/
mpg123 homepage		: http://mpg123.org/
FLAC homepage		: http://xiph.org/flac/
			  http://sourceforge.net/projects/flac/
MikMod homepage		: http://mikmod.sourceforge.net/
ALSA homepage		: http://www.alsa-project.org/
GCC homepage		: http://gcc.gnu.org/
Binutils homepage	: http://sourceware.org/binutils/
clang homepage		: http://clang.llvm.org/
VBCC homepage		: http://sun.hasenbraten.de/vbcc/
			  http://www.compilers.de/vbcc.html
NASM homepage		: http://www.nasm.us/
YASM homepage		: http://yasm.tortall.net/
DJGPP homepage		: http://www.delorie.com/djgpp/
WATT-32 homepage	: http://www.watt-32.net/
MinGW/MSYS homepage	: http://mingw.org/
			  http://sourceforge.net/projects/mingw/
MinGW-w64 homepage	: http://mingw-w64.sourceforge.net/
			  http://sourceforge.net/projects/mingw-w64/
Open Watcom		: http://www.openwatcom.org/
			  https://efbe.musca.uberspace.de/
			  https://github.com/open-watcom/

