openMSX Catapult Compilation Guide

# Catapult Compilation Guide

## Contents

## 1. Introduction

### 1.1. New Versions of this Document

The latest version of the openMSX Catapult manual can be found on the openMSX home page:

http://openmsx.sourceforge.net/catapult-manual/

The latest version of the openMSX manual can also be found there:

http://openmsx.sourceforge.net/manual/

You can also use these URLs to get up-to-date versions of the hyper links if you printed out this manual.

### 1.2. Purpose

This guide is about Catapult, the (optional) GUI for openMSX. 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. That's why we decided to create a GUI for it, so most users can use it a little bit more comfortably. For people who want to (or have to) compile Catapult themselves, we have written this guide. It explains how you can get it running on your system, i.e. how to get the sources and compile them. Note that some software distributions may have packaged openMSX Catapult 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 Catapult. If you use such a package, you can skip the largest part of this manual and start reading at chapter 5. Next Steps.

This guide describes how you can get the openMSX sources and compile them. 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. Compilation instructions for Linux are mostly also valid for other UNIX-like operating systems.
Windows
  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 Catapult on Windows yourself. The former main Catapult developer used mainly Windows, so compilation is very well supported on this platform as well. This manual gives a few pointers in the right direction for that.
FreeBSD
  Catapult was compiled successfully on FreeBSD 4 and 5. FreeBSD is not a platform we support officially, but whenever a user finds compilation problems on FreeBSD, we fix them, so usually FreeBSD compilation should work.
Mac OS X
  Unfortunately, we have not been able to get Catapult working on Mac OS X. There is a port of wxWidgets (the base of Catapult), but version 2.4 doesn't support toggle buttons yet and we did not get the menu working (amongst other things) with version 2.6.
other operating systems
  Catapult 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. Still, it shouldn't take much effort to make Catapult build on a new OS.

If you need help compiling Catapult, please contact us. If you needed any modifications to make Catapult compile, please send those modifications to us, so we can make Catapult 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 Catapult (and with that openMSX) more.

### 1.3. Contributors

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

- Herman Oudejans
- 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 SVN log for that), only the big picture.

2004-04-25 Herman Oudejans
  Initial version based on the openMSX manuals by Manuel Bilderbeek, Jorrith Schaap and Maarten ter Huurne.
2004-10-04 Herman Oudejans
  Added touch.exe to the compilation packages
2005-02-06 Herman Oudejans
  Updated this manual for compilation with wxWidgets 2.5 and for compilation with MinGW.
2005-12-30 Manuel Bilderbeek
  Updates for compilation with wxWidgets 2.6.
2009-04-26 Max Feingold
  Updates for compilation with SVN and Visual C++.
2010-06-20 Max Feingold
  Updates for compilation with Visual C++ 2010.

## 2. Getting the Source Code

Catapult is a sub-project of openMSX, developed using the tools SourceForge.net freely offers to open source projects. The code is stored in Subversion, an open source version management system. Catapult is released at every openMSX release. It can be released in between openMSX releases as well, if there is a lot of development that we want to share with the users without waiting for the next openMSX release.

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 Catapult development is 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 Catapult developers are using. This is the bleeding edge: the latest stuff, which may be great or may be horribly broken. Usually Catapult 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`.

### 2.1. Released Version

You can download a released version of Catapult from the openMSX download page at SourceForge. The latest version is probably the best one. At least try to get one matching the version of openMSX you are using.

After downloading, type:

tar xzvf Catapult-VERSION.tar.gz

in which `VERSION` is the Catapult 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.

Note: Windows doesn't natively support tar or gzip, but there are enough utilities available to decompress these sources anyway. Examples of such utilities are PowerArchiver 6.1 (free), Wiz (free), 7-Zip (free) or WinZip (commercial).

### 2.2. SVN Checkout

Getting a SVN checkout means you use SVN to retrieve the latest version of the source code of Catapult. 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 SlikSVN for a command line tool, TortoiseSVN for Windows Explorer integration, or ankhSVN for Visual Studio integration.

With the following line you can retrieve the latest sources:

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

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 (wxcatapult in this case, which is the module that contains the sources of the main Catapult 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 wxcatapult in this example).

In TortoiseSVN, use `https://openmsx.svn.sourceforge.net/svnroot/openmsx/wxcatapult/trunk` as the "URL of repository" and the directory of your choice as the "Checkout directory". Use the `HEAD` revision and click OK. When compiling Catapult on Windows with gcc, it's often convenient to use `C:\msys\1.0\home\<username>\wxcatapult` as the checkout directory, as this is easy to reach from an MSYS shell - it's your MSYS home directory.

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 `wxcatapult` for you in the current directory (or in the "Checkout directory" you specified in TortoiseSVN). In addition to the Catapult 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 right click on the wxcatapult directory in Windows Explorer and select "SVN Update".

