# openMSX Compilation Guide

## Contents

## 1. Introduction

### 1.1 New Versions of this Document

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.

### 1.2 Purpose

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:

Linux
  Most openMSX developers run some form of Linux, so this is the platform on which compilation is supported best.
Windows
  Windows is also a supported platform for openMSX. Most Windows users will just download the binary release. But if you want to follow the latest developments or like to play with the code a bit, it is possible to compile openMSX on Windows yourself. For this you need MSYS and a variety of libraries.
Mac OS X
  You can compile openMSX on Mac OS X. Nowadays we have at least one developer that runs Mac OS X and as a result support for Mac OS X has improved a lot in openMSX 0.5.1. However, we do not have a binary package or a GUI yet, so you will have to use openMSX from the command line for now.
  This manual contains all the essential info to compile openMSX on Mac OS X. However, if you are not experienced in compiling software yourself, there is a nice article at The MSX Games bOX which explains everything in more detail.
FreeBSD/NetBSD/OpenBSD
  openMSX was compiled successfully on FreeBSD 4 and 5 and OpenBSD. NetBSD build support is also integrated and should work as well, but we cannot easily test this. These are not platforms we support officially, but whenever a user finds compilation problems, we fix them, so usually compilation should work.
other operating systems
  openMSX theoretically can compile on every system where you have g++ (the C++ compiler of GCC) and the required libraries are available. However, in practice every system is slightly different and a new operation system will not work out-of-the-box, especially because we have to explicitly add an integration file for each OS to support it. Still, it shouldn't take much effort to make openMSX build on a new OS.

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.

### 1.3 Contributors

The following people contributed to this document in one way or another:

- Jorrith Schaap
- Manuel Bilderbeek
- Maarten ter Huurne
- other openMSX developers

Thanks to all of them!

### 1.4 Revision History

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.

2005-02-19: Manuel Bilderbeek
  Updates for release 0.5.1. OpenBSD is also integrated now and we also support Mac OS X better.
2004-04-21: Manuel Bilderbeek
  Updates for release 0.4.0. The compilation method has changed quite a lot.
2004-01-16: Manuel Bilderbeek
  Updates for release 0.3.4.
2003-07-06: Maarten ter Huurne
  Split the Compilation Guide off from the openMSX HOWTO. Converted to XHTML. Restructured the document. Rewrote some text to fit better in the new structure and format.
2002, 2003: Manuel Bilderbeek & others
  Various updates to the HOWTO.
2002: Manuel Bilderbeek & Jorrith Schaap
  Original text written as part of the openMSX HOWTO.

## 2. Getting the Source Code

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:

Released Version
  These are tested versions, which should give you little problem compiling and running. However, as openMSX development if often quite fast, they may not have all the latest features. Also there could be bugs that have been fixed since the last release.
CVS Checkout
  Through anonymous CVS you can get the same development version the openMSX developers are using, although most of the time it lags at least a few hours behind the current state of affairs. This is the bleeding edge: the latest stuff, which may be great or may be horribly broken. Usually openMSX CVS compiles and runs fine, but we're only human, so once in a while it breaks. Also there may be changes that are not documented yet.
CVS Snapshot
  A snapshot is created from a recent CVS checkout, in a `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`.

### 2.1 Released Version

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:

tar xzvf openmsx-VERSION.tar.gz

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.

### 2.2 CVS Checkout

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:

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/openmsx login

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:

jorrith@jardel openmsx $ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/openmsx login
Logging in to :pserver:anonymous@cvs.sourceforge.net:2401/cvsroot/openmsx
CVS password:
jorrith@jardel openmsx $

Now you can retrieve the latest sources with the following command:

cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/openmsx checkout openMSX

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:

cvs update -d

The `-d` option tells CVS to check out new directories that were created since your last checkout/update.

### 2.3 CVS Snapshot

First, download the most recent CVS snapshot.

After downloading, type:

tar xzvf openMSX-CVS-snapshot.tar.gz

The directory that is created by uncompressing the `tar.gz` file is called the top of the source tree.

## 3. Compilation

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.

### 3.1 Build Tools

For compilation, you need Make and a C++ compiler. If you have compiled packages from source before, you probably have these installed already.

make
  GNU implementation of the Make tool. Make interprets rules that define how a project should be built. At least version 3.79 and higher should suffice.
g++
  The GNU C++ compiler. Version 3.2 or later is recommended; 2.95 is not supported anymore since openMSX 0.3.4.

##### Mac OS X

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.

### 3.2 Libraries

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:

libsdl1.2debian and libsdl1.2-dev
  Simple DirectMedia Layer.
libsdl-image1.2 and libsdl-image1.2-dev
  Image loading library for SDL.

Furthermore, you need the XML library and the PNG library:

libxml2 and libxml2-dev
  XML C library, originally developed for GNOME.
libpng12-0 and libpng12-dev
  Library for handling PNG images.

Finally you will also need Tcl 8.4:

tcl8.4 and tcl8.4-dev
  Tcl (the Tool Command Language) v8.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).

##### Mac OS X

You can get the libraries from either DarwinPorts or Fink. 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`.

### 3.3 Compilation Itself

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:

export OPENMSX_FLAVOUR=devel

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:

./configure

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:

make

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.

##### Mac OS X

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.

## 4. Installation

To install openMSX, run the following command:

make install

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

##### Mac OS X

The easiest way to install openMSX system-wide is this command:

sudo make install

## 5. Next Steps

If all went well, you should have openMSX installed now. You can test it by executing openMSX from the command line:

openmsx

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:

openmsx ~/msx/games/my-favourite-game.rom

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.

##### Mac OS X

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:

/opt/openMSX/bin/openmsx

## 6. Contact Info

Since openMSX is still in heavy development, feedback and bug reports are very welcome!

If you encounter problems, you have several options:

1. If you're a regular user and want to discuss openMSX and possible problems, join our `openmsx-user` mailing list. More info on the openMSX mailing lists, including an archive of old messages, can be found at SourceForge.
2. Go to our IRC channel: `#openMSX` on `irc.freenode.net` and ask your question there.
3. If you want to address the openMSX developers directly, post a message to the `openmsx-devel` mailing list. More info on the openMSX mailing lists, including an archive of old messages, can be found at SourceForge.
4. Use one of the openMSX trackers at SourceForge. At the moment of writing, there are four trackers: Bugs, Support Requests, Patches and Feature Requests.
5. Post a message on the openMSX forums 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.20 2005/02/25 04:28:30 mthuurne Exp $