
Installation notes for VICE 0.12.1
----------------------------------

This version of VICE can be compiled and installed both under Un*x/X-Window and
MS-DOS.  The MS-DOS version is still experimental and does not work very well
yet, so beware. (in fact, an official MS-DOS version has not been released at
the time of writing)

1. What you will need

  1.1. Unix

    To compile VICE under Un*x, you basically need a Un*x machine running the
    X-Window system version 11 R5 or better, with the standard Xt and Xaw 
    libraries (it could probably work with R4 as well, but this has not been 
    tested).  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 at sunsite.unc.edu.  You can also use a customized 
    joystick-0.8.0.1.tar.gz that has support for digital joysticks connected 
    to the parallel port.  This is available from our home page (see the 
    `README' file).

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

    The 0.12.1 release has been tried successfully on the following Un*x
    systems:

      Various i486/Pentium/Pentium Pro PCs running Linux 2.0.x and XFree 3.2
      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 or 2.4 (using gcc)
      SGI Indy R5000 and R4600 running Irix 5.3 and 6.2
      AlphaStation 500/533 with Digital Unix 3.2

    If you compile under a Un*x system that is not listed here, please tell us.

    If you are compiling on a Pentium machine under Linux or FreeBSD, you might
    consider using the Pentium-specific gcc compiler, which is available at
    http://www.goof.com/pcg.  The compiler is still in alpha stage, but it has
    been able to compile correct executables each time we have tried it, and
    the performance was always at least 20% better (even with just -O2 or -O3).
    Important notice: if you use the Pentium-specific gcc, remove all the 
    optimiziation options (the ones that start with `-f') from `COPTS' in 
    Makefile and just keep a `-On' where `n' is the level of optimization you
    want.  In fact, some of those options are broken and might silently produce 
    wrong code!

    Warning: you will need quite a lot of memory to compile VICE with full
    optimizations on some platforms (in particular, on the Pentium-specific
    gcc).
    
  1.2. MS-DOS

    If you want to compile for MS-DOS, you'll have to grab the VICE MS-DOS
    support sources.  Since they are quite broken, we are not going to make
    them publically available; if you want them, just e-mail us.  Moreover,
    you must have DJGPP (http://www.delorie.com) or a cross-compiling gcc on
    your system (a Linux binary is available at
    ftp://sunsite.unc.edu/pub/Linux/devel/msdos) and the (swapware) ALLEGRO
    library by Shawn Hargreaves (http://talula.demon.co.uk/allegro).

    If you are cross-compiling on a Un*x system, you can configure the package
    for MS-DOS directly (see below); otherwise, you will need to rename
    autoconf.dos to autoconf.h and Makefile.dos to Makefile first.  Notice
    that operation under DJGPP has not been tested very much and that, in
    order to make it work, you will need to run under a system that provides
    long file names (e.g. Windows 95 -- consult your DJGPP documentation to
    see how long file name support can be enabled in DJGPP).

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; it must be executed before compiling 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 `src' directory of the
    distribution 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 Un*x 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 text 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).

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

    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.

    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 (x64, xvic, xpet, petcat, c1541)
    under the `bin' directory.  It is possible that configure is not able to
    find all the needed libraries automatically (this is usually due to 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 Makefiles 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; in order
    to provide multiple architectures and versions to be installed at once,
    some links will be created as follows:

      PREFIX/X11/bin/x64 -> PREFIX/lib/VICE/ARCH/x64-VERSION

    Where `ARCH' is the autoconf identificator of the architecture of the
    machine you have compiled binaries for (e.g. i586-pc-linux-gnu), and
    VERSION is the version number (in this case, 0.12.0).  Use strip(1) on the
    binary files if you like.

    If you want to provide site-specific defaults, you can build a
    PREFIX/lib/VICE/vicerc resource file that will be loaded by default.
    Consult the documentation in MANUAL.html to see how this works.

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

      make uninstall

  2.2. Compiling under MS-DOS, for MS-DOS

    This is the hard way, as we have just tested this once.  You should
    basically run the configur.bat batch file, that simply copies autoconf.dos 
    and Makefile.dos to autoconf.h and Makefile respectively.  Then you should 
    be able to build everything with ``make''.

    Notice that (many) troubles can come from long file names: if you run under
    plain MS-DOS, some names may conflict.  There should be no problems at all
    if you compile under a Win95 DOS box.  (hopefully)

3. Hints

  On Un*x, if you are using alternative Xaw libraries and you are having
  troubles with the GUI, try to use the standard Xaw or Xaw3d (the latter will 
  be autodetected by the configure script and linked automatically if present, 
  as it is known to work).  There are some incompatibilities that can cause 
  them to crash or not to work properly.

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

  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, edit
  Makefile by hand and remove that option.

