==============================================================================
Installing epocemx and related stuff                                2003-03-08
==============================================================================

------------------------------------------------------------------------------
Prerequisites
------------------------------------------------------------------------------

Building the programs and libraries requires a Unix-like operating
system; so far, only Linux, Solaris, and cygwin have been tested.  It
is assumed that G++, GNU make, GNU patch, GNU recode, and gzip are
installed.

You need source code archives for several programs; either .tar.gz or
.tar.bz2 archives can be used, but only the .tar.gz file is mentioned
below.  Download the following archives (available from all GNU
mirrors):

  binutils-2.11.tar.gz     (required)
  diffutils-2.8.tar.gz     (optional)
  findutils-4.1.tar.gz     (optional)
  gawk-3.1.0.tar.gz        (optional)
  grep-2.4.2.tar.gz        (optional)
  gzip-1.2.4a.tar.gz       (optional)
  less-374.tar.gz          (optional)
  recode-3.6.tar.gz        (optional)
  sed-3.02.tar.gz          (optional)
  sh-utils-2.0.tar.gz      (optional)
  tar-1.13.tar.gz          (optional)
  textutils-2.0.tar.gz     (optional)

Download gcc-20010205.tar.gz (required), which was available from GCC
snapshot archives, but seems to have disappeared.

Download bzip2-1.0.2.tar.gz (optional) from:

  http://sources.redhat.com/bzip2
  ftp://sources.redhat.com/pub/bzip2/v102/bzip2-1.0.2.tar.gz

Download unzip550.tar.gz (optional) and zip23.tar.gz (optional) from:

  http://www.info-zip.org/pub/infozip/

and rename them to unzip-5.50.tar.gz and zip-2.3.tar.gz, respectively
(or create symbolic links).

Exactly these versions are required, don't try newer or older
versions.  In particular, using the correct versions of GCC and
binutils is essential.

------------------------------------------------------------------------------
Using the `build' script
------------------------------------------------------------------------------

The `build' script builds all the stuff and installs it on your Unix
machine:

- Unpack the epocemx source distribution:

    tar xzf epocemx-YYYYMMDD.tar.gz                 (GNU tar)
    gunzip < epocemx-YYYYMMDD.tar.gz | tar xf -     (any other tar)

  This creates the directory epocemx-YYYYMMDD, whose pathname will be
  called $b in the following instructions.

- Only this step requires login as `root': Create the directory
  /usr/local/epocemx and chown it to your userid (`myself' in this
  example):

    su -
    mkdir /usr/local/epocemx
    chown myself /usr/local/epocemx
    exit

- Add /usr/local/epocemx/bin to your PATH

- Configure the pathname of the archives listed above by running

    ./cfg-src -set PATH

  where PATH is the pathname of the directory containing the archives.
  Example:

    cd $b
    ./cfg-src -set $HOME/download

- Configure the pathname of the ER5 C++ SDK by running

    ./cfg-sdk -set PATH

  where PATH is the pathname of the directory in which the ER5 C++ SDK
  is installed.  Example:

    cd $b
    ./cfg-sdk -set /c/CPPER5SDK

- The `build' script can install adapted and fixed versions of the
  EPOC SDK headers and libraries.  This involves copying files of the
  EPOC SDK and modifying some of the copied files; by doing this, you
  may violate the EPOC SDK license; you may have to delete the
  original SDK files so that only one copy is left, or download
  another copy, and/or register for another copy, or whatever.  You're
  on your own, I never told you that you should type "./build all sdk"
  instead of "./build all" to install the SDK.  Unfortunately,
  building without letting `build' install the SDK won't work.

  You might want to use a fresh installation of the SDK to avoid
  copying the headers and libraries of any sample programs you've
  built.

- Run the `build' script:

    cd $b
    ./build all

  If you don't have all the archives listed above, use the -m option
  of `build':

    cd $b
    ./build -m all

  If you don't want to build GCC for running under EPOC, add `-without
  gcc' at the end of the command:

    cd $b
    ./build all -without gcc

- See README for a description of the SIS files; install those you need

