Add more detailed docs for building cmake-based AFDKO from source

README.md

@@ -45,6 +45,8 @@ Note for macOS users: we recommend that you do **not** use the system Python. Am
 
 Note for all users: if you are in a Python 3 only environment, then the command `pip` is sufficient.  If you are in a mixed Python 2 and Python 3 environment, or you are unsure of your environment, then the command `pip3` ensures that you are using the Python 3 version of `pip`. It is for this reason that we have used `pip3` in the instructions below.
 
+Note for Linux users (and users of other platforms that are not macOS or Windows): When there is not a pre-built "wheel" for your platform `pip` will attempt to build the C and C++ portions of the package from source. This process will only succeed if both the C and C++ development tools and libuuid are installed. See [build from source](#Build-from-source) below.
+
 ### Installing
 
 **Option 1 (Recommended)**
@@ -107,8 +109,15 @@ On Linux (Ubuntu 17.10 LTS or later), install these with:
     apt-get -y install python3.6
     apt-get -y install python-pip
     apt-get -y install python-dev
+    apt-get -y install uuid-dev
+
+On other POSIX-like operating systems, `libuuid` and its header files
+may be in a package named `libuuid-devel` or `util-linux-libs`. The
+source code for `libuuid` is maintained in the
+[util-linux repository](https://github.com/karelzak/util-linux).
+
+On Windows, you need Visual Studio 2017 or later.
 
-On Windows, you need Visual Studio 2017.
 
 To build the **afdko** from source, clone the [afdko GitHub
 repository](https://github.com/adobe-type-tools/afdko), ensure the `wheel`
@@ -117,6 +126,9 @@ directory of the afdko, and run:
 
     pip3 install .
 
+For further information on building from source see
+[docs/FDK\_Build\_Notes.md](docs/FDK_Build_Notes.md).
+
 **Note**
 
 It's not possible to install the afdko in editable/develop mode using

docs/FDK_Build_Notes.md

@@ -1,6 +1,6 @@
 # FDK Build Notes
 
-#### v1.3.0 May 2021
+#### v1.3.0 June 2021
 
 ## Overview
 These instructions are for users who wish to build the C programs in the AFDKO on their own. If you have obtained the AFDKO through [PyPI](https://pypi.org/project/afdko/) (`pip`), you can ignore this, as everything is pre-built for distribution on PyPI. These are really only for users who need to build on platforms that are not officially supported, or wish to make other custom changes.
@@ -44,6 +44,8 @@ cmake -S . -B build
 cmake --build build
 ```
 
+Note that unless you are using macOS or Windows you must have `libuuid` and its header files installed in order to build `makeotfexe`. These will typically be part of a package named `uuid-dev`, `libuuid-devel`, or `util-linux-libs`. (`libuuid` is a dependency of the Antlr 4 Cpp runtime, which is built by `cmake/ExternalAntlr4Cpp.cmake`. If you have build trouble after installing the library the [Antlr 4 Cpp runtime documentation](https://github.com/antlr/antlr4/tree/master/runtime/Cpp) may help.)
+
 If the build is successful each program (e.g. makeotfexe) will be built as `build/bin/[program]`.  If you would like to install them in `/usr/local/bin` you can then run `cmake --build build -- install`.
 
 ### Noted CMake options
@@ -55,7 +57,8 @@ These options can be added to the end of the first CMake command above:
 3. To build with `ninja` rather than `make` add `-GNinja`
 4. To build XCode project files use `-GXcode`
 5. More recent versions of Visual Studio (e.g. 2019) should recognize `CMakeLists.txt` files. Just open the main project folder.
-6. To add a sanitizer add `-DADD_SANITIZER=[san]`, where `[san]` is `address`, `memory`, etc. (Currently only works with compilers that support GCC-style directives.)
+6. When building directly on Windows you can specify the Visual Studio generator with `-G` and the platform with `-A`, as in `cmake -G "Visual Studio 16 2019" -A Win32`. See [Visual Studio Generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) in the CMake documentation for more information.
+7. To add a sanitizer add `-DADD_SANITIZER=[san]`, where `[san]` is `address`, `memory`, etc. (This currently only works with compilers that support GCC-style directives.) The top-level `CMakeLists.txt` will also honor an `ADD_SANITIZER` environment variable with the same values.
 
 ## Tests
 
@@ -67,6 +70,16 @@ To run the tests manually/individually before installation you need to set a few
 
 ## Troubleshooting
 
+### `utfcpp` Timeout
+
+The Antlr 4 build process downloads its `utfcpp` dependency using a `git` protocol URL. In some situations this action can time out. As a workaround you can substitute the more reliable `https` URL by running this command (which will modify your git configuration):
+
+```
+git config --global url.https://github.com/.insteadOf git://github.com/
+```
+
+### Antlr 4 Cpp runtime and Windows path lengths
+
 You may have trouble building the Antlr 4 Cpp runtime on Windows due to git
 being conservative about filename lengths. If you see an error like
 
@@ -81,7 +94,8 @@ git config --system core.longpaths true
 ```
 
 #### Document Version History
-Version 1.0.0
-Version 1.2.0 July 18 2019
-Version 1.2.1 - Convert to Markdown, update content - October 2019
-Version 1.3.0 - Document switch to CMake-driven builds - May 2021
+
+- Version 1.0.0
+- Version 1.2.0 July 18 2019
+- Version 1.2.1 - Convert to Markdown, update content - October 2019
+- Version 1.3.0 - Document switch to CMake-driven builds - June 2021