### 2.3. SVN Snapshot

Snapshots for this version of Catapult are not available anymore, because we are working on a total rewrite of Catapult. It doesn't seem useful to provide snapshots for sources that do not change anymore. You can download an SVN snapshot of the Catapult rewrite from the openMSX web site.

## 3. Compilation

Before you can start compiling Catapult, you have to make sure your system has all the necessary build tools installed, as well as the libraries Catapult depends upon. The former you have probably already done if you have compiled openMSX itself before Catapult. The following sections list the packages you need.

### 3.1. Build Tools

For compilation, you need Python, a C++ compiler, and some compiler-specific programs. If you have compiled packages from source before, you probably some of have these installed already.

Python
  A compact and dynamic programming language. Version 2.5 or later is required. However, Python 3.0 contains incompatible changes in the language, so make sure you install a version from the 2.x series. Eventually Python will replace Make completely in our build system, but at the moment both are required.
There are two compilers that are can be used to build Catapult: gcc and Visual C++. The gcc compiler builds Catapult on all supported platforms, while Visual C++ is an alternative option on Windows.

#### gcc

For compilation in Linux, you need Make and a C++ compiler. If you have compiled packages from source before (like openMSX), you probably have these installed already.

make
  GNU implementation of the Make tool. Make interprets rules that define how a project should be built.
g++
  The GNU C++ compiler. Version 3.2 or later is necessary; 2.95 is not supported for openMSX, so we also don't support it for Catapult. To be on the safe side: we recommend 3.4 or later.

For compilation in Windows you will need the combination of Minimal System (msys) and Minimalist GNU for Windows (MinGW). This is the same combination that is needed to compile openMSX on Windows. Although compilation works, the generated executable will be larger than the binary released version (which is compiled with Visual C++) and will also need the MinGW runtime DLL.

#### Visual C++

There are three different ways to obtain the Visual C++ compiler:

Visual C++ 2010
  This is the professional IDE and development environment that comes with Visual Studio, as a standalone purchase or via an MSDN subscription.
Windows SDK
  This is a free (as in beer) command line environment that provides a full set of compilers, headers and libraries. This is the best option for people who wish to build openMSX with minimal hassle. We recommend using the Microsoft Windows SDK for Windows 7 and .NET Framework 4 or newer. (When installing, the Documentation, Samples and .NET Development Tools options are not required to build openMSX. This reduces the download size considerably, from about 1.2GB to about 100MB.)
Visual C++ 2010 Express
  This is a free (as in beer) IDE and development environment. It builds 32-bit binaries out of the box, and can be made to build 64-bit binaries with some coaxing. This is the best option for developers looking to browse the source code or use other benefits of an IDE.

To build with Visual C++ from the command line, you need to open a Visual Studio command prompt. A shortcut for this can usually be found in your start menu. For Visual C++ 2010, it will be in "Microsoft Visual Studio 2010\Visual Studio Tools" as the "Visual Studio Command Prompt". For the Windows SDK, it will be in "Microsoft Windows SDK vX.Y" as the "CMD Shell".

When building with Visual C++, the result is a static executable with minimal dynamic library dependencies. Two platforms are supported:

- Win32 - a 32-bit binary that runs on both 32 and 64-bit versions of Windows
- x64 - a 64-bit binary that runs only on 64-bit versions of Windows

Two different configurations are supported:

- Unicode Debug: assertions enabled, no optimization
- Unicode Release: assertions disabled, full optimization

### 3.2. Libraries

Catapult depends on a few libraries. Using Linux you must have the runtime packages of these libraries installed to be able to run Catapult. The runtime package for the "Foo" library is typically called `libfoo`. Also, for compiling Catapult you need the development packages of these libraries installed as well. Development packages are typically named `libfoo-dev` or `libfoo-devel`. Windows users need to have the proper DLL's installed (`foo.dll`) to be able to run Catapult. Compiling in Windows means that you also need the lib-files (`foo.lib`).

If there are no binary versions of the required libraries available for your system or you rather compile them yourself, please see the next section for a few hints about compiling them from their sources.

Catapult depends on the following libraries:

wxWidgets
  Formerly known as wxWindows, this is a cross-platform C++ GUI toolkit (GTK+ runtime).
libxml2
  XML C library, originally developed for GNOME.

##### Debian Linux

On a Debian testing system, the packages are called:

libwxgtk2.6-0
  This is the main runtime wxWidgets library
libwxgtk2.6-dev
  This package contains the necessary headers to compile.
libxml2 and libxml2-dev
  XML C library, originally developed for GNOME.

Although other versions are available, we recommend to use wxWidgets 2.6 (but 2.8 will probably also work).

