The EMX Frequently Asked Questions list, file 1 revision 1.


******************* Questions this file tries to address ********************

1) What the heck is "EMX"?
2) Why would I want the EMX package?
3) Where do I get the EMX package?
4) How do I install the EMX package?
5) How do I compile 32 bit OS/2 programs with the EMX package?
6) How do I compile programs to use unix emulation?


************************  What the heck is "EMX"? ***************************

EMX is a unix emulator for dos and OS/2.  The name EMX stands for "EMulate
uniX".  You take unix source code, compile it with any compiler and link
it with the EMX libraries, and it'll run under the unix emulator.

The EMX unix emulator is available for unix as a DLL, and available for
dos as a dos extending .EXE.

******************** Why would I want the EMX package? ***********************

Because it's got a free, reliable, compatible, efficient C++ compiler.

--- What you get with the EMX development package:

The EMX package contains a fully functional port of the GNU C/C++
compiler, capable of producing two different kinds of .exe files.

This compiler (GCC) can produce 32 bit OS/2 native mode executables
comprable to those produced by most commercial compilers currently
available for the OS/2 platform.  It can produce both text mode and
presentation manager apps, multi-threaded apps, and .DLL Dynamic Link
Libraries.

The EMX port of GCC is also capable of compiling unix apps to use the
unix emulator EMX. Since unix has been around for twenty years, and since
unix was designed in such a way that almost all unix programs must come
with source code to be of any use, there is a heck of a lot of unix code
out there which can be easily ported to run under OS/2 (or DOS) with this
unix emulator.

The compiler comes with documentation in several formats, including
ascii text (.doc files) and "view" books (.inf files) containing enough
information for an average C/C++ programmer with little or no OS/2
experience to write multi-threaded OS/2 presentation manager applications.

The main disadvantage of this compiler is that it does not come with an
Integrated Development Environment (IDE) yet.  You have to do everything
from the command line, or get a "make" utility and use "make" files.  The
shareware editor "boxer" is recommended as a substitute for an IDE.
Although users are encouraged to register boxer, which is fairly expensive,
some people prefer it to professional Integrated Development Environments
(IDEs).  Perhaps an IDE for GCC will become available in the future.

--- The advantages of GCC under EMX:

1) It produces small, efficient 32 bit OS/2 executables.
2) It can also compile unix programs to use the unix emulator EMX, which
   can run under both dos and OS/2.
3) The whole package only takes up around 10 megs of hard drive space.
4) The compiler works comfortably in 8 megs of ram, with room left over.
5) It can compile all three types of 32 bit OS/2 programs (full screen,
   text window, PM window).
6) It's highly debugged, and has regular updates and patches.
7) It's compatible with almost all existing standards, including
   ANSI, POSIX, and dos programming conventions.
8) It's absolutely free.  No strings attatched unless you try to sell it
   (the EMX package) for profit.  The .exe files you compile with it can
   be sold for profit, just like any other compiler.

--- The disadvantages of GCC under EMX:

1) It's command line only (no IDE).
2) It only makes 32 bit apps (I.E. you can't make drivers, which are 16
   bit apps.)
3) The documentation, while thorough, is poorly organized.  The docs also
   don't explain the difference between compiling for native OS/2 and
   compiling for the unix emulator very clearly.
4) The dos version of the EMX unix emulator (EMX.EXE) uses the VCPI method
   of extending dos, which will not run under either OS/2 or microsoft's
   windows.  This means you can't run the compiler (gcc.exe) in a dos window
   under OS/2, you must run it in an OS/2 window, where it will use emx.dll.


******************** How do I get the EMX package? *********************

--- Where:

EMX is available via anonymous ftp from any "hobbes" archive site in the
unix/emx09a directory.  Two of the largest are ftp.cdrom.com (directory
/pub/os2) and hobbes.nmsu.edu (directory /os2).  Under each of those,
the EMX package is in the directory unix/emx09a.  The name of this
directory changes with each major version number, so it may be different
by the time you read this.

--- Don't panic:

If you look in the emx09a directory, you will see zillions of files.
Rest assured that you don't need most of them, at least not to start out
with.  At least half of the files in there are the source code to things
you can download pre-compiled.  The source code to almost everything
(emx, gcc, the libraries, the utilities, etc.) is available here.  Most
professional programmers wouldn't need this stuff, although it is nice to
have it available.  Some of the extra files in this directory may be useful
later, especially the optional libraries (curses, BSD, graphics,
"objective c", etc).

--- How it's distributed:

All of the files ending in the extension .zip are compressed archive
files, which must be uncompressed before you can use them.  The utility
that created them is called "zip", and the one that can undo them is
called "unzip".  A version of unzip is available on the hobbes archive
site, in the subdirectory "archiver", filename "unz512x2.exe".  If the
version number has changed, look for something similar starting with "unz".

Run unz512x2.exe in an empty directory.  This is a specially constructed
archive that will unzip itself when you run it. It will split itself apart
into several files (including documentation, some utilities, and the
executable itself).  Copy the file unzip.exe into your path somewhere,
it's a nice thing to keep around.

To use it, type "unzip filename.zip".  Putting ".zip" on the filename is
optional, if you don't have it, it'll figure it out.

// If you would like a copy of zip to create your own zip files with (they
// really do save space), get the file "zip201x2.exe" (or whatever the
// version number's up to by then).  It's also in the archiver directory of
// each hobbes ftp site, and it should create the file zip.exe when you run
// it.  To create a zip archive file, go "zip filename.zip file1 file2..."
// and so on.  Yes, it'll take wildcards.  Read the docs that came with
// zip and unzip for more info.

--- What you need:

You need to get the following four files to compile C and C++ programs with
the EMX package.

    1)  The EMX Runtime Environment                 Filename: emxrt.zip

This is the unix emulator, needed to run the compiler.

The "EMX Runtime Environment" is the unix emulator itself.  For dos,
this is EMX.EXE.  For OS/2, this is emx.dll.  Most programs compiled to
use unix emulation don't actually link the emulator into the program's
.exe file, because it takes up a lot of room.  Instead, they call an
external emulator when they're run, the way edit.com under dos 6 calls
qbasic.exe.  This is why the same file can run under both dos and OS/2,
it's the emulator doing the running, and that's what's specific to the
platform.

Since GCC is a unix program which has been compiled to use the external
unix emulator (emx.exe under dos, emx.dll under OS/2), you need to have
the emulator available on the system to run gcc.exe, even if you only
intend to create 32 bit OS/2 native programs with it, which do not require
unix emulation.

    2)  The EMX Development package                 Filename: emxdev.zip

You need this to compile EMX programs.

These are the libraries and header files that you link with to compile
programs that are going to use the EMX unix emulator.  There are also
some libraries here to compile 32 bit OS/2 programs (most notably
sys.lib), and a REXX file (omflibs.cmd) to convert most of the rest of
the unix "*.a" libraries to 32 bit OS/2 "*.lib" format.  Don't worry
about that now, just get it.

    3)  The GNU development package                 Filename: gnudev.zip

This contains the GNU C compiler itself.

This is a copy of the GNU C Compiler (GCC), ported to run under the EMX
unix emulator.  GCC is one of the most popular ANSI C compilers for
unix.  By default it creates unix style executables (for the intel 386 CPU
(or higher) platform), which will be run by the EMX unix emulator, versions
of which are available for both DOS and OS/2.  In addition, this version
of GCC has been modified and supplemented to create 32 bit OS/2 native mode
executables, including full screen text mode, windowed text mode, and
presentation manager applications.  These do not need EMX to run, they
are pure OS/2 executables.  The command line options to do this are
-Zomf -Zsys.  See the "how do I compile" section for details.

    4)  The C++ preprocessor and libraries          Filename: gppdev.zip

This turns the C compiler into a C++ compiler.

Without this, GCC will only compile ANSI C.  This contains the
libraries, header files, and compiler add-on executable to compile C++
source code.  If you're only compiling ANSI C programs, and no C++, you
can save some hard drive space space by not installing this, but I'd
recommend getting it anyway.

--- Additional interesting files (optional):

