Compiling MegaZeux

Compiling any MegaZeux 2.80 or later source requires a POSIX compatible shell (bash, dash) to be installed. Download the source .tar.bz2 or .tar.xz and extract it to a new folder.

General Commands

./config.sh

This will give you help about how to configure MegaZeux.

./config.sh --platform unix

To configure the sources. On OS X, the platform is "darwin", and on Windows the platform is either "win64" or "win32".

make

This will build MegaZeux from sources. If it fails, you probably don't have one of SDL, libvorbis, libogg, libpng, zlib or the corresponding dev packages installed.

make install

This will install MegaZeux to the system. This should not be used with the "unix-devel" platform or any other option intended to run straight out of the source directory.

Please see debian/README for more information.

Windows

For developing and testing MegaZeux with Windows, the generally supported POSIX platform is MSYS2. Other available options include MINGW32/msys, Cygwin, MSVC, etc., but are typically more complicated to set up than MSYS2. Download and install MSYS2 before continuing. MSYS2 no longer works on 32-bit Windows and recommends the UCRT64 environment, so that will be used here.

It is no longer recommended to produce release builds with MSYS2, as they have increased the default architecture of MINGW32 to pentium4 and the default architecture of MINGW64 to nocona. MegaZeux still targets i686 and x86-64 respectively. While most dependencies can be rebuilt, MSYS2 may or may not embed system library stubs that require the newer architectures into the binary (untested). Linux Mingw-w64 cross compilers are now recommended for release builds instead.

Windows with MSYS2

Run ucrt64.exe in the msys2 directory. You will be in the "{MSYS DIRECTORY}\home\{your username}\" directory. (This will display in the mingw64 shell as either "~" or "/home/{your username}")

First, run this command. MSYS2 will need to restart when it is finished.

yes Y | pacman -Syu

After restarting MSYS2, run the following commands.

yes Y | pacman -Su
yes Y | pacman -S git
yes Y | pacman -S make
yes Y | pacman -S mingw-w64-ucrt-x86_64-gcc
yes Y | pacman -S mingw-w64-ucrt-x86_64-gdb
yes Y | pacman -S mingw-w64-ucrt-x86_64-pkgconf
yes Y | pacman -S mingw-w64-ucrt-x86_64-zlib
yes Y | pacman -S mingw-w64-ucrt-x86_64-libpng
yes Y | pacman -S mingw-w64-ucrt-x86_64-libogg
yes Y | pacman -S mingw-w64-ucrt-x86_64-libvorbis
yes Y | pacman -S mingw-w64-ucrt-x86_64-SDL2
git clone https://github.com/AliceLR/megazeux.git
cd megazeux
./config.sh --platform win64
make

MegaZeux should be built and ready to run! If you are not running MegaZeux from ucrt64.exe, add the folder containing your dependencies (generally C:\msys64\ucrt64\bin) to your Windows PATH variable. Otherwise, MegaZeux will not be able to start from Explorer.

The following optional tools packages may be of use. They are not required or are part of the packaging process for some architectures.

yes Y | pacman -S autoconf
yes Y | pacman -S automake
yes Y | pacman -S libtool
yes Y | pacman -S nano
yes Y | pacman -S p7zip
yes Y | pacman -S mingw-w64-ucrt-x86_64-clang
yes Y | pacman -S mingw-w64-ucrt-x86_64-cmake
yes Y | pacman -S mingw-w64-ucrt-x86_64-diffutils
yes Y | pacman -S mingw-w64-ucrt-x86_64-imagemagick
yes Y | pacman -S mingw-w64-ucrt-x86_64-ntldd

The following optional library packages may be useful for testing with alternate configurations. These packages may not be available for all targets (especially MINGW32/i686).

# SDL 3 (--enable-sdl3)
yes Y | pacman -S mingw-w64-ucrt-x86_64-sdl3
# SDL 1.2.15 (--enable-sdl1)
yes Y | pacman -S mingw-w64-ucrt-x86_64-SDL
# ANGLE (--enable-gles)
yes Y | pacman -S mingw-w64-ucrt-x86_64-angleproject

Troubleshooting

- "The program can't start because ___.dll is missing."

If you are running MegaZeux from Explorer, add the folder containing your dependencies (generally C:\msys64\ucrt64\bin) to your Windows PATH variable.

- "The procedure entry point inflateReset2 could not be located in the dynamic link library zlib1.dll." (and similar errors)

This can happen because the Windows PATH variable contains a directory older copy of zlib1.dll (or the DLL in question). You can use where zlib1.dll in Command Prompt to view the different PATH locations that contain the DLL, as well as the order in which Windows will try to load it.

Linux cross compilation with Mingw-w64

