[BUILD.md] updated build documentation with v4.x build tooling changes

docs/BUILD.md

@@ -1,37 +1,104 @@
+# Hack Font Builds from Source Files
+
+Hack is compiled from UFO v2 spec source files to ttf, woff, and woff2 fonts with free, open source build tools.  The default build approach requires a *nix platform (macOS, Linux, Unix-like development platform for Windows such as MinGW) and uses pinned build dependency versions in order to support font files that render in a reproducible fashion (relative to upstream repository builds) in a given rendering environment.  See the bottom of this document for an alternative approach that uses system-installed versions of all build dependencies and supports build dependency versions that differ from those used in the upstream repository.
+
+## Quickstart
+The following commands will do the following:
+
+1. Clone the Hack source repository
+2. Install the `pipenv` dependency
+3. Compile and install a local version `ttfautohint` (i.e., *off of the system PATH*)
+4. Build *.ttf desktop fonts
+5. Build *.woff web fonts (including subsets)
+6. Build *.woff2 web fonts (including subsets)
+
+**Quickstart Hack font compile process**
+
+```
+$ git clone https://github.com/source-foundry/Hack.git
+$ cd Hack
+$ pip3 install pipenv
+$ make compile-local-dep
+$ make
+```
+
+The build process takes minutes to complete on the average system.  You will see a great deal of text stream by in your terminal during the build.  This is normal and expected during the build.
+
+You will find the compiled fonts in the build directory (located in the top level of the source repository) after you complete these steps.
+
+Detailed instructions follow if you have difficulties with any of the above steps.  If you encounter an error that is not addressed in this build documentation, please report it as a new issue report on the repository.  *Please review the entire build document below to confirm that we have not explained how to address your problem before you submit a new issue report*!
+
 ## Build dependencies
 