The file "00index.txt" lists all the files available in each directory
of the hobbes archive, with a one line description for each file.  The
monolithic one is in the root directory of the hobbes archive (for
ftp.cdrom.com this is /pub/os2), and a smaller one is in each
subdirectory.  The copy of 00index.txt in the emx09a directory explains
(briefly) what all the other EMX related files are.

You'll probably want to look at "bsddev.zip", which contains some extra
libraries and functions, including the curses package and the random()
function, to name a couple.  All of the extra library packages include
the header files for those libraries.

Another compiler add-on similar to the C++ extensions is something
called "Objective C".  This allows gcc to compile Objective C programs.
If you don't know what it is, don't worry about it, but it's available.

Some of the files with "view" in their name might come in handy too.
They're extra documentation in OS/2's ".inf" online book format.  This
documentation is also avilable in "texinfo" format (the files with "doc"
in their name), which can be viewed if you get "gnuinfo.zip" and install
it.

Down near the bottom there's a graphics package for doing full screen
SVGA graphics, but you're on your own figuring out how to use it.  The
mandatory file "emxdev.zip" includes its own MCGA graphics package
(320x200x256 colors full screen,) so you can do some low resolution
graphics without this SVGA package.

--- Updates:

If EMX has been updated since you got your copy, there will be a file
in the emx directory on hobbes called "emxfix??.zip" where the ?? is a
two digit patch level number (at the time of this writing, 03).  If you
get this and unzip it in the root directory of the drive that has EMX,
and allow it to overwrite the existing files, it will update your copy of
the EMX package.  These patches are mostly minor bug fixes; when any major
changes are made the version number of EMX will change, in which case you
should probably just get a whole new copy.  Expect patches every few
months, with complete new versions perhaps once a year.  If you're happy
with your copy of EMX, of course, you can just stick with it.

You don't need to worry about an emxfix??.zip file in the directory when
you get a complete copy of EMX.  The files in the FTP site will already
have been updated to include the patches.  If you miss a patch number,
just install the newest patch: it will automatically include all older
patches since the last change major revision where the version number
changed.


******************* How do I install the EMX package? *********************

You unzip it, then meddle with config.sys a bit, reboot, then run omflibs.

--- Unzipping everything:

Once you have the ".zip" files and a copy of unzip.exe, pick a drive you
want to put it on.  Go to the root directory of that drive and type:

"unzip c:\path\*.zip" where c:\path is whatever drive and directory the .zip
files are on currently on.  If you're short of space, you don't have to
have the .zip files on the drive where you're installing EMX.

This unzipping will create the directory "emx" from the root directory,
and also a lot of subdirectories under it, where it will put all the
various files.  Some files are duplicated in each archive (such as the
GNU general public license in the file "COPYING" that basically gives
you the legal right to use GNU programs as long as you don't try to sell
them for profit.)  During the course of this unzipping, it will ask you
if you want to overwrite these duplicate files.  Since they're
identical, it really doesn't matter if you answer N or Y, a fast way to
do it is to type capital A for all, which tells it to always overwrite
and stop pestering you about it.

The useful directories under "\emx" are:

"bin"     All the .exe files go here, including gcc.exe.  You'll want this
          in your path.

"dll"     The dynamic link libraries are here.  You'll want this in your
          dll path.  This directory contains emx.dll for unix emulation,
          several additional .dll files for gcc, and dll versions of the C
          runtime library (optional, but keep it anyway.  You may want it
          later).

"doc"     The plain text documentation files.  The three most interesting
          files are (in order of interest) LIBREF.DOC, GNUDEV.DOC, and
          EMXDEV.DOC.

"include" All the header files.  You need this to compile anything.

"lib"     All the library files.  You need this to link anything.

"book"    Duplicates of some of the files in "doc", in OS/2's ".inf"
          online book format.  Not exactly vital, but nice to have.

Most other directories you find in there can probably be deleted,
unless they're from an additional file you unzipped like bsddev.zip
or emxdoc.zip.  I'd recommend unzipping the first three "vital" files,
investigating and cleaning up everything you don't need, and only then
unzipping additional optional files.  Otherwise it's too easy to get
lost in a sea of unfamiliar files.

