From 33d8b76e74579a27b06fa788d0bf696a9dd44cc4 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Mon, 17 Jun 2019 21:54:20 -0700 Subject: [PATCH] [config] Flesh out CONFIG.md Part of https://github.com/harfbuzz/harfbuzz/issues/1652 --- CONFIG.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 3 deletions(-) diff --git a/CONFIG.md b/CONFIG.md index b6b54f187..393553c0a 100644 --- a/CONFIG.md +++ b/CONFIG.md @@ -44,8 +44,89 @@ be adding unneeded bytes to your binary. Combining the above three build options should already shrink your library a lot. The rest of this file shows you ways to shrink the library even further at the -expense of removing functionality (that may not be needed). +expense of removing functionality (that may not be needed). The remaining +options are all enabled by defining pre-processor macros, which can be done +via `CXXFLAGS` or `CPPFLAGS` similarly. -## Custom configuration -TODO +## Unicode-functions + +Access to Unicode data can be configured at compile time as well as run-time. +By default, HarfBuzz ships with its own compact subset of properties from +Unicode Character Database that it needs. This is a highly-optimized +implementation that depending on compile settings (optimize-size or not) +takes around ~40kb or ~60kb. Using this implementation (default) is highly +recommended, as HarfBuzz always ships with data from latest version of Unicode. +This implementation can be disabled by defining `HB_NO_UCD`. + +For example, if you are enabling ICU as a built-in option, or GLib, those +can provide Unicode data as well, so defining `HB_NO_UCD` might save you +space without reducing functionality (to the extent that the Unicode version +of those implementations is recent.) + +If, however, you provide your own Unicode data to HarfBuzz at run-time by +calling `hb_buffer_set_unicode_funcs` on every buffer you create, and you do +not rely on `hb_unicode_funcs_get_default()` results, you can disable the +internal implementation by defining both `HB_NO_UCD` and `HB_NO_UNICODE_FUNCS`. +The latter is needed to guard against accidentally building a library without +any default Unicode implementations. + + +## Font-functions + +Access to certain font functionalities can also be configured at run-time. By +default, HarfBuzz uses an efficient internal implementation of OpenType +functionality for this. This internal implementation is called `hb-ot-font`. +All newly-created `hb_font_t` objects by default use `hb-ot-font`. Using this +is highly recommended, and is what fonts use by default when they are created. + +Most embedded uses will probably use HarfBuzz with FreeType using `hb-ft.h`. +In that case, or if you otherwise provide those functions by calling +`hb_font_set_funcs()` on every font you create, you can disable `hb-ot-font` +without loss of functionality by defining `HB_NO_OT_FONT`. + + +## Thread-safety + +By default HarfBuzz builds as a thread-safe library. The exception is that +the `HB_TINY` predefined configuring (more below) disables thread-safety. + +If you do /not/ need thread-safety in the library (eg. you always call into +HarfBuzz from the same thread), you can disable thread-safety by defining +`HB_NO_MT`. As noted already, this is enabled by `HB_TINY`. + + +## Pre-defined configurations + +The [`hb-config.hh`](src/hb-config.hh) internal header supports three +pre-defined configurations as well grouping of various configuration options. +The pre-defined configurations are: + + * `HB_MINI`: Disables shaping of AAT as well as legacy fonts. Ie. it produces + a capable OpenType shaper only. + + * `HB_LEAN`: Disables various non-shaping functionality in the library. See + the definition for details. + + * `HB_TINY`: Enables both `HB_MINI` and `HB_LEAN` configurations, as well as + disabling thread-safety and debugging, and use size-optimized data tables. + + +## Tailoring configuration + +Most of the time, one of the pre-defined configuration is exactly what one needs. +Sometimes, however, the pre-defined configuration cuts out features that might +be desired in the library. Unfortunately there is no quick way to undo those +configurations from the command-line. But one can add a header file called +`config-override.h` to undefine certain `HB_NO_*` symbols as desired. Then +define `HAVE_CONFIG_OVERRIDE_H` to make `hb-config.hh` include your configuration +overrides at the end. + + +## Notes + +Note that the config option `HB_NO_CFF`, which is enabled by `HB_LEAN` and +`HB_TINY` does /not/ mean that the resulting library won't work with CFF fonts. +The library can shape valid CFF fonts just fine, with or without this option. +This option disables (among other things) the code to calculate glyph exntents +for CFF fonts.