1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/freetype2/docs/INSTALL.CROSS Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,177 @@
1.4 +This document contains instructions on how to cross-build the FreeType
1.5 +library on Unix systems, for example, building binaries for Linux/MIPS
1.6 +on FreeBSD/i386. Before reading this document, please consult the
1.7 +file `INSTALL.UNIX' for required tools and the basic self-building
1.8 +procedure.
1.9 +
1.10 +
1.11 + 1. Required Tools
1.12 + -----------------
1.13 +
1.14 + For self-building the FreeType library on a Unix system, GNU Make
1.15 + 3.80 or newer is required. `INSTALL.UNIX' contains hints how to
1.16 + check the installed `make'.
1.17 +
1.18 + The GNU C compiler to cross-build the target system is required.
1.19 + Currently, using a non-GNU cross compiler is untested. The cross
1.20 + compiler is expected to be installed with a system prefix. For
1.21 + example, if your building system is FreeBSD/i386 and the target
1.22 + system is Linux/MIPS, the cross compiler should be installed with
1.23 + the name `mips-ip22-linuxelf-gcc'.
1.24 +
1.25 + A C compiler for a self-build is required also, to build a tool
1.26 + (`apinames') that is executed during the build procedure. Non-GNU
1.27 + self compilers are acceptable, but such a setup is untested.
1.28 +
1.29 +
1.30 + 2. Configuration
1.31 + ----------------
1.32 +
1.33 + 2.1. Building and target system
1.34 +
1.35 + To configure a cross-build, the options `--host=<system>' and
1.36 + `--build=<system>' must be passed to the `configure' script.
1.37 + For example, if your build system is FreeBSD/i386 and the target
1.38 + system is Linux/MIPS, say
1.39 +
1.40 + ./configure \
1.41 + --build=i386-unknown-freebsd \
1.42 + --host=mips-ip22-linuxelf \
1.43 + [other options]
1.44 +
1.45 + It should be noted that `--host=<system>' specifies the system
1.46 + where the built binaries will be executed, not the system where
1.47 + the build actually happens. Older versions of GNU autoconf use
1.48 + the option pair `--host=' and `--target='. This is broken and
1.49 + doesn't work. Similarly, an explicit CC specification like
1.50 +
1.51 + env CC=mips-ip22-linux-gcc ./configure # BAD
1.52 +
1.53 + or
1.54 +
1.55 + env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure # BAD
1.56 +
1.57 + doesn't work either; such a configuration confuses the
1.58 + `configure' script while trying to find the cross and native C
1.59 + compilers.
1.60 +
1.61 +
1.62 + 2.2. The prefix to install FreeType2
1.63 +
1.64 + Setting `--prefix=<prefix>' properly is important. The prefix
1.65 + to install FreeType2 is written into the `freetype-config'
1.66 + script and `freetype2.pc' configuration file.
1.67 +
1.68 + If the built FreeType 2 library is used as a part of the
1.69 + cross-building system, the prefix is expected to be different
1.70 + from the self-building system. For example, a configuration
1.71 + with `--prefix=/usr/local' installs binaries into the
1.72 + system-wide `/usr/local' directory, which then can't be executed
1.73 + due to the incorrect architecture. This causes confusion in
1.74 + configuration of all applications that use FreeType2. Instead,
1.75 + use a prefix to install the cross-build into a separate system
1.76 + tree, for example, `--prefix=/usr/local/mips-ip22-linux/'.
1.77 +
1.78 + On the other hand, if the built FreeType 2 library is used as a
1.79 + part of the target system, the prefix to install should reflect
1.80 + the file system structure of the target system.
1.81 +
1.82 +
1.83 + 2.3. Library dependencies
1.84 +
1.85 + FreeType normally depends on external libraries like `libpng' or
1.86 + `libharfbuzz'. The easiest case is to deactivate all such
1.87 + dependencies using the `--without-XXX' configuration options.
1.88 + However, if you want to use those libraries, you should ensure
1.89 + that they are available both on the target system and as
1.90 + (cross-compiled) libraries on the build system.
1.91 +
1.92 + FreeType uses `pkg-config' to find most of the libraries; the
1.93 + other libraries it links to are expected in the standard system
1.94 + directories. Since the default pkg-config's meta-information
1.95 + files (like `harfbuzz.pc') of the build platform don't work, use
1.96 + one of the two possible solutions below.
1.97 +
1.98 + o Use pkg-config's meta-information files that are adjusted to
1.99 + cross-compile and cross-link with the target platform's
1.100 + libraries. Make sure those files are found before the build
1.101 + system's default files. Example:
1.102 +
1.103 + ./configure \
1.104 + --build=i386-unknown-freebsd \
1.105 + --host=mips-ip22-linuxelf \
1.106 + PKG_CONFIG_LIBDIR="/usr/local/mips-ip22-linux/lib/pkgconfig" \
1.107 + [other options]
1.108 +
1.109 + See the manpage of `pkg-config' for more details.
1.110 +
1.111 + o Set variables like LIBPNG_LIBS as additional options to the
1.112 + `configure' script, overriding the values `pkg-config' would
1.113 + provide. `configure --help' shows the available environment
1.114 + variables. Example:
1.115 +
1.116 + ./configure \
1.117 + --build=i386-unknown-freebsd \
1.118 + --host=mips-ip22-linuxelf \
1.119 + LIBPNG_CFLAGS="-I/usr/local/mips-ip22-linux/include" \
1.120 + LIBPNG_LIBS="-L/usr/local/mips-ip22-linux/lib -lpng12" \
1.121 + [other options]
1.122 +
1.123 +
1.124 + 3. Building command
1.125 + -------------------
1.126 +
1.127 + If the configuration finishes successfully, invoking GNU make
1.128 + builds FreeType2. Just say
1.129 +
1.130 + make
1.131 +
1.132 + or
1.133 +
1.134 + gmake
1.135 +
1.136 + depending on the name the GNU make binary actually has.
1.137 +
1.138 +
1.139 + 4. Installation
1.140 + ---------------
1.141 +
1.142 + Saying
1.143 +
1.144 + make install
1.145 +
1.146 + as usual to install FreeType2 into the directory tree specified by
1.147 + the argument of the `--prefix' option.
1.148 +
1.149 + As noted in section 2.2, FreeType2 is sometimes configured to be
1.150 + installed into the system directory of the target system, and
1.151 + should not be installed in the cross-building system. In such
1.152 + cases, the make variable `DESTDIR' is useful to change the root
1.153 + directory in the installation. For example, after
1.154 +
1.155 + make DESTDIR=/mnt/target_system_root/ install
1.156 +
1.157 + the built FreeType2 library files are installed into the directory
1.158 + `/mnt/target_system_root/<prefix_in_configure>/lib'.
1.159 +
1.160 +
1.161 + 5. TODO
1.162 + -------
1.163 +
1.164 + Cross building between Cygwin (or MSys) and Unix must be tested.
1.165 +
1.166 +
1.167 +----------------------------------------------------------------------
1.168 +
1.169 +Copyright 2006, 2008, 2012, 2014 by suzuki toshiya
1.170 +David Turner, Robert Wilhelm, and Werner Lemberg.
1.171 +
1.172 +
1.173 +This file is part of the FreeType project, and may only be used,
1.174 +modified, and distributed under the terms of the FreeType project
1.175 +license, LICENSE.TXT. By continuing to use, modify, or distribute
1.176 +this file you indicate that you have read the license and understand
1.177 +and accept it fully.
1.178 +
1.179 +
1.180 +--- end of INSTALL.CROSS ---
