Update the build instructions for all platforms.

Also includes packaging notes for Linux and macOS, with a placeholder
for Windows.

sc2/INSTALL

@@ -1,87 +1,89 @@
-To build The Ur-Quan Masters, you need at least the following software:
+               THE UR-QUAN MASTERS: BUILD INSTRUCTIONS
+               ---------------------------------------
 
-For unix-like platforms (such as Linux, BSD, Solaris, MinGW):
+INSTALLING PREREQUISITES
-GCC 3.0 - GNU C Compiler
+------------------------
-	http://gcc.gnu.org/
-	Debian package: gcc
 
-GNU Make 3.80
+To build The Ur-Quan Masters, you must first install its
-	ftp://ftp.gnu.org/
+prerequisites: SDL2, PNG, Ogg Vorbis, and Zlib. How to do this will
-	Debian package: make
+depend on what operating system you are running:
 
-For Windows:
+On Debian or similar systems like Ubuntu, install the following packages:
-Microsoft Visual C++ 6 or newer (or MinGW+MSYS, see INSTALL.mingw for that)
-Visual C++ 6.0 Processor Pack (if using VC6, to build MMX-accelerated code)
-	http://msdn.microsoft.com/vstudio/downloads/tools/ppack/
 
-For Mac OS X:
+  sudo apt-get install build-essential libogg-dev libpng-dev libsdl2-dev \
-Apple Developer Tools (for Mac OS X 10.2 and older)
+                       libvorbis-dev libz-dev
-	http://connect.apple.com/
-Xcode Tools (for Mac OS X 10.3)
-	http://developer.apple.com/tools/macosxtools.html
 
-Additionally, The Ur-Quan Masters requires the following libraries:
+On Fedora or similar systems like CentOS, install these packages:
-Note that dependencies can differ between different OS's.
+  sudo dnf install libogg-devel libpng-devel libvorbis-devel make SDL2-devel \
+                   zlib-devel
 
-OpenGL v1.2 (if HAVE_OPENGL is defined, which is the default)
+On macOS, install Xcode from the App Store, and then install
-    Win32 users should have all by default, following is for Linux version:
+"Additional components" when you run it for the first time. You can
-	http://www.xfree86.org/
+then install brew from https://brew.sh and then use it to install your
-	Debian package: xlibmesa-dev OR nvidia-glx OR <vendor specific>
+requirements from the Terminal:
-	XFree86 4.x comes with Mesa, which is a clone.
-	Note: Mesa is a software emulation. For enjoyable results
-	you will need hardware accelerated OpenGL (GLX).
-	These usually conflict with mesa (can result in X server crash).
 
-SDL v1.2
+  brew install libogg libpng libvorbis sdl2
-	The Simple Direct-Media Layer
-	A fairly good multiplatform low level graphics library.
-	Homepage: www.libsdl.org
-	Download: http://www.libsdl.org/download-1.2.php
-	Debian package: libsdl1.2-dev (and various runtime debs)
 
-libpng
+On Windows, you will need to use the MSYS2 system from
-	An image loading library.
+https://www.msys2.org -- after you install the base system, open an
-	Homepage: http://www.libpng.org/pub/png/libpng.html
+"MSYS2 MSYS" window and update the system with the command
-	Debian packages: libpng-devxs
-	
-OpenAL (optional)
-	A cross-platform spatialized audio library.
-	Homepage: http://www.openal.org/
-	Windows SDK download: http://connect.creativelabs.com/openal/Downloads/OpenAL11CoreSDK.zip
 
-libogg and libvorbis (optional but highly recommended)
+  pacman -Syuu
-	Audio codec to play Ogg Vorbis files, used for music and speech.
-	Homepage: http://www.xiph.org/ogg/vorbis/index.html
-	Download:
-	    For Windows:
-			SDK download: http://www.vorbis.com/files/1.0.1/windows/OggVorbis-win32sdk-1.0.1.zip
-	    For Linux:
-			http://www.xiph.org/downloads/
-			download libogg and libvorbis.
 
