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

If you just want to use openMSX, there is likely a pre-packaged version you can use. This document describes how you can compile openMSX from source, which is useful if:

- There is not yet a pre-packaged version for your favourite platform.
- You want to closely follow the latest developments.
- You want to make changes to openMSX.

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.

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

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 tell you how you can prepare your system.

Every section starts with generic instructions, that apply to all platforms. At the end of each section, platform specific notes cover differences or additional steps for certain platforms.

### 2.1 Build Tools

For compilation, you need GNU 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. Version 3.79 or higher should suffice.
`g++`
  The GNU C++ compiler. Version 4.1 or later is recommended; any version lower than 3.4 will not be able to build openMSX at all.

##### Mac OS X

Install the Xcode Tools from Apple, which you can find on the Mac OS X installation DVD. Alternatively, you can download it from the Apple Developer Connection (free registration required). The Xcode Tools package contains up-to-date versions of Make, GCC and SVN. If you are running Mac OS X 10.5 (Leopard), make sure you also install support for compiling for Mac OS X 10.3 (Panther), which is an optional component.

Note that Mac OS X 10.3 uses GCC 3.3 as the system compiler, which is not able to compile openMSX. The easy solution for this is to use a Mac with OS X 10.4 or 10.5 and compile a stand-alone binary (see next section), which will run on 10.3 as well. An alternative would be to get a more recent GCC running on OS X 10.3, but that seems to be problematic.

##### Microsoft Windows

You need to install MinGW, MSYS and cURL.

