Building EDuke32 on Windows

From EDukeWiki
Revision as of 13:42, 25 November 2019 by Hendricks266 (talk | contribs) (→‎setup)
Jump to navigation Jump to search
EDuke32 Distribution

Download · Source Code · APT repository · Packages
Building from source on: Linux · Windows · macOS


There are several options available to develop EDuke32 on Windows. Before you begin, you will need to acquire the EDuke32 source code.

Microsoft Visual Studio

For many developers, Visual Studio will be the easiest and most familiar way to work with the source. While the EDuke32 team prefers GCC for production builds, the VS IDE is a valuable and useful resource for development.

setup

Visual Studio can be downloaded from Microsoft's website. The free version, Visual Studio Community, works perfectly. If you don't want the IDE, the Build Tools for Visual Studio will install the toolchain by itself.

Visual Studio 2013 is the minimum supported version for building EDuke32, but the newest version is always recommended.

building

from the IDE

Either click on the green play button, or navigate Build → Build eduke32 in the menus to start the build process.

from the command line

You will need to set up your paths to contain the VS toolchain. Newer versions provide shortcuts in the start menu to start a terminal with the appropriate settings. Doing so manually is out of scope of this article.

Navigate to platform/Windows in the EDuke32 source code and enter:

nmake -f msvc.mak

MinGW-w64/GCC with MSYS2

For a more Unix-like style of development, MSYS2 provides a bash shell, native GCC and clang builds, and the pacman package manager originally from Arch Linux.

tips to remember

  • You can press the middle mouse button to paste text into the MSYS2 terminal, or right-click for more options.
  • You can navigate folders using the cd command (short for change directory), or the pushd command, which adds the new path you specify to a stack, allowing you to return to your previous location with popd.
  • Paths use forward slashes (/) instead of backslashes (\) and drive letters take the form /c/ instead of C:\, though it will likely understand either way if you put your path in "quotes".

setup

  1. First, install MSYS2, following the instructions on that page fully. Install whichever architecture matches your computer; both can cross-compile to the other.
    • If you see the prompt warning: terminate MSYS2 without returning to shell and check for updates again during this process, press Ctrl+C to dismiss it, then exit and the session and open a new one. Alternatively, close pacman.exe, bash.exe, and mintty.exe in the Task Manager, or by using taskkill /f /im <exe> from a Windows command prompt (cmd.exe).
  2. The installer will create three shortcuts in the Start Menu. Ignore MSYS2 MSYS. Open MSYS MinGW (32-bit) or (64-bit) to select which architecture you would like to target while building during the shell session that begins. Unfortunately, one deficiency in MinGW-w64 is that the each of the two targets (32-bit and 64-bit) require their own separate executables, instead of using one binary with the -arch parameter as on other platforms.
  3. Try updating all packages with pacman -Syuu to verify you've completed the instructions. If all is well, you should see there is nothing to do. Otherwise, accept the update and repeat until there is nothing further to update.
  4. Next, we will need to install some additional packages. The pacman package manager covers all of MSYS2 and is not affected by which shortcut you chose in the previous item.
    • These packages are necessary to build:
      • pacman -S --needed --noconfirm mingw-w64-i686-toolchain mingw-w64-x86_64-toolchain make nasm yasm
    • If you would like to use Subversion and Git directly from the MSYS2 shell:
      • pacman -S --needed --noconfirm subversion git
    • If you would like clang as an additional compiler option:
      • pacman -S --needed --noconfirm mingw-w64-i686-clang mingw-w64-x86_64-clang
    • EDuke32 includes prebuilt Windows static libraries for all external dependencies with its source code, and therefore installing them through the package manager is superfluous. However, for reference:
      • pacman -S --needed --noconfirm `pacman -Ssq sdl` `pacman -Ssq libogg` `pacman -Ssq libvorbis` `pacman -Ssq flac` `pacman -Ssq libvpx` `pacman -Ssq luajit`

You should now be all set.

building

Now that we've got everything together, you can try building EDuke32 and Mapster32. Navigate to the base directory containing the EDuke32 source code, type the following and eduke32.exe and mapster32.exe should be created.

make

For quick testing of changes, it is recommended to build a debug executable, which skips all compiler optimizations for a much faster compile time, and also includes information about the source code called debug symbols for debugging with GDB. Append RELEASE=0 to the command, like this:

make RELEASE=0

You can enable parallelism and build multiple objects at the same time with '-j'. The flag by itself will use the total number of threads available, or you can specify a number, such as '-j2'.

make RELEASE=0 -j4

To compile only either the game or the editor, simply give make the name of the executable, like

