You can also use this URL to get up-to-date versions of the hyperlinks
63
if you printed out this manual.
64
</p>
65
66
<h3><aid="purpose">1.2 Purpose</a></h3>
67
<p>
68
This guide is about openMSX, the open source MSX emulator that tries to achieve
69
near-perfect emulation by using a novel emulation model.
70
You can find more information about openMSX on the
71
<aclass="external"href="http://openmsx.org/">openMSX home page</a>.
72
</p>
73
74
<p>
75
If you just want to use openMSX, there is likely <aclass="external"href="faq.html#easyinstall">a pre-packaged version</a> you can use. This document describes how you can compile openMSX from source, which is useful if:
76
</p>
77
<ul>
78
<li>There is not yet a pre-packaged version for your favourite platform.</li>
79
<li>You want to closely follow the latest developments.</li>
80
<li>You want to make changes to openMSX.</li>
81
</ul>
82
83
<p>
84
If you only want to follow the latest developments, chances are an
85
automatic build has been performed for your platform. Links to such
86
development builds can be found on the <aclass="external"
87
href="http://openmsx.org/">openMSX website</a>, at the bottom of the Download
88
box.
89
</p>
90
91
<p>
92
If you need help compiling openMSX, please
93
<aclass="internal"href="#contact">contact us</a>.
94
If you needed any modifications to make openMSX compile,
95
please send those modifications to us,
96
so we can make openMSX ever more portable.
97
</p>
98
99
<h3><aid="history">1.3 Revision History</a></h3>
100
101
<p>
102
For the revision history, please refer to the <aclass="external"
<dd>A compact and dynamic programming language. The latest version should work fine. Note: on Windows you may have to add the path to Python (e.g. <code>C:\Python</code>) to your <code>PATH</code> manually.</dd>
130
<dt>C++ compiler</dt>
131
<dd>There are three compilers that are supported to build openMSX: GCC, clang
132
and Visual C++. The GCC compiler builds openMSX on all supported platforms, clang (Xcode) is the default on macOS, while Visual C++ is the primary compiler for Windows.</dd>
133
134
</dl>
135
136
<h4>GCC</h4>
137
138
<p>For compilation with GCC, you need GNU Make and g++:</p>
139
140
<dl>
141
142
<dt>make</dt>
143
<dd>GNU implementation of the Make tool.
144
Make interprets rules that define how a project should be built.
145
Version 3.80 or higher is required.</dd>
146
147
<dt>g++</dt>
148
<dd>The GNU C++ compiler.
149
At least version 13 is required to build openMSX.
150
</dd>
151
152
</dl>
153
154
<h4>clang</h4>
155
156
<h5>macOS</h5>
157
158
<p>
159
Install Xcode from Apple, which you can find in the Mac App Store. The openMSX build is not done inside the Xcode IDE, but it uses the SDK and command line tools that are provided by Xcode. Xcode 16.4 or higher is required.
160
</p>
161
162
<h4>Visual C++</h4>
163
164
<p>To build with Visual C++ you need to have the latest version of it installed. Currently, this is Visual C++ 2022.</p>
165
166
<p>How to obtain the Visual C++ compiler:</p>
167
<dl>
168
<dt><aclass="external"href="http://www.visualstudio.com/downloads/">Visual Studio Community</a></dt>
169
<dd>This is a free (as in beer) IDE and development environment. It builds 32 and 64-bit binaries out of the box. Make sure you download the latest version. </dd>
170
171
</dl>
172
173
<p>To generate an MSI installation package, you also need:</p>
<dd>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 <aclass="external"href="http://www.mesa3d.org/">Mesa</a> with a DRI driver can be an alternative.</dd>
<dd>The Laserdisc emulation expects audio encoded with Vorbis in the Ogg container format for the audio of Laserdiscs. Vorbis was chosen since it is not patent-encumbered.</dd>
<dd>The Laserdisc emulation expects video encoded with the Theora codec in the Ogg container format for the video of Laserdiscs. Again, Theora was chosen since it is not patent-encumbered.</dd>
220
221
<dt><aclass="external"href="http://www.alsa-project.org/">ALSA</a> (optional, Linux only)</dt>
222
<dd>The ALSA library for ALSA MIDI out support on Linux.</dd>
223
224
</dl>
225
226
<h4>GCC / clang</h4>
227
<p>
228
You can install the required libraries system-wide, or you can use the "3rd party libraries" support in the openMSX build system and build a stand-alone binary. System-wide is recommended if you run a modular operating system (such as Linux, BSD or macOS with MacPorts, Homebrew 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 macOS 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 <aclass="internal"href="#standalone">Stand-alone Binary</a> chapter.
229
</p>
230
<h5>Debian and Ubuntu Linux</h5>
231
<p>
232
You can easily install all required packages using the "build dependencies" feature of the APT package manager (if you have source packages in your package sources list):
233
</p>
234
<divclass="commandline">
235
sudo apt-get build-dep openmsx
236
</div>
237
<p>
238
Do note that if the Debian/Ubuntu package that is in the version of the distribution you are currently running is older than the openMSX version you are trying to compile (which is typically so), you might miss some dependencies that were added in the newer version. The build system will complain and you will have to install the remaining (missing) packages manually. Read on to get some tips about that.
239
</p>
240
<p>
241
Typical depending packages are: <code>libsdl2-ttf-dev</code><code>libogg-dev</code><code>tcl-dev</code><code>libpng-dev</code><code>libtheora-dev</code><code>libvorbis-dev</code><code>libsdl2-dev</code><code>libglew-dev</code>. The complete list for Debian (which will be very very similar) is <aclass="external"href="https://packages.debian.org/source/sid/openmsx">here</a>.
242
</p>
243
244
<h5>Other Linux</h5>
245
<p>
246
Most Linux distributions have their libraries split over two packages: a runtime package and a development package.
247
The runtime package for the "Foo" library is typically called
248
<code>libfoo</code>, the development package is typically named
249
<code>libfoo-dev</code> or <code>libfoo-devel</code>.
250
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.
251
</p>
252
253
<h5>macOS</h5>
254
255
<p>
256
The easiest thing to do is to use the <aclass="internal"href="#standalone">stand-alone binary</a> method, which will get the libraries automatically.</p>
257
<p>
258
If you want to do things manually, you can get the libraries from
<aclass="external"href="http://www.finkproject.org/">Fink</a>. These tools provide access to a large collection of software packages or ports. You can use them to install those packages (or ports). The manual approach is not regularly tested by the openMSX developers; unless you enjoy tinkering with builds we suggest you use the stand-alone binary approach instead.
263
</p>
264
265
<h4>Visual C++</h4>
266
267
<p>
268
When building with Visual C++, the optional libraries mentioned above are
269
treated as follows:</p>
270
<ul>
271
<li>Headers and libraries for OpenGL are included with Visual C++ by default.</li>
272
<li>The GLEW, Ogg, Theora and Vorbis libraries are not optional, but required.</li>
273
</ul>
274
<p>
275
Also, when building with Visual C++, the "3rd party libraries" support in the openMSX
276
build system must be used. The resulting binary statically links in all
277
dependencies, including the C runtime. For more details, please see the <aclass="internal"href="#standalone">
278
Stand-alone Binary</a> chapter.
279
</p>
280
<h2><aid="getsource">3. Getting the Source Code</a></h2>
users might want to have a look at <aclass="external"href="https://git-for-windows.github.io/">msysGit</a> as a command line tool, <aclass="external"href="http://code.google.com/p/tortoisegit/">TortoiseGit</a>, which offers Windows Explorer integration, or <aclass="external"href="http://gitextensions.github.io/">Git Extensions</a>, a tool which also includes Visual Studio integration.
366
</p>
367
368
<p>
369
The following command (which is also displayed when you <aclass="external"href="https://github.com/openMSX">browse an openMSX Git repository</a>) retrieves the latest source code (also works on Windows when using msysGit):
Pro tip: <aclass="external"href="https://help.github.com/articles/generating-ssh-keys/#platform-all">read the GitHub docs about SSH keys</a> if you want this to work smoothly, without having to (re)type your password all the time.
392
</p>
393
394
<p>
395
The Git command creates a directory called <code>openMSX</code> for you
396
in the current directory (or in the directory you specified in TortoiseGit).
397
In this manual, this directory is referred to as <em>the top
398
of the source tree</em>.
399
In addition to the openMSX code, you will see a hidden
400
Git administration directory called <code>.git</code>.
401
Do not mess with it (nor move contents of this directory around), otherwise Git will get very confused.
402
</p>
403
404
<p>
405
If you want to update your source tree later,
406
go to the top of the source tree and type:
407
</p>
408
<divclass="commandline">
409
git pull
410
</div>
411
<p>
412
or right-click on the openMSX directory in Windows Explorer and select "TortoiseGit -> Pull...".
413
</p>
414
415
<h2><aid="local">4. Binary for Local System</a></h2>
416
417
<p>
418
This section explains how to build openMSX for a local system. If you want to create a binary that runs everywhere, we recommend to skip this chapter and use the <aclass="internal"href="#standalone">stand-alone binary</a> method. This is also the recommended approach for macOS and especially for Microsoft Windows systems.
419
</p>
420
421
<h3><aid="compilelocal">4.1 Compilation</a></h3>
422
423
<p>
424
Now that all the necessary tools and libraries are installed,
425
you are almost ready to start the actual compilation of openMSX.
426
</p>
427
428
<h4>GCC / clang</h4>
429
430
<p>
431
The first thing you may want to know is that you can build openMSX in
432
different flavours. The generic optimized flavour "opt" should work for all CPUs.
433
</p>
434
<p>
435
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:
436
</p>
437
<divclass="commandline">
438
export OPENMSX_FLAVOUR=devel
439
</div>
440
<p>
441
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 <code>build/flavour-*.mk</code>.
442
</p>
443
444
<p>
445
You can select the C++ compiler to be used by setting the <code>CXX</code> environment variable like this:
446
</p>
447
<divclass="commandline">
448
export CXX=g++-5
449
</div>
450
<p>
451
or:
452
</p>
453
<divclass="commandline">
454
export CXX=clang++
455
</div>
456
<p>
457
This can be useful if the default compiler on your system is an old version which is either not capable of compiling openMSX, or generates less efficient code.
458
</p>
459
460
<p>
461
Now we can let a script check if you have indeed all necessary libraries and headers installed.
462
Go to the top of your openMSX source tree and run the following script:
463
</p>
464
<divclass="commandline">
465
./configure
466
</div>
467
<p>
468
This script will report what versions of libraries you have installed.
469
It also reports which components can be built with those libraries.
470
If the script reports that it can't build the openMSX core component,
471
you should install the missing ones before you can continue.
472
Otherwise, you can decide to install the libraries needed for the optional
473
components, or to continue without building some components (e.g. the Laserdisc support).
474
</p>
475
476
<p>
477
If installing the correct libraries doesn't help,
478
<aclass="internal"href="#contact">contact the openMSX developers</a>.
479
When filing a bug report, please attach the <code>probe.log</code> file
480
created by the <code>configure</code> script in the directory
If that doesn't help, or we forgot to list a library openMSX depends on, please
513
<aclass="internal"href="#contact">contact the openMSX developers</a>.
514
Make sure to include the error message you got.
515
</p>
516
517
<p>
518
If you want to debug openMSX compilation problems yourself, you can add <code>V=1</code> (verbose) to the Make command line to see all build commands as they are executed.
519
</p>
520
521
<h5>macOS</h5>
522
523
<p>
524
The version of Xcode required also determines which version of macOS you need to build openMSX out of the box.
525
</p>
526
527
<h4>Visual C++</h4>
528
529
<p>
530
While it is possible to configure the supplied Visual C++ project files to
531
dynamically link against import libraries, this is not currently supported.</p>
532
<h3><aid="installlocal">4.2 Installation</a></h3>
533
534
<h4>GCC / clang</h4>
535
536
<h5>Linux and BSD</h5>
537
538
<p>
539
To install openMSX, run the following command:
540
</p>
541
<divclass="commandline">
542
make install
543
</div>
544
<p>
545
This installs openMSX in <code>/opt/openMSX</code> by default.
546
Note that only root has rights to write to system-wide directories such as
547
<code>/opt</code>,
548
so you may have to do <code>su</code> before <code>make install</code>, or use <code>sudo</code>:
549
</p>
550
551
<divclass="commandline">
552
sudo make install
553
</div>
554
555
<h5>macOS</h5>
556
557
<p>
558
On macOS, the build creates an application folder. You can "install" this simply by copying this folder to a different location. The application folder will depend on system-wide installed libraries, so it will not work on Macs lacking those libraries.
559
</p>
560
<p>
561
You can run openMSX from the application folder with the following command:
562
</p>
563
<divclass="commandline">
564
open derived/<cpu>-darwin-<flavour>/bindist/openMSX.app
565
</div>
566
<p>
567
If you want to see the messages openMSX prints to stdout and stderr, start openMSX like this:
This chapter describes how to build a binary of openMSX that does not depend on any libraries except those that are available on the platform by default. This procedure is highly recommended on Microsoft Windows. It is also recommended on macOS.
577
</p>
578
579
<p>
580
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.</p>
If you want to change something about this process, for example switch to a newer library release, edit the <code>build/3rdparty.mk</code> Makefile.
587
</p>
588
589
<p>
590
Similar to standard compilation, you can set environment variables such as <code>OPENMSX_FLAVOUR</code>, <code>CXX</code>, <code>OPENMSX_TARGET_CPU</code> and <code>OPENMSX_TARGET_OS</code>.
591
</p>
592
593
<p>
594
To build a stand-alone binary, run the following command at the top of the source tree:
595
</p>
596
<divclass="commandline">
597
make staticbindist
598
</div>
599
<p>
600
The final output files will be produced in <code>derived/<cpu>-<os>-<flavour>-3rd/bindist</code>.
601
</p>
602
603
<h5>macOS</h5>
604
605
<p>
606
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.
607
</p>
608
<p>
609
If you have an Apple Developers ID, you can automatically sign the app bundle by providing the following environment variable in your shell before building the app bundle:
610
</p>
611
<divclass="commandline">
612
<pre>
613
export CODE_SIGN_IDENTITY=<your Apple Application Developer ID here>
614
make staticbindist
615
</pre>
616
</div>
617
<p>
618
To find the exact string needed for the CODE_SIGN_IDENTITY, use the command:
<p>When building with Visual C++, the result is a static executable with minimal
633
dynamic library dependencies. Two platforms are supported:</p>
634
<ul>
635
<li><strong>Win32</strong> - a 32-bit binary that runs on both 32 and 64-bit versions of Windows</li>
636
<li><strong>x64</strong> - a native 64-bit binary that runs only on 64-bit versions of Windows</li>
637
</ul>
638
<p>Three different configurations are supported:</p>
639
<ul>
640
<li><strong>Debug</strong>: assertions enabled, debug prints enabled, no optimization,
641
very slow</li>
642
<li><strong>Developer</strong>: assertions enabled, debug prints disabled, no optimization</li>
643
<li><strong>Release</strong>: assertions disabled, debug prints disabled, full optimization</li>
644
</ul>
645
<p>When building with Visual C++, you can either use the IDE or build from the command line using <code>msbuild</code>. To do the latter, you need to open a Visual Studio command prompt. A shortcut to a Visual Studio command prompt can usually be found in your start menu. For Visual Studio Community 2017, it will be in "Microsoft Visual Studio 2017\Visual Studio Tools" as the "Visual Studio Command Prompt".</p>
646
<!-- TODO - Replace this section when we have integration with the broader 3rd party system -->
647
<p>In order to build openMSX, the libraries it depends on need to be
648
downloaded and unpacked:</p>
649
<ul>
650
<li>Open a command prompt and go to the <em>top of the openMSX source tree</em></li>
The following steps can then be used to build openMSX:</p>
656
<ul>
657
<li>Open a Visual Studio command prompt</li>
658
<li>Go to the <em>top of the openMSX source tree</em></li>
659
<li>To build 3rd party libraries, type <code>msbuild -p:Configuration=<strong>Release</strong>;Platform=<strong>x64</strong> build\3rdparty\3rdparty.sln</code></li>
660
<li>To build openMSX, type <code>msbuild -p:Configuration=<strong>Release</strong>;Platform=<strong>x64</strong> build\msvc\openmsx.sln</code></li>
661
</ul>
662
663
<p>The openMSX executable will be generated in <code>derived\x64-VC-Release\install</code>.</p>
664
<p>To build for other platforms or configurations, simply replace "Release" and
665
"x64" in the command lines above with the desired options.</p>
666
<p>To build using the Visual C++ IDE, simply open the aforementioned solution files and from the Build menu select "Build Solution". This is the same as building from the command line using <code>msbuild</code>.</p>
which describes all the things you can do with openMSX once
755
it is fully running.
756
</p>
757
758
<p>
759
If you got stuck somewhere in the compilation and installation process,
760
please contact us. The next chapter will tell you how.
761
</p>
762
763
<h5>macOS</h5>
764
765
<p>
766
You can run the openMSX application folder from Finder or from the command line:
767
</p>
768
<divclass="commandline">
769
open derived/<cpu>-darwin-<flavour>-3rd/bindist/openMSX.app
770
</div>
771
772
<h2><aid="contact">8. Contact Info</a></h2>
773
774
<p>
775
Since openMSX is still under heavy development, feedback and bug reports are very
776
welcome!
777
</p>
778
779
<p>
780
Should you encounter problems, you have several options:
781
</p>
782
783
<ol>
784
<li>
785
Go to our IRC channel: <aclass="external"href="ircs://irc.libera.chat:6697/#openMSX"><code>#openMSX</code> on <code>libera.chat</code></a>
786
and ask your question there. Also reachable via <aclass="external"href="https://web.libera.chat/#openMSX">webchat</a>! 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 live in time zone GMT+1. You may get no response if you contact them in the middle of their night...
787
</li>
788
<li>
789
Post a message on <aclass="external"href="http://www.msx.org/forum/semi-msx-talk/openmsx">the openMSX forum on MRC</a>.