The Windows port of MegaZeux can be compiled on Linux using the same Mingw-w64 toolchains used by MSYS2. It can also be run like any other program in Linux if you have Wine and binfmt-misc installed. MegaZeux uses self-built dependency bundles (rather than dependencies offered by whatever distro you are using) for consistency.

Install toolchains (Fedora; other distros will vary):

sudo dnf install mingw{32,64}-{gcc,gcc-c++,binutils}

Download a MinGW dependency bundle from here into the MegaZeux scripts/deps directory and extract it. The bundle contains both i686 and x86_64 dependencies, which will be located at scripts/deps/mingw/x86 and scripts/deps/mingw/x64, respectively.

(cd scripts/deps && wget https://github.com/AliceLR/megazeux-dependencies/releases/download/v2.93c-r1/megazeux-dependencies-2.93c-r1-mingw.tar.xz)
(cd scripts/deps && tar -xJf megazeux-dependencies-2.93c-r1-mingw.tar.xz)

Configure:

# x86_64
./config.sh --platform mingw64 --prefix scripts/deps/mingw/x64 --enable-release --enable-lto
# i686
./config.sh --platform mingw32 --prefix scripts/deps/mingw/x86 --enable-release --enable-lto

Build:

make -j8 debuglink

Build and run regression tests (requires Wine and binfmt-misc):

make -j8 test

Generate manifest (requires sha256sum and xargs with the -P option) and archive (requires Info-ZIP or 7-Zip):

make archive

Ubuntu/Debian

sudo apt install build-essential

Download compilers to build MegaZeux. MegaZeux will also build with clang.

supo apt install libpng-dev libogg-dev libvorbis-dev libsdl2-dev 

Download the dependencies required to build MegaZeux. To build with SDL 1.2, install the package libsdl1.2-dev.

To install the latest master, use:

sudo apt install git
git clone https://github.com/AliceLR/megazeux.git [dest dir]

Alternatively, download and extract the latest .tar.xz or .tar.bz2 source archive to the desired location.

See the "general commands" section above for more information.

Packaging

sudo apt install devscripts debhelper

Download the packaging tools.

From the MegaZeux source directory:

debuild -us -uc

Fedora

sudo dnf install gcc gcc-c++ make binutils

Download compilers to build MegaZeux. MegaZeux will also build with clang/clang++.

supo dnf install zlib-devel libpng-devel libogg-devel libvorbis-devel SDL2-devel

Download the dependencies required to build MegaZeux. To build with SDL 1.2, install the package sdl12-compat-devel (SDL-devel for older Fedora releases).

To install the latest master, use:

sudo dnf install git
git clone https://github.com/AliceLR/megazeux.git [dest dir]

Alternatively, download and extract the latest .tar.xz or .tar.bz2 source archive to the desired location.

See the "general commands" section above for more information.

Packaging

The rpm-build package is required:

sudo dnf install rpm-build

If you're building from a cloned Git repository, checkout the appropriate MegaZeux version tag. For example:

git checkout v2.93

To build the rpm:

make distclean
rpm-build -bb --build-in-place megazeux.spec

Mac OS X

With MacPorts (testing only)

You will need to install XCode and MacPorts before continuing. This method is suitable only for testing builds, and should not be used to produce releases.

Compile/install dependencies. At least one SDL package is required, but there are several different options.

sudo port install zlib libpng libogg libvorbis

# Newer versions of macOS can use SDL3; configure MegaZeux with --enable-sdl3
sudo port install SDL3

# Most versions of macOS support SDL2.
sudo port install libsdl2

# Snow Leopard users may need this build of SDL2 instead.
sudo port install libsdl2-snowleopard

# Even older versions of macOS may need SDL 1.2; configure MegaZeux with --enable-sdl1
sudo port install libsdl

Navigate to the MegaZeux source directory and configure MegaZeux. Add any relevant SDL option here. For debug builds, omit --enable-release and --enable-lto.

./config.sh --platform darwin-devel --prefix /opt/local --enable-release --enable-lto

Build MegaZeux as usual:

make -j8

Multiarchitecture .app

THIS SECTION IS A WORK IN PROGRESS. Please refer to the documentation in arch/darwin/ and docs/platform_matrix.html for more details.

Environment Setup

This is heavily dependent on the architectures being targeted. For compilation on a Mac, typically select the highest Xcode being targeted as a base and install the lower versions using XcodeLegacy. Linux cross compilation isn't tested currently.

Architecture	MegaZeux PREFIX	SDK version	OS minimum version	Xcode toolchain	Cross toolchain	Last working SDL	Notes
arm64	PREFIX_ARM64	11.0	11.0	Xcode 12.2 or higher	osxcross	Latest
arm64e	PREFIX_ARM64E	11.0	11.0	Xcode 12.2 or higher	osxcross	Latest	Builds containing this architecture seem to be killed immediately by the kernel when run on ARM64; avoid for now.
i686	PREFIX_I686	10.13	10.6	Xcode 9.4.1	osxcross	2.0.22	Mac OS X Snow Leopard is targeted to support Core Duo Macs.
x86_64	PREFIX_AMD64	10.13	10.6	Xcode 9.4.1	osxcross	2.0.22 (10.6) or latest (10.9+)
x86_64h	PREFIX_AMD64H	10.13	10.9	Xcode 9.4.1	osxcross	Latest	OS X Mavericks is the minimum version for this architecture. Versions prior to Yosemite may have no clue how to handle software with both x86_64 and x86_64h executables; probably avoid unless targeting 10.10+.
ppc	PREFIX_PPC	10.4	10.4	Xcode 3.2.6	osxcross (ppc-test)	2.0.3 (panther_SDL2) or 1.2.15	Mac OS X Tiger is targeted to support G3 Macs. SDL2 has Core Audio issues, 1.2.15 recommended.
ppc64	PREFIX_PPC64	10.5	10.5	Xcode 3.2.6	osxcross (ppc-test)	2.0.3 (panther_SDL2) or 1.2.15	Mac OS X Leopard is targeted as Objective-C is broken for PowerPC64 in the Tiger SDK. SDL2 has Core Audio issues, 1.2.15 recommended.

WARNING: if targeting PowerPC64 via XcodeLegacy, you need to revert a fix that XcodeLegacy applies to libgcc_s.10.5.dylib OR apply this patch to XcodeLegacy before building your SDK bundles.

cp /Developer/SDKs/MacOSX10.5.sdk/usr/lib/libgcc_s.10.5.dylib /Developer/SDKs/MacOSX10.5.sdk/usr/lib/libgcc_s.10.5.dylib.vectorfix
cp /Developer/SDKs/MacOSX10.5.sdk/usr/lib/libgcc_s.10.5.dylib.bak /Developer/SDKs/MacOSX10.5.sdk/usr/lib/libgcc_s.10.5.dylib

WARNING: when installing the Xcode 3 compilers via XcodeLegacy, it will replace the current Xcode's ld with a wrapper which either selects the original ld or redirects all PowerPC usage and Intel <=10.6 usage to the Xcode 3 ld. This breaks linking anything targeting Intel 10.6 with newer SDKs, so the ld script needs to be modified to redirect <=10.5 instead to fix this. It can be found at

/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/ld

Other required tools

dylibbundler, which can be installed using MacPorts:

sudo port install dylibbundler

WARNING: dylibbundler relies on otool and therefore llvm-objdump. LLVM currently lacks support for reading the LC_UNIXTHREAD load commands of PowerPC64 Mach-O executables, so bundling will fail. Workarounds:

1) Currently, MegaZeux's bundle script (arch/darwin/bundle.sh) will add an otool wrapper to PATH (arch/darwin/bin/otool) which instead invokes xcrun otool-classic. This only works for Xcode versions which contain otool-classic.

