modules/freetype2/docs/INSTALL.CROSS@b8a032363ba2 (annotated)
modules/freetype2/docs/INSTALL.CROSS
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 | This document contains instructions on how to cross-build the FreeType |
| michael@0 | 2 | library on Unix systems, for example, building binaries for Linux/MIPS |
| michael@0 | 3 | on FreeBSD/i386. Before reading this document, please consult the |
| michael@0 | 4 | file `INSTALL.UNIX' for required tools and the basic self-building |
| michael@0 | 5 | procedure. |
| michael@0 | 6 | |
| michael@0 | 7 | |
| michael@0 | 8 | 1. Required Tools |
| michael@0 | 9 | ----------------- |
| michael@0 | 10 | |
| michael@0 | 11 | For self-building the FreeType library on a Unix system, GNU Make |
| michael@0 | 12 | 3.80 or newer is required. `INSTALL.UNIX' contains hints how to |
| michael@0 | 13 | check the installed `make'. |
| michael@0 | 14 | |
| michael@0 | 15 | The GNU C compiler to cross-build the target system is required. |
| michael@0 | 16 | Currently, using a non-GNU cross compiler is untested. The cross |
| michael@0 | 17 | compiler is expected to be installed with a system prefix. For |
| michael@0 | 18 | example, if your building system is FreeBSD/i386 and the target |
| michael@0 | 19 | system is Linux/MIPS, the cross compiler should be installed with |
| michael@0 | 20 | the name `mips-ip22-linuxelf-gcc'. |
| michael@0 | 21 | |
| michael@0 | 22 | A C compiler for a self-build is required also, to build a tool |
| michael@0 | 23 | (`apinames') that is executed during the build procedure. Non-GNU |
| michael@0 | 24 | self compilers are acceptable, but such a setup is untested. |
| michael@0 | 25 | |
| michael@0 | 26 | |
| michael@0 | 27 | 2. Configuration |
| michael@0 | 28 | ---------------- |
| michael@0 | 29 | |
| michael@0 | 30 | 2.1. Building and target system |
| michael@0 | 31 | |
| michael@0 | 32 | To configure a cross-build, the options `--host=<system>' and |
| michael@0 | 33 | `--build=<system>' must be passed to the `configure' script. |
| michael@0 | 34 | For example, if your build system is FreeBSD/i386 and the target |
| michael@0 | 35 | system is Linux/MIPS, say |
| michael@0 | 36 | |
| michael@0 | 37 | ./configure \ |
| michael@0 | 38 | --build=i386-unknown-freebsd \ |
| michael@0 | 39 | --host=mips-ip22-linuxelf \ |
| michael@0 | 40 | [other options] |
| michael@0 | 41 | |
| michael@0 | 42 | It should be noted that `--host=<system>' specifies the system |
| michael@0 | 43 | where the built binaries will be executed, not the system where |
| michael@0 | 44 | the build actually happens. Older versions of GNU autoconf use |
| michael@0 | 45 | the option pair `--host=' and `--target='. This is broken and |
| michael@0 | 46 | doesn't work. Similarly, an explicit CC specification like |
| michael@0 | 47 | |
| michael@0 | 48 | env CC=mips-ip22-linux-gcc ./configure # BAD |
| michael@0 | 49 | |
| michael@0 | 50 | or |
| michael@0 | 51 | |
| michael@0 | 52 | env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure # BAD |
| michael@0 | 53 | |
| michael@0 | 54 | doesn't work either; such a configuration confuses the |
| michael@0 | 55 | `configure' script while trying to find the cross and native C |
| michael@0 | 56 | compilers. |
| michael@0 | 57 | |
| michael@0 | 58 | |
| michael@0 | 59 | 2.2. The prefix to install FreeType2 |
| michael@0 | 60 | |
| michael@0 | 61 | Setting `--prefix=<prefix>' properly is important. The prefix |
| michael@0 | 62 | to install FreeType2 is written into the `freetype-config' |
| michael@0 | 63 | script and `freetype2.pc' configuration file. |
| michael@0 | 64 | |
| michael@0 | 65 | If the built FreeType 2 library is used as a part of the |
| michael@0 | 66 | cross-building system, the prefix is expected to be different |
| michael@0 | 67 | from the self-building system. For example, a configuration |
| michael@0 | 68 | with `--prefix=/usr/local' installs binaries into the |
| michael@0 | 69 | system-wide `/usr/local' directory, which then can't be executed |
| michael@0 | 70 | due to the incorrect architecture. This causes confusion in |
| michael@0 | 71 | configuration of all applications that use FreeType2. Instead, |
| michael@0 | 72 | use a prefix to install the cross-build into a separate system |
| michael@0 | 73 | tree, for example, `--prefix=/usr/local/mips-ip22-linux/'. |
| michael@0 | 74 | |
| michael@0 | 75 | On the other hand, if the built FreeType 2 library is used as a |
| michael@0 | 76 | part of the target system, the prefix to install should reflect |
| michael@0 | 77 | the file system structure of the target system. |
| michael@0 | 78 | |
| michael@0 | 79 | |
| michael@0 | 80 | 2.3. Library dependencies |
| michael@0 | 81 | |
| michael@0 | 82 | FreeType normally depends on external libraries like `libpng' or |
| michael@0 | 83 | `libharfbuzz'. The easiest case is to deactivate all such |
| michael@0 | 84 | dependencies using the `--without-XXX' configuration options. |
| michael@0 | 85 | However, if you want to use those libraries, you should ensure |
| michael@0 | 86 | that they are available both on the target system and as |
| michael@0 | 87 | (cross-compiled) libraries on the build system. |
| michael@0 | 88 | |
| michael@0 | 89 | FreeType uses `pkg-config' to find most of the libraries; the |
| michael@0 | 90 | other libraries it links to are expected in the standard system |
| michael@0 | 91 | directories. Since the default pkg-config's meta-information |
| michael@0 | 92 | files (like `harfbuzz.pc') of the build platform don't work, use |
| michael@0 | 93 | one of the two possible solutions below. |
| michael@0 | 94 | |
| michael@0 | 95 | o Use pkg-config's meta-information files that are adjusted to |
| michael@0 | 96 | cross-compile and cross-link with the target platform's |
| michael@0 | 97 | libraries. Make sure those files are found before the build |
| michael@0 | 98 | system's default files. Example: |
| michael@0 | 99 | |
| michael@0 | 100 | ./configure \ |
| michael@0 | 101 | --build=i386-unknown-freebsd \ |
| michael@0 | 102 | --host=mips-ip22-linuxelf \ |
| michael@0 | 103 | PKG_CONFIG_LIBDIR="/usr/local/mips-ip22-linux/lib/pkgconfig" \ |
| michael@0 | 104 | [other options] |
| michael@0 | 105 | |
| michael@0 | 106 | See the manpage of `pkg-config' for more details. |
| michael@0 | 107 | |
| michael@0 | 108 | o Set variables like LIBPNG_LIBS as additional options to the |
| michael@0 | 109 | `configure' script, overriding the values `pkg-config' would |
| michael@0 | 110 | provide. `configure --help' shows the available environment |
| michael@0 | 111 | variables. Example: |
| michael@0 | 112 | |
| michael@0 | 113 | ./configure \ |
| michael@0 | 114 | --build=i386-unknown-freebsd \ |
| michael@0 | 115 | --host=mips-ip22-linuxelf \ |
| michael@0 | 116 | LIBPNG_CFLAGS="-I/usr/local/mips-ip22-linux/include" \ |
| michael@0 | 117 | LIBPNG_LIBS="-L/usr/local/mips-ip22-linux/lib -lpng12" \ |
| michael@0 | 118 | [other options] |
| michael@0 | 119 | |
| michael@0 | 120 | |
| michael@0 | 121 | 3. Building command |
| michael@0 | 122 | ------------------- |
| michael@0 | 123 | |
| michael@0 | 124 | If the configuration finishes successfully, invoking GNU make |
| michael@0 | 125 | builds FreeType2. Just say |
| michael@0 | 126 | |
| michael@0 | 127 | make |
| michael@0 | 128 | |
| michael@0 | 129 | or |
| michael@0 | 130 | |
| michael@0 | 131 | gmake |
| michael@0 | 132 | |
| michael@0 | 133 | depending on the name the GNU make binary actually has. |
| michael@0 | 134 | |
| michael@0 | 135 | |
| michael@0 | 136 | 4. Installation |
| michael@0 | 137 | --------------- |
| michael@0 | 138 | |
| michael@0 | 139 | Saying |
| michael@0 | 140 | |
| michael@0 | 141 | make install |
| michael@0 | 142 | |
| michael@0 | 143 | as usual to install FreeType2 into the directory tree specified by |
| michael@0 | 144 | the argument of the `--prefix' option. |
| michael@0 | 145 | |
| michael@0 | 146 | As noted in section 2.2, FreeType2 is sometimes configured to be |
| michael@0 | 147 | installed into the system directory of the target system, and |
| michael@0 | 148 | should not be installed in the cross-building system. In such |
| michael@0 | 149 | cases, the make variable `DESTDIR' is useful to change the root |
| michael@0 | 150 | directory in the installation. For example, after |
| michael@0 | 151 | |
| michael@0 | 152 | make DESTDIR=/mnt/target_system_root/ install |
| michael@0 | 153 | |
| michael@0 | 154 | the built FreeType2 library files are installed into the directory |
| michael@0 | 155 | `/mnt/target_system_root/<prefix_in_configure>/lib'. |
| michael@0 | 156 | |
| michael@0 | 157 | |
| michael@0 | 158 | 5. TODO |
| michael@0 | 159 | ------- |
| michael@0 | 160 | |
| michael@0 | 161 | Cross building between Cygwin (or MSys) and Unix must be tested. |
| michael@0 | 162 | |
| michael@0 | 163 | |
| michael@0 | 164 | ---------------------------------------------------------------------- |
| michael@0 | 165 | |
| michael@0 | 166 | Copyright 2006, 2008, 2012, 2014 by suzuki toshiya |
| michael@0 | 167 | David Turner, Robert Wilhelm, and Werner Lemberg. |
| michael@0 | 168 | |
| michael@0 | 169 | |
| michael@0 | 170 | This file is part of the FreeType project, and may only be used, |
| michael@0 | 171 | modified, and distributed under the terms of the FreeType project |
| michael@0 | 172 | license, LICENSE.TXT. By continuing to use, modify, or distribute |
| michael@0 | 173 | this file you indicate that you have read the license and understand |
| michael@0 | 174 | and accept it fully. |
| michael@0 | 175 | |
| michael@0 | 176 | |
| michael@0 | 177 | --- end of INSTALL.CROSS --- |
