Replace packaging/3rdParty-devel/readme.txt with README.md

packaging/3rdParty-devel/README.md

@@ -0,0 +1,97 @@
+# Third party dependency builds for Speed Dreams
+
+On platforms where a package manager is not available, such as Microsoft
+Windows, third party dependencies must be built from source so CMake can find
+them when building Speed Dreams. Builds are based on the
+[`ExternalProject`](https://cmake.org/cmake/help/latest/module/ExternalProject.html)
+CMake module.
+
+Therefore, Speed Dreams holds [a list](./thirdpartydefinitions.cmake) of
+pinnings against third-party dependencies. A build consists of:
+
+1. Fetching the source code from different repositories.
+2. Building the dependencies.
+3. Installing them to the `3rdParty/` directory, inside the build directory.
+**This is the directory referred to by the top-level**
+**[`CMakeLists.txt`](/CMakeLists.txt)**
+**when performing Windows builds, via either `CMAKE_PREFIX_PATH` or**
+**`CMAKE_FIND_ROOT_PATH`**. Read
+[the relevant section from the top-level `README.md`](/README.md#windows)
+for further reference.
+
+## Requirements
+
+### Debian/Ubuntu
+
+```
+sudo apt install cmake subversion git
+```
+
+A modern version of the C++ compiler is required because
+[OpenAL](https://github.com/kcat/openal-soft) makes use of C++11's
+`std::mutex`, which was added to `win32` only recently.
+So far, only `14.2.0` has been successfully tested.
+Therefore, **this might require to build GCC from source,**
+**until distributions ship more modern versions of the C++ compiler**.
+
+#### `x86_64`
+
+```
+sudo apt install g++-mingw-w64-x86-64-win32
+```
+
+#### `i686`
+
+```
+sudo apt install g++-mingw-w64-i686-win32
+```
+
+### Windows
+
+- [CMake](https://cmake.org/download/#latest) `3.5.0` or newer
+- [Git](https://git-scm.com/download/win)
+- [TortoiseSVN](https://tortoisesvn.net/)
+- [MinGW](https://winlibs.com/), with support for C++11 and `std::mutex`.
+So far, `14.2.0` has been tested successfully.
+
+> Please ensure these tools are added to the `%PATH%` environment variable.
+
+## Configuring
+
+### Natively from Windows
+
+```
+cmake -B build
+```
+
+### Cross-building from Linux
+
+CMake defines the
+[`CMAKE_TOOLCHAIN_FILE`](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html)
+variable to set up the cross-toolchain. This directory defines several files,
+according to the target platform:
+
+#### `x86_64`
+
+```
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=x86_64-w64-mingw32.cmake
+```
+
+#### `i686`
+
+```
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=i686-w64-mingw32.cmake
+```
+
+## Building
+
+Once the project is configured according to the steps above, build with:
+
+```
+cmake --build build/ # Optionally, add -j8 or any other number for faster builds
+```
+
+The build will probably take a long time, as it builds tens of third-party
+libraries fetched from multiple sources. Once finished, a directory called
+`3rdParty/` should be available inside the build directory, ready to be
+consumed by [the top-level `CMakeLists.txt`](/CMakeLists.txt).

packaging/3rdParty-devel/readme.txt

@@ -1,58 +0,0 @@
-Building the dependencies for Speed-Dreams makes use of CMake's ExternalProject
- module. The source for each is downloaded from each project's site, patched if
- necessary, and built. This can take considerable time and accesses several
- different sites. See the thirdpartydefinitions.cmake file for the exact sites.
- The installation also contains a folder 3rdParty/source_info in which you
- will find the source link for each project.
-
-
- =============================================================================
- Windows
- As of version 2.3, this will download approximately 35MB of compressed source
- files.
- You will need more than 1GB of free disk space for the build.
-
- Prerequisites:
- DirectX SDK (June 2010) - needed by SDL and possibly OpenAL
- http://www.microsoft.com/en-us/download/details.aspx?id=6812
-
- CMake version 3.4 or greater.
-
- Building the 3rd Party dependencies for Windows
-
- Get the code
-
-    Using Subversion:
-        svn co https://svn.code.sf.net/p/speed-dreams/code/trunk/packaging/3rdParty-devel C:\src\3rdParty-devel
-
-    If you already have the speed-dreams code:
-        copy <Path-to sd-code>\packaging\3rdParty-devel\*.* C:\src\3rdParty-devel
-
-    Important - Keep the path short ie: C:\src\3rdParty-devel
-    The building of OpenSceneGraph with CMake's ExternalProject_Add creates quite a deep tree and the build may fail.
-
- CMake CLI Build
-
-    Make a directory under the source directory (C:\src\3rdParty-devel)
-        mkdir build-vs2015-release
-
-    Change to the new directory:
-        cd build-vs2015-release
-
-    Generate the build system:
-        cmake -G "Visual Studio 14 2015" .. -D CMAKE_BUILD_TYPE=Release -A Win32
-
-    Build the package:
-        cmake --build . --target PACKAGE --config Release
-
- Note:
-   To build with VS2019 on Windows 7 or 8x, you may need to add -D CMAKE_SYSTEM_VERSION=10.0 to the command line:
-         cmake -G "Visual Studio 16 2019" .. -D CMAKE_BUILD_TYPE=Release -D CMAKE_SYSTEM_VERSION=10.0 -A Win32
-
-  =============================================================================
- OS X
- TODO
-
-   =============================================================================
- Linux
- TODO