==============================================================================
README (emx.txt)                                                    2003-05-08
==============================================================================

Here are a couple of preliminary notes about the programs and
libraries shipped in the epocemx kit.  Most of the stuff is licensed
under the GNU General Public License (GPL, see COPYING); however,
libemx.a isn't (see COPYING.EMX), so linking with libemx.a doesn't
infect your programs with the GPL.

The best way to run the command line programs under EPOC is to run
them from sh.exe using EmxConsole.  To get started, run \emx.exe.

epocemx is available for ER5 only.

------------------------------------------------------------------------------
Important note
------------------------------------------------------------------------------

This release of emx.dll is not compatible with executables built for
earlier versions of emx.dll (up to and including epocemx-20020523, ie,
versions less than 1.0).

Incompatible executables will be terminated by panic EMX 11.
Rebuilding those executables solves that problem.

------------------------------------------------------------------------------
SIS files
------------------------------------------------------------------------------

If you don't want to develop programs on your EPOC device, the
following SIS files should be sufficient:

  emxbzip2.sis         bzip2, bzip2recover ([un]compressing files)
  emxdiff.sis          GNU diff (comparing files)
  emxfind.sis          GNU find and xargs (searching for files)
  emxgawk.sis          GNU awk (pattern scanning and text processing)
  emxgrep.sis          GNU grep (searching files)
  emxgzip.sis          GNU gzip, gunzip, zcat ([un]compressing files)
  emxless.sis          less (the opposite of more, a pager)
  emxrecode.sis        GNU recode (convert files between character sets)
  emxsed.sis           GNU sed (stream editor)
  emxshutils.sis       GNU shell utilities
  emxtar.sis           GNU tar (archiver)
  emxtextutils.sis     GNU text utilities
  emxunzip.sis         a port of unzip
  emxuser.sis          contains the following three components:
    emxdll.sis           emx.dll and emxrun.exe -- essential
    emxconsole.sis       EmxConsole -- essential for command line programs
    emxshell.sis         highly recommended for command line programs
  emxzip.sis           a port of zip

At least, emxuser.sis must be installed.

For developing programs on your EPOC device, you also have to install
these SIS files (development system):

    emxbinutils.sis     GNU binary utilities
    emxdev.sis          epocemx development tools
    emxgcc-base.sis     GCC base package (driver and preprocessor)
    emxgcc-c.sis        GCC C compiler
    emxgcc-c++.sis      GCC C++ compiler

and parts of the ER5 C++ SDK (you need header files and import
libraries from CPPER5six.zip and CPPER5seven.zip).

Note that emxrsc.exe (of emxdev.sis) requires cpp.exe (which lives in
emxgcc-base.sis).

------------------------------------------------------------------------------
Installing the SIS files
------------------------------------------------------------------------------

Select the desired SIS files from the lists above and install them.
If you don't know how to install software from SIS files, epocemx
currently isn't for you.  If epocemx is required by third-party
software, see the documentation of that software.

For performance reasons, it's recommended to install the files of
emxuser.sis on drive C:.  You can install epocemx (and the ported
programs) either on one drive or on two drives.  If you want to use
three or more drives, you have to figure out yourself what to do.

The recommended setup is to install the files of emxuser.sis on drive
C:, the development system on drive D: (if installed at all), and the
other packages either on drive C: or drive D:.  In that case, no
additional work is required.

If you install everything on drive C:, go to the root directory of
drive C:, start emx.exe, and type:

  cd /
  rm usr
  ln -s c:/emx usr

If you install everything on drive D:, no additional work is required.

If you install everything on drive E:, go to directory \emx\bin of
drive E:, start sh.exe, and type:

  cd /
  rm usr
  ln -s e:/emx usr

If you install the files of emxuser.sis on drive C:, the development
system on drive E: (if installed at all), and the other packages
either on drive C: or drive E:, go to the root directory of drive C:,
start emx.exe, and type:

  cd /
  rm usr
  ln -s e:/emx usr

Other combinations of packages and drives are left as exercise.

Background: The pathname "/usr" is used for the "\emx" directory of
the secondary installation drive (if present).  The pathname "/usr" is
hardcoded into many programs of the development system, therefore
"/usr" must point to "\emx" on the drive on which the development
system is installed.  See below for details.

------------------------------------------------------------------------------
EPOC directories and Unix directories
------------------------------------------------------------------------------