--- Meddling with config.sys:

The emx package wants to be in the path, and it also likes to have a
couple of environment variables set.  This means you have to mess with
config.sys and then reboot so the changes will take effect.  Yes, it is
a pain, but you only have to do it once.

First, we need to add c:\emx\bin to the PATH statmement, and c:\emx\dll
to the LIBPATH statement.  These two lines already exist, we're just
appending a bit onto the end of each one.  Something like this...

    SET PATH=blah;blah;blah;blah;c:\emx\dll;
    SET LIBPATH=blah;blah;blah;blah;c:\emx\lib;

Next, add the following new lines to the end of your config.sys file
(modifying it for whatever drive you installed emx on, of course):

     set C_INCLUDE_PATH=c:/emx/include
     set C_PLUS_INCLUDE_PATH=c:/emx/include/cpp;c:/emx/include
     set LIBRARY_PATH=c:/emx/lib
     set PROTODIR=c:/emx/include/cpp/gen

NOTICE!!!!!  Those are foreward slashes.  GCC is running under the unix
emulator, remember?  Unix uses foreward slashes "/" instead of back
slashes "\" to seperate directories.

// If you want to use "objective C" (It's a variant of C that's neither C
// nor C++, if you don't know what it is, you probably don't need it),
// you'll need to add one more line to the end config.sys:
//
//     set OBJC_INCLUDE_PATH=c:/emx/include
//
// And you'd probably want to get gobjcdev.zip, too.

--- Rebooting:

Select "shutdown" from the launch pad, or click with the right mouse
button on the background of the presentation manager and select
"shutdown now" from the little pop-up menu.  You'll have to confirm it a
couple of times.  Once a message comes up telling you that OS/2 has
written all its buffers to disk and is ready to shutdown now, you can
either press the "reset" button on your computer or give it the standard
three-finger salute (ctrl-alt-delete).  When OS/2 finishes rebooting,
the EMX package should have all the paths it needs set up just fine,
assuming there were no typos in config.sys.

--- Converting the libraries:

Finally, you'll want to go into the lib directory under the emx
directory and run a file called omflibs, which is a REXX file that will
convert all your unix style .a libraries into OS/2 style .lib libraries.
This is the last step.  EMX and the GNU C/C++ compiler should now be
installed and working.



*****  How do I compile 32 bit OS/2 programs with the EMX package? *****

To make 32 bit OS/2 native programs, you do this:

gcc -Zsys -Zomf -s -o filename.exe *.cpp

--- What that means:

The default activity for GCC is to compile programs to use the unix
emulator "EMX".  To compile 32 bit OS/2 programs that use OS/2 system
calls instead of the EMX unix emulator, you must add the command line
switch -Zomf to the compiling phase, and -Zomf -Zsys to the linking
phase. The above line combines the two activities into one command line.
Yes, upper and lower case matters.

"-Zomf" tells the compiler to use .obj style object modules and .lib
style libraries.  By default it uses the unix .o object modules and .a
libraries, which can only be linked into a unix executable, needing EMX
to run.

"-Zsys" tells the compiler to link with the OS/2 system call library
"sys.lib" instead of the EMX unix emulation library "emx.a".  Since the
system call library is only available in .lib format, you must use the
-Zomf option to make -Zsys work.

