$Id$

This COMPILE file describes how to compile the various LMPC binaries for
Unix, MS-DOS, Win32 (Cygwin and Mingw32) on any Unix system.

This is a high-level file. If you are Joe Windows User, don't even try to
read it. It would be a complete waste of your time.



1. Unix binaries

LMPC comes with an Autoconf configure script. This makes it very easy to
compile it on various systems. Read the INSTALL text file for more general
information on Autoconf configure scripts. The simple way is
	./configure ; make ; make install
as usual.



2. MS-DOS binaries

The MS-DOS binaries can be cross-compiled with a GO32 compatible gcc.

doc/COMPILE-go32 is a shell script which can be used to compile such a 
cross-compiler under Linux. You'll have to change some things but it should 
be fairly easy to use.

The MS-DOS binaries may be cross-compiled as usual:
	CC=/path/to/cross-gcc \
	CXX=/path/to/cross-g++ \
	RANLIB=/path/to/cross-ranlib \
	./configure --host=i386-pc-msdosdjgpp && make
but the main Makefile provides the target go32 to simplify this task.
I use it for the MS-DOS Binary Package. You may have to adapt some paths
in Makefile.in (or better Makefile.am if you have Automake) and re-configure.

The executables created with the cross-compiler need the special runtime
program bin/cwsdpmi.exe (it is also available from the Quake CD).



3. Win32 (Cygwin) binaries

The Win32 (Cygwin) binaries can be cross-compiled on any Unix system
using `the Cygwin toolset' (formerly known as GNU-Win32/Cygwin32) from Cygnus.

doc/COMPILE-cygwin is a shell script which can be used to compile such a 
cross-compiler under Linux. You'll have to change some things but it should 
be fairly easy to use.

The Win32 (Cygwin) binaries may be cross-compiled as usual:
	CC=/path/to/cross-gcc \
	CXX=/path/to/cross-g++ \ 
	RANLIB=/path/to/cross-ranlib \
	./configure --host=i386-pc-cygwin && make
but the main Makefile provides the target cygwin to simplify this task.
I use it for the Win32 (Cygwin) Binary Package. You may have to adapt 
some paths in Makefile.in (or better Makefile.am if you have Automake) and 
re-configure.

The executables created with the cross-compiler need the additional DLL
cygwin1.dll in their c:\windows\system directory to run.
Copy cygwin1.dll from /usr/cygnus/bin/ to this place. You may have to
strip the just (with -g) compiled DLL.



4. Win32 (Mingw32) binaries

The Win32 (Mingw32) binaries can be cross-compiled on any Unix system
with the same compiler, which was used for the Cygwin binaries.

The only difference is to use the additional flag -mno-cygwin in the compile
run (to get a different set of include files) and in the link run (to leave
out the cygwin1.dll).

The Win32 (Mingw32) binaries may be cross-compiled as usual:
	CC=/path/to/cross-gcc \
	CXX=/path/to/cross-g++ \
	RANLIB=/path/to/cross-ranlib \
	CFLAGS=-mno-cygwin \
	LDFLAGS=-mno-cygwin \
	./configure --host=i386-pc-mingw32 && make
but the main Makefile provides the target mingw32 to simplify this task.
I use it for the Win32 (Mingw32) Binary Package. You may have to adapt 
some paths in Makefile.in (or better in Makefile.am if you have Automake) and 
re-configure.



5. Why 2 different Win32 packages?

My programs are (from a programmers point of view) so simple, they don't
need the full power of the Cygwin library. With Mingw32 I can compile a native
Win32 program, which doesn't need any extra files.

There are some drawbacks coming with Mingw32 because the Microsoft
C-Library crtdll.dll is far from being ANSI-compliant (let alone any kind of
POSIX compliance). Standard functions like strsep or memmem are missing but in
general the GNU C library source code and a good Autoconf system helps a lot
in such cases.

Users report a bit slower execution of lmpcm.exe in comparison to lmpc32.exe.



6. Program tests

My computers are all "Linux only". This makes it a bit difficult to check the
cross-compiled programs.

I test the Linux versions with a simple script, which does all possible
conversions and compares the first and last binary file. They must be
identical. I have a bunch of demo files for this but I do need always new
and strange ones.

I test the MS-DOS versions in the DOS emulator (DOSemu) of Linux shortly.

I test the Win32 (Mingw32) versions in the Windows emulator (Wine) of Linux
shortly.

I test the Win32 (Cygwin) versions in the Windows emulator (Wine) of Linux
shortly.



7. Additional compilation hints

You need lex(1) and yacc(1) to compile the package. I compile it with flex
version 2.5.33 and GNU Bison version 2.3 because they were included in my
openSUSE Linux 10.2. They should compile just fine with other versions too.
I don't provide precompiled C-files for the scanner and parser because
standard (non-GNU) C compilers have difficulties with the bison created C
source.

The full package is written for Automake 1.9.6 and Autoconf 2.60 compliance.
The cross-compile rules were added very rude but anyway, it works as it is.



8. Compiling speed

The whole process of configuring and compiling Linux, MS-DOS and Win32
(Cygwin and Mingw32) binaries of LMPC, DEMcut and DBS, the creation of the
documentation for the distribution packages (html, pdf) and the packaging
itself takes on my Athlon 2600+ about 90 seconds (make pack).



9. C++ issues

I recently decided to use a C++ compiler to find some more warnings in my
programs. Now I only need to solve some problems with my several
cross-compilers. Until these things are cleared up, I'll continue to compile
and distribute all my packages with plain C.

Who wants to use the new C++ variant first, can do this with the Perl script 
bin/cprep, which makes the usual changes (file extension change from .c to
.cc, changes in configure.ac, configure, src/Makefile.am, src/Makefile.in
and src/Makefile. bin/cprep can reverse these changes to .c as well.



10. Compiler warnings

I am a fussy programmer. If even a stupid compiler can find some syntax
warnings in my programs, then I surely made some even worse semantic mistakes
as well. My (unreachable) goal is to eliminate all warnings coming from all
possible compilers. Please send me more compiler warnings from several
platforms.



Uwe Girlich