-Tremor (alternative for libogg and libvorbis)
+until there is nothing left to do. Aftr that you can install the
-	Audio codec to play Ogg Vorbis files, used for music and speech.
+packages you will need to build the 32-bit version of UQM:
-	This library avoids floating point math and should be used instead
-	of libogg and libvorbis when floating point support is not available
-	or slow (on some handhelds and game consoles).
-	Homepage: http://www.xiph.org/vorbis/
-	Download: http://svn.xiph.org/trunk/Tremor (Subversion)
 
-Libmikmod (also included with UQM source)
+  pacman -S make pkg-config mingw-w64-i686-gcc mingw-w64-i686-libogg \
-	Audio codec to play .mod files, used for the original PC music.
+            mingw-w64-i686-libpng mingw-w64-i686-libsystre \
-	Homepage: http://mikmod.raphnet.net/
+            mingw-w64-i686-libvorbis mingw-w64-i686-SDL2 mingw-w64-i686-zlib
-	Download: https://sourceforge.net/projects/mikmod/files/
 
-Zlib v1.2
+Actually building UQM will need to be done from a "MSYS2 MinGW 32-bit"
-	Data compression / decompression library
+window, not "MSYS2 MSYS".
-	Homepage: http://www.gzip.org/zlib/
-	Download:
-	    For Windows:
-		http://www.gzip.org/zlib/ (mid-page 'zlib compiled DLL')
 
+BUILDING THE PROGRAM
+--------------------
 
-If you find these aren't enough, or if you know the names
+Building and configuration is managed by the "build.sh" script in the
-of the corresponding RPM etc. packages, please report to
+same directory as this file. Ordinarily, you will only need the command
-<sc2-devel@lists.sourceforge.net> or visit
+
-http://sourceforge.net/projects/sc2/
+  ./build.sh uqm
+
+To configure and build the system. Pass an argument like "-j5" for a
+parallel build using 5 processes. To delete the current bulid and
+reconfigure, issue the command
+
+  ./build.sh uqm clean
+
+And it will clear out all configuration choices.
+
+The configuration process is interactive; for unattended or scripted
+installs, consult the "config.state" file generated by the
+configuration process and synthesize an equivalent as needed; builds
+will then skip the configure step after that.
+
+After the build completes, a binary named "uqm" or "uqm-debug" will be
+created, and should be runnable out of this directory. To produce a
+distributable or installable package that runs on any system, more
+work is needed.
+
+BUILDING AN INSTALLABLE PACKAGE
+-------------------------------
+
+LINUX: The UQM project does not officially maintain any installation
+packages for any Linux distro, but other volunteers have often done
+this already. In general, all that will be needed is to arrange
+matters so that the uqm binary and the content directory are installed
+into globally accessible locations, and that it is invoked with
+arguments that properly identify those directories.
+
+WINDOWS: An installable Windows build takes the UQM.EXE file created
+by the build process and then correlates it with the prepackaged
+content packs to produce an installer executable that will download
+all other data from sourceforge. See INSTALL.win32 for the extra steps
+required for this.
+
+MAC: A redistributable package on macOS is an app bundle that contains
+everything needed to run the program. Because of the way brew handles
+system dependencies, the program must be built differently to be
+redistributable. See INSTALL.macos for details on how to do this.
 

sc2/INSTALL.macos

