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.
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:
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.
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.
Catapult is a sub-project of openMSX, developed using the tools SourceForge.net freely offers to open source projects. The code is stored in CVS, 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:
tar.gz
archive. A snapshot is therefore quite similar to a CVS checkout, but it
doesn't require you to install and use CVS.
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
Catapult/doc/manual.
You can download a released version of Catapult from the 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:
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).
Getting a CVS checkout means you use CVS to retrieve the latest version of the
source code of Catapult.
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. On this site you can also find
a CVS command line tool for Windows.
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, since Catapult is a sub-project of openMSX).
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 Catapult for you in the current
directory.
This directory created by CVS is the called top of the source tree.
In addition to the Catapult 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.
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.
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.
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.
For compilation in Windows you will need one of the following:
sed.exe from
GNU Home and touch.exe
from UnxUtils. Although this may still work, we haven't tested this in ages, so in case of problems, please revert to the MinGW method described below.
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.
First of all, you need some wxWidgets (formerly known as wxWindows) packages or libraries. On a Debian testing system, the packages are called:
Although other versions are available, we recommend to use wxWidgets 2.6. For Windows there are no binary releases available. Please read the next section for instructions for compiling wxWidgets from source.
Furthermore, you need the XML library that is also used in openMSX itself. In Debian its packages are called:
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.
Compilation of wxWidgets 2.6 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. We do give the proper configure command line here:
Because of bugs in wxWidgets 2.6, you need to patch the source code of wxWidgets if you use the --disable-fontmap option. To do this, do the following in your MSYS terminal, in the source directory of wxWidgets:
This patch was written for wxWidgets 2.6.4, the latest stable 2.6 version. If you are using another version, you'll have to adapt the patch manually (which is not hard, but you have to know what you're doing).
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:
You can build different flavours by setting the CATAPULT_FLAVOUR environment variable.
The following values are supported:
In Visual Studio, just open build\wxCatapult.dsw, choose a target
and build it.
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.
To install Catapult in Linux, run the following command:
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.
Windows doesn't really provide us with an installation system, 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:
Catapult.exe and libxml2.dll should be in the same directory
or libxml2.dll should be somewhere in your pathmingwm10.dll, when compiling with MinGWCatapult.exe) ..\resources\dialogsCatapult.exe) ..\resources\bitmapsIf all went well, you should have Catapult installed now. You can test it by starting Catapult from the command line:
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.
Since Catapult 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.
In any case, try to give as much information as possible when you describe your bug or request.
$Id: compile.html,v 1.23 2007/10/22 17:48:25 manuelbi Exp $