From 97c1c46cd2241d77b531a582dd1a2432af976357 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Wed, 10 Oct 2018 16:38:22 -0500 Subject: [PATCH] Docs: update and linearize build instructions; add installation overview material. --- docs/usermanual-install-harfbuzz.xml | 247 +++++++++++++++++++++------ 1 file changed, 197 insertions(+), 50 deletions(-) diff --git a/docs/usermanual-install-harfbuzz.xml b/docs/usermanual-install-harfbuzz.xml index 899cc5bd6..9d10e2da0 100644 --- a/docs/usermanual-install-harfbuzz.xml +++ b/docs/usermanual-install-harfbuzz.xml @@ -1,70 +1,217 @@ - Install HarfBuzz + Installing HarfBuzz +
- Download + Downloading HarfBuzz - For tarball releases of HarfBuzz, look - here. - At the same place you will - also find Win32 binary bundles that include libharfbuzz DLL, hb-view.exe, - hb-shape.exe, and all dependencies. + The HarfBuzz source code is hosted at github.com/harfbuzz/harfbuzz. The + same source tree is also available at the + Freedesktop.org + site. - The canonical source tree is available - here. - Also available on github. + Tarball releases and Win32 binary bundles (which include the + libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all + dependencies) of HarfBuzz can be downloaded from github.com/harfbuzz/harfbuzz/releases + or from + Freedesktop.org. - The API that comes with hb.h will - not change incompatibly. Other, peripheral, headers are more likely to go - through minor modifications, but again, will do our best to never change - API in an incompatible way. We will never break the ABI. + Release notes are posted with each new release to provide an + overview of the changes. The project tracks bug + reports and other issues on GitHub. Discussion and + questions are welcome on the HarfBuzz + mailing list. - If you are not sure whether Pango or HarfBuzz is right for you, read - this. + The API included in the hb.h file will not change in a + compatibility-breaking way in any release. However, other, + peripheral headers are more likely to go through minor + modifications. We will do our best to never change APIs in an + incompatible way. We will never break the ABI.
+
- Building + Building HarfBuzz + +
+ Building on Linux - On Linux, install the development packages for FreeType, Cairo, and GLib. - For example, on Ubuntu / Debian, you would do: - -sudo apt-get install gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev - - whereas on Fedora, RHEL, CentOS, and other Red Hat based systems you would do: - -sudo yum install gcc gcc-c++ freetype-devel glib2-devel cairo-devel - - or using MacPorts: - -sudo port install freetype glib2 cairo - + (1) To build HarfBuzz on Linux, you must first install the + development packages for FreeType, Cairo, and GLib. The exact + commands required for this step will vary depending on + the Linux distribution you use. - If you are using a tarball, you can now proceed to running - configure and make as with any - other standard package. That should leave you with a shared library in - src/, and a few utility programs including hb-view - and hb-shape under util/. + For example, on an Ubuntu or Debian system, you would run: + + sudo apt install gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev + + On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run: + + sudo yum install gcc gcc-c++ freetype-devel glib2-devel cairo-devel + + + + + + (2) The next step depends on whether you + are building from the source in a downloaded release tarball or + from the source directly from the git repository. - If you are bootstrapping from git, you need a few more tools before you - can run autogen.sh for the first time. Namely, - pkg-config and ragel. - Again, on Ubuntu / Debian: - -sudo apt-get install autoconf automake libtool pkg-config ragel gtk-doc-tools - - and on Fedora, RHEL, CentOS: - -sudo yum install autoconf automake libtool pkgconfig ragel gtk-doc - - or using MacPorts: - -sudo port install autoconf automake libtool pkgconfig ragel gtk-doc - + (2)(a) If you downloaded the HarfBuzz + source code in a tarball, you can now extract the source. + + From a shell in the top-level directory of the extracted source + code, you can run ./configure followed by + make as with any other standard package. + + + This should leave you with a shared + library in the src/ directory, and a few + utility programs including hb-view and + hb-shape under the util/ + directory. + + + (2)(b) If you are building from the source in the HarfBuzz git + repository, rather than installing from a downloaded tarball + release, then you must install two more auxiliary tools before you + can build for the first time: pkg-config and + ragel. + + + On Ubuntu or Debian, run: + + sudo apt-get install autoconf automake libtool pkg-config ragel gtk-doc-tools + + On Fedora, RHEL, CentOS, run: + + sudo yum install autoconf automake libtool pkgconfig ragel gtk-doc + + + + + With pkg-config and ragel + installed, you can now run ./autogen.sh, + followed by ./configure and + make to build HarfBuzz. + +
+ + +
+ Building on Windows + + + On Windows, consider using Microsoft's free vcpkg utility + to build HarfBuzz, its dependencies, and other open-source + libraries. + + + If you need to build HarfBuzz from source, first put the + ragel binary on your + PATH, then follow the appveyor CI cmake + build + instructions. + +
+ + +
+ Building on macOS + + + There are two ways to build HarfBuzz on Mac systems: MacPorts + and Homebrew. The process is similar to the process used on a + Linux system. + + + (1) You must first install the + development packages for FreeType, Cairo, and GLib. If you are + using MacPorts, you should run: + + sudo port install freetype glib2 cairo + + + + If you are using Homebrew, you should run: + + brew install freetype glib cairo + + + + (2) The next step depends on whether you are building from the + source in a downloaded release tarball or from the source directly + from the git repository. + + + (2)(a) If you are installing HarfBuzz + from a downloaded tarball release, extract the tarball and + open a Terminal in the extracted source-code directory. Run: + + ./configure + + followed by: + + make + + to build HarfBuzz. + + + (2)(b) Alternatively, if you are building + HarfBuzz from the source in the HarfBuzz git repository, then + you must install several built-time dependencies before + proceeding. + + If you are + using MacPorts, you should run: + + sudo port install autoconf + automake libtool pkgconfig ragel gtk-doc + + to install the build dependencies. + + If you are using Homebrew, you should run: + + brew install autoconf automake libtool pkgconfig ragel gtk-doc + + Finally, you can run: + + ./autogen.sh + + + + (3) You can now build HarfBuzz (on either + a MacPorts or a Homebrew system) by running: + + ./configure + + followed by: + + make + + + + This should leave you with a shared + library in the src/ directory, and a few + utility programs including hb-view and + hb-shape under the util/ + directory. + + +
+ +