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