@@ -0,0 +1,44 @@
+               BUILDING THE UR-QUAN MASTERS ON MAC OS X
+               ----------------------------------------
+
+Starting with 0.7.1, it is possible to build and run The Ur-Quan
+Masters with the brew system (https://brew.sh). This is much easier
+than building a redistributable package, and personal builds should
+probably rely on this. See the main INSTALL file for instructions
+there.
+
+To create a .app file that will work on most Macs, you will need to
+create an app bundle with custom copies of its libraries. To do
+*that*, you will to build most of them yourself:
+
+SDL2: https://www.libsdl.org
+    The development libraries for macOS available here already work
+    fine and do not need any extra work.
+
+Ogg Vorbis: http://www.xiph.org
+    You will need to build frameworks out of libogg and libvorbis,
+    which will be named Ogg.framework and Vorbis.framework.
+
+libpng: http://www.libpng.org/pub/png/libpng.html
+    You will ultimately need to create libpng.framework.
+
+These frameworks should be built as "archives" in Xcode with a macOS
+deployment target of 10.6. Copy the framework directories out of the
+archives into /Library/Frameworks.
+
+With these in place, copy the content packages that you intend to
+undle with the app (at minimum content, but potentially also voice and
+3DO music or even remixes) into a subdirectory under this one named
+"dist-packages".
+
+You are now ready to actually build and package the application:
+
+    DEPS_PATH=/Library/Frameworks ./build.sh uqm
+    build/unix_installer/copy_mac_frameworks.pl
+
+This should produce a working app bundle named "The Ur-Quan
+Masters.app". For proper redistribution this app should be put in a
+disk image with the Disk Utility. If you are running on a version of
+macOS later than 10.12, don't forget to make sure you use HFS+ instead
+of APFS, or your disk image won't be mountable on any version of macOS
+10.12 or earlier!

sc2/INSTALL.macosx

@@ -1,30 +0,0 @@
-BUILDING THE UR-QUAN MASTERS ON MAC OS X
-
-Starting with 0.7.1, it is possible to build and run The Ur-Quan
-Masters with the brew system (https://brew.sh).
-
-To install the necessary prerequisite libraries, run this command:
-
-    brew install sdl2 libpng libogg libvorbis
-
-To build:
-- Run `./build.sh uqm` in the sc2/ directory and choose your
-  configuration options. The only truly important one is to use
-  Included MikMod instead of System MikMod.
-
-The result can be run directly from the Terminal.
-
-- If it builds without errors (last line is LINK uqm or LINK
-  uqm-debug), `./build.sh uqm install` will build a .app file you can
-  run from the build directory.
-
-Be aware that the .app file built by this procedure still links
-against brew's versions of the libraries in their install locations,
-and will not run on other Macs unless they also have brew installed
-with the relevant packages. To make a standalone build you will need
-to build against frameworks that are properly configured to work as
-part of an app bundle and then package them with the result. The
-build/unix_installer/copy_mac_frameworks.pl script automates some of
-this work, but it's not particularly user-friendly or part of a
-conveniently automatable script system yet. That level of support is
-forthcoming.

sc2/INSTALL.mingw

@@ -1,64 +0,0 @@
-Instructions for building UQM in Windows with MinGW and MSYS
-============================================================
-
-First, download and install the latest version of MinGW and then MSYS.
-(You can get them from <http://www.mingw.org/>).
-
-You'll need all the libraries described in the INSTALL file in SVN.
-You should get the 'mingw' development build for SDL, and follow the
-instructions to install it into mingw. All others will be either for win32
-or VC.
-
-These are the files you need to download:
-
-http://www.libsdl.org/release/SDL-devel-1.2.14-mingw32.zip
-http://www.libsdl.org/projects/SDL_image/release/SDL_image-devel-1.2.10-VC.zip
-http://connect.creativelabs.com/openal/Downloads/OpenAL11CoreSDK.zip (optional)
-http://www.vorbis.com/files/1.0.1/windows/OggVorbis-win32sdk-1.0.1.zip
-http://www.gzip.org/zlib/zlib125-dll.zip
-
-
-You can now do either of the following:
-1) Copy the DLLs for each library to \[MinGW]\lib.  Copy the header files for
-   each library to \[MinGW]\include, (where [MinGW] is the directory where you
-   installed MinGW) except for the Ogg Vorbis headers -- copy the folders (ogg
-   and vorbis) containing the header files to the include directory.
-
-2) Within MSYS set C_INSTALL_PATH and LIBRARY_PATH to point at all of the 
-   respective include and library dirs where you installed them.
-   i.e. something like:
-
-   export C_INCLUDE_PATH=/mingw/include/SDL:/c/VClibs/SDL_image-1.2.10/include/:/c/VClibs/OpenAL\ 1.1\ SDK/Include/:/c/VClibs/oggvorbis-win32sdk-1.0.1/include/:c/VClibs/zlib/include/
-   export LIBRARY_PATH=/c/VClibs/SDL_image-1.2.10/lib/:/c/VClibs/OpenAL\ 1.1\ SDK/libs/:/c/VClibs/oggvorbis-win32sdk-1.0.1/lib/:c/VClibs/zlib/lib/
-
-NOTE:  If you use the 2nd method above, you need to include the path to SDL
-in C_INCLUDE_PATH (but not in LIBRARY_PATH)
-
-The Ogg Vorbis headers want a header that is not included with MinGW. To get
-this file, download <http://sc2.sourceforge.net/misc/_G_config.h>
-and put it to \[MinGW]\include.
-
-If you want to build with OpenAL support, you need to modify the OpenAL SDK
-installation somewhat:
-- Create a directory "AL" in "C:\VClibs\OpenAL 1.1 SDK\include"
-- Copy all the .h files from "C:\VClibs\OpenAL 1.1 SDK\include"
-  into the newly created "AL" directory.
-
-Now you're ready to build. Start up MSYS (the installer put an icon in your
-Start Menu and on the desktop).
-
-cd to the UQM directory. It'll be at /[drive letter]/[path to uqm].
-
-./build.sh uqm config
-
-It should correctly detect everything, and give you a menu.
-
-Next run './build.sh uqm depend' (just to be sure)
-and lastly:
-./build.sh uqm
-
-If you did everything correctly, it should now build successfully.
-
-To run the built executable, you should copy all the required DLLs to the
-same directory the executable is in, or copy them to your Windows directory.
-