You can download MinGW and MSYS from the download page of the MinGW project. Download the latest version of the "Automated MinGW Installer" (5.1.4 is the latest at the time of writing) and download also "MSYS Base System" (use 1.0.10, because 1.0.11 seems to give problems and doesn't have an installer yet anyway). Double click on the MinGW package after downloading, choose "Download and Install", Package "Current" and add component "g++". Use the default installation directory (`C:\MinGW`), or at least a directory without spaces and not a network folder (i.e. shared folder on another computer). For MSYS, the installer's default settings (destination directory `C:\msys\1.0`) will be OK. If you get questions in a post-install Command Prompt dialog, type: `y`, `y`, `C:/MinGW` (or the other directory you chose without spaces; but do note that you should use forward slashes in the path here!), `y`.

Note: there is a bug in the MinGW Runtime (mingwrt) package version 3.15.1, which will cause FreeType not to compile (and probably more). This has been reported here and the fix in the code can be found here. You need to apply this small fix to your MinGW `stdlib.h` header file in order to be able to compile openMSX, if you are using this version of the MinGW run time package.

The openMSX build system for Windows will use the program cURL to download the source code of the 3rd party libraries that openMSX is depending on. You need to have it in your default search path of Windows (or, if you're lazy, put it in the top of the openMSX source tree, see below to find out what this means). You can download a binary of cURL from its download page. Use a binary from the "Win32 - Generic" category, near the bottom of the web page. Use one without SSL, otherwise you may get errors about `libeay32.dll` not getting found. (Currently, the top one is OK.)

### 2.2 Libraries

openMSX depends on the following libraries:

SDL
  Simple DirectMedia Layer, a cross-platform library that provides low-level access to video, audio and input devices.
SDL_image
  Library that integrates image reading and writing with SDL. SDL_image can support many image formats, but openMSX only requires PNG support.
SDL_ttf
  Library that provides support for TrueType Fonts in SDL.
libpng
  Library for handling PNG images.
libxml2
  XML C library, originally developed for GNOME.
zlib
  Library for file compression.
Tcl
  The Tool Command Language, an embeddable scripting language. openMSX requires Tcl 8.4; version 8.3 will not work.
OpenGL (optional)
  Library for accelerated graphics. It is likely that OpenGL is already installed on your system. If not, you should probably get the OpenGL implementation from the manufacturer of your graphics card. On Linux, using Mesa with a DRI driver can be an alternative.
GLEW (optional)
  The OpenGL Extension Wrangler, a library that greatly simplifies the use of OpenGL extensions.
JACK (optional)
  The JACK Audio Connection Kit is a sound server that provides low latency connections between audio applications. Currently openMSX can use JACK only for connecting the cassette port (CassetteJack).

You can install the required libraries systemwide, or you can use the "3rd party libraries" support in the openMSX build system and build a stand-alone binary. Systemwide is recommended if you run a modular operating system (such as Linux, BSD or Mac OS X with MacPorts or Fink) and you intend to only use the openMSX binary on your computer. The 3rd party library system is recommended if you build for other operating systems (Windows, plain Mac OS X or embedded systems) or if you want to build a binary that can be used on other computers besides your own. If you choose the latter, please skip to the Stand-alone Binary chapter.

##### Debian and Ubuntu Linux

You can easily install all required packages using the "build dependencies" feature of the APT package manager:

sudo apt-get build-dep openmsx

##### Other Linux

Most Linux distributions have libraries split over two packages: a runtime package and a development package. The runtime package for the "Foo" library is typically called `libfoo`, the development package is typically named `libfoo-dev` or `libfoo-devel`. Applications that use a library only require the runtime package to be installed, but compilation requires both the runtime package and the development package to be installed.

##### Mac OS X

The easiest thing to do is to use the stand-alone binary method, which will get the libraries automatically. If you want to do things manually, you can get the libraries from either MacPorts 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 MacPorts, 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

We strongly recommend to use the stand-alone binary method, which means the openMSX build system will download and compile all libraries automatically.

## 3. 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 turned off cron jobs, which means the snapshots may be 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 `doc/manual`.

### 3.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. This works in a UNIX or MSYS shell, you can also use another decompression tool, of course. The directory that is created by uncompressing the `tar.gz` file is called the top of the source tree.

### 3.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).

In TortoiseSVN, use `https://openmsx.svn.sourceforge.net/svnroot/openmsx/openmsx/trunk` as "URL of repository" and e.g. `C:\msys\1.0\home\<username>\openMSX` (this is easy to reach from an MSYS shell, it's your MSYS home directory) as "Checkout directory". Use the `HEAD` revision and click OK.

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

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

The SVN command created a directory called `openMSX` for you in the current directory (or in the "Checkout directory" you specified in TortoiseSVN). 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 (nor move contents of this checkout directory around), 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

or rightclick on the openMSX directory in your Windows explorer and select "SVN Update".

### 3.3 SVN Snapshot

First, download the most recent SVN snapshot.

After downloading, type:

tar xzvf openmsx-SVN-snapshot.tar.gz

This works in a UNIX or MSYS shell, you can also use another decompression tool, of course. The directory that is created by uncompressing the `tar.gz` file is called the top of the source tree.

## 4. Binary for Local System

This section explains how to build openMSX for a local system. If you want to create a binary that runs everywhere, we recommend you to skip this chapter and use the stand-alone binary method. We also recommend to do that for Mac OS X and especially for Microsoft Windows systems.

### 4.1 Compilation

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 depends on the CPU, but is always one that is optimized for performance. For example for x86 processors the default flavour is "i686": i.e., with optimisations for Pentium II and higher, without any debugging stuff. 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.

If you are testing new openMSX developments or making changes in openMSX, you can benefit from asserts and debug symbols. To get those, you should select the "devel" flavour, like this:

export OPENMSX_FLAVOUR=devel

Although the default flavours will probably be OK for most cases, you may want to write a specific flavour for your particular wishes. The flavour files are all named `build/flavour-*.mk`.

You can select the C++ compiler to be used like this:

export OPENMSX_CXX=g++-4.2

This can be useful if the default compiler on your system is an old GCC version which is either not capable of compiling openMSX, or generates less efficient code.

Now we can 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`. The most likely thing you might want to customise is 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

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

If you have a G4 or better PPC CPU, using `export OPENMSX_FLAVOUR=ppcg4` may give you a faster openMSX executable.

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. This application folder will still depend on the systemwide libraries, so it will not work on Macs without those libraries. But unlike the plain executable, it has a high resolution icon.

### 4.2 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`, or use `sudo`.

##### 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. 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 is recommended to use on Mac OS X and especially on Microsoft Windows.

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.

Just like for normal compilation, you can set environment variables such as `OPENMSX_FLAVOUR`, `OPENMSX_CXX`, `OPENMSX_TARGET_CPU` and `OPENMSX_TARGET_OS`.

To build a stand-alone binary, run the following command at the top of the source tree:

make staticbindist

The final output files will be produced in `derived/<cpu>-<os>-<flavour>-3rd/bindist`.

##### Mac OS X

The final output is a DMG file (Mac disk image) containing the openMSX application folder and documentation. This file is internet-enabled, which means it will be automatically mounted after it is downloaded.

##### Microsoft Windows

Here's the very short version if you want quick results on Microsoft Windows:

- open an MSYS shell
- go to the top of the source tree (e.g.: `cd openMSX` if you chose the MSYS home directory as checkout directory)
- type: `make staticbindist`

You get a complete package in `derived\x86-mingw32-i686-3rd\bindist\install`.

If you additionally want to build the openMSX installer, you should refer to the `package-win32` module in our Subversion repository. It contains a README file with a manual.

## 6. Next Steps

If all went well, you should have openMSX installed now or have a stand alone working binary. You can test it by executing openMSX from the command line:

openmsx

or, by double clicking the openMSX executable that resulted from the previous step.

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

or, you can just drop it on the openMSX executable.

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

We do not have a finished 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.

## 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. Also reachable via Mibbit! If you don't get a reply immediately, please stick around for a while, or ask your question on the mailinglist (see below).
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 8405 2008-12-12 18:09:44Z manuelbi $