modules/freetype2/docs/CUSTOMIZE@b8a032363ba2 (annotated)
modules/freetype2/docs/CUSTOMIZE
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
| michael@0 | 1 | How to customize the compilation of the library |
| michael@0 | 2 | =============================================== |
| michael@0 | 3 | |
| michael@0 | 4 | FreeType is highly customizable to fit various needs, and this |
| michael@0 | 5 | document describes how it is possible to select options and |
| michael@0 | 6 | components at compilation time. |
| michael@0 | 7 | |
| michael@0 | 8 | |
| michael@0 | 9 | I. Configuration macros |
| michael@0 | 10 | |
| michael@0 | 11 | The file found in `include/config/ftoption.h' contains a list of |
| michael@0 | 12 | commented configuration macros that can be toggled by developers to |
| michael@0 | 13 | indicate which features should be active while building the library. |
| michael@0 | 14 | |
| michael@0 | 15 | These options range from debug level to availability of certain |
| michael@0 | 16 | features, like native TrueType hinting through a bytecode |
| michael@0 | 17 | interpreter. |
| michael@0 | 18 | |
| michael@0 | 19 | We invite you to read this file for more information. You can |
| michael@0 | 20 | change the file's content to suit your needs, or override it with |
| michael@0 | 21 | one of the techniques described below. |
| michael@0 | 22 | |
| michael@0 | 23 | |
| michael@0 | 24 | II. Modules list |
| michael@0 | 25 | |
| michael@0 | 26 | If you use GNU make please edit the top-level file `modules.cfg'. |
| michael@0 | 27 | It contains a list of available FreeType modules and extensions to |
| michael@0 | 28 | be compiled. Change it to suit your own preferences. Be aware that |
| michael@0 | 29 | certain modules depend on others, as described in the file. GNU |
| michael@0 | 30 | make uses `modules.cfg' to generate `ftmodule.h' (in the object |
| michael@0 | 31 | directory). |
| michael@0 | 32 | |
| michael@0 | 33 | If you build FreeType in a directory separate from the source files, |
| michael@0 | 34 | put your customized `modules.cfg' in that directory; that way you |
| michael@0 | 35 | can keep the source files `clean'. |
| michael@0 | 36 | |
| michael@0 | 37 | If you don't use GNU make you have to manually edit the file |
| michael@0 | 38 | `include/config/ftmodule.h' (which is *not* used with if compiled |
| michael@0 | 39 | with GNU make) to add or remove the drivers and components you want |
| michael@0 | 40 | to compile into the library. See `INSTALL.ANY' for more |
| michael@0 | 41 | information. |
| michael@0 | 42 | |
| michael@0 | 43 | |
| michael@0 | 44 | III. System interface |
| michael@0 | 45 | |
| michael@0 | 46 | FreeType's default interface to the system (i.e., the parts that |
| michael@0 | 47 | deal with memory management and i/o streams) is located in |
| michael@0 | 48 | `src/base/ftsystem.c'. |
| michael@0 | 49 | |
| michael@0 | 50 | The current implementation uses standard C library calls to manage |
| michael@0 | 51 | memory and to read font files. It is however possible to write |
| michael@0 | 52 | custom implementations to suit specific systems. |
| michael@0 | 53 | |
| michael@0 | 54 | To tell the GNU Make-based build system to use a custom system |
| michael@0 | 55 | interface, you have to define the environment variable FTSYS_SRC to |
| michael@0 | 56 | point to the relevant implementation: |
| michael@0 | 57 | |
| michael@0 | 58 | on Unix: |
| michael@0 | 59 | |
| michael@0 | 60 | ./configure <your options> |
| michael@0 | 61 | export FTSYS_SRC=foo/my_ftsystem.c |
| michael@0 | 62 | make |
| michael@0 | 63 | make install |
| michael@0 | 64 | |
| michael@0 | 65 | on Windows: |
| michael@0 | 66 | |
| michael@0 | 67 | make setup <compiler> |
| michael@0 | 68 | set FTSYS_SRC=foo/my_ftsystem.c |
| michael@0 | 69 | make |
| michael@0 | 70 | |
| michael@0 | 71 | |
| michael@0 | 72 | IV. Overriding default configuration and module headers |
| michael@0 | 73 | |
| michael@0 | 74 | It is possible to override the default configuration and module |
| michael@0 | 75 | headers without changing the original files. There are three ways |
| michael@0 | 76 | to do that: |
| michael@0 | 77 | |
| michael@0 | 78 | |
| michael@0 | 79 | 1. With GNU make |
| michael@0 | 80 | |
| michael@0 | 81 | [This is actually a combination of method 2 and 3.] |
| michael@0 | 82 | |
| michael@0 | 83 | Just put your custom `ftoption.h' file into the objects directory |
| michael@0 | 84 | (normally `<topdir>/objs' if you build in the source tree, or the |
| michael@0 | 85 | directory where you invoke configure if you build in a separate |
| michael@0 | 86 | directory), which GNU make prefers over the standard location. No |
| michael@0 | 87 | action is needed for `ftmodule.h' because it is generated |
| michael@0 | 88 | automatically in the objects directory. |
| michael@0 | 89 | |
| michael@0 | 90 | 2. Using the C include path |
| michael@0 | 91 | |
| michael@0 | 92 | Use the C include path to ensure that your own versions of the |
| michael@0 | 93 | files are used at compile time when the lines |
| michael@0 | 94 | |
| michael@0 | 95 | #include FT_CONFIG_OPTIONS_H |
| michael@0 | 96 | #include FT_CONFIG_MODULES_H |
| michael@0 | 97 | |
| michael@0 | 98 | are compiled. Their default values being <config/ftoption.h> and |
| michael@0 | 99 | <config/ftmodule.h>, you can do something like: |
| michael@0 | 100 | |
| michael@0 | 101 | custom/ |
| michael@0 | 102 | config/ |
| michael@0 | 103 | ftoption.h => custom options header |
| michael@0 | 104 | ftmodule.h => custom modules list |
| michael@0 | 105 | |
| michael@0 | 106 | include/ => normal FreeType 2 include |
| michael@0 | 107 | ... |
| michael@0 | 108 | |
| michael@0 | 109 | then change the C include path to always give the path to `custom' |
| michael@0 | 110 | before the FreeType 2 `include'. |
| michael@0 | 111 | |
| michael@0 | 112 | |
| michael@0 | 113 | 3. Redefining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H |
| michael@0 | 114 | |
| michael@0 | 115 | Another way to do the same thing is to redefine the macros used to |
| michael@0 | 116 | name the configuration headers. To do so, you need a custom |
| michael@0 | 117 | `ft2build.h' whose content can be as simple as: |
| michael@0 | 118 | |
| michael@0 | 119 | #ifndef __FT2_BUILD_MY_PLATFORM_H__ |
| michael@0 | 120 | #define __FT2_BUILD_MY_PLATFORM_H__ |
| michael@0 | 121 | |
| michael@0 | 122 | #define FT_CONFIG_OPTIONS_H <custom/my-ftoption.h> |
| michael@0 | 123 | #define FT_CONFIG_MODULES_H <custom/my-ftmodule.h> |
| michael@0 | 124 | |
| michael@0 | 125 | #include <config/ftheader.h> |
| michael@0 | 126 | |
| michael@0 | 127 | #endif /* __FT2_BUILD_MY_PLATFORM_H__ */ |
| michael@0 | 128 | |
| michael@0 | 129 | Place those files in a separate directory, e.g., |
| michael@0 | 130 | |
| michael@0 | 131 | custom/ |
| michael@0 | 132 | ft2build.h => custom version described above |
| michael@0 | 133 | my-ftoption.h => custom options header |
| michael@0 | 134 | my-ftmodule.h => custom modules list header |
| michael@0 | 135 | |
| michael@0 | 136 | and change the C include path to ensure that `custom' is always |
| michael@0 | 137 | placed before the FT2 `include' during compilation. |
| michael@0 | 138 | |
| michael@0 | 139 | ---------------------------------------------------------------------- |
| michael@0 | 140 | |
| michael@0 | 141 | Copyright 2003, 2005, 2006, 2012, 2013 by |
| michael@0 | 142 | David Turner, Robert Wilhelm, and Werner Lemberg. |
| michael@0 | 143 | |
| michael@0 | 144 | This file is part of the FreeType project, and may only be used, |
| michael@0 | 145 | modified, and distributed under the terms of the FreeType project |
| michael@0 | 146 | license, LICENSE.TXT. By continuing to use, modify, or distribute |
| michael@0 | 147 | this file you indicate that you have read the license and understand |
| michael@0 | 148 | and accept it fully. |
| michael@0 | 149 | |
| michael@0 | 150 | |
| michael@0 | 151 | --- end of CUSTOMIZE --- |