sc2/INSTALL.msvc

@@ -1,159 +0,0 @@
-This file describes step-by-step how to use Microsoft Visual C++ to build
-The Ur-Quan Masters. It assumes you want to install the Microsoft Visual C++
-Express Edition, which can be downloaded for free from Microsoft.
-If you already have another version of MSVC++ installed, you can skip step 1,
-and you do not need to add the Platform SDK paths to the include and library
-locations in steps 5.2 and 5.3.
-The files and locations are for compilation on 32 bits systems; on 64 bits
-systems some will be slightly different.
-
-
-1. Install the Microsoft development environment
-
-1.1. Install Microsoft Visual C++ 2008 Express Edition:
-- Download the installer from
-  http://www.microsoft.com/downloads/details.aspx?familyid=94de806b-e1a1-4282-abc5-1f7347782553
-- Run the installer, and follow the instructions. There's no need
-  to register your copy of MSVC++ to use it for compiling UQM.
-
-1.2. Install the Microsoft Windows Platform SDK:
-- Download the installer from
-  http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB
-  or a newer version of the SDK
-- Run the installer, and follow the instructions.
-
-
-2. Install the tools needed to install all the requirements:
-
-2.1. Install TortoiseSVN, a Subversion client which we will use to check out the most
-recent development version of the UQM source:
-- Download the installer from http://tortoisesvn.net/downloads
-- Run the installer, and follow the instructions
-
-2.2. Install WinZip, if you cannot open .zip files natively:
-- Download WinZip from http://www.winzip.com/downwzeval.htm
-- Run the installer, and follow the instructions
-
-
-3. Install the dependencies
-
-3.1. Prepare the build location
-Create a folder "Build" in "C:\"; this is where we will put our dependency
-packages.
-
-3.2 Install the SDL SDK:
-- Download SDL-devel-1.2.14-VC6.zip from
-  http://www.libsdl.org/download-1.2.php
-- Unzip ("Extract" in WinZip) the file in "C:\Build"
-  A folder "SDL-1.2.14" will be created.
-
-3.3 Install the SDL_image SDK:
-- Download SDL_image-devel-1.2.10-VC.zip from
-  http://www.libsdl.org/projects/SDL_image/
-- Unzip ("Extract" in WinZip) the file in "C:\Build"
-  A folder "SDL_image-1.2.10" will be created.
-
-3.4 Install the Ogg Vorbis SDK
-- Download
-  http://www.vorbis.com/files/1.0.1/windows/OggVorbis-win32sdk-1.0.1.zip
-- Unzip ("Extract" in WinZip) the file in "C:\Build"
-  A folder "oggvorbis-win32sdk-1.0.1" will be created.
-
-3.5 Install zlib:
-- Download zlib123-dll.zip ("zlib compiled DLL") from
-  http://www.gzip.org/zlib/
-- Create a folder "zlib-1.2.5" in "C:\Build\"
-- Unzip "zlib125-dll.zip" in C:\Build\zlib-1.2.5\"
-
-3.6 Install OpenAL
-- Download http://connect.creativelabs.com/openal/Downloads/OpenAL11CoreSDK.zip
-- Unzip and run the installer and follow the instructions
-- Create a directory "AL" in "C:\Program Files\OpenAL 1.1 SDK\include"
-- Copy all the .h files from "C:\Program Files\OpenAL 1.1 SDK\include"
-  into the newly created "AL" directory.
-
-
-4. Install the UQM files
-
-4.1. Checkout the UQM source
-- Open the folder "C:\"
-- Right click on "Build", and select "SVN Checkout..."
-- In the "URL of repository" field input
-  	https://sc2.svn.sourceforge.net/svnroot/sc2/trunk/sc2/
-- In the "Checkout directory" field input
-	C:\Build\sc2
-- Press ok and the checkout will begin. This may take a while.
-  A folder "sc2" will be created in "C:\Build\".
-
-4.2. Copy the runtime libraries where they can be found by UQM when run
-     from MSVC++.
-- Copy the following files to "C:\Build\sc2\":
-  - "C:\Build\SDL-1.2.14\lib\SDL.dll"
-  - "C:\Build\SDL_image-1.2.10\lib\jpeg.dll"
-  - "C:\Build\SDL_image-1.2.10\lib\libpng12-0.dll"
-  - "C:\Build\SDL_image-1.2.10\lib\libtiff-3.dll"
-  - "C:\Build\SDL_image-1.2.10\lib\SDL_image.dll"
-  - "C:\Build\SDL_image-1.2.10\lib\zlib1.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\ogg.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\ogg_d.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\vorbis.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\vorbis_d.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\vorbisenc.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\vorbisenc_d.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\vorbisfile.dll"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\bin\vorbisfile_d.dll"
-
-
-5. Set up the The Ur-Quan Masters project in Visual C++
-
-5.1. Import the VC6 .dsp file:
-- Open C:\Build\sc2\build\msvc6\ and double-click on "UrQuanMasters.dsp".
-  Visual C++ will start. Confirm when it asks to convert the VC6 .dsp file.
-
-5.2. Setup the additional include locations for the project:
-- Still in MSVC++, right click on 'UrQuanMasters' in the Solution Explorer,
-  and choose "Properties"
-- In the left part of the screen, select "Configuration Properties", then
-  "C/C++", and then "General"
-- In the right part, select "Additional Include Directories", then click on
-  "..."
-- Add the paths to the "include" folders of all of the dependency
-  libraries:
-  - "C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include"
-  - "C:\Build\SDL-1.2.14\include"
-  - "C:\Build\SDL_image-1.2.10\include"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\include"
-  - "C:\Program Files\OpenAL 1.1 SDK\include"
-  - "C:\Build\zlib-1.2.5\include"
-
-5.3. Setup the additional library locations for the project:
-- Still in the project properties pages, in the left part of the screen,
-  click on "Linker", then "General"
-- In the right part, select "Additional Library Directories", then click on
-  "..."
-- Add the paths to the "lib" folders of all of the dependency
-  libraries:
-  - "C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib"
-  - "C:\Build\SDL-1.2.14\lib"
-  - "C:\Build\SDL_image-1.2.10\lib"
-  - "C:\Build\oggvorbis-win32sdk-1.0.1\lib"
-  - "C:\Program Files\OpenAL 1.1 SDK\libs\Win32"
-  - "C:\Build\zlib-1.2.5\lib"
-
-5.4. Remove unnecessary dependencies
-- Still in the "Linker" part of the project properties pages, in the left
-  part of the screen, click on "Input".
-- In the right part, select "Additional Dependencies", then click on "..."
-- Remove odbc32.lib and odbccp32.lib
-
-5.5. Add user32.lib
-- Still in "Additional Dependencies", add "user32.lib"
-
-
-6. Build The Ur-Quan Masters
-- Still inside MSVC++, press F7
-  If MSVC++ asks to save the project, confirm.
-  If everything is right, you should now have a working uqm executable.
-  You can press F5 to run it from MSVC++.
-
-

sc2/INSTALL.win32

@@ -0,0 +1,6 @@
+BUILDING THE WIN32 INSTALLER
+----------------------------
+
+At the moment, alas, this file is a stub. The process needs some
+refinement before a minimal set of build steps may be assembled. This
+file should be updated before any 0.8 release candidate.