new build from source documentation

docs/BUILD.md

@@ -0,0 +1,83 @@
+## 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.
+
+### Desktop font (ttf) build dependencies
+
+To build the Hack desktop fonts (ttf) from source you will need the following build dependencies:
+
+- [fontmake](https://github.com/fonttools/fonttools) Python executable
+- [fonttools](https://github.com/googlei18n/fontmake) Python library
+- [ttfautohint](https://www.freetype.org/ttfautohint/) executable (includes Harfbuzz and FreeType dependencies)
+
+### Web font (woff + woff2) build dependencies
+
+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:
+
+- [sfnt2woff-zopfli](https://github.com/bramstein/sfnt2woff-zopfli) C++ executable
+- [woff2_compress](https://github.com/source-foundry/woff2) C++ executable
+
+
+### Automated build dependency installation
+
+Install all build dependencies for desktop and web fonts with the following make command:
+
+```
+$ make build-with-dependencies
+```
+
+This will install all necessary build dependencies and complete a build of all desktop and web fonts.
+
+
+## Automated font builds
+
+After the build dependencies are installed, use make targets from the root of the Hack repository to build font sets.
+
+
+#### Build all desktop and web fonts (including web font subsets)
+
+```
+$ make
+```
+
+#### Build ttf desktop fonts
+
+```
+$ make ttf
+```
+
+#### Build all web fonts (includes woff, woff2 with character subsets)
+
+```
+$ make webfonts
+```
+
+#### Build woff web fonts only (complete sets only)
+
+```
+$ make woff
+```
+
+#### Build woff2 web fonts only (complete sets only)
+
+```
+$ make woff2
+```
+
+
+#### Build woff and woff2 subsets only
+
+```
+$ make subsets
+```
+
+## Build paths
+
+### Desktop fonts (ttf)
+
+Desktop fonts are available on the path `build/ttf` from the root of the repository upon completion of your build.
+
+
+### Web fonts (woff + woff2)
+
+Web fonts are available on the path `build/web` from the root of the repository upon completion of your build.

docs/BUILD_INSTRUCTIONS.md

@@ -1,56 +0,0 @@
-# How to build Hack from source
-
-To build Hack from the UFO source files, you need the following build application dependencies:
-
-- [fontTools](https://github.com/fonttools/fonttools) - must be able to import into a Python module
-- [fontmake](https://github.com/googlei18n/fontmake) - must be accessible as a PATH executable
-- [ttfautohint](https://www.freetype.org/ttfautohint/) (Version 1.6+) - may be installed in a temporary local directory (see below) or installed on PATH
-
-## Build Dependency Management
-
-### Install the dependencies
-
-You can install all necessary build dependencies with our build.sh script and the `--install-dependencies` flag.  This script is found in the root of the Hack repository.  Clone the Hack repository to your system with the following command:
-
-```
-$ git clone https://github.com/source-foundry/Hack.git
-```
-
-Navigate to the root of the Hack repository with:
-
-```
-$ cd Hack
-```
-
-and excecute the following command:
-
-```
-$ ./build.sh --install-dependencies
-```
-
-The execution of this script with the `--install-dependencies` flag installs all build dependencies and builds the ttf fonts from source to final compiled ttf fonts that are intended for end users.  These build files can be found in the repository on the path `build/ttf/`.
-
-### How dependencies are installed
-
-- The Python fontTools library is installed with `pip install fonttools`.
-- The Python fontmake executable is installed with `pip install fontmake`.
-- ttfautohint and its build dependencies are installed locally on the path `$HOME/ttfautohint-build`.  The ttfautohint executable is found on the path `$HOME/ttfautohint-build/local/bin/ttfautohint`.
-
-
-### How to remove installed build dependencies
-
-If you are not setting up a development environment that requires repeat builds (e.g. to make changes, test, and contribute back upstream or to create a new Hack fork project), you can remove the build dependencies with the following set of commands:
-
-```
-$ pip uninstall fonttools
-$ pip uninstall fontmake
-$ rm -rf "$HOME/ttfautohint-build"
-```
-
-## Build Hack fonts
-
-If your system already meets all build dependency requirements, you can build without the dependency install step by navigating to the root of the Hack repository and executing the command:
-
-```
-$ ./build.sh
-```