# 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, because 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
  Since openMSX 0.6.0 we have a binary package for PPC and since openMSX 0.6.1 a universal binary. But if you like to make changes to the openMSX source code or follow the latest developments inbetween releases, you can compile openMSX yourself.
  We do not have a GUI yet that works on Mac OS X, so you can either use openMSX from the command line for now, or use third party software like Nekolauncher openMSX or openMSX Peashooter.
FreeBSD/NetBSD/OpenBSD
  openMSX was compiled successfully on FreeBSD 4 and 5 and OpenBSD. In FreeBSD 6, openMSX can even be found in the ports tree. 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

For the revision history, please refer to the SVN log.

## 2. Getting the Source Code

openMSX is developed using the tools SourceForge.net freely offers to open source projects. The code is stored in Subversion (SVN), 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.
SVN Checkout
  Through SVN you can get the same development version the openMSX developers are using. This is the bleeding edge: the latest stuff, which may be great or may be horribly broken. Usually openMSX SVN 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.
SVN Snapshot
  A snapshot is created from a recent SVN checkout, in a `tar.gz` archive. A snapshot is therefore quite similar to a SVN checkout, but it doesn't require you to install and use SVN. It may lag a couple of days from the latest SVN 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, SVN and SVN 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 SVN later. If you update often, it is best to use a SVN checkout rather than a SVN 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 SVN Checkout

Getting a SVN checkout means you use SVN to retrieve the latest version of the source code of openMSX. This means you will need to install an SVN client. This package is usually named `subversion`. There are graphical front-ends for SVN, but this guide will tell you how to use SVN from the command line. More information about SVN can be found on the Subversion book site. Windows users might want to look at TortoiseSVN.

With the following line you can retrieve the latest sources:

svn co https://openmsx.svn.sourceforge.net/svnroot/openmsx/openmsx/trunk openMSX

In this line you specified where you want to retrieve the files from (host name of the SVN server), what project you want to retrieve (openmsx in this case), what module you want to get (openmsx in this case, which is the module that contains the sources of the main openMSX program), which branch you want to retrieve (trunk in this case, which is the main development branch) and what directory it should be checked out to (we chose openMSX in this example).

If you're a developer, it makes sense to add the following option as well:

--username <name-of-your-sourceforge-account>

The SVN command created a directory called `openMSX` for you in the current directory. In addition to the openMSX code, you will see hidden SVN administration directories which are all called `svn` or `.svn`. Do not mess with these, otherwise SVN will get confused. This directory created by SVN is what we will call in this manual the top of the source tree.

If you want to update your source tree later, go to the top of the source tree and type:

svn up

### 2.3 SVN Snapshot

First, download the most recent SVN snapshot.

After downloading, type:

tar xzvf openmsx-SVN-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 as of 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 SVN. If you are running Mac OS X 10.4 (Tiger), Xcode should be installable from the installation CD.

### 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. Since openMSX 0.6.1, we use the GLEW library (version 1.3.2 or later, 1.3.4 recommended) to handle OpenGL extensions:

libglew1 and libglew-dev
  The OpenGL Extension Wrangler.

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 `libgl1-mesa-glx` and `libgl1-mesa-dev` (Debian) or `Mesa` and `Mesa-devel` (SUSE). However, nowadays there is a big chance that your system already has hardware accelerated OpenGL supported in the default installation of your Xorg or Windows environment. Just make sure you install the development header files for the OpenGL library if you want to compile openMSX with support for it.

##### Mac OS X

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

##### Microsoft Windows

If you want to build SDL yourself, please check out the patch which you can find in the directory `doc.dll\libSDL`. Apply this patch to the extracted `libSDL-1.2.9.zip`. Make sure you have the DirectX headers installed, see also this README.txt. After that, build it like this:

./autogen.sh
./configure --enable-stdio-redirect=no
make
make install

The other libraries can be downloaded in binary and source form from several places.

### 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. A final note: on an older VIA Epia (with the Samuel 2 CPU at least), a binary built with i686 flavour will not run. Please use the "opt" flavour for that platform.

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 based renderers).

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/<cpu>-<os>-<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 PPC CPU, using `export OPENMSX_FLAVOUR=ppcg4` may give you a faster openMSX executable.

By default, openMSX is compiled for the type of CPU that is present in your Mac. If you want to build for a different CPU, use `export OPENMSX_TARGET_CPU=ppc` (PowerPC) or `export OPENMSX_TARGET_CPU=x86` (Intel). If you want to build a universal binary, use `export OPENMSX_TARGET_CPU=univ`.

By default, only the openMSX executable itself is produced. If you want to create an application folder, define `export OPENMSX_TARGET_OS=darwin-app` before compilation.

The normal build will link dynamically against the libraries available on your Mac. So if someone else wants to run the binary you built, that person has to install the same libraries. If you want a binary that does not have these external dependencies, read the chapter about building a stand-alone binary.

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

If you defined `export OPENMSX_TARGET_OS=darwin-app`, `make install` will create an application folder in `derived/<cpu>-darwin-app-<flavour>/bindist`. No `sudo` is needed.

## 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.21        cbios.sf.net

    No cartridge found.

    This version of C-BIOS can
    only start cartrdiges.
    Please restart your MSX
    (emulator) with a cartridge
    inserted.

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

If you built an application folder, you can run it from Finder or from the command line:

open derived/<cpu>-darwin-app-<flavour>/bindist/openMSX.app

## 6. Stand-alone Binary

This chapter describes how to build a binary of openMSX that does not depend on any library except those that are available on the platform by default. This procedure has only been implemented for Mac OS X, but it could be expanded for other operating systems without too much effort.

The stand-alone binary is made by linking statically against all libraries which are not available as part of the basic platform. The build system will automatically download the sources for these libraries and build them in the minimal configuration needed by openMSX. If you want to change something about this process, for example switch to a newer library release, edit the `build/3rdparty.mk` Makefile.

To build a stand-alone binary, run `make staticbindist`. Just like for normal compilation, you can set `OPENMSX_TARGET_CPU` to `ppc`, `x86` or `univ` to build for a different CPU. The files will be produced in `derived/<cpu>-darwin-app-<flavour>/bindist`.

The stand-alone binary will be built in the special `bindist` flavour, which is optimized to give a good balance between speed and size. You can override it only by passing another flavour to Make like this: `make staticbindist OPENMSX_FLAVOUR=<flavour>`.

The final output of `make staticbindist` is a DMG file in `derived/<cpu>-darwin-app-<flavour>/bindist`. This file is internet-enabled, which means it will be automatically mounted after it is downloaded.

## 7. 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 forum on www.openmsx.org.

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. Another useful thing to do is to install the debug versions of libstdc++ and libc6, and then run openmsx with an `LD_LIBRARY_PATH=/usr/lib/debug` exported in the environment. This will give a more detailed stacktrace, especially in optimized code.

In any case, try to give as much information as possible when you describe your bug or request.

$Id: compile.html 6286 2007-04-10 00:17:45Z mthuurne $