The latest version of the openMSX manual can be found on the openMSX home page:
http://openmsx.sourceforge.net/manual/
You can also use this URL to get up-to-date versions of the hyperlinks if you printed out this manual.
This guide is about openMSX, the open source MSX emulator that tries to achieve near-perfect emulation by using a novel emulation model. You can find more information about openMSX on the openMSX home page. You can also download the emulator itself from there.
openMSX is in alpha state, which means that some things work but not all features are implemented yet. Many emulation features are implemented, but in terms of user interface it is rather bare bones, unless you use the optional Graphical User Interface dubbed openMSX Catapult. However, since the emulation is already pretty good, it would be nice if non-insiders would be able to play with it, too. For those people, we have written this guide. It explains how you can get the emulator running on your system, i.e. how to get the sources and compile them. Note that some software distributions may have packaged openMSX and will enable you to install it directly using package management tools. We refer to the documentation of the tools of the distribution you are using to install openMSX. If you use such a package, you can skip the largest part of this manual and start reading at chapter 5. Next Steps.
The level of support for compilation depends on the operating system:
If you need help compiling openMSX, please contact us. If you needed any modifications to make openMSX compile, please send those modifications to us, so we can make openMSX ever more portable.
Disclaimer: We do not claim this guide is complete or even correct. What you do with the information in it is entirely at your own risk. We just hope it helps you enjoy openMSX more.
The following people contributed to this document in one way or another:
Thanks to all of them!
This section gives an overview of the changes that were made to this document. It doesn't contain every single modification (use the CVS log for that), only the big picture.
openMSX is developed using the tools SourceForge.net freely offers to open source projects. The code is stored in CVS, an open source version management system. Once in a while an openMSX release is made.
There are several options for getting the source code:
tar.gz archive.
A snapshot is therefore quite similar to a CVS checkout,
but it doesn't require you to install and use CVS. It may lag a couple of days from the latest CVS sources. Moreover, SF.net staff recently turned off cron jobs, which means the snapshots are now updated on a very irregular basis.
Releases are intended for general users, CVS and CVS snapshots are intended for (would be) developers, heavy testers and people who want to follow new developments closely. It might be a good idea to play with a release first. If you like what you see and want to get in deeper, you can switch to CVS later. If you update often, it is best to use a CVS checkout rather than a CVS snapshot, because with a checkout you can do efficient incremental updates, saving network bandwidth and compile time.
If you downloaded a version that is either a lot older or a lot newer than
this guide, it is a good idea to read the guide included in your downloaded
version instead of the version you're reading right now.
You can find the Compilation Guide in the directory
openMSX/doc/manual.
You can download a released version of openMSX from the download page at SourceForge. The latest version is probably the best one. This guide assumes that you are using the latest release.
After downloading, type:
in which VERSION is the openMSX version you downloaded,
or use the file name you saved the tar.gz file with.
The directory that is created by uncompressing the tar.gz file
is called the top of the source tree.
Getting a CVS checkout means you use CVS to retrieve the latest version
of the source code of openMSX.
This means you will need to install a CVS client.
This package is usually simply named cvs.
There are graphical front-ends for CVS,
but this guide will tell you how to use CVS from the command line.
More information about CVS can be found on the
CVS Home site.
With the following line you can login to the openMSX CVS server:
In this line you specified where you want to retrieve the files from
(host name of the CVS server),
as who you want to retrieve the stuff
(since you're not a developer, anonymous will do),
and what project you want to retrieve (openmsx in this case).
You will be prompted for a password.
The password for user anonymous is empty, so just press enter.
Example output:
Now you can retrieve the latest sources with the following command:
This will create a directory called openMSX for you
in the current directory.
This directory created by CVS is the called top of the source tree.
In addition to the openMSX code, you will see CVS administration directories
which are all called CVS.
Do not mess with these, otherwise CVS will get confused.
If you want to update your source tree later, go to the top of the source tree and type:
The -d option tells CVS to check out new directories that were
created since your last checkout/update.
First, download the most recent CVS snapshot.
After downloading, type:
The directory that is created by uncompressing the tar.gz file
is called the top of the source tree.
Before you can start compiling openMSX, you have to make sure your system has all the necessary build tools installed, as well as the libraries openMSX depends upon. The following sections list the packages you need.
For compilation, you need Make and a C++ compiler. If you have compiled packages from source before, you probably have these installed already.
Install the Xcode Tools from Apple, which you can download from the Apple Developer Connection (free registration required). This package contains up-to-date versions of Make, GCC and CVS. If you are running Mac OS X 10.4 (Tiger), Xcode should be installable from the installation CD.
openMSX depends on several libraries.
You must have the runtime packages of these libraries install to be
able to run openMSX.
The runtime package for the "Foo" library is typically called
libfoo.
Also, for compiling openMSX you need the development packages of these
libraries installed as well.
Development packages are typically named
libfoo-dev or libfoo-devel.
First of all, you need some SDL packages, the run time ones and also the developer packages. You need the general SDL libs and SDL_image. The exact names of the package are different for each distribution. On a Debian testing system, they are called:
Furthermore, you need the XML library and the PNG library:
Finally you will also need Tcl 8.4:
Tcl 8.3 will not work. For some reason, several distributions still ship Tcl 8.3, even though Tcl 8.4 was released in 2002. If that is the case for your distribution, you should install Tcl 8.4 from source; you can find it on the Tcl site.
openMSX can optionally use OpenGL for graphics.
If you want to use this, make sure you have both the runtime and development
packages for OpenGL installed.
If you have an nVidia card, go to the
nVidia web site
for drivers, which include an OpenGL implementation. ATI users can check out the ATI web site for drivers.
For other cards, try Mesa, which can be found in packages like
xlibmesa-gl and xlibmesa-gl-dev (Debian)
or XFree86-GLX and XFree86-GLX-devel (SUSE).
You can get the libraries from either
DarwinPorts
or
Fink. These are tools to give you access to a large collection of software packages (or ports). You can use them to install those packages (or ports).
If you are using DarwinPorts, you should install the ports
libpng, libsdl and libsdl_image.
If you are using Fink, you should install the packages
libpng3, sdl and sdl-image.
Now that all the necessary tools and libraries are installed, you are almost ready to start the actual compilation of openMSX.
The first thing you may want to know is that you can build openMSX in different flavours. The default flavour for each platform will probably OK for most cases. For the Linux-on-x86 platform the default flavour is "i686": i.e., with optimisations for Pentium II and higher, without any debugging stuff. If you are a tester, you should set the flavour to "devel", like this:
This will enable debugging symbols and asserts. Although the default
flavours will probably be OK for most cases, you may want to write a
specific flavour for your particular wishes. Check out the examples in
the build directory.
Now, we have the option to let a script check if you have indeed all necessary libraries and headers installed. Go to the top of your openMSX source tree and run the following script:
This script will report what versions of libraries you have installed. It also reports which components can be built with those libraries. If the script reports that it can't build the openMSX core component, you should install the missing ones before you can continue. Otherwise, you can decide to install the libraries needed for the optional components, or to continue without building some components (e.g. the OpenGL renderer).
If installing the correct libraries doesn't help,
contact the openMSX developers.
If you file a bug report, please attach the probe.log file
that is written by the configure script in the directory
derived/[PLATFORM]-[FLAVOUR]/config/.
You can customise the build process by editing the file
build/custom.mk.
Currently, there is one thing you can customise there:
the installation directory (INSTALL_BASE).
If you are installing openMSX on a system on which you do not have
superuser (root) privileges, you can set the installation directory
to a subdirectory of your home directory.
After successfully running configure,
it's time to compile everything.
To start compilation, type:
Depending on how fast your system is, this may take several minutes to half an hour.
If you get errors during compilation, there may be something wrong that was not detected by configure. Verify that you installed all required libraries, both the run time and development packages. If that doesn't help, or we forgot to list a library openMSX depends on, contact the openMSX developers. Make sure you provide us with the error message you got.
The steps above apply to Mac OS X as well.
If you have a G4 or better CPU, using export OPENMSX_FLAVOUR=ppcg4 may give you a faster openMSX executable.
To install openMSX, run the following command:
This installs openMSX, by default in /opt/openMSX.
Note that only root has rights to write to system-wide directories such as
/opt,
so you may have to do su before make install.
The easiest way to install openMSX system-wide is this command:
If all went well, you should have openMSX installed now. You can test it by executing openMSX from the command line:
You should get a screen similar to this:
C-BIOS 0.20 cbios.sf.net
[C-BIOS logo]
No cartridge found.
Please restart your MSX (or emu-
lator), with a cartridge inser-
ted.
C-BIOS MSX2+ is the default system BIOS used by openMSX. It was written from scratch by BouKiCHi and he was kind enough to let us distribute it together with openMSX. It is not perfect yet, but it runs many ROM games well. Nowadays C-BIOS is a separate SourceForge.net project, with its own web page.
If you have a ROM image ready, you can try to run it with C-BIOS:
The next step would be to read the openMSX Setup Guide. That document describes how you can configure openMSX to emulate actual MSX machines, such as the Panasonic FS-A1GT (turboR). It also describes how you can have openMSX start up with your personal settings, how you can configure openMSX and your system for optimal performance and several other configuration related topics. And finally there is of course the openMSX User's Manual, which describes all the things you can do with openMSX once it is fully running.
If you got stuck somewhere in the compilation and installation process, please contact us. The next chapter will tell you how.
By default openMSX will not be in your search path. So to start it, you will have to specify the full path on the command line. For example:
Since openMSX is still in heavy development, feedback and bug reports are very welcome!
If you encounter problems, you have several options:
openmsx-user mailing list.
More info on the
openMSX mailing lists,
including an archive of old messages, can be found at SourceForge.
#openMSX on irc.freenode.net
and ask your question there.
openmsx-devel mailing list.
More info on the
openMSX mailing lists,
including an archive of old messages, can be found at SourceForge.
For experienced users: if you get a crash,
try to provide a gdb backtrace.
This will only work if you did not strip the openMSX binary
of its debug symbols.
In any case, try to give as much information as possible when you describe your bug or request.
$Id: compile.html,v 1.22 2005/06/06 20:57:03 manuelbi Exp $