Note: throughout this guide we will refer to Catapult as wxCatapult. Both are the same in every case. The openMSX team used wxCatapult as an internal name where Catapult is the application name.
The latest version of the openMSX Catapult manual can be found on the openMSX home page:
http://openmsx.org/catapult-manual/
The latest version of the openMSX manual can also be found there:
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 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 Git log for that), only the big picture.
Catapult is a sub-project of openMSX, developed using the tools GitHub freely offers to open source projects. The code is stored in Git, an open source version management system. Catapult is released at every openMSX release.
There are several options for getting the source code:
Releases are intended for general users. 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 Git later. If you update often, it is best to use a Git checkout rather than a Git 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 the latest released version of Catapult from our website (check the Download box).
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 Git clone means you use Git to retrieve the latest version
of the source code of wxcatapult.
This means you will need to install a Git client.
This package is usually named git.
There are graphical front-ends for Git,
but this guide will tell you how to use Git from the command line. More information about git can be found on the Git Documentation site.
Windows users might want to look at msysGit for a command line tool, TortoiseGit for Windows Explorer integration, or Git Extensions, which also includes Visual Studio integration.
With the following line (which is also displayed when you browse an openMSX Git repository) you can retrieve the latest sources (also works on Windows when using msysGit):
In this line you specified where you want to retrieve the files from (host name of the Git server), what project you want to retrieve (openMSX in this case), what module you want to get (wxcatapult.git in this case, which is the module that contains the sources of the wxcatapult program) and what directory it should be cloned to (we chose openmsx-wxcatapult in this example).
When compiling wxcatapult on Windows with GCC, it's often convenient to use C:\MinGW\msys\1.0\home\<username>\openmsx-wxcatapult
as the target directory, as this is easy to reach from your MinGW Shell - it's
your MinGW home directory.
If you're a developer, it makes sense to use this Git commandline:
For this to work smoothly, without having to type your password all the time, it's probably a good idea to read the GitHub docs about SSH keys.
The Git command created a directory called openmsx-wxcatapult for you
in the current directory (or in the directory you specified in TortoiseGit).
This directory is what we will call in this manual the top
of the source tree.
In addition to the wxcatapult code, you will see a hidden
Git administration directory called .git.
Do not mess with it (nor move contents of this directory around), otherwise Git will get confused.
If you want to update your source tree later, go to the top of the source tree and type:
or right click on the openmsx-wxcatapult directory in Windows Explorer and select "TortoiseGit -> Pull...".
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.
Use this way 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.
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 3.0, as we haven't tested much with other versions.
Get the source code for wxWidgets. Version 3.0.5 is what we used, so that's recommended. Please read the next section for instructions for compiling wxWidgets from source.
For Windows, version 2.9.14 of libxml2 is recommended.
Unpack the source packages into the derived\3rdparty\src directory. This will generate a subdirectory called libxml2-v2.9.14.
For wxWidgets, unzip the sources somewhere else. For Windows, the compilation inside the 3rdparty folder is not supported at the moment.
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++:
for 32-bit
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x86msbuild -p:Configuration="Unicode Release";Platform=Win32 build\3rdparty\3rdparty.slnfor 64-bit
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64msbuild -p:Configuration="Unicode Release";Platform=x64 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 Studio and compiling the projects inside them using the IDE.
Note that there seems to be confusion on where the vcvarsall.bat is located... Microsoft documented it in this help page, but other people seem to disagree... Please check what is applicable for your case.
For now, wxWidgets has to extracted to derived\3rdparty\src\wxWidgets-3.0.5 (yes, that version and that specific location, otherwise the compiler won't find the include files for the library) and be built manually, after which the results must be manually copied to the proper place in the 3rdparty tree. Here are the steps with a Visual Studio command prompt in the location where the wxWidgets source files were unzipped (derived\3rdparty\src\wxWidgets-3.0.5).
For 32-bit
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x86cd build\mswnmake /f makefile.vc BUILD=release TARGET_CPU=x86 RUNTIME_LIBS=staticFor 64-bit
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64cd build\mswnmake /f makefile.vc BUILD=release TARGET_CPU=X64 RUNTIME_LIBS=static
Then copy the results to the Catapult build specific 3rdparty folder. E.g. for 64-bit, copy the contents of lib\vc_x64_lib to derived\x64-VC-Unicode Release\3rdparty\install\lib\.
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 Studio:
for Win32
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x86msbuild -p:Configuration="Unicode Release";Platform=Win32 build\msvc\wxCatapult.slnfor Win64
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64msbuild -p:Configuration="Unicode Release";Platform=x64 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 Studio and compiling the projects inside them using the IDE.
Note that there seems to be confusion on where the vcvarsall.bat is located... Microsoft documented it in this help page, but other people seem to disagree... Please check what is applicable for your case.
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.
Feedback and bug reports are always very welcome!
If you encounter problems, you have several options:
#openMSX on libera.chat
and ask your question there. Also reachable via webchat! If you don't get a reply immediately, please stick around for a while, or use one of the other contact options. The majority of the developers lives in time zone GMT+1. You may get no response if you contact them in the middle of the night...
openmsx-user mailing list.
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.
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.
As of Windows Vista SP1 and later operating systems, you can find user dump files for crashed processes in the "%LocalAppData%\CrashDumps" directory. The default Windows crash dump behavior can be further customized as per MSDN.
To generate a user dump on demand on any Windows OS, please read KB286350.