make RELEASE=0 -j4 eduke32.exe

To build with clang, append the setting CLANG=1 to your make invocation.

make RELEASE=0 -j4 eduke32.exe CLANG=1

troubleshooting

If something doesn't go as planned, don't despair. Most issues are resolved rather quickly.

  • If you see a barrage of error messages saying that some symbols are not defined, check whether you have all necessary prerequisites like the DirectX SDK installed and that the paths in the Makefile point to the right location.
  • If you get errors at the end of the build process (technically, at link time), there's usually a problem with the libraries -- the linker can't find one or more .a files [needs explanation].
  • Finally, if the executable starts but aborts shortly thereafter, a dynamic link library may be missing. Usually you'll get a helpful message with its name.

debugging

See Troubleshooting EDuke32.

MinGW-w64/GCC (Standalone)

MSYS2 has some minor downsides: occasional slowness in the shell and file I/O, and the unchangeable default of using POSIX threading (requiring distribution of libwinpthread-1.dll with your binaries) instead of native Win32 threads. For advanced users seeking the best-quality binaries for distribution, it is possible to build with nothing but a standalone MinGW-w64 toolchain and cmd.exe.

setup

GCC

  1. First, download one or more MinGW-w64 packages. These contain the entire toolchain. For our purposes, Win32 threads are preferred to POSIX threads, and seh (for 64-bit) and dwarf (for 32-bit) exception handling methods are preferred to sjlj.
  2. You are going to want to extract these in an organized fashion. For example:
    • C:\MinGW-w64\mingw32\bin\gcc.exe
    • C:\MinGW-w64\mingw64\bin\gcc.exe
  3. If you are interested in building 32-bit binaries, also download NASM and extract its contents to the i686 bin folder, so nasm.exe is located there.
    • C:\MinGW-w64\mingw32\bin\nasm.exe
  4. Unfortunately, one deficiency in MinGW-w64 is that the each of the two targets (32-bit and 64-bit) require their own separate executables, instead of using one binary with the -arch parameter as on other platforms. You will need to use the included mingw32env.cmd or mingw64env.cmd to set up your PATH variables for a session that can use the toolchain you have set up. When building, the executables generated will match the target of whatever compiler is the highest in PATH--no extra make parameters needed.
    • Power users can permanently set up their PATH to one or the other toolchain through Advanced system settings (aka sysdm.cpl) if desired. If you have enabled the "Launch folder windows in a separate process" option in Windows Explorer, you will need to restart explorer.exe (either by terminating and relaunching it in Task Manager, or restarting your computer) for changes made to persistent PATH to take effect in command prompt windows launched from within Explorer.
  5. MinGW-w64 comes with GNU Make, but it is named mingw32-make.exe. If you don't want to type mingw32-make where you would normally type make, feel free to copy mingw32-make.exe make.exe.
  6. One final note: If you are trying to build ebacktrace1.dll and are getting errors about a missing "bfd.h", you need to copy the following files from <root>\include\ to <root>\<target>-w64-mingw32\include\:
ansidecl.h
bfd.h
bfdlink.h
dis-asm.h
symcat.h

clang

This process should set up a fully working GCC. Unfortunately, clang is a different story. Recent releases of clang for Windows default to acting as a drop-in replacement for Visual Studio, rather than MinGW. However, for the adventurous:

  1. Download clang for Windows.
  2. Extract your choice of 32-bit and/or 64-bit binaries to the bin folder of the corresponding MinGW-w64 toolchain installed above.
  3. When building EDuke32, append CUSTOMOPT="-target i686-w64-mingw32" (targeting a 32-bit build) or CUSTOMOPT="-target x86_64-w64-mingw32" (targeting 64-bit) in addition to CLANG=1 so clang tries to use GCC's headers instead of Visual Studio's headers.

Since primary purpose of a standalone setup is producing the most optimized production binaries possible, clang on Windows may or may not be stable, robust, and mature enough to be worth it in this setting. For simple development aids such as clang's very nice diagnostic output, using it in MSYS2 should be sufficient.

building

Open mingw32env.cmd or mingw64env.cmd (double-clicking is fine) to start a command prompt window. Once there, building is the same as with MSYS2, with the exception of using mingw32-make instead of make if you did not copy it.

In order to allow building in the absence of an sh.exe, the PRETTY_OUTPUT colorful build process message feature provided by EDuke32's Makefile is disabled with this setup. Advanced users can open the MSYS2 MSYS shortcut, if installed above, or Git Bash, in combination with manually configuring their Unix-style PATH variable, to get colorful output with a standalone toolchain.