WIP documentation on building for macOS and building wider Linux compatibility

README.md

@@ -5,7 +5,7 @@
 
        /\         +-------------------------------------------------------+
   ____/  \____   /| Open source game framework licensed to freely use,    |
-  \          /  / | copy, and modify. Created for --> dank.game <--       |
+  \          /  / | copy, and modify. Created for [dank.game]             |
 +--\ ^__^   /--+  |                                                       |
 | ~/        \~ |  | Download at https://open.shampoo.ooo/shampoo/spacebox |
 | ~~~~~~~~~~~~ |  +-------------------------------------------------------+
@@ -16,7 +16,7 @@
 
 *SPACE🪐BOX* is a C++ framework that makes creating cross-platform games and other interactive applications easier and faster by providing an added layer of abstraction between SDL + OpenGL and the project.
 
-Users can start a project by extending only a single function, the Game class's update function. Using a standard Makefile that can be taken from the examples, the framework can export the same code to multiple platforms such as, in order of current stability, Linux, Web, Android, OS X, Windows, and Raspberry Pi.
+Users can start a project by extending only a single function, the Game class's update function. Using a standard Makefile that can be taken from the examples, the framework can export the same code to multiple platforms such as, in order of current stability, Linux, Web, Android, macOS, Windows, and Raspberry Pi.
 
 It is in an early, untested state. It comes with a few simple examples that demonstrate how to use it.
 
@@ -67,6 +67,70 @@ SPACEBOX itself currently needs to be compiled along with the project's source,
 
 This is the platform SPACEBOX is built on, so it has the most straightforward build process. Copy the Makefile from the fill_screen demo, which demonstrates how to compile SPACEBOX and link to required libraries, adapt it to fit a new project, and build a Linux executable with GNU make.
 
+#### Linux Distributable
+
+[Stack Overflow thread](https://stackoverflow.com/q/2856438)
+
+There are few techniques that can be used to increase compatibility among Linux versions for the resulting binary.
+
+##### Checking dependencies
+
+Use `readelf` to see which libraries a binary uses and what the extra search path is
+
+    $ readelf -d build/x86_64/Cakefoot-linux.x86_64
+    Dynamic section at offset 0x1a2c10 contains 36 entries:
+    Tag        Type                         Name/Value
+    0x0000000000000001 (NEEDED)             Shared library: [libSDL2-2.0.so.0]
+    0x0000000000000001 (NEEDED)             Shared library: [libGL.so.1]
+    0x0000000000000001 (NEEDED)             Shared library: [libGLESv2.so.2]
+    0x0000000000000001 (NEEDED)             Shared library: [libSDL2_image-2.0.so.0]
+    0x0000000000000001 (NEEDED)             Shared library: [libSDL2_ttf-2.0.so.0]
+    0x0000000000000001 (NEEDED)             Shared library: [libSDL2_mixer-2.0.so.0]
+    0x0000000000000001 (NEEDED)             Shared library: [libstdc++.so.6]
+    0x0000000000000001 (NEEDED)             Shared library: [libm.so.6]
+    0x0000000000000001 (NEEDED)             Shared library: [libgcc_s.so.1]
+    0x0000000000000001 (NEEDED)             Shared library: [libc.so.6]
+    ...
+
+Use `objdump` to see which symbols a binary uses. In this case `ios_base` is needed from `GLIBCXX_3.4.32` (an older version of GLIBCXX couldn't be used for the `ios_base_library_init` symbol during compilation).
+
+    $ objdump -x build/x64/Cakefoot-linux.x64 | grep GLIBCXX_3.4.32 | c++filt
+    0x0297f842 0x00 23 GLIBCXX_3.4.32
+    0000000000000000       F *UND*  0000000000000000              std::ios_base_library_init()@GLIBCXX_3.4.32
+
+##### Static flags
+
+Adding `-static-libgcc` and `-static-libstdc++` to the linker flags will remove the dependencies on `libstdc++` and `libgcc_s`.
+
+##### Older compiler
+
+Using an older version of GCC to compile can lower the version of some symbols.
+
+##### Packaging shared libraries
+
+The `rpath` property can be used to add a local library search path to the linker, and any libraries to package with the distributable can be added to the local path. For example, this is how SDL is packaged with Cakefoot.
+
+This flag is used to add a relative library lookup path
+
+    -Wl,-rpath $(X64_BUILD_LIB_DIR)
+
+This block is used to copy the SDL libraries into the local library folder
+
+    cp $$(ldd $(X64_BUILD_DIR)/$@ | grep libSDL2-2.0 | cut -d" " -f3) \
+        $$(ldd $(X64_BUILD_DIR)/$@ | grep libSDL2_image | cut -d" " -f3) \
+        $$(ldd $(X64_BUILD_DIR)/$@ | grep libSDL2_ttf | cut -d" " -f3) \
+        $$(ldd $(X64_BUILD_DIR)/$@ | grep libSDL2_mixer | cut -d" " -f3) ${basename $@}/$(X64_BUILD_LIB_DIR)
+
+##### Virtualization using Docker
+
+Docker can be used to compile for a target platform with a desired baseline compatibility profile, for example, Ubuntu 16.04.
+
+    apt install docker.io
+    
+Make sure your user has sudo permissions to use `/usr/bin/docker` by editing either `/etc/sudoers/` or a file in `/etc/sudoers.d/`. Then pull the Ubuntu 16.04 image.
+
+    sudo docker pull ubuntu:16.04
+
 ### Emscripten
 
 Exporting a browser build with [Emscripten][] and its built-in version of SDL has worked well on a few projects. The general process is to create a separate make target that uses Emscripten's C++ to WebAssembly compiler. See the browser webcam demo below for an example.
@@ -297,6 +361,8 @@ Install MinGW. The simplest way to install is through the package manager. On De
 Add `-DGLEW_STATIC` to compile the GLEW library into a [SPACE BOX] project using MinGW.
 
 Add `-static-libgcc` and `-static-libstdc++` to the linker flags to compile GCC and C++ STD runtime DLLs into the executable instead of distributing the DLL file with the executable.
+
+Add `-mwindows` to the linker flags to prevent Windows from opening a console window in the background when launching the game.
     
 See the Windows section of `demo/box/Makefile` for a complete list of necessary flags and build process.
     
@@ -305,9 +371,13 @@ See the Windows section of `demo/box/Makefile` for a complete list of necessary
 * `std::filesystem::path::c_str` returns a `const wchar_t*` instead of `const char*`. To make a platform generic call, convert the path to a string, then use `std::filesystem::path::string::c_str` instead.
 * In order to use `std::thread` with MinGW, you must use the POSIX version of the compiler, for example `x86_64-w64-mingw32-g++-posix` and add `-lpthread` to the linker flags.
 
-### OS X
+### macOS
 
-Builds for OS X have only passed the proof of concept phase. An early version of SPACEBOX was compiled for it, but none of the demos have been compiled in their current form, so there is only some broken code available in the box demo's `Makefile`.
+[SDL Wiki - macOS](https://wiki.libsdl.org/SDL2/Installation#macos)
+
+To fully support macOS, both Intel `x86_64-macos` and ARM `aarch64-macos` architecture versions must be compiled.
+
+Make sure the version of macOS on the build host system is supported by the version of SDL being used. There is information in the documentation in the SDL source at `SDL2-2.X.X/docs/README-macos.md`. If possible, upgrade the macOS operating system, one version at a time, until the version installed is supported by SDL, using the [official Apple support links](https://support.apple.com/en-us/102662), or downgrade SDL by [downloading a lower version](https://github.com/libsdl-org/SDL/releases/).
 
 Demos
 -----