2) Disabling those lines of bundle.sh and instead selecting a pre-LLVM Xcode to build for PowerPC64 should also work.

Dependencies

Fetch a macOS dependencies bundle from the MegaZeux dependencies GitHub repository and extract it to scripts/deps/ in your local MegaZeux Git repository.

Alternatively, if you are feeling very brave, you may attempt to compile the dependencies yourself using the Makefile in scripts/deps/. This requires the same environment as described above for compiling MegaZeux, plus cmake and wget (available from MacPorts or Homebrew).

Compilation

Unlike most other architectures, the prefix is provided PER ARCHITECTURE to a Makefile meta target.

./config.sh --platform darwin-dist --enable-release --enable-lto

To compile for a given architecture, provide to Make one or more of the PREFIX variables defined in the table above:

make PREFIX_I686=scripts/deps/macos/i686 PREFIX_AMD64=scripts/deps/macos/x86_64

For each architecture, Make will invoke:

make ARCH=[arch] PREFIX=[prefix] package
make ARCH=[arch] PREFIX=[prefix] clean

The "package" target is similar to "all", except afterward, dylibbundler is used to generate a dependency bundle in "bundles/", and then all binaries are moved to [binary].[arch].

Finally, Make will perform

make lipo

to merge all of the currently existing [binary].[arch] files into a new multiarchitecture file [binary].

Packaging

Make sure there is not a "MegaZeux" volume mounted before continuing.

rm -r build/
make archive

You can test the .app files generated in build/darwin-dist/ to make sure they run. A .dmg will appear in build/dist/darwin-dist/ containing the generated .app files, documentation, and multiarchitecture utilities.

HTML5 (Emscripten)

