1# Configuring HarfBuzz 2 3Most of the time you will not need any custom configuration. The configuration 4options provided by `meson` should be enough. In particular, if you just want 5HarfBuzz library plus hb-shape / hb-view utilities, make sure FreeType and Cairo 6are available and found during configuration. 7 8If you are building for distribution, you should more carefully consider whether 9you need Glib, ICU, Graphite2, as well as CoreText / Uniscribe / DWrite. Make 10sure the relevant ones are enabled. 11 12If you are building for custom environment (embedded, downloadable app, etc) 13where you mostly just want to call `hb_shape()` and the binary size of the 14resulting library is very important to you, the rest of this file guides you 15through your options to disable features you may not need, in exchange for 16binary size savings. 17 18## Compiler Options 19 20Make sure you build with your compiler's "optimize for size" option. On `gcc` 21this is `-Os`, and can be enabled by passing `CXXFLAGS=-Os`. On clang there 22is an even more extreme flag, `-Oz`. Meson also provides `--buildtype=minsize` 23for more convenience. 24 25HarfBuzz heavily uses inline functions and the optimize-size flag can make the 26library smaller by 20% or more. Moreover, sometimes, based on the target CPU, 27the optimize-size builds perform *faster* as well, thanks to lower code 28footprint and caching effects. So, definitely try that even if size is not 29extremely tight but you have a huge application. For example, Chrome does 30that. Note that this configuration also automatically enables certain internal 31optimizations. Search for `HB_OPTIMIZE_SIZE` for details, if you are using 32other compilers, or continue reading. 33 34Another compiler option to consider is "link-time optimization", also known as 35'lto'. To enable that, feel free to use `-Db_lto=true` of meson. 36This, also, can have a huge impact on the final size, 20% or more. 37 38Finally, if you are making a static library build or otherwise linking the 39library into your app, make sure your linker removes unused functions. This 40can be tricky and differ from environment to environment, but you definitely 41want to make sure this happens. Otherwise, every unused public function will 42be adding unneeded bytes to your binary. The following pointers might come 43handy: 44 45 * https://lwn.net/Articles/741494/ (all of the four-part series) 46 * https://elinux.org/images/2/2d/ELC2010-gc-sections_Denys_Vlasenko.pdf 47 48Combining the above three build options should already shrink your library a lot. 49The rest of this file shows you ways to shrink the library even further at the 50expense of removing functionality (that may not be needed). The remaining 51options are all enabled by defining pre-processor macros, which can be done 52via `CXXFLAGS` or `CPPFLAGS` similarly. 53 54 55## Unicode-functions 56 57Access to Unicode data can be configured at compile time as well as run-time. 58By default, HarfBuzz ships with its own compact subset of properties from 59Unicode Character Database that it needs. This is a highly-optimized 60implementation that depending on compile settings (optimize-size or not) 61takes around ~40kb or ~60kb. Using this implementation (default) is highly 62recommended, as HarfBuzz always ships with data from latest version of Unicode. 63This implementation can be disabled by defining `HB_NO_UCD`. 64 65For example, if you are enabling ICU as a built-in option, or GLib, those 66can provide Unicode data as well, so defining `HB_NO_UCD` might save you 67space without reducing functionality (to the extent that the Unicode version 68of those implementations is recent.) 69 70If, however, you provide your own Unicode data to HarfBuzz at run-time by 71calling `hb_buffer_set_unicode_funcs` on every buffer you create, and you do 72not rely on `hb_unicode_funcs_get_default()` results, you can disable the 73internal implementation by defining both `HB_NO_UCD` and `HB_NO_UNICODE_FUNCS`. 74The latter is needed to guard against accidentally building a library without 75any default Unicode implementations. 76 77 78## Font-functions 79 80Access to certain font functionalities can also be configured at run-time. By 81default, HarfBuzz uses an efficient internal implementation of OpenType 82functionality for this. This internal implementation is called `hb-ot-font`. 83All newly-created `hb_font_t` objects by default use `hb-ot-font`. Using this 84is highly recommended, and is what fonts use by default when they are created. 85 86Most embedded uses will probably use HarfBuzz with FreeType using `hb-ft.h`. 87In that case, or if you otherwise provide those functions by calling 88`hb_font_set_funcs()` on every font you create, you can disable `hb-ot-font` 89without loss of functionality by defining `HB_NO_OT_FONT`. 90 91 92## Shapers 93 94Most HarfBuzz clients use it for the main shaper, called "ot". However, it 95is legitimate to want to compile HarfBuzz with only another backend, eg. 96CoreText, for example for an iOS app. For that, you want `HB_NO_OT_SHAPE`. 97If you are going down that route, check if you want `HB_NO_OT`. 98 99This is very rarely what you need. Make sure you understand exactly what you 100are doing. 101 102Defining `HB_NO_FALLBACK_SHAPE` however is pretty harmless. That removes the 103(unused) "fallback" shaper. This is defined by the `HB_TINY` profile already 104(more below). 105 106 107## Thread-safety 108 109By default HarfBuzz builds as a thread-safe library. The exception is that 110the `HB_TINY` predefined configuration (more below) disables thread-safety. 111 112If you do *not* need thread-safety in the library (eg. you always call into 113HarfBuzz from the same thread), you can disable thread-safety by defining 114`HB_NO_MT`. As noted already, this is enabled by `HB_TINY`. 115 116 117## Pre-defined configurations 118 119The [`hb-config.hh`](src/hb-config.hh) internal header supports three 120pre-defined configurations as well grouping of various configuration options. 121The pre-defined configurations are: 122 123 * `HB_MINI`: Disables shaping of AAT as well as legacy fonts. Ie. it produces 124 a capable OpenType shaper only. 125 126 * `HB_LEAN`: Disables various non-shaping functionality in the library, as well 127 as esoteric or rarely-used shaping features. See the definition for details. 128 129 * `HB_TINY`: Enables both `HB_MINI` and `HB_LEAN` configurations, as well as 130 disabling thread-safety and debugging, and use even more size-optimized data 131 tables. 132 133To setup the build with these options use something like: 134``` 135$ meson setup build -Dcpp_args=-DHB_MINI -Dc_args=-DHB_MINI 136``` 137 138## Tailoring configuration 139 140Most of the time, one of the pre-defined configuration is exactly what one needs. 141Sometimes, however, the pre-defined configuration cuts out features that might 142be desired in the library. Unfortunately there is no quick way to undo those 143configurations from the command-line. 144 145However, configuration can still be overridden from a file. To do that, add your 146override instructions (mostly `undef` instructions) to a header file and define 147the macro `HB_CONFIG_OVERRIDE_H` to the string containing to that header file's 148name. HarfBuzz will then include that file at the appropriate place during 149configuration. 150 151Up until HarfBuzz 3.1.2, the configuration override header file's name was 152fixed and called `config-override.h`, and was activated by defining the macro 153`HAVE_CONFIG_OVERRIDE_H`. That still works. 154 155 156## Notes 157 158Note that the config option `HB_NO_CFF`, which is enabled by `HB_LEAN` and 159`HB_TINY` does *not* mean that the resulting library won't work with CFF fonts. 160The library can shape valid CFF fonts just fine, with or without this option. 161This option disables (among other things) the code to calculate glyph extents 162for CFF fonts or draw them, which many clients might not need. 163