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.