The following EPOC directories will be used:

  EPOC                    Unix              Description
  --------------------------------------------------------------------
  \                                         emx.exe
  \System\Apps\EmxConsole                   The EmxConsole application
  \System\Apps\EmxDevice                    The EmxDevice application
  \System\Apps\EmxLink                      The EmxLink application
  \System\Libs                              emx.dll, emxrun.exe, and other DLLs
  \System\Data                              emx.ini
  \emx                    /                 Unix root direcory (see below)
  \emx\bin                /bin, /usr/bin    User-visible programs and some DLLs
  \emx\doc                /doc, /usr/doc    Documentation
  \emx\epocsdk            /usr/epocsdk      Files from the ER5 C++ SDK:
  \emx\home               /home             .profile
  \emx\include            /usr/include      GNU and emx header files
  \emx\lib                /usr/lib          emx libraries
  \emx\lib\gcc-lib        /usr/lib/gcc-lib  GNU libraries/programs for GCC
  \emx\man                /man, /usr/man    Manual pages (read with `less')

The Unix root directory ("/") is mapped to EPOC directory \emx on the
drive where emx.dll is installed. Under that directory, there are
symbolic links "c", "d", "e", and "z", pointing to EPOC directories "c:\",
"d:\", "e:\", and "z:\", respectively.  Example: Assuming that emx.dll is
installed on drive C:, "/d/system" is mapped to "c:\emx\d\system",
which in turn is mapped to "d:\system".

"/usr" (alias "\emx\usr" on the drive on which emx.dll is installed)
is a symbolic link to the "second" installation drive.  If everything
is installed on one drive, "/usr" is equivalent to "/".

The Unix directory "//" is mapped to the root directory of the current
working directory's EPOC drive.  In `sh', you'll note that "cd //"
will change the current working directory to, say, "/C:/", which
denotes the root directory of drive C:, as absolute Unix pathname.

EPOC paths can also be used, either with "/" or "\" as separator (note
that "\" must be escaped in the shell):

  cd c:/documents
  cd 'c:\documents'

There are symbolic links

  /c -> c:\
  /d -> d:\
  /e -> e:\
  /z -> z:\

therefore you can also do this:

  cd /c/documents

Devices:

  /dev/console          same as /dev/tty
  /dev/null
  /dev/raw/c            raw access to disk C: (and so on)
  /dev/tty              same as /dev/console
  /dev/zero

------------------------------------------------------------------------------
GCC: arm-epoc-pe-gcc / gcc.exe
------------------------------------------------------------------------------

Under Unix, the cross compiler is called "arm-epoc-pe-gcc", under
EPOC, the compiler is called "gcc".

You can build directly EPOC executables, without having to invoke ld,
dlltool, or emximage yourself:

        arm-epoc-pe-gcc -o hello.exe hello.c

Use -shared to create a DLL:

        arm-epoc-pe-gcc -shared -o sample.dll sample.cc

GCC does this by calling eld instead of ld; eld calls the appropriate
tools.  See the eld documentation for details.

It is unknown whether this port of GCC works with (those incredible)
Makefiles generated by makmake of the ER5 C++ SDK.

This port of GCC is based on the 20010205 snapshot, the last one which
supported the old C++ ABI required by the EPOC API.

New and changed GCC switches:

  -heap MAX

	Set the maximum heap size (reserved size) to MAX bytes.  The
	number can be given as hexadecimal number by prepending "0x".
	You can give the number in KB by appending "K", in MB by
	appending "M".  The default value of MAX is 1M.  Example:
	-heap 8M

  -heap-min MIN

	Set the minimum heap size (committed size) to MIN bytes.  The
	number can be given as hexadecimal number by prepending "0x".
	You can give the number in KB by appending "K", in MB by
	appending "M".  The default value of MIN is 4K.

  -shared

	Build an EPOC DLL file (.DLL or .APP or whatever).

  -stack MAX

	Set the maximum stack size to MAX bytes.  The stack size can
	be given as hexadecimal number by prepending "0x".  You can
	give the stack size in KB by appending "K", in MB by appending
	"M".  The default stack size is 64K.  Example: -stack 128K

  -uid1 UID1  -uid2 UID2  -uid3 UID3

	Set the UIDs of the executable file.  The UIDs can be given as
	hexadecimal numbers by prepending "0x".  The default for UID1
	is 0x10000079 with -shared, 0x1000007a without -shared.  With
	-shared, the default for UID2 is 0x1000006c if the output file
	name ends with ".app", 0x1000008d if the output file name ends
	with ".dll", 0x00000000 otherwise.  Usually, only -uid3 is
        required.

	If you need the -u (linker) switch to fake a reference to a
	symbol, insert a space between -u and the symbol name.

  -Zdef DEFNAME

	Write a .def file named DEFNAME.  Can be used with -shared
	only.  Example: -Zdef sample.def

  -Zexportdata LISTNAME

        Export data from a DLL; LISTNAME is the name of a file
        containing the symbols to be exported, one symbol per line.
        Only variables in .data and .bss can be exported, const
        variables in .rdata cannot be exported.  This switch can only
        be used with -Zimplib; moreover, the address of the data
        section must be set with -Tdata.

  -Zimplib LIBNAME

	Write an import library named LIBNAME.  This switch can be
	used only with -shared.  Example: -Zimplib mylib.lib

  -Zmap MAPNAME

	Write a map file named MAPNAME.  Example: -Zmap sample.map

  -Znoemx

        Use the startup code of the ER5 C++ SDK, don't link with
        libemx.a

Two additional file name suffixes are treated specially by GCC (and
eld):

  .def

	Module definition file containing an EXPORTS statement
	defining the symbols to be exported and the ordinals to be
	used (unless overriden by a .frz file)

  .frz

	Module definition file (freeze file) containing an EXPORTS
	statement defining the ordinals to be used for exporting the
	symbols listed in the EXPORTS statement.  The DLL may export
	additional symbols, which will be assigned ordinals not used
	by the freeze file.  The ordinals defined in a freeze file
	override the ordinals defined in any .def file.

  Any number of .def or .frz files can be used, but all the
  definitions in .def must not conflict with each other, and the
  definitions in .frz files must not conflict with each other.
  Conflicts between definitions in .def files and .frz files are
  resolved in favor of the definitions in .frz files.

  If at least one .def file is used, only the symbols listed in the
  EXPORTS statements of the .def and .frz files will be exported.  If
  no .def file is used, eld runs dlltool to find all the symbols to be
  exported (marked with EXPORT_C in the source code).

  If .frz files are used, the ordinals defined in those files will be
  used.  Any (new) symbols found by dlltool which are not defined in
  .frz files will be assigned ordinals which are not used by the .frz
  files and warnings will be issued to tell you that there are new
  symbols and you should create a new freeze file when releasing the
  DLL.

  Use a .frz file if you want to maintain binary compatibility with a
  previous release of a DLL (as EPOC imports by ordinal, the ordinals
  must stay unchanged).  Use the .def file of the previous version of
  the DLL as .frz file of the new DLL.  That .def file can be
  generated with the -Zdef switch of GCC or with dlltool.

  Use a .def file if you want to control exports and ordinals
  completely yourself, that is, if not all symbols marked EXPORT_C
  should be exported.  But note that .frz files may override your .def
  files.

  Use neither a .frz nor a .def file during development of a DLL or
  for the first release of a DLL.

To link against a library ABC, use the switch -lABC.  Example: -leikon

You don't need -lestlib and -leuser as ESTLIB isn't needed and -leuser
is provided by default unless the -nostdlib option is used.  In fact,
you must never use -lestlib as that would break emx.dll (unless you
also use -Znoemx).

To save memory under EPOC, you should create the directory /usr/tmp
and let the TMPDIR environment variable point to that directory:

  mkdir /usr/tmp
  export TMPDIR=/usr/tmp

Note that this will increase the power consumption and reduce the
lifetime of the CF card.

------------------------------------------------------------------------------
Building AIF files: emxaif / emxaif.exe
------------------------------------------------------------------------------

emxaif builds an AIF file from an RSC or RSS file and a MBM file
(icons).  To build an AIF file, call emxaif like this:

  emxaif [-s] [-v] [-P] [-D SYMBOL[=VALUE]]... [-o FILENAME.aif]
         FILENAME.rsc [FILENAME.mbm]

FILENAME.rsc is the resource file specifying the UID and other
features of the application.  If the filename ends with ".rss", emxaif
will automatically run emxrsc to compile that resource file and will
then use the compiled file.  FILENAME.mbm must be specified if at
least one icon is to be used.

These switches are available:

  -o FILENAME.aif    Write the AIF file FILENAME.aif; that file will be
                     used on the EPOC device.  If the -o switch is not
                     used, emxaif will derive the name of the AIF file
                     from the name of the source file FILENAME.rsc by
                     replacing the suffix with ".aif".

  -s                 Force emxaif to run emxrsc even if the suffix of
                     FILENAME is not ".rss".

  -v                 Verbose mode; list the contents of the RSC file
                     and the MBM file.  The contents of the RSC file
                     will be listed in a format suitable as input of
                     emxrsc.

  -D SYMBOL=[VALUE]  This switch is passed down to emxrsc.  emxrsc
                     will pass it down to the C preprocessor.

  -P                 This switch is passed down to emxrsc.  With -P,
                     emxrsc won't run the C preprocessor.

emxaif can also be used to list the contents of an AIF or MBM file:

  emxaif [p] -d FILENAME [-o OUTPUT]

These switches are available:

  -p                 Dump pixels (only compression schemes 0 and 1
                     are supported)

  -d FILENAME        Dump (list) the AIF or MBM file FILENAME.

  -o OUTPUT          Write to the file OUTPUT instead of stdout

There's not yet available a tool comparable to bmconv; you have to
create the MBM file on your EPOC device or use bmconv on a Windows
machine.

------------------------------------------------------------------------------
Dumping executables: emxdump / emxdump.exe
------------------------------------------------------------------------------

Dumps and checks an EPOC executable file.  Usage:

  emxdump [SWITCHES] INPUTFILE [OUTPUTFILE]

INPUTFILE is the executable file to disect; output goes to OUTPUTFILE.
If no OUTPUTFILE is specified, emxdump will write to stdout (quite
unusable under EPOC).

These switches are available:

  -8        Assume that characters having codes 0x20 through 0xff are
            printable.  Without -8, characters having codes 0x20
            through 0x7e are considered to be printable.  In the hex
            dumps, a dot is displayed instead of a non-printable
            character

  -d        Disassemble the text section.  The disassembler is far
            from complete, using it may violate licenses anyway

  -i        Use the import list files $ROOT/epocsdk/lib/epoc.imp and
            $ROOT/lib/emx.imp, which list all symbols of the ER5 C++
            SDK import libraries and libemx.a, respectively.  Using
            import list files enables emxdump to print the names of
            exported and imported symbols in the dump of the import
            table and in the disassembly listing

  -I FILE   Read an import list file from FILE.  You can specifiy
            multiple files by using multiple -I switches

An import list file is a text file which looks like this:

  DLL FOO[00000000].DLL
  1 E32Dll__F10TDllReason
  2 whatever

A line starting with "DLL" defines the DLL to which the succeeding
lines apply, up to the next DLL line.  A line starting with a number
lists the ordinal and the name of an import from that DLL.  There can
be any number of DLL lines in one file.

emxdump keeps track of all the bytes read from the input file and
checks whether each byte has been read exactly once.

------------------------------------------------------------------------------
Creating EPOC executables: emximage / emximage.exe
------------------------------------------------------------------------------

emximage (like the SDK's petran) transforms COFF/PE executable files
into EPOC executable files.  It also can dump COFF/PE executable
files.  This program is called by eld, which in turn is called by GCC,
so you usually don't have to call emximage directly.

There are three ways to call emximage: Transforming a COFF/PE
executable file into an EPOC executable file:

  emximage [switches] INPUTFILE OUTPUTFILE

Modifying (applying switch values) to an existing EPOC executable
file:

  emximage [switches] FILE

Dumping a COFF/PE executable file:

  emximage -d INPUTFILE

The following switches are available:

  -d                    Dump file contents
  -D                    Enable output for debugging emximage
  -v                    Verbose
  -xpetran              Output will be closer to XPeTran's
  -call[entrypoint]     Call DLL entry point E32Dll (default)
  -nocall[entrypoint]   Don't call DLL entry point E32Dll
  -moving               Create relocatable EXE file (default)
  -fixed                Create non-relocatable EXE file
  -flags FLAGS          Set flags
  -acs                  Use alternative code checksum
  -allowdlldata         Don't reject DLLs with data
  -exportdata LIST LIB  Export data symbols, appending to LIB
  -Tdata ADDR           Set data base address
  -stack SIZE           Set stack size
  -heap MIN MAX         Set heap size
  -priority PRIO        Set process priority
  -uid1 UID1            Set UID1
  -uid2 UID2            Set UID2
  -uid3 UID3            Set UID3

If all three UIDs are zero (which is the default setting) when
creating an EPOC executable, UID1 will be set to 0x1000007a (EXE).

The -acs switch causes the code checksum to be replaced with its
complement to work around a problem in EPOC.  The -acs can be used
only for programs which use the emx startup code, emxexe.o, as the
checksum is also changed in the emx header (which is defined in
emxexe.o), resulting in a checksum which is still correct.  See
spawn*() for details.

If -Tdata is used with ADDR between 0x30000000 and 0x3ff00000,
emximage won't check for DLLs with data.

The -exportdata switch is used for exporting data from DLLs with data
(that is, -Tdata must be used). LIST is the name of a file containing
the symbols to be exported, one symbol per line; empty lines and lines
starting with ";" are ignored.  Only variables in .data and .bss can
be exported, const variables in .rdata cannot be exported.  Modules
defining absolute symbols are appended to the library file LIB (which
is created if it does not yet exist); ranlib must be applied to LIB
afterwards.

DLLs with data should be avoided if possible; they use undocumented
features of EPOC and, if misused, need too much memory.

------------------------------------------------------------------------------
Find a symbol for a location: emxmap
------------------------------------------------------------------------------

{TODO}

------------------------------------------------------------------------------
Managing resource files: emxrsc / emxrsc.exe
------------------------------------------------------------------------------

emxrsc is a resource compiler similar to the SDK's rcomp; some
features as well as lots of bugs of rcomp are missing in emxrsc.  Note
that emxrsc rejects invalid input with an error message instead of
accepting errors silently and creating a bad binary resource file, as
rcomp does.  Floating point literals (for DOUBLE) are supported only
if the host uses IEC 754 floating point arithmetic.

To compile a resource file, call emxrsc this way:

  emxrsc [-P] [-D SYMBOL[=VALUE]]... -s FILENAME.rss
         [-o FILENAME.rsc] [-h FILENAME.rsg] 

(Note that rcomp does not allow a space between a switch and its
argument and does not allow -o and -h to be omitted.)  These switches
are available:

  -h FILENAME.rsg    Write the header file FILENAME.rsg defining names
                     for the resource IDs.  emxrsc won't rewrite the file
                     if a file with equivalent contents already exists;
                     this avoids unnecessary rebuilds of components
                     depending on the header file

  -o FILENAME.rsc    Write the binary resource file FILENAME.rsc; that
                     file will be used on the EPOC device

  -s FILENAME.rss    Read the resource source file FILENAME.rss

  -D SYMBOL=[VALUE]  This switch is passed down to the C preprocessor

  -P                 Do NOT feed the source file through the C preprocessor
                     (for rcomp compatibility)

emxrsc can also be used to list the contents of a binary resource
file:

  emxrsc [-a|-r] -d FILENAME.rsc [-o OUTPUT]

These switches are available:

  -a                 Format the output such that it can be used as resource
                     source file; attempt to interpret data as EIKON
                     resources.  Using this switch may violate
                     licenses

  -d FILENAME.rsc    Dump (list) the binary resource file FILENAME.rsc

  -o OUTPUT          Write to the file OUTPUT instead of stdout

  -r                 Format the output such that it can be used as resource
                     source file; data is not interpreted.  Using this
                     switch may violate licenses

(Use emxaif for dumping the contents of a binary resource file used
for generating an AIF file.)

------------------------------------------------------------------------------
Linker wrapper: eld / eld.exe
------------------------------------------------------------------------------

This is the linker wrapper which calls ld, dlltool, and emximage.  All
command line arguments which are not switches (or their arguments) are
input files.  The following switches are available:

  -acs               Use alternative code checksum
  -allowdlldata      Don't reject DLLs with data
  -e SYMBOL          Override entry point
  -g                 Ignored
  -heap MAX          Maximum heap size
  -heap-min MIN      Minimum heap size
  -l LIB             Search library LIB
  -L DIR             Search directory DIR for libraries
  -o OUT             Set filename of executable to OUT (default: a.out)
  -s                 Strip symbols
  -save-temps        Do not delete intermediate files
  -shared            Build a DLL
  -stack STK         Set stack size
  -u SYMBOL          Fake a reference to SYMBOL
  -uid# UID          Set UID# (# is one of 1, 2, 3)
  -v                 Be verbose
  -Tdata ADDR        Set data base address
  -Zdef DEF          Write .def file DEF
  -Zexec DIR         Search directory DIR for executables
  -Zexportdata LIST  Export data from DLL, symbols listed in LIST
  -Zimplib LIB       Create the import library LIB
  -Zlist             List PECOFF executable
  -Zmap MAP          Write map file MAP
  --help             Dispay help message

The -Zexportdata switch requires the -Zimplib switch.

------------------------------------------------------------------------------
Managing SIS files: emxsis / emxsis.exe
------------------------------------------------------------------------------

emxsis creates and dumps SIS files.  Extracting files is not yet
completely implemented.

*** For creating a SIS file, call emxsis this way (like makesis):

  emxsis [-v] [-D SYMBOL=VALUE]... INPUTFILE.pkg [OUTPUTFILE.sis]

If OUTPUTFILE.sis is omitted, emxsis will derive the name of the
output file from the input file by replacing an existing suffix with
".sis" or by adding ".sis" if there's no suffix.

The name of the input file can also be "-", in which case emxsis will
read from standard input; the name of the output file must be
specified.

If a source file is not found and the EPOCROOT environment variable is
set, emxsis tries again with the value of EPOCROOT (plus a slash, if
required) prepended to the pathname of the source file.

In some areas, emxsis is more fussy than makesis about the syntax of
the .pkg file; in other areas, emxsis is less strict than makesis.

*** To create a new .pkg file which differs from the original one only
be the minor version number having been incremented by one, call
emxsis this way:

  emxsis -i [-v] [-D SYMBOL=VALUE]... INPUTFILE.pkg OUTPUTFILE.pkg

The name of the output filename must be specified; it's not possible
to modify the .pkg file in place, so the two filenames must refer to
different files (however, emxsis does not check for this situation).

*** To dump (list) the contents of SIS files, call emxsis this way:

  emxsis -d [-8] [-c] [-f] [-l] [-p] [-q] [-v] INPUTFILE.sis...

These switches are available:

  -8    Assume that characters having codes 0x20 through 0xff are
        printable.  Without -8, characters having codes 0x20 through
        0x7e are considered to be printable

  -c    Check whether all bytes of the SIS file have been read (this is
        used for verifying emxsis)

  -d    Dump a SIS file (without -d, emxsis will create a SIS file)

  -f    For installed SIS files (in \system\install), check if the files
        exist and have the correct size. Example:

            emxsis -dfq c:/system/install/*.sis

  -l    For installed SIS files (in \system\install), list the installed
        files

  -p    Use the .pkg file format for the output file

  -q    Display less information

  -v    Display more information

  -D SYMBOL=VALUE

        Define the identifier SYMBOL to have the value VALUE, which
        must be an unsigned 32-bit number (hexadecimal numbers
        prefixed by "0x", octal numbers prefixed by "0").  The symbol
        SYMBOL can be used everywhere in the .pkg file where a number
        is expected.

See the ER5 C++ SDK documentation on details about the format of .pkg
files.

*** To extract a file from a SIS file, call emxsis this way:

  emxsis -X INPUTFILE.sis FILENAME OUTPUTFILE

FILENAME is the name of the file in the SIS file INPUTFILE.sis; it
should match exactly one file (either its source file name or its
destination file name).  The pathname must match exactly.  If found,
the file will be written OUTPUTFILE (which will be overwritten if it
already exists).

*** To move all installed SIS files of one drive to the drive where
they belong (where their files are supposed to be installed according
to the SIS files), call emxsis this way:

  emxsis -m [-v] SOURCE_DRIVE: [TARGET_DRIVE:]

This switch is available:

  -v    Display more information

The directory SOURCE_DRIVE:\system\install will be scanned for SIS
files whose files are supposed to be installed on TARGET_DRIVE (if
present) or on a drive different from SOURCE_DRIVE (if TARGET_DRIVE:
is not present).  For any such SIS file, you'll be asked whether the
file should be moved to the drive where it belongs.  If you answer
"y", the file will be moved to the directory \system\install on the
drive where its files are supposed to be installed.  Example:

  emxsis -m c: d:

This is useful if you have multiple CF cards; installed SIS files for
applications installed on a CF card should be on that CF card to avoid
confusion.  emxsis does not check whether the files (of a SIS file)
are really installed on the target drive.

------------------------------------------------------------------------------
Creating symbolic links: emxlink
------------------------------------------------------------------------------

This program is used to create "epocemx symbolic link files" under Unix
for inclusion in SIS files.  To create a symbolic link under EPOC, use
the "ln -s" command of sh.exe.

  emxlink OLD NEW

The file NEW will be created, containing a symbolic link to OLD.

------------------------------------------------------------------------------
Creating device files: emxmknod, mknod.exe
------------------------------------------------------------------------------

"emxmknod" is used to create "epocemx device files" under Unix for
inclusion in SIS files:

  emxmknod PATH TYPE MAJOR MINOR

"mknod.exe" is used under EPOC to create "epocemx device files"
{currently, there's no mknod() system call}:

  mknod PATH TYPE MAJOR MINOR

PATH is the name of the file; TYPE is either b (for a block device) or
c (for a character device), MAJOR and MINOR are the major and minor
device number, respectively.

------------------------------------------------------------------------------
Debugging panics: emxpanic.exe
------------------------------------------------------------------------------

This is a very experimental program; it just sits there and waits for
any thread to panic; as soon as a thread panics, information about
that thread is displayed. See also _emx_trap().  {TODO}

------------------------------------------------------------------------------
Building programs: make.exe
------------------------------------------------------------------------------

{TODO} A simple make tool for EPOC.  Chaining of implicit rules is not
implemented and emake is somewhat more fussy than other make tools.
For now, see tools/emake.cc.

------------------------------------------------------------------------------
Command line shell: sh.exe / sh-acs.exe
------------------------------------------------------------------------------

A simple Unix-like shell for EPOC.  Lots of features are missing.  An
Emacs-like command line editor with history (not saved in a file)
provided by emx.dll.  Here are some short notes {TODO}:

This is a Unix-like shell, so use "/" instead of "\" in pathnames, or
use quoting or escaping.  See EmxConsole below for the keybindings of
the line editor.

Command line switches (see below for examples):

  -a                  Export all variables
  -c CMDS [ARG...]    Execute commands CMDS
  -i                  Force interactive shell
  --cd DIR            Change to directory DIR
  --login             Force login shell
  --run CMD [ARG...]  Execute command CMD with ARGs (used for builtins)
  --debug             Enable debugging output

You can start \bin\sh by running \emx.exe (a very small program -- put
it into your favorite folders).

Interactive login shells read $HOME/.profile (HOME is initially
"/home").  You might want to put

  export LESS=-C

into /home/.profile to improve the performance of less.

As the default value of PATH does not include the current working
directory, you have to prepend "./" to run a program from the current
working directory unless you change PATH.

C++ and OPL applications can be run by using the name of their
application file: "editor.app Makefile".  The \system\apps directories
of drives E:, D:, C:, and Z: are searched for applications.

Shell commands:

  if/then/elif/else/fi
  case/in/esac               {patterns aren't expanded}
  for/in/do/done
  time
  until/do/done
  while/do/done
  ( ... )
  { ... }

Builtin commands:

  .
  :
  [
  break
  cd
  continue
  cp                    {no -r option, -f is the default setting!}
  echo
  epocpath              {given a Unix pathname, prints the EPOC pathname}
  eval
  exit
  export
  false
  function              {no redir, not in background, not in pipeline}
  kill                  {be careful!}
  ln                    {only symbolic links, only two pathnames}
  mkdir                 {should be external, no -p option}
  mv                    {-f is the default setting!}
  ps                    {-m lists threads}
  pwd
  rm                    {should be external, no -r option}
  rmdir                 {should be external, no -p option}
  set                   {-a only}
  shift
  sleep
  source
  test
  true
  unset
  wait
  which                 {displays EPOC pathname with symlinks resolved}

Redirections {no parameter expansion in FILENAME and NUMBER, only 0
through 2 can be used for NUMBER, all these redirections can be
prefixed by 0 through 2, no << yet}:

  <FILENAME
  <&-
  <&NUMBER
  <>FILENAME
  >FILENAME
  >>FILENAME
  >&NUMBER

Escape sequences in PS1 and PS2:

  \n
  \r
  \w
  \\

Special variables:

  HOME                  {no ~ expansion}
                        {IFS is not implemented}
  OLDPWD
  PATH                  {see below}
  PS1
  PS2
  PWD

Parameter expansion:

  $!
  $#
  $$
  $*
  $?
  $@
  $WORD
  $NUMBER
  ${all of the above}
  $'...'                {no $"..."}

Other expansions:

  ? * [...]             {[...] is case-sensitive}
  {,}
  `cmd`                 {broken}
  $(cmd)                {broken}

Here are some examples which should point out the differences between
the various ways to run the shell:

  sh /dev/tty a b c

    The first argument is the name of a shell script, so this example
    reads commands from the terminal.  If you type "echo $2", the
    output will be "b" ($0 is "a").

  sh -c 'echo $1;echo $2' a b c

    This will print "b" and "c" ($0 is "a").

  sh --run echo a  b  'c  d'

    This will print "a b c  d".

There's no difference between sh.exe and sh-acs.exe, except for the
code checksum.  This is used to work around a bug in EPOC.  If you
delete sh-acs.exe, emx.dll will work around the problem by using
emxrun.exe.  If you also delete emxrun.exe, emx.dll will work around
the problem by keeping zombies.

------------------------------------------------------------------------------
Listing directory contents: ls.exe
------------------------------------------------------------------------------

Switches of ls {sorry, no -R switch yet}:

  -1            One file per line (default if output is not a terminal)
  -a            Don't omit files starting with "."
  -d            List names of directories instead of the files they contain
  -l            One file per line, additional information
  -m            Multiple files per line, separated by ", "
  -n            Ignored
  -p            Like -F, but don't use "*"
  -r            Reverse the sorting
  -t            Sort by modification time (newest first)
  -C            Multiple columns (default if output is a terminal)
  -F            Append "/" or "*"
  -S            Sort by size (biggest first)
  -U            Don't sort (default: sort by name)
  -Z            Use opendir() even under EPOC -- for debugging only
  --uid123      Show UIDs (a non-empty combination of 1, 2, 3 is required)

------------------------------------------------------------------------------
Dissecting pathnames: basename.exe and dirname.exe
------------------------------------------------------------------------------

{TODO}

------------------------------------------------------------------------------
Copying and concatening files to standard output: cat.exe
------------------------------------------------------------------------------

{This is cat.exe of emxshell.sis -- emxtextutils.sis contains GNU's
version.}

Switches of cat:

  -b  Number non-empty lines
  -e  Like -v -E
  -n  Number all lines
  -s  Display only one empty line for each sequence of empty lines
  -t  Like -v -T
  -v  Make control characters printable by prefixing ^
  -E  Display $ at end of line
  -S  Ignore non-existent input files\
  -T  Display TAB as ^I

------------------------------------------------------------------------------
Showing disk usage: du.exe
------------------------------------------------------------------------------

Type "du -?" to get a list of available switches.

Unfortunately EPOC conceals the filesystem's block size; use the -B
option to set the block size for accurate results (the default value
is 512).

Bug: du follows symbolic links (which is a good thing for /c and /d).

------------------------------------------------------------------------------
Printing the environment: printenv.exe
------------------------------------------------------------------------------

{TODO}

------------------------------------------------------------------------------
Displaying UIDs: uidtool.exe
------------------------------------------------------------------------------

Type "uidtool -?" to get a list of available switches.

------------------------------------------------------------------------------
GNU awk
------------------------------------------------------------------------------

{TODO}

awk.exe                      {no networking, no pipes}

------------------------------------------------------------------------------
GNU binary utilities
------------------------------------------------------------------------------

{TODO}

ar.exe
as.exe
dlltool.exe
ld.exe
nm.exe
objdump.exe
ranlib.exe
size.exe
strings.exe

------------------------------------------------------------------------------
GNU diff utilities
------------------------------------------------------------------------------

{TODO}

cmp.exe
diff.exe                     {uses binary mode currently}
diff3.exe
sdiff.exe                    {editor does not work -- file in use}

------------------------------------------------------------------------------
GNU find utilities
------------------------------------------------------------------------------

{TODO}

find.exe
xargs.exe

Hint: As /c and /d (and so on) are symbolic links (rather than mount
points), you have to use

  find /c/ ...

instead of

  find /c ...

------------------------------------------------------------------------------
GNU grep
------------------------------------------------------------------------------

{TODO}

egrep.exe                    {uses binary mode currently}
fgrep.exe                    {uses binary mode currently}
grep.exe                     {uses binary mode currently}

------------------------------------------------------------------------------
GNU gzip
------------------------------------------------------------------------------

See [/usr]/man/gzip.1. {TODO}

gzip.exe
gunzip.exe
zcat.exe

------------------------------------------------------------------------------
GNU recode
------------------------------------------------------------------------------

{TODO}

recode.exe                   {quite big}

------------------------------------------------------------------------------
GNU sed
------------------------------------------------------------------------------

See [/usr]/man/sed.1. {TODO}

sed.exe                      {uses binary mode currently}

------------------------------------------------------------------------------
GNU shell utilities
------------------------------------------------------------------------------

{TODO}

date.exe                     {no timezone}
echo.exe
env.exe
expr.exe
factor.exe
false.exe
printf.exe
seq.exe
sleep.exe
tee.exe
test.exe
true.exe
tty.exe

------------------------------------------------------------------------------
GNU tar
------------------------------------------------------------------------------

{TODO}

tar.exe                      {no compression}

The z and I options are implemented for decompressing the input, but
not for compressing the output.

------------------------------------------------------------------------------
GNU text utilities
------------------------------------------------------------------------------

{TODO}

cat.exe                      {another one}
cksum.exe
comm.exe
csplit.exe
cut.exe
expand.exe
fmt.exe
fold.exe
head.exe
join.exe
nl.exe
od.exe
pr.exe
ptx.exe
sort.exe
split.exe
sum.exe
tac.exe
tail.exe                       {cannot interrupt "tail -f"}
tr.exe
tsort.exe
unexpand.exe
uniq.exe
wc.exe

------------------------------------------------------------------------------
bzip2
------------------------------------------------------------------------------

See [/usr]/man/bzip2.1. {TODO} Warning: bzip2 requires at least 7.5 MB
of memory.

bzip2.exe
bzip2recover.exe

------------------------------------------------------------------------------
less
------------------------------------------------------------------------------

`less' is a better pager than `more'; it can be used for reading the
manual pages in [/usr]/man. {TODO}

less.exe
man
more.exe                     {a symbolic link to less.exe}
zless

------------------------------------------------------------------------------
unzip and zip
------------------------------------------------------------------------------

See [/usr]/man/unzip.1 and [/usr]/man/zip.1. {TODO}

unzip.exe
zip.exe

Note that this port of unzip and zip is derived from the Unix port and
therefore does not support drive letters and other DOSisms and
EPOCisms!

------------------------------------------------------------------------------
Managing object files and libraries: emxobj / emxobj.exe
------------------------------------------------------------------------------

This tool changes the name mangling of symbols in COFF/PE object files
and libraries to reflect changes in GCC.  It can also dump COFF/PE
object files (but objdump is better at that).  (To dump COFF/PE
executable files, use objdump or emximage.)

This line shows how to call emxobj to copy INPUTFILE (a COFF/PE object
file or library) to OUTPUTFILE, remangling symbols in the process:

  emxobj [-n] [-m0|-m1] [-x EXPLICITFILE] INPUTFILE OUTPUTFILE

These lines show how to call emxobj to create various text listings of
a COFF/PE object file or library; output goes to standard output:

  emxobj -d INPUTFILE
  emxobj -e [-m0|-m1] INPUTFILE
  emxobj -i [-m0|-m1] INPUTFILE
  emxobj -p INPUTFILE...
  emxobj -r INPUTFILE...

For testing emxobj, it can invoked this way to act as filter (reading
from standard input, writing to standard output):

  emxobj -f [-c] [-m0|-m1] [-x EXPLICITFILE] [-D]

Switches:

  -c           In filter mode, only output those symbols which are
               changed by remangling

  -e           Write an EXPORTS statement to standard output (this can
               be used to recreate a .def file for a DLL if you have
               the import library)

  -f           Filter mode, read symbols (one per line) from standard
               input, write remangled symbols to standard output using
               the format "OLD -> NEW"

  -i           Output an import list to stdout, see emxdump for the
               file format

  -d           List (dump) the input file

  -m0          Don't remangle symbols

  -m1          Remangle symbols from GCC 2.7.2 960323 to GCC 2.97
               20010205 (this is the default setting)

  -n           Don't change symbols (equivalent to -m0, but invalid with -f)

  -p           Find initialized and uninitialized data; emxobj tries to
               give hints (using some obscure output format) about the
               name of the offending objects and from where they are
               referenced

  -r           Find suspect relocations, that is, references to symbols
               with a negative offset.  This can be used to find out
               which part of the code triggers the message

                 *** Value (...) at location to be fixed up (...) does not
                 point into any section

               of emximage.  However, emxobj may give false positives and
               it may miss the real culprit.

  -x FILENAME  Read explicit mappings from the text file named FILENAME,
               each line should have the format "OLD -> NEW"

  -D           Used for debugging emxobj

emxobj is used by tools/install-epocsdk-headers, which in turn is
invoked for target install-sdk of emxtool/Makefile.

------------------------------------------------------------------------------
Adapting SDK header files: emxfixhdr / emxfixhdr.exe
------------------------------------------------------------------------------

This program removes bugs of Symbian's ER5 SDK header files and makes
them usable with later versions of GCC.  It is called like this:

  emxfixhdr [-n] [SOURCE [DESTINATION]]

If no filenames are specified, emxfixhdr reads from stdin and writes
to stdout.  If one filename (SOURCE) is specified, emxfixhdr reads
from that file and writes to stdout.  If two filenames are specified,
emxfixhdr reads from SOURCE and writes to DESTINATION.

If the -n switch is used, no changes are done, except for converting
CRLF to LF.  If the -n switch is not used, emxfixhdr modifies the
contents of the lines while copying.

emxfixhdr is used by tools/install-epocsdk-libs, which in turn is
invoked for target install-sdk of emxtool/Makefile.

------------------------------------------------------------------------------
Disassembling: disasm
------------------------------------------------------------------------------

This program is used for testing the disassembler, but it can also be
used for disassembling raw files such as sys$rom.bin.  To disassemble
EPOC executables, use emxdump, to disassemble object files, use
objdump.  The disassembler is far from complete.  Using this program
may violate licenses.

------------------------------------------------------------------------------
Installing EPOC files: emxinstall
------------------------------------------------------------------------------

Shell script for installing EPOC files.  See INSTALL.

------------------------------------------------------------------------------
MISSING PROGRAMS
------------------------------------------------------------------------------

Programs not (yet) available: aleppo, bmconv, fnttran, fontcomp,
makmake, pdrtran, etc., etc.  Build steps involving these tools still
need to be done using the ER5 C++ SDK; if you don't want to use
Windows, see http://gnupoc.sourceforge.net.

------------------------------------------------------------------------------
EmxConsole
------------------------------------------------------------------------------

EmxConsole is an EIKON application which provides terminal emulation
for a tree of processes.  Output written to stdout and stderr by the
client processes is displayed by EmxConsole.  Keyboard input is
redirected to that client process which reads from stdin.  (As
processes are usually started synchronously, at most one process at a
time is reading from the console; asynchronous child processes cannot
read from the console.)

Important: Client processes continue to run if EmxConsole is
terminated; client processes doing proper error checking will detect
that EmxConsole is no longer running on their next access to the
console (errno will be set to ENXIO).

EmxConsole is also used to configure emx.dll (see menu "Tools"); you
can configure these features:

  - drives on which symbolic links are to be supported (do not disable
    symbolic links on the drive where emx.dll is installed!)

  - number of lines the command line editor will remember

  - filename completion

A line editor is used for reading from stdin.  Keybindings (cf. Emacs):

  Key           Function
  -------------------------------------------------------------------------
  Enter         End editing the line
  Left arrow    Move left by one character
  Right arrow   Move right by one character
  Down arrow    Move to the next line in the history
  Up arrow      Move to the previous line in the history
  Home          Move to beginning of line
  End           Move to end of line
  Del           Delete the character to the left of the cursor
  Shift-Del     Delete the character under the cursor
  Tab           Simple filename completion (Shift-Tab to cycle backwards)
  Ctrl-D        End editing the line or, if line is empty, EOF
  Ctrl-K        Delete all characters under and to the right of the cursor
  Ctrl-Q        Same as Ctrl-V
  Ctrl-U        Delete all characters to the left of the cursor
  Ctrl-V        Insert next (control) character verbatim
  Ctrl-W        Delete spaces and the word to the left of the cursor
  Ctrl-Y        Paste from the line editor's clipboard

Note that EmxConsole intercepts Ctrl-Q and Ctrl-V unless reconfigured
to use Shift-Ctrl-Q and Shift-Ctrl-V!

The keys Ctrl-K, Ctrl-U, and Ctrl-W move the deleted characters to the
line editor's clipboard.  Note that Ctrl-Q and Ctrl-V are used by
EmxConsole (unless EmxConsole is configured to use Shift+Ctrl instead
of Ctrl for hotkeys), so they don't reach the line editor.

EmxConsole emulates an ANSI/VT100 subset (n, x, and y are numbers):

  NUL           Ignored
  BEL           Make noise
  BS            Move cursor left (wraps)
  TAB           Move to next tab stop
  CR            Move cursor to beginning of line
  LF            Line feed {TODO: currently does CR automatically}
  CAN           Reset mode
  SUB           Reset mode
  ESC [ n A     Move cursor up
  ESC [ n B     Move cursor down
  ESC [ n C     Move cursor right
  ESC [ n D     Move cursor left
  ESC [ x G     Move cursor to column x
  ESC [ y ; x H Move cursor
  ESC [ J       Clear to end of screen
  ESC [ 2 J     Clear screen
  ESC [ 0 K     Clear from cursor to end of line
  ESC [ n L     Insert lines
  ESC [ n M     Delete lines
  ESC [ y d     Move cursor to row y
  ESC [ n m     Set mode (multiple n separated by ";" -- see below)

Modes (for ESC [ n m):

   0            Reset mode
   4            Enable underline
   7            Enable inverse
  24            Disable underline
  27            Disable inverse

------------------------------------------------------------------------------
EmxDevice
------------------------------------------------------------------------------

EmxDevice is an EIKON application which exists only to provide an icon
for device files.  Use the following commands of sh.exe to manage
device files:

  mknod NAME TYPE MAJOR MINOR       Create a device file
  ls -l NAME                        List a device file
  rm NAME                           Remove a device file

------------------------------------------------------------------------------
EmxLink
------------------------------------------------------------------------------

EmxLink is an EIKON application which exists only to provide an icon
for symbolic links.  Use the following commands of sh.exe to manage
symbolic links:

  ln -s OLDNAME NEWNAME             Create a symbolic link
  ls -l NEWNAME                     List a symbolic link
  rm NEWNAME                        Remove a symbolic link

------------------------------------------------------------------------------
\system\libs\emx.dll
------------------------------------------------------------------------------

emx.dll contains an implementation of spawn*() which does not limit
command line arguments and lets child processes (which use emx.dll)
inherit the current working directory, the file descriptors of the
parent process, and the environment of the parent process.  This works
only for programs which are "emx applications", that is, programs
which define main() and use emx.dll (as they were not linked with
-Znoemx).  Other programs can also be run by spawn*(), but the total
size of command line arguments is limited and those progams won't
inherit the current working directory, open file descriptors, etc.

"emx applications" use EmxConsole for input and output.  Child
processes use the same EmxConsole instance as their parent process.
In asynchronous child processes (P_NOWAIT), read() panics for attempts
to read from the console.  If P_NOTTYINPUT has been used, read() fails
(EBADF) for attempts to read from the console.

{TODO: If starting or connecting to EmxConsole fails, the standard
console of EPOC will be used.  The line editor, however, will still
work (more or less, due to console bugs).  Note that printing a TAB
character which causes the cursor to move across the end of the line
causes the program to hang.  Note that the width of the console is not
80 characters unless EmxConsole is used.  Running emx applications
without EmxConsole should be done in emergency cases only.}

The function _emx_trap(), declared in <emx.h>, installs an exception
handler which, when the program crashes, may be able to display the
location at which the program crashes.  Various other information is
available, see lib/emxtrap.cc.  There's one major problem with
_emx_trap(): if the exception is due to stack overflow, EPOC will
reboot.  See also emxpanic.exe.

To use the global variable `environ', you have to #include <emx.h>.

<emx.h> should be #included after the standard headers (as the SDK's
<sys/reent.h> uses `environ' as structure member).

Compared to ESTLIB, libemx.a adds full or partial implementations of
these functions:

  atol, fcntl, ffs, getopt, getprotobyname, getprotobynumber, getw,
  kill, lstat, mktemp, pathconf, pclose, pipe, popen, readlink, putw,
  spawnl, spawnle, spawnv, spawnve, spawnlp, spawnlpe, spawnvp,
  spawnvpe, symlink, sysconf, system, times, utime

libemx.a adds these dummy functions:

  endgrent, endpwent, getegid, geteuid, getgid, getgrent, getgrgid,
  getgrnam, getpwent, getpwnam, getpwuid, getuid, raise, setgrent,
  setpwent, signal, umask

libemx.a adds these emx-specific functions:

  _emx_trap, _emx_map_error, _emx_set_errno, _emx_parent, _epocpath, _samefile

All this is subject to change.

getcwd() may return a pathname of the form "/C:/System", that is, with
a leading slash.  This ensures that Unix programs know that it's an
absolute path.  Of course, pathnames of that form are acceptable to
all library functions.

send() and sendto() ignore their FLAGS argument.  recv() and
recvfrom() ignore all bits of their FLAGS argument except for
MSG_PEEK.

If you create your own version of emx.dll, please use a different name
and different UID.

------------------------------------------------------------------------------
\system\libs\emxrun.exe
------------------------------------------------------------------------------

This program is used to work around a bug in EPOC, see spawn*().

------------------------------------------------------------------------------
spawn*()
------------------------------------------------------------------------------

{TODO}

There's a problem in EPOC: A program running another program which has
the same code checksum (for instance, if it's the same program) will
crash as soon as it closes the RProcess handle to the child process.
To work around the problem, spawn*() does the following when it
detects that the program to be run (child program) has the same code
checksum as the parent:

- If the filename of the child program does not end with "-acs"
  (preceding the extension), "-acs" will be added, otherwise removed.
  For instance, "sh.exe" becomes "sh-acs.exe" and vice versa.  If
  there's an executable having that filename and having a code
  checksum which is the one's complement of the original code
  checksum, that executable will be run.  See the -acs switch of
  emximage and the sh-acs.exe target of tools/Makefile.

- If the above fails, spawn*() tries to run emxrun.exe which is
  supposed to live in the same directory as emx.dll.  emxrun.exe will
  then run the the child program.  If emxrun.exe cannot be found or if
  emxrun.exe has the same code checksum as the child program, spawn*()
  will fall back to the last resort:

- If all of the above fails, spawn*() will not close the RProcess
  handle to the child process, resulting in a resource leak and
  zombies.

------------------------------------------------------------------------------
Environment variables
------------------------------------------------------------------------------

For programs which are not started by spawn*(), the environment will
contain these variables:

  PATH=/bin:/usr/bin
  HOME=/home

Please don't put paths containing drive letters into PATH as ":" is
used as separator.  Instead, use symbolic links:

  ln -s d:/mybin /mybin
  PATH=$PATH:/mybin

Some programs use the directory pointed to by the TMPDIR environment
variable for temporary files.  You may want to let it point to a CF
card to save real memory.

------------------------------------------------------------------------------
Common problems
------------------------------------------------------------------------------

If running a program under EPOC causes a dialog box of this form to be
displayed:

  Program closed
  ----------------------
  Program:       ...
  Reason code:   LDR-IMPORT
  Reason number: 2

your emx.dll is probably outdated.  Please install the latest version.

------------------------------------------------------------------------------
Thanks
------------------------------------------------------------------------------

I wish to thank Ondra Cada, Fritz Elfert, Olaf Flebbe, Alfred
E. Heggestad, Tomas Hurka, Rudolf Knig, Philip Proudman, and Matt
Williams.

------------------------------------------------------------------------------
Your help is needed
------------------------------------------------------------------------------

EmxConsole, EmxDevice and EmxLink are in desparate need of nice icons
(they should be available under the GPL).

A port of epocemx to ER6 (Symbian OS) would be nice.

------------------------------------------------------------------------------
Pointers
------------------------------------------------------------------------------

epocemx home site:     http://epocemx.sourceforge.net

------------------------------------------------------------------------------
Future plans
------------------------------------------------------------------------------

Replace CEikConsole to be able to implement Edit->Copy and scrolling
with the keyboard (and for getting rid of bugs).

Implement O_TEXT and O_BINARY (currently, O_BINARY is used for all
files; this may or may not change in the future, so please always
specify O_TEXT or O_BINARY (or "b" or "t" for fopen)).

Fully support sockets (e.g., non-blocking sockets, getsockopt, setsockopt).

Support I/O, wait(), etc. for multithread programs.

Provide more clones of ER5 C++ SDK tools.

Backport GCC bug fixes.

Remove the preprocessor from cc1 and cc1plus to save memory.  Try to
reduce the memory requirements of cc1plus to make it really work on
the PSION 5mx PRO.

Replace dlltool (which is incredibly slow under EPOC because it calls
"as" and "ar") and use a sane format for import libraries (the EPOC
import libraries are incredibly big).

Improve esh.  Port some essential Unix tools.

WTFM.

Make the tools more EPOC-friendly (don't crash when out of memory).

Fix the Mtools and Linux bugs/features mentioned in INSTALL.

==============================================================================
                                  END
==============================================================================
