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


This version of VICE can be compiled and installed both under Unix/X-Window and
MS-DOS.


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.  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.1.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.

    The 0.13.0 release has been tried successfully on the following Unix
    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 Unix 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
    `CFLAGS' 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!  If you still have troubles, try to
    define `NO_REGPARM' to avoid passing parameters in the registers to
    certain functions (you can do this by adding `-DNO_REGPARM' to the
    `CFLAGS', via configure or by editing the Makefile by hand).  At the time
    of writing, this feature seems to be randomly broken in the recent PGCC
    snapshots.

    Warning: you might need quite a lot of memory to compile VICE with full
    optimizations on some platforms (in particular, this happened with old
    versions of the Pentium-specific GCC, but not with the latest ones).

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

    The MS-DOS port requires the Allegro library by Shawn Hargreaves
    (`http://talula.demon.co.uk/allegro') and the MIDAS Digital Audio System
    by Petteri Kangaslampi and Jarno Paananen (`http://www.s2.org/midas') to
    be compiled.  Moreover, you also need DJGPP, the MS-DOS port of GCC
    (`http://www.delorie.com').

    Anyway, the current source distribution is only suitable for
    cross-compilation from a Unix system.  This might change in future
    versions.


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 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 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')

    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 could 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

    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 `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; 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.13.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 `doc/MANUAL.html' to see how this works.

    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

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

    Sorry, no Makefile is currently provided for native MS-DOS compilation.

    
  2.3. 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}/src/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.13.0
      mkdir i386-go32-msdos
      cd i386-go32-msdos
      CC="gcc-dos" CFLAGS="-O5" ../src/configure --host=i386-go32-msdos
      make x64

      
3. Hints
========

  On Unix, 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.  In any case, please try to use the 
  standard Xaw library before reporting bugs.

  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 or reconfigure by specifying the
  `CFLAGS' as explained above.