- `build all' should have built hello/hello.exe; you might want to
  test that program on your EPOC device

------------------------------------------------------------------------------
How to install programs on your EPOC device
------------------------------------------------------------------------------

There are two ways to install the files:

(A) copy the SIS files and install from the SIS files

(B) copy the individual files

SIS files are provided for all components except for the EPOC SDK, so
(B) has to be used for the EPOC SDK.  For all other components, (A) is
recommended.

You need a CF card with at least 27 MB free space for the complete
installation.  You can save space by not installing programs and
libraries you won't need.

Do not yet insert your CF card into your build machine!  These
instructions will tell you why you should not directly write to the CF
card and they will tell you when exactly to insert and remove the CF
card if you insist on directly writing to it.

There are at least five ways to copy the files to the CF card:

(1) Mount the filesystem of your CF card on your Unix machine and copy
    the files directly to the filesystem -- see warnings below

(2) Use Mtools to copy the files to your CF card -- see warnings below

(3) Build the complete directory tree (destined for EPOC) on your Unix
    machine and then copy that directory tree to the CF card (by
    mounting the file system or by using Mtools) -- see warnings below

(4) Use plpnfsd to mount your EPOC device (over the serial or infrared
    link) and build the directory tree under the mount point.
    Unfortunately, this may take a couple of hours

(5) Build the complete directory tree (destined for EPOC) on your Unix
    machine, copy that tree over the serial or infrared link to your
    EPOC device (preferably packaged in a ZIP file).  Unfortunately,
    this may take a couple of hours

See http://plptools.sourceforge.net for (4) and (5).

Mounting a CF card as MSDOS/VFAT file system under Linux doesn't work
as EPOC assumes that the end of a directory is marked by a filename
starting with a zero byte.  Apparently, the MSDOS/VFAT file system of
Linux (like that of Windows 2000, at least), neither respects nor adds
that end marker, resulting in weird effects, including hard crashes
with data lost from the harddisks.  Mtools also used to have serious
problems (resulting in data loss on the CF card); as of version
pre6-3.9.8, some of those seem to have been fixed (at least when using
a freshly formatted CF card) -- but Mtools still fail to update the
second FAT correctly.  Anyway, Linux has serious problems with
hot-swapping PCMCIA devices.

If you still want to write directly to a CF card, follow these steps:

- Do not yet insert your CF card into your build machine!

- Build the programs to be installed (see above)

- Save your data and terminate any running applications on your
  *build* machine because Linux will become instable during the
  following steps

- Set EMXINSTALL_ROOT as described above.

- Insert the CF card

- Install the files (see below)

- Prepare for removing the CF card:

    sync
    cardctl eject 0   (or 1, depending on the PCMCIA slot)

  Then remove the CF card and reboot your Linux machine.  Otherwise
  strange things will happen to your hard disk.

------------------------------------------------------------------------------
Installing without SIS files
------------------------------------------------------------------------------

If you want to directly write to a CF card, see the caveats above.

The emxinstall program is used by scripts and the Makefiles to copy
(individual) files for EPOC; the target root directory is specified by
the environment variable EMXINSTALL_ROOT.  If the value of
EMXINSTALL_ROOT starts with a letter followed by a colon, emxinstall
will use Mtools.  If the value of EMXINSTALL_ROOT starts with a slash,
emxinstall will copy to that Unix path.  In both cases, the value of
EMXINSTALL_ROOT must not end with a slash.  Examples:

  EMXINSTALL_ROOT=/mnt                          (1)
  EMXINSTALL_ROOT=f:                            (2)
  EMXINSTALL_ROOT=/tmp/epoc                     (3), (5)
  EMXINSTALL_ROOT=/mnt/psion/D:                 (4)
  export EMXINSTALL_ROOT

To let emxinstall only show the commands instead of executing them,
type this:

  EMXINSTALL_CMD=echo
  export EMXINSTALL_CMD

Here are the instructions for installing the files (except for those
of emxuser.sis and emxdev.sis):

- Set EMXINSTALL_ROOT as described above

- Create the directories and install the files:

    ./build -n -u -i all

  Use the -m option if you haven't built all optional modules.
  Depending on how you set EMXINSTALL_ROOT, you may have to transfer
  files to your EPOC device now.

- If you don't mind violating the EPOC SDK license (or if you are sure
  that this step doesn't violate that license), you may copy the
  adapted and fixed versions of the EPOC SDK headers and libraries
  from /usr/local/epocemx/epocsdk to your EPOC device.  You're on your
  own, I never told you to type:

    cp -r /usr/local/epocemx/epocsdk $EMXINSTALL_ROOT/emx

  or

    mmd f:/emx/epocsdk
    mcopy -/Q /usr/local/epocemx/epocsdk/* $EMXINSTALL_ROOT/emx/epocsdk

  or whatever is necessary to transfer the files.

- Don't forget to follow the instructions above for removing the CF card.

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