Installation notes for VICE
***************************


This version of VICE can be compiled and installed under Unix/X-Window,
MS-DOS, MS-Windows, OS2, and this file explains how this can be done.
There is currently no documentation how to compile under RiscOS or BeOS.

1. What you will need
=====================

  1.1. Unix
  ---------

    To compile VICE under Unix, you basically need a Unix machine
    running the X-Window system version 11 R5 or better, with the
    standard Xt and Xaw libraries.  R4 should work too, but hasn't
    been tested lately.

    If you want to use joysticks under Linux, you must install the
    proper joystick module (`joystick-0.8.0.tar.gz' or more recent),
    which is available from `sunsite.unc.edu'.  You can also use a
    customized `joystick-0.8.0.2.tar.gz' that has support for digital
    joysticks connected to the parallel port.  This is available from
    the VICE home page (see the `README' file).

    Unlike previous (pre-0.12) versions that only worked with 8-bit
    displays, this release will work with all depths, though 8-bit is
    still highly recommended for best performance.

    With version 0.16.0, VICE includes Dag Lem's reSID engine; to
    compile it, you will need a C++ compiler.

    NLS (national language support) has been tested with Linux and
    Solaris systems. The following environment variables have to be
    set and exported before starting an emulator:

    - Linux: LANGUAGE=de        # de is currently the only available 
                                # translation
                        
    - Solaris: NLSPATH=${prefix}/lib/locale
               LC_MESSAGES=de

    VICE has been compiled successfully on the following Unix systems
    in the past:

      - Various i486/Pentium/Pentium Pro PCs running Linux 2.0.x and
        XFree86 3.2/3.3, with both libc 5 and glibc 2;
	Further support for October Gnome and newer Versions should work.

      - Some HP9000 (712, 715, 735, 800) machines running HP-UX 9.x
        and 10.x;

      - SUN SPARC 5, 10 and Ultra running Solaris 2.3, 2.4, 2.5, 2.5.1
        and 2.7.
	Further support for October Gnome and newer Versions should
        work. Gnome Libraries prior to October Gnome are known to be
        broken with Vice.
        (using gcc);

      - SUN SPARC 10 running SunOS 4.1 with both X11R4 and X11R5
        (using gcc);

      - SUN SPARC 20 running Linux (2.0.30, RedHat 4.2);

      - SGI Indy R5000 and R4600 running Irix 5.3 and 6.2;

      - AlphaStation 500/533 with Digital Unix 3.2;

      - IBM RS6000 running AIX4.1 (using gcc or IBM C++ Set compiler);

      - MkLinux on Apple Macintosh, Kernel 2.0.33, X11R6.3 (no sound).

    Unluckily, not all of these systems have been tested with the
    current release.  Success/failure reports are welcome at any time.
    If you encounter any problems, you probably want to read the Hints
    section below.

    If you are compiling on a Pentium machine, you might consider
    using the Pentium-specific GCC compiler, which is available at
    `http://www.goof.com/pcg'.  Each time we have tried it, and the
    performance was always at least 20% better (even with just `-O2'
    or `-O3').  However some versions of PGCC are known to produce
    broken executables.  If you observe graphics errors try to compile
    without optimizations.  If the graphics errors disappear, throw
    away your compiler and install another one.

    Warning: you might need quite a lot of memory to compile VICE with
    full optimizations on some platforms (in particular, this happens
    with the Pentium-specific GCC).  Moreover, archaic versions of GCC
    (e.g. 2.5.x and older) are known to cause trouble.  In that case,
    it is a good idea to upgrade the compiler to a more recent
    version.

  1.2. MS-DOS
  -----------

    The MS-DOS port requires the Allegro library by Shawn Hargreaves
    (`http://www.talula.demon.co.uk/allegro') to be compiled.

    You might apply this patch to `src/djgpp/timer.c' to achieve better
    results on low end machines.

    --- old-timer.c Sat Jan  2 03:29:55 1999
    +++ timer.c     Sat Jan  2 03:30:02 1999
    @@ -197,8 +197,9 @@
           new_delay = bios_counter;

        /* fudge factor to prevent interrupts coming too close to each other */
    -   if (new_delay < 1024)
    -      timer_delay = 1024;
    +   /* FIXME: changed from 1024 to 0 (EP) */
    +   if (new_delay < 0)
    +      timer_delay = 0;
        else
           timer_delay = new_delay;

    Moreover, you also need DJGPP, the MS-DOS port of GCC
    (`http://www.delorie.com').

    There is a separate file `MSDOS-Howto.txt' in the `doc' directory
    describing what is required to compile VICE under MS-DOS.

  1.3.MS-Windows 
  --------------

    There is a separate file `Win32-Howto.txt' in the `doc' directory
    describing what is required to compile VICE under MS-Windows.

  1.4. OS/2
  --------------

    After unzipping the archive and moving the folder 'Vice2' to
    where-ever-you-want run 'install.cmd' to create the desktop-objects.

    Mention that 'install.cmd' does nothing else than creating desktop-
    objects which could be easily removed.
    

2. Configuring and compiling
============================

  2.1. Compiling under Unix, for Unix or MS-DOS
  ---------------------------------------------

    The release comes with an auto-configuring script created using
    the GNU autoconf package; this script must be executed before
    compiling VICE to detect the characteristics of your machine and
    specify certain features you might want to enable or disable.

    To execute the configuration script, enter the distribution directory
    and type:

      ./configure <options>

    There are several options available, and some of them are not
    necessary for the configuration. The important ones are:

      --prefix=PREFIX (default is `/usr/local/')
      --bindir=DIR (default is `PREFIX/bin')
      --mandir=DIR (default is `PREFIX/man')

        Specify the place where the VICE executable and support files
        will be installed.

      --host=HOST

        Specify the host for which the executable will be produced.
        If you want to compile for MS-DOS from a Unix machine using
        GCC, use `--host=i386-go32-gnu'.  If not specified, the
        configure script tries to guess it by itself, so you normally
        don't need to use this option.

      --x-includes=DIR
      --x-libraries=DIR

        Specify the paths for X11 include files and libraries.  The
        configure script is usually smart enough to find them by
        itself if the setup is not too odd; use these option if it is
        not.

      --enable-autobpp
      --enable-8bpp
      --enable-16bpp
      --enable-24bpp

        Specify the bit depth of your X11 display.  The default is
        `autobpp', that enables support for all bit depths (the
        emulator tries to find the ones your server supports by itself
        at runtime).  If you think you are going to use only one type
        of display, specifying this might give you (very) slightly
        better performance.

      --disable-textfield

        Disable Robert W. McMullen's text widget; if you experience
        problems with the text or file manager widgets, you can enable
        the standard Athena one by using this option.  This can also
        be useful if you are using a non-standard Athena-compatible
        library that provides a better looking text widget; it that
        case, using this option will give you that one (this is true
        for neXtaw, for example).
        Problems are known to occur on DEC Alpha systems running
        Digital Unix.

      --with-xaw3d

        Use Xaw3d (instead of plain Xaw) if present.

      --without-resid
      --with-resid=no

        Compile without the enhanced reSID engine.

      --with-resid=PATH

        Compile with a reSID engine located at `PATH'.  This is useful
        in case you want to compile VICE with another version of the
        reSID engine.

      --enable-gnomeui

        Compile Vice supporting the Gnome libraries. The location of
        the Gnome/Gtk+ libraries are not detected automatically,
        therefore `gnome-config' has to be found in the configuring
        users path. Refer `to src/arch/unix/x11/gnome/TODO' for a list
        of known problems/limitations.

     --disable-nls

        Force configure to ignore NLS support.


    (to obtain a complete list of the available options with a
    description, use `./configure --help')

    By default, VICE will be compiled by passing the following options
    to the C compiler:

      `-g -Wall -O5 -fomit-frame-pointer -funroll-loops
       -finline-functions -fno-strength-reduce'
          on Intel-based x86 Unix systems that have gcc installed;

      `-g -Wall -O5 -finline-functions'
          on other systems that have gcc installed;

      `-g'
          on systems that do not have gcc installed.

    If these options do not fit your needs, you can specify what
    options you want by simply passing them in the `CFLAGS' variable,
    e.g. this is something you might want to do on HP-UX:

      CFLAGS="-Ae -g +O3" ./configure

    In the same way, you can force usage of a specific C compiler by
    passing the `CC' variable, e.g.:

      CC="cc" CFLAGS="-Ae -g +O3" ./configure

    To specify a C++ compiler, use the `CXX' variable:

      CXX="g++" CFLAGS="-Wall -Wno-strict-prototypes" ./configure

    Important notice: if you use the Pentium-specific GCC, some
    optimizations might have to be disabled.  The best way to make
    sure everything works is

      CFLAGS="-mpentium -O5 -DNO_REGPARM" ./configure

    `-DNO_REGPARM' may also be needed with versions of GCC that have
    buggy implementations of regparms.  Unluckily, we have no way of
    finding about all of them, so you might have to play a bit.

    If you are running on a Linux system and the joystick module is
    installed properly, the configure script will auto-detect it and
    support for it will be enabled.  Otherwise, the joystick will be
    only emulated with the numeric keypad.

    In case the `configure' script fails or complains about missing
    libraries and you cannot explain this, please send the
    `config.log' file to us together with a precise description of
    your setup; otherwise, we cannot guess what is wrong with it.

    When the configure script has finished, the necessary Makefiles
    will be produced and you can simply type

      make

    to build all the emulators and utilities (`x128', `x64', `xcbm2',
    `xpet', `xplus4', `xvic', `c1541', `petcat') under the `src'
    directory.  It is possible that `configure' is not able to find all
    the needed libraries automatically (this is usually due to a weird
    setup); if this happens, the script will report a warning message
    but the `Makefile' will be produced anyway.  In this case, you can
    try to re-run `configure' with different options or edit the
    `Makefile's by hand to add the missing options.

    If you are cross-compiling for MS-DOS, check that all the DJGPP
    libraries and include files, together with Allegro, are in the
    right places.

    If you want to install the emulators and utilities, together with
    the documentation and ROM files, just type

      make install

    The binaries and support files will all go under PREFIX/lib/vice.
    You must of course have write permissions for the directories where
    VICE is to be installed. Normally only the system administrator
    has write access to /usr/local, the default PREFIX. Either ask
    your system administrator to install VICE for you or use a PREFIX
    in your home directory for example, where you do have write access.

    If you want to remove VICE from your system, you can use

      make uninstall

    If you want to re-compile with different options, you should do a

      make mrproper

    This will also remove the cache of the `configure' script,
    assuring that all the tests are performed from scratch.

  2.2. Configuring for multiple architectures
  -------------------------------------------

    As with most packages using GNU autoconf, you can compile VICE for
    multiple architectures from the same source tree.

    To do so, simply create a build directory:

      mkdir {build-dir}

    Then run `configure' from the VICE source tree:

      {vice-source-path}/configure

    Of course, you can specify options, flags, etc. as explained on
    par. 2.1.

    After you have configured VICE this way, you can simply compile
    VICE as you would normally do, by typing `make'.

    For example, you might want to do something like this to produce
    and MS-DOS executable of X64 (let's suppose a cross-compiling GCC
    is installed as `gcc-dos' somewhere in your `$PATH'):

      cd sources/vice-0.14.2
      mkdir i386-go32-msdos
      cd i386-go32-msdos
      CC="gcc-dos" CFLAGS="-O5" ../configure --host=i386-go32-msdos
      make x64


3. Hints
========

  In this section we compiled some hints about problems we encountered
  on different test machines and different setups. Any comments on or even 
  solutions to these problems are welcome. 

  On Unix, if you are using alternative Xaw libraries (e.g. neXtaw,
  Xaw95, Xaw3d) and you are having troubles with the GUI, try to use
  the standard Xaw first.  There are some incompatibilities that can
  cause them to crash or not to work properly.  Xaw3d should work, but
  in any case please try to use the standard Xaw library before
  reporting bugs.

  If you can, please use GCC (or EGCS) instead of the vendor's CC
  supplied with your machine: it is usually less buggy and produces
  better code.  On certain systems (most notably SunOS), configure
  might completely refuse to use the standard CC.

  Some version of the HP-UX 10.x linker was also reported to fail
  linking `x128'.  Unluckily, we believe it's a bug in the system and
  we don't know a way to fix this problem (and we did not try very
  hard, either).  If you know how, please let us know.

  Some versions of GCC seem to have troubles with `-funroll-loops' on
  certain architectures; on an Alpha and a SPARC we have tried to
  compile VICE on, the compiler died while trying to optimize the code
  when this option was specified (GCC version 2.7.2).  If you
  experience such a problem reconfigure by specifying the `CFLAGS' as
  explained above, removing `-funroll-loops'.

  SunOS 4.1.x systems running X11R4 can cause a couple of troubles.
  The first one is that `configure' might not find `-lXmu' and `-lXaw'
  properly, because of some issues related to dynamic libraries.  This
  would need some custom `configure' checks, which might be made
  available in future versions.  For now, just edit `src/Makefile'
  after it has been created by `configure' and add `-lXaw -lXmu' (in
  this order) before `-lXt' on the `LIBS=...' line.  Moreover, you
  might get undefined references to

    _get_wmShellWidgetClass
    _get_applicationShellWidgetClass

  when linking `x64', `xvic' or `xpet'.  In that case you have to link
  `-lXmu' statically (default is dynamically).  This can be done by
  editing the `Makefile' by hand and replacing `-lXmu' with `-Bstatic
  -lXmu -Bdynamic' in the `LIBS=...'  line.  A simplier way is to link
  *everything* statically; this can be achieved by running `configure'
  like this:

    LDFLAGS="-static" ./configure

  This will build much bigger executables, though.  We are sorry, but
  that is not our fault.

  Some HP-UX (versions 9 and 10) need the "--without-readline" switch
  because autoconf fails to detect that it needs "-lcurses"
  (the configure test passes, but the compile is broken. Is this an
  autoconf bug?). 

  One HP-UX 9 test machine failed to compile resid.cc, probably 
  due to a broken gcc installation. In this case try to apply this 
  patch:
--------------------------
--- vice-old/src/sid/resid.cc  Wed Mar 10 22:57:19 1999
+++ vice-new/src/sid/resid.cc  Mon Apr 12 16:22:03 1999
@@ -27,10 +27,11 @@
 
 #include "resid/sid.h"
 
-extern "C" {
 
 #include <stdio.h>
 #include <math.h>
+
+extern "C" {
 
 #include "vice.h"
 #include "sid.h"
--------------------------
  
  When compiling on AIX in a directory different from where the source 
  is and with the native C++ compiler "cc", then the C++ compiler mixes 
  up the order in which include files are included. This makes the `resid'
  package wrongly believe that `bool' is defined. You might use
  `CXX="cc -qidirfirst"' instead. 
  On the other hand using "cc" as C++ compiler resulted in a linkage 
  error on our test machine. We thus recommend using the GCC C++ compiler 
  or the configure switch `--without-resid'.
  If you know how to fix this, any comments are welcome.

  On a DEC alpha-EV6 machine (64 bit, OSF1 operating system) when using
  the DEC compiler, you might want to use `CC="cc -std1"' to enforce ANSI C
  standard.

  To build a debug version of VICE, use `CFLAGS="-g -DNO_INLINE"'.
  This disables inlining of functions in most of the places and does not
  do any optimization. This way the debugger can produce a much better 
  output. This also serves as a test whether the compiler optimization
  breaks the code.