"-s" tells the compiler not to include the symbol table (it's debugging
information you really don't need) into the .exe file.  This makes the
.exe smaller, and doesn't affect the way it runs at all.

"-o" tells it you're about to name the .exe file.  Be sure to include
the extension .exe on the filename, which must be the next thing on the
command line right after the -o switch.  If you don't do this, it'll
name the .exe file after the first source code file on the command line.

The rest of the command lists all of the source files to create the
program out of, in this case all files in the current directory ending
with the extension ".cpp".  Files with the extensions .cpp, .cxx, .cc,
or .C (capital C) will be compiled as C++.  Files with the extension .c
(lower case) will be compiled as origional C.  Files with the extension
.def will be used as module definition files, and files with the extension
.res will be used as resource files.  Both of those are explained later.

Also, if you want to link with any extra libraries, you use the "-lname"
parameter, where "name" is the name of the library (which must be in the
/emx/lib directory when you compile.)  To link in the curses library, use
the command line option "-lcurses".  Remember that upper/lower case matters.

--- If you've just moved up from DOS:

If your structures don't save to disk the way they did under dos, try
putting the line "#pragma pack(1)" into the source code, before your
structure definitions.  GCC defaults to aligning things on 4 byte
boundaries for faster access, which can screw up binary structures that
expect data items of fixed size with no gaps in them.  The #pragma tells
it to stop that.

Temember that an "int" in OS/2 defaults to "long" (4 bytes), while an int
under dos defaulted to "short" (2 bytes).  It's a good idea to always say
"short" or "long" when you declare any int in a structure you're going to
write to disk.

Direct screen writes don't work the same way under OS/2, use the "curses"
library (in "bsddev.zip") instead.  It's for advanced cursor control.


*********** How do I compile programs to use unix emulation? *************

This is the default.  Just go "gcc -o filename.exe *.cc"

--- What unix emulation does:

EMX can emulate many aspects of the unix operating system, including the
way unix handles files, pipes, child processes, signals, and even core
dump files.  Even complex apps like internet MUDs, or the GNU C compiler
can be (and have been) compiled and run under EMX with little or no
modification.  Currently X-windows is not supported by EMX, but only
because nobody's ported it yet.

--- How you use unix emulation:
                   
Compiling for unix emulation is the default for the version of GCC that
comes with the EMX package.  If you don't include the -Zsys switch on the
command line when you link the program, it will be linked to use the EMX
unix emulator.

By default, the compiler will generate unix style .o object files and link
with unix style .a library files.  This is not particularly efficient under
EMX, because the emulator has to do a lot more work and the .exe file is a
great deal bigger.  However, this provides the highest level of unix
compatability, and the files created can be run under dos with the dos
program "EMX.EXE".

--- How to optimize it for OS/2:

If you include the switch -Zomf, the compiler will generate OS/2 style .obj
object files and link with OS/2 style .lib library files.  This creates a
smaller, faster executable, which still uses unix emulation to run.  However,
this does sacrifice a small degree of unix compatability. For example,
executables created with -Zomf cannot create core dump files.

Files created with -Zomf will only run under OS/2.  They will not run
under dos.


****************************** Now What ? ********************************

At this point, a book on programming for OS/2 would probably come in handy.

--- Read the docs:

There are several good documentation files in the "doc" directory under
the "emx" directory.

Read the file "libref.doc" through from beginning to end.  Print it out
if you can, although you're going to have trouble stapling it as it's
about 200 pages.  It lists and describes every single function,
variable, and structure in the default libraries for the EMX compiler.
There are hundreds of functions available to you, if you don't know what
they are you can't use them.

Skim the files "gccdev.doc" and "emxdev.doc".  They explain additional
things that GCC and EMX can do, including generating .DLL's,
multi-threaded apps, and dynamically linking the C runtime library so it
creates a very small .exe and calls a .DLL at runtime instead of the
library code it didn't link in.

--- Whatever:

This is the end of EMXFAQ1.TXT.  If I get time, I may write an EMXFAQ2.txt
explaining make files, .DEF files, .RES files, simple Presentation Manager
programming, making multi-threaded apps with EMX, using .DLL's, making your
own .DLL's, the -Zcrtdll option, and why #pragma pack(1) is a good idea.

This FAQ was written by Rob Landley (landley@clam.rutgers.edu, although
I just graduated so that address is going away, and fidonet 1:266/30
although I'm moving soon, so THAT address is going away).  I got bored
one day and decided to write up what I knew about EMX after a rather
frustrating learning process where I had to figure most of this out on
my own.

Like all written works, this FAQ is copyright the author (me), may 1995.
Permission to reproduce and transmit this thing in unmodified form is
hereby granted.  But if you even want to correct my spelling mistakes, you
have to get my permission.

                                                   Rob Landley