mxe-minetest "build" instructions Release 200527 ---------------------------------------------------------------------- 1. Introduction. Welcome to "mxe-minetest", also known as the Final Minetest for Win- dows "build" kit. This is release 200527. "mxe-minetest" is a set of source files, scripts, and "build"-related files that can be used on a Linux system to cross-build Final Minetest for Windows. The result is a complete distribution, including Bucket Game, Bucket City, Wonder World, the Bucket Schems, and a preloaded media cache. The core engine is built as a single Windows EXE file. No special DLLs are required. Everything is included in the EXE. It's believed that this is the most portable and complete Windows cross-build kit for Minetest that has existed since the start of the project. ---------------------------------------------------------------------- 2. Dependencies. 2.1. Linux packages. This "build" kit requires, in general terms, at least the following Linux packages. In the case of libraries, "development" versions of the packages are needed. "Development" versions means that both header files and ".so" or ".a" library files must be installed. autoconf automake bash bison bzip2 cmake coreutils cpan-xml-parser flex gawk gcc gdk-pixbuf gettext git glibc gperf grep intltool libtool make openssl p7zip patch perl pkgconf python2 ruby sed tar unzip wget xzutils zlib The exact names of packages and/or "development" versions will vary from distro to distro. ---------------------------------------------------------------------- 2.2. To install the required dependencies for Debian and/or Ubuntu re- leases, try these commands: sudo apt-get update sudo apt-get install \ autoconf automake autopoint autotools-dev \ bash binutils bison bzip2 \ cmake coreutils e2fsprogs expat \ flex fontconfig g++ gawk \ gcc gettext git g++-multilib \ gperf grep gzip htop \ icu-devtools intltool joe less \ libbz2-dev libc6-dev-i386 libedit-dev libexpat1-dev \ libgmp-dev libjpeg-dev libltdl-dev libncurses5-dev \ libogg-dev libopenal-dev libpng-dev libreadline-dev \ libsqlite3-dev libssl-dev libtool libtool-bin \ libvorbis-dev libx11-dev libxxf86vm-dev lynx \ nano nettle-dev p7zip-full patch \ perl pkgconf python3 python3-dev \ python-dev rake ruby sed \ tar tcl unzip util-linux \ wget xz-utils zip \ \ libcurl4-openssl-dev \ libfreetype6-dev \ libgdk-pixbuf2.0-dev \ libglu1-mesa-dev \ libxml-parser-perl \ xserver-xorg-dev Note: "apt-get install" may prompt for timezone information, so that command should be run interactively. ---------------------------------------------------------------------- 2.3. To install the required dependencies for recent Fedora releases, try this command instead: sudo dnf install \ autoconf automake bzip2 \ bzip2-devel cmake expat-devel \ flex fontconfig-devel freetype-devel \ gcc gcc-c++ git \ glibc-devel gmp-devel libcurl-devel \ libedit-devel libgcc libjpeg-devel \ libogg-devel libpng-devel libstdc++-devel \ libtool libvorbis-devel libX11-devel \ lzo-devel make ncurses-devel \ openal-soft-devel openssl-devel patch \ pkgconf readline-devel ruby \ tcl which xz \ zlib-devel xorg-x11-server-devel ---------------------------------------------------------------------- 2.4. For other distros, use a web browser to open the following file in this directory tree: docs/index.html The file in question suggests dependency installation commands that may work. For newer Red Hat distro releases, substitute "dnf install" commands for "yum install" commands. ---------------------------------------------------------------------- 2.5. "upx" package. If a package named "upx" or "upx-ucl" is available for your distro, it's recommended that a recent copy of the package be installed as well. "upx" isn't essential. However, if it's installed, the Minetest EXE file will be less than 10 MB in size despite all of the libraries that are linked into it. ---------------------------------------------------------------------- 2.6. Dependency advisories. 2.6.1. "emacs" warning. Warning: If "emacs" is installed on the host system, it might be ad- visable to rename the "emacs" executable, perhaps to "emacs.save", temporarily while the MXE build procedure is running. On a Debian 8 host, we've seen the MXE build procedure go into an in- finite loop related to "emacs". The loop created a large log file which might have filled the disk. Renaming the "emacs" executable file temporarily bypassed the problem. ---------------------------------------------------------------------- 2.6.2. "cmake" release. The host system's copy of "cmake" should be at least release 3.10.3. ---------------------------------------------------------------------- 2.6.3. "gcc" release. Most "gcc" releases (including "g++") from 6.2 to 8.3 should work on the host side. "gcc" 4.9.2 and up might or might not work. However, if a distro is old enough to be using "gcc" 4.9.2, MXE builds will probably fail, re- gardless, as "cmake" and/or other components will most likely be too old to work. ---------------------------------------------------------------------- 2.6.4. "pbzip2" issue. If you've installed "pbzip2" and replaced "/bin/bzip2" with a symlink to the "pbzip2" binary, the MXE build system might print an error mes- sage about "bzip2" being a missing dependency. If this happens, you'll need to put the original "/bin/bzip2" file back, at least temporarily, while you're doing the MXE build proce- dure. ---------------------------------------------------------------------- 3. Host machine. The Linux system used to cross-build should be 64-bits. However, the "build" kit is able to produce either a 64-bit or a 32-bit version of Minetest. The default mode is to build a 64-bit EXE. A 32-bit EXE requires extra steps. These are discussed at the appropriate points below. ---------------------------------------------------------------------- 4. Prebuilt library files. This "build" kit may include some pre-built library files; i.e., ".a" files. The pre-built ".a" files are provided for your convenience. You can use them or rebuild them as suits your preferences. The full source code for these files is included in this kit. ---------------------------------------------------------------------- 5. Software frameworks and "build" stages. This directory tree holds two related software frameworks: (5a) A specially tailored copy of the MXE Linux-to-Windows cross- build framework. (5b) Source code for the Final Minetest core engine plus a script that can be used to cross-compile it for Windows. There are three "build" stages. In the first two stages, (5a) is built. In the third stage, (5b) is built. ---------------------------------------------------------------------- 6. Notes on the MXE framework. * The MXE part of "mxe-minetest" includes pre-built Windows static libraries (".a" files), both 32-bit and 64-bit format, sufficient to make it possible to cross-link Final Minetest. * The associated development header (".h") files are included. * Irrlicht and LuaJit -- static libraries and development header files -- are included in the package set. * Irrlicht has been patched to fix one problem and to disable exces- sive warning messages. LuaJit is a git release that partly addresses a long-term memory issue. * Source code for the "gcc" cross-build toolchain needed to cross- build things is also included. Note: The cross-build toolchain is based on "gcc" 7.3.1 regardless of the release of "gcc" installed on the host. Pre-built toolchain binaries, aside from library files, are *not* pro- vided. These must be built locally as explained below. ---------------------------------------------------------------------- 7. First build stage. There are three "build" stages. The first "build" stage builds a cross-build toolchain. Here are the instructions for the first stage. ---------------------------------------------------------------------- 7.1. Initial requirements. * Start with a 64-bit Linux system. Note: You can cross-build for 32- bit or 64-bit Windows, but the host where the cross-build is done presently needs to be 64-bits. * The system should have at least 5 GB of free disk space. * Make sure that a standard "gcc" toolchain is installed on the Linux system. "gcc" should ideally be in the 5.5, 6.4, 7.2, 7.3, 8.2, or 8.3 series. * Install the other dependencies discussed in part 2 above. ---------------------------------------------------------------------- 7.2. "multilibs" support. If you'd like to build 32-bit EXE files as well as 64-bit EXE files, enable "multilibs" support for your distro. Exactly how to do this is distro-dependent. You may need to do some Web searches. For Debian and derivatives, the following command might work: sudo apt-get install g++-multilib libc6-dev-i386 For recent copies of Fedora and/or other Red Hat distros, the follow- ing alternate command might work: sudo dnf install glibc-devel libgcc libstdc++-devel ---------------------------------------------------------------------- 7.3. Internet access. For this stage, and for the others, Internet access isn't required. The source files used are pre-loaded. So, the build procedures used aren't supposed to download anything. If you're familiar with MXE and attempt to build more of it than the subset discussed here, Internet access will be required and downloads will be attempted. Optional: If you'd like to be sure that the build procedure isn't able to download files, disable DNS until all of the "build" stages are done. ---------------------------------------------------------------------- 7.4. Unpack "mxe-minetest.zip". Unpack this directory tree somewhere convenient but not transient. For example: mkdir -p /opt cd /opt rm -fr mxe-minetest unzip -o /somewhere/mxe-minetest.zip Delete any existing "mxe-minetest" directory before unpacking as shown here. The example shown here assumes that the user is logged in as "root". The working area doesn't need to be in a system directory. A directory inside a user's "home" directory should work. The directory chosen should be in a filesystem that has at least 5 GB of disk space free. ---------------------------------------------------------------------- 7.5. Go to the top-level directory in the "mxe-minetest" tree; i.e., the directory which contains this file. ---------------------------------------------------------------------- 7.6. Edit "Makefile". Look for a line similar to the following: DEFAULT_MAX_JOBS := 4 The number used should be an integer from 1 to 8. Set the number to the number of CPU threads that the host computer has. If you're not sure, use 4 as a default. For computers that overheat or crash under load, reduce the number to about half of the selected value. Conversely, if you'd like to overclock a bit and speed things up at increased risk of crashes, use 6 as a default. ---------------------------------------------------------------------- 7.7. Edit "settings.mk". Look for a line similar to the following: JOBS := 4 Set the number to the value that you used in the preceding step. ---------------------------------------------------------------------- 7.8. Select architectures. Edit "Makefile" and "settings.mk", both files, again. You'll see a line similar to the following: MXE_TARGETS := x86_64-w64-mingw32.static.posix If you'd just like to support 64-bit EXE files, the line should look exactly as shown above. If you'd just like to support 32-bit EXE files, the line should look exactly as follows: MXE_TARGETS := i686-w64-mingw32.static.posix If you'd like to support both 64-bit and 32-bit EXE files, combine the two targets as follows: MXE_TARGETS := x86_64-w64-mingw32.static.posix \ i686-w64-mingw32.static.posix The setting above is recommended. It will take longer to run but will simplify part 10. Make the appropriate change, if any, to each of the two files and save both files. ---------------------------------------------------------------------- 7.9. Warning. Do *not* execute "make" without parameters unless you're an MXE expert and know what you're doing. This will cause MXE to download source code for numerous packages and to build all of them. ---------------------------------------------------------------------- 7.10. Execute the following command in the top-level "mxe-minetest" directory: make cc If the operation is successful, "gcc" and related cross-build tools will be built. ---------------------------------------------------------------------- 8. Second build stage. In the second "build" stage, libraries (such as Irrlicht) and develop- ment header files are rebuilt. This stage may be optional. You may not need to rebuild the ".a" files. Or you may wish to do so, regardless. If you'd like to rebuild the library files provided, or if it's neces- sary to do so, execute the following command in the top-level "mxe- minetest" directory: bash -e buildlibs.sh The procedure may take several hours or overnight. If the operation is successful, a number of library files and develop- ment header files will be built. ---------------------------------------------------------------------- 9. Size-reduction step. This step comes after the first two build stages and before the third one. It's optional, but recommended. Execute the following command in the top-level "mxe-minetest" direc- tory: bash -e stripfiles.sh The command may take several minutes to complete. It "strips" ".exe" files and partially "strips" ".a" files. Note: Partially "strips" means "removes debug symbols from". If the files weren't "stripped" before, this step should reduce the size of the directory tree by about 31%. ---------------------------------------------------------------------- 10. Third "build" stage. In the third "build" stage, Final Minetest is cross-built. If you set MXE_TARGETS to include both i686... and x86_64... previous- ly, this is very simple and most of this section [part 10] can be skipped. In this case, simply go to the "minetree" subdirectory and execute: bash crossbuild-both.sh This may take a long time to run but will put production ZIP files in a directory next to "minetree" named "sendmine". ---------------------------------------------------------------------- 10.1. Otherwise, edit the following script: minetree/crossbuild-minetest.sh and ensure that one and only one of the indicated lines is commented out: # THE_ARCH=i686-w64-mingw32.static.posix THE_ARCH=x86_64-w64-mingw32.static.posix The line that isn't commented out will determine the architecture that Minetest will be built for. Note: You can only enable "i686" (or 32-bit) mode here if you built 32-bit support previously in the first stage. ---------------------------------------------------------------------- 10.2. Execute the following command in the top-level "mxe-minetest" directory: bash -e minetree/crossbuild-minetest.sh ---------------------------------------------------------------------- 10.3. If the build procedure is successful, a distribution tree will be created in the top-level "mxe-minetest" directory: minetest-win32 # If 32-bits mode is selected minetest-win64 # If 64-bits mode is selected (end of document)