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 SVN 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 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:
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.
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:
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 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:
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:
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:
or right click on the wxcatapult directory in Windows Explorer and select "SVN 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, 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.
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 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.
There are three different ways to obtain the Visual C++ compiler:
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++ 2008, it will be in "Microsoft Visual Studio 2008\Visual Studio Tools" as the "Visual Studio 2008 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:
Two different configurations are supported:
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:
On a Debian testing system, the packages are called:
Although other versions are available, we recommend to use wxWidgets 2.6 (but 2.8 will probably also work).
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.
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.
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):
The following steps build third-party libraries with Visual C++:
msbuild -p:Configuration="Unicode Release";Platform=Win32 build\3rdparty\3rdparty.slnTo 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.
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:
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.
The following steps build Catapult with Visual C++:
msbuild -p:Configuration="Unicode Release";Platform=Win32 build\msvc\wxCatapult.slnTo 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.
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.
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:
Catapult.exe) ..\resources\dialogsCatapult.exe) ..\resources\bitmapsCatapult.exe and libxml2.dll (or libxml2-2.dll) should be in the same directory
or libxml2.dll should be somewhere in your pathmingwm10.dll, when compiling with MinGWIf 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 under 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. 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).
openmsx-devel mailing list.
More info on the
openMSX mailing lists,
including an archive of old messages, can be found at SourceForge.
In all cases, please provide as much information as possible when you describe your bug or request.
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.
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 11012 2009-12-23 11:23:11Z manuelbi $