##### Microsoft Windows

For Windows the wxWidgets package is called wxMSW. Version 2.8.9 is recommended (it's compatible with 2.6). Please read the next section for instructions for compiling wxWidgets from source.

For Windows, version 2.7.3 of libxml2 is recommended.

Unpack the source packages into the derived\3rdparty\src directory. This will generate two subdirectories called libxml2-2.7.3 and wxMSW-2.8.9.

### 3.3. Compilation of the Libraries

For some distributions it's necessary to manually compile the libraries. This section gives a few pointers to get it to work. It's not intended to be a substitute for the documentation supplied with the libraries. The wxWidgets sources can be found at wxWidgets Home and the libxml2 sources are available at Libxml2 Home.

Building the libxml2 library should be easy enough with the docs available. You can also use the libraries that are built in openMSX using the staticbindist method.

#### gcc

Compilation of wxWidgets couldn't be more straightforward. The docs provided are easy to follow and it takes only a few steps. There is no need to give any pointers here about this library as its documentation says exaclty how to compile it. We do give the proper `configure` command line here (although some options might be already default):

./configure --disable-shared --disable-unicode --enable-xrc --enable-controls --with-msw

#### Visual C++

The following steps build third-party libraries with Visual C++:

- Open a Visual Studio command prompt.
- Go to the top of the Catapult source tree
- Type `msbuild -p:Configuration="Unicode Release";Platform=Win32 build\3rdparty\3rdparty.sln`

To build for other platforms or configurations, simply replace "Unicode Release" and "Win32" in the command lines above with the desired options, which are explained above.

It is worth noting that running `msbuild` from a command line is exactly equivalent to opening the respective solution files in Visual C++ and compiling the projects inside them using the IDE.

### 3.4. Compilation Itself

#### gcc

We have made compilation of Catapult itself as easy as possible. In most cases Linux or msys users only have to open a shell, go to the top of the source tree and type:

make

You can build different flavours by setting the `CATAPULT_FLAVOUR` environment variable. The following values are supported:

debug
  No optimization and full debug symbols
devel
  Some optimization but still full debug symbols available (this is the recommended flavour for testing)
i686
  Fully optimized and no debug symbols (this is the default flavour)
opt
  Basically the same as i686, but also for non Intel targets
ppc
  Specifically for Power PC processors
win32
  Optimised for PIII but runnable with Pentium MMX and higher

Depending on how fast your system is, this may take several seconds to several minutes.

If you get errors during compilation, 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 Catapult depends on, contact the openMSX developers. Make sure you provide us with the error message(s) you got.

#### Visual C++

The following steps build Catapult with Visual C++:

- Open a Visual Studio command prompt.
- Go to the top of the Catapult source tree
- Type `msbuild -p:Configuration="Unicode Release";Platform=Win32 build\msvc\wxCatapult.sln`

To build for other platforms or configurations, simply replace "Unicode Release" and "Win32" in the command lines above with the desired options. Note: the options should be consistent with the ones you provided for the 3rdparty libraries build, see above!

It is worth noting that running `msbuild` from a command line is exactly equivalent to opening the respective solution files in Visual C++ and compiling the projects inside them using the IDE.

## 4. Installation

To install Catapult in Linux, run the following command:

make install

This installs Catapult, by default in `/opt/openMSX-Catapult`. You can change this location by modifying the `config.mk` file. 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`.

Catapult has no individual installation system on Windows, so it's up to you to make sure the files are in the right directory. Please follow these pointers to make sure it should work:

- The resources (XRC) should be in the directory (relative from `Catapult.exe`) `..\resources\dialogs`
- The bitmaps (png) should be in the directory (also relative from `Catapult.exe`) `..\resources\bitmaps`

#### gcc

- `Catapult.exe` and `libxml2.dll` (or `libxml2-2.dll`) should be in the same directory or `libxml2.dll` should be somewhere in your path
- The same goes for `mingwm10.dll`, when compiling with MinGW

## 5. Next Steps

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

catapult

or by double clicking the icon in Windows.

Using Catapult should be intuitive, but if it's not, please read the Catapult User's Manual. This should give a complete description on how to use Catapult.

If you got stuck somewhere in the compilation and installation process, please contact us. The next chapter will tell you how.

## 6. Contact Info

Since Catapult is still under 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.

In all cases, please provide as much information as possible when you describe your bug or request.

#### gcc

For experienced users: if you get a crash or a hang, 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.

#### Visual C++

For experienced users: if you get a crash or a hang, try to provide a user dump. This will work for any openMSX binary, including pre-built binaries obtained from www.openmsx.org. For more information on generating a user dump, please read KB286350.

$Id: compile.html 11539 2010-06-21 01:15:44Z mfeingol $