NOTE: emsdk may not function properly in MSYS2. Using Linux or similar is strongly recommended.

Download and install emsdk.

git clone https://github.com/emscripten-core/emsdk /opt/emsdk
cd /opt/emsdk
./emsdk install latest
./emsdk activate latest
. ./emsdk_env.sh

Configure and build MZX:

./config.sh --platform emscripten --enable-release
make -j8
make archive

Note that compiling MZX will make emsdk automatically install all required dependencies.

BlocksDS/Wonderful (Nintendo DS)

Follow the instructions here to install Wonderful and BlocksDS.

Install the following packages:

wc-pacman -S toolchain-gcc-arm-none-eabi-zlib

Configure and build:

arch/nds-blocksds/CONFIG.NDS
make -j8
make archive

devkitARM, devkitA64, and devkitPPC

Follow the instructions here to install the devkitPro toolchains.

Note that if you're using MSYS2 (or a Linux distribution with pacman already installed), you can simply add the devkitPro repository to your pacman.conf and install devkitpro-keyring:

[dkp-libs]
Server = http://downloads.devkitpro.org/packages

[dkp-windows]
Server = http://downloads.devkitpro.org/packages/windows

Nintendo DS

Install the following packages:

pacman --needed --noconfirm -S devkitARM libnds libfat-nds maxmod-nds nds-zlib ndstool dstools

Configure and build:

arch/nds/CONFIG.NDS
make -j8
make archive

Nintendo 3DS

Install the following packages:

pacman --needed --noconfirm -S devkitARM libctru citro3d picasso 3dstools general-tools
pacman --needed --noconfirm -S 3ds-zlib 3ds-libpng 3ds-libogg 3ds-libvorbisidec

Configure and build:

arch/3ds/CONFIG.3DS
make -j8
make archive

Nintendo Wii

Install the following packages:

pacman --needed --noconfirm -S devkitPPC libogc libfat-ogc gamecube-tools
pacman --needed --noconfirm -S ppc-zlib ppc-libpng ppc-libogg ppc-libvorbisidec

Configure and build:

arch/wii/CONFIG.WII
make -j8
make archive

Nintendo Wii U

Install the following packages:

pacman --needed --noconfirm -S devkitPPC wut wut-tools
pacman --needed --noconfirm -S ppc-zlib ppc-libpng ppc-libogg ppc-libvorbis wiiu-sdl2

Configure and build:

arch/wiiu/CONFIG.WIIU
make -j8
make archive

Nintendo Switch

Install the following packages:

pacman --needed --noconfirm -S devkitA64 libnx switch-tools
pacman --needed --noconfirm -S switch-glad switch-glm switch-mesa switch-libdrm_nouveau
pacman --needed --noconfirm -S switch-zlib switch-libpng switch-libogg switch-libvorbis switch-sdl2

Configure and build:

arch/switch/CONFIG.SWITCH
make -j8
make archive

DJGPP

Get a pre-built copy of DJGPP for your operating system from here. Create an environment variable DJGPP pointing to the location you extracted DJGPP and add the toolchain to your PATH variable:

export DJGPP=/opt/djgpp
export PATH="$PATH:$DJGPP/bin"

or

export DJGPP_PREFIX=/c/djgpp
export PATH="$PATH:$DJGPP/bin"

Build zlib:

CHOST=i586-pc-msdosdjgpp ./configure --prefix=$DJGPP
make -j8
make install

Build libpng:

CFLAGS="-I$DJGPP/include" \
CPPFLAGS="-I$DJGPP/include" \
LDFLAGS="-L$DJGPP/lib -lz" \
./configure --prefix=$DJGPP --host=i586-pc-msdosdjgpp --disable-shared --enable-static
make -j8
make install

Build tremor (lowmem):

git clone https://gitlab.xiph.org/xiph/tremor
git checkout lowmem
./autogen.sh --prefix=$DJGPP --host=i586-pc-msdosdjgpp --disable-shared --enable-static
make -j8
make install

Build libogg and libvorbis:

./configure --prefix=$DJGPP --host=i586-pc-msdosdjgpp --disable-shared --enable-static
make -j8
make install

Configure and build MegaZeux (libpng disabled and using tremor by default):

arch/djgpp/CONFIG.DJGPP
make -j8
make archive

VitaSDK

Follow the instructions here to set up the Vita toolchain. It is strongly recommended you substitute all instances of /usr/local/vitasdk in their instructions for /opt/vitasdk. /opt is the location that is intended for monolithic software, and placing VitaSDK here will group it with every other toolchain used by the MegaZeux console ports. install_all.sh should install every dependency that MegaZeux needs.

Configure and build MegaZeux:

arch/psvita/CONFIG.PSVITA
make -j8
make archive