From 1e1e3d9edc714e2bc7d83b17d77afc07ee050107 Mon Sep 17 00:00:00 2001 From: Skef Iterum Date: Wed, 16 Jun 2021 15:15:39 -0700 Subject: [PATCH 1/2] Add more detailed docs for building cmake-based AFDKO from source --- README.md | 14 +++++++++++++- docs/FDK_Build_Notes.md | 18 ++++++++++++------ 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 298f76a5c..29bf94439 100644 --- a/README.md +++ b/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 diff --git a/docs/FDK_Build_Notes.md b/docs/FDK_Build_Notes.md index 3d7ee5048..750ae1d6e 100644 --- a/docs/FDK_Build_Notes.md +++ b/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,8 @@ To run the tests manually/individually before installation you need to set a few ## Troubleshooting +### 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 +86,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 From 3e32fca0723d001ff1c9594a0ad3cfc224d79dcb Mon Sep 17 00:00:00 2001 From: Skef Iterum Date: Sun, 25 Jul 2021 18:36:13 -0700 Subject: [PATCH 2/2] Add note about https url for utfcpp download --- docs/FDK_Build_Notes.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/FDK_Build_Notes.md b/docs/FDK_Build_Notes.md index 750ae1d6e..6cecaa0ae 100644 --- a/docs/FDK_Build_Notes.md +++ b/docs/FDK_Build_Notes.md @@ -70,6 +70,14 @@ 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