-Hack is compiled from UFO v2 spec source files to ttf, woff, and woff2 fonts with free, open source build tools.  You can either install the tools manually or use the automated build dependency installation approach documented below.
+### Python interpreter dependency
+
+The Hack fonts are built with a Python version 3 interpreter.  The Python interpreter version is fixed at each git commit. You may view the Python interpreter in use at any commit in the Pipfile and Pipfile.lock files that are located in the root directory of the repository.  [Click here](https://sourcegraph.com/search?q=repo:%5Egithub%5C.com/source-foundry/Hack%24%40master+python_version) to search for these values in the current HEAD commit of the master branch.
+
+If this version of the Python interpreter is not available on your development system, you may install [`pyenv`](https://github.com/pyenv/pyenv-installer) before you attempt your build.  If `pyenv` is installed prior to the build, `pipenv` will automatically install the interpreter defined in the Hack build in the virtual environment used for the build, even if it is not currently installed on your system.
 
-### Desktop font (ttf) build dependencies
+The pyenv project defines the following command as a supported approach to install `pyenv`:
+
+
+**Pull and install the pyenv executable**
+
+```
+curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
+```
+
+### Desktop font (ttf) dependencies
 
 To build the Hack desktop fonts (ttf) from source you will need the following build dependencies:
 
+- [pipenv](https://github.com/pypa/pipenv) Python executable
 - [fontmake](https://github.com/googlei18n/fontmake) Python executable
 - [fonttools](https://github.com/fonttools/fonttools) Python library
 - [ttfautohint](https://www.freetype.org/ttfautohint/) executable (includes Harfbuzz and FreeType dependencies)
 
-### Web font (woff + woff2) build dependencies
+`fontmake` and `fontTools` are automatically installed during the compile process.
+
+`pipenv` must be installed manually with the following command before you attempt a build:
+
+**Install pipenv**
 
-To build the Hack web fonts from source you will need all of the build dependencies listed above for desktop font builds.  In addition you will need the following dependencies for the web font build steps:
+```
+$ pip3 install pipenv
+```
+
+`ttfautohint` (including its Harfbuzz and FreeType dependencies) can be installed locally on the path defined for use in Hack builds with the following command:
+
+**Compile and install a local copy of ttfautohint**
+
+```
+$ make compile-local-dep
+```
+
+This path is defined as the following subdirectory on your $HOME path:
+
+- ttfautohint: `$HOME/ttfautohint-build`
+
+### Web font (woff + woff2) dependencies
+
+To build the Hack web fonts from source you will need all of the build dependencies listed above for desktop font builds and the following additional dependencies:
 
 - [sfnt2woff-zopfli](https://github.com/bramstein/sfnt2woff-zopfli) C++ executable
 - [woff2_compress](https://github.com/source-foundry/woff2) C++ executable
 
+The sfnt2woff-zopfli executable and woff2_compress executable are compiled and installed on a local build path (i.e., off of system PATH) with the following command:
 
-### Automated build dependency installation
-
-Install all build dependencies for desktop and web fonts with the following make command:
+**Compile and install local copies of sfnt2woff-zopfli and woff2_compress**
 
 ```
-$ make build-with-dependencies
+$ make compile-local-dep
 ```
 
-This will install all necessary build dependencies and complete a build of all desktop and web fonts.
+These paths are defined as the following subdirectories on your $HOME path:
 
+- sfnt2woff-zopfli: `$HOME/sfnt2woff-zopfli-build`
+- woff2: `$HOME/woff2`
 
 ## Automated font builds
 
-After the build dependencies are installed, use make targets from the root of the Hack repository to build font sets.
+After the build dependencies are installed, use make targets from the root of the Hack repository to build font sets.  The following commands build the regular, bold, italic, and bold italic variants of the respective build types:
 
 
 #### Build all desktop and web fonts (including web font subsets)
@@ -40,7 +107,7 @@ After the build dependencies are installed, use make targets from the root of th
 $ make
 ```
 
-#### Build ttf desktop fonts
+#### Build ttf desktop fonts only
 
 ```
 $ make ttf
@@ -80,37 +147,27 @@ Desktop fonts are available on the path `build/ttf` from the root of the reposit
 
 ### Web fonts (woff + woff2)
 
-Web fonts are available on the path `build/web/fonts` from the root of the repository upon completion of your build.
-
+Web fonts are available on the path `build/web/fonts` from the root of the repository upon completion of your build.  CSS files that may be used with your web font builds are available on the path `build/web`.
 
 ## Uninstall
 
-All build dependencies installed with the automated approaches can be uninstalled with the following commands:
+Python packages that are used during the build process are installed in a virtual environment with `pipenv`.  The virtual environment and all Python packages installed in that environment can be eliminated with execution of the following command in the root of the repository:
 
 ```
-$ pip uninstall fontmake
-$ pip uninstall fonttools
-$ rm -rf ~/ttfautohint-build
-$ rm -rf ~/sfnt2woff-zopfli-build
-$ rm -rf ~/woff2
+$ pipenv -rm
 ```
 
-Here are all of the above commands in a single line that can be copied/pasted into your terminal to accomplish the entire uninstall process:
+All compiled project build dependencies installed as part of this build process can be uninstalled with the following commands:
 
 ```
-$ pip uninstall fontmake && pip uninstall fonttools && rm -rf ~/ttfautohint-build && rm -rf ~/sfnt2woff-zopfli-build && rm -rf ~/woff2
+$ rm -rf ~/ttfautohint-build
+$ rm -rf ~/sfnt2woff-zopfli-build
+$ rm -rf ~/woff2
 ```
 
-In cases where a compile did not proceed to completion (e.g. you intentionally exited early or an exception was raised) a temporary directory may still exist in the root of the repository on the path `master_ttf`.  This can be removed with:
+In cases where a compile did not proceed to completion (e.g. you intentionally exited early or an exception was raised that halted the build prior to completion) a temporary directory may still exist in the root of the repository on the path `master_ttf`.  This can be removed with:
 
 ```
 $ rm -rf master_ttf
 ```
 
-### Uninstall Details
-
-fontmake and fonttools are Python packages and are uninstalled with pip.
-
-The FreeType library (including its build dependency Harfbuzz), ttfautohint, sfnt2woff-zopfli, and woff2 are built in directories on your $HOME path.  They are not installed on your $PATH (unless of course you have defined $HOME on $PATH) so they **will not** work from the command line with the name of the executable file only (e.g. `$ ttfautohint [file path]`).  This is intentional.
-
-Repeat execution of the build process cleans up the temporary directory `master_ttf` if found so this step is not mandatory to repeat a build and should not lead to errors with the build.