CONFIG.md

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