summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/INSTALL')
-rw-r--r--Build/source/libs/freetype/freetype-1.5/INSTALL733
1 files changed, 0 insertions, 733 deletions
diff --git a/Build/source/libs/freetype/freetype-1.5/INSTALL b/Build/source/libs/freetype/freetype-1.5/INSTALL
deleted file mode 100644
index 42ce7020a8b..00000000000
--- a/Build/source/libs/freetype/freetype-1.5/INSTALL
+++ /dev/null
@@ -1,733 +0,0 @@
-
- The FreeType compilation guide
-
-
-Table of contents
------------------
-
- I. Introduction
-
- II. Compiling and installing the C library
-
- 1. Choosing a configuration file
- 2. Compiling the library
- 3. System-specific builds
- 4. Compiling the extensions
- 5. Using a Makefile
- 6. Building a dynamic library (`so' or `DLL')
- 7. Internationalization and the `ftxerr18' extension
- 8. TrueType patents
-
-
-III. Compiling the test programs
-
- 1. Compiling the graphics sub-system
- 2. Internationalization on Unix
- 3. Compiling the test programs
- 4. The `fdebug' program
-
-
- IV. Compiling the Pascal source
-
-
---------------------------------------------------------------------
-
-
-
-I. Introduction
-===============
-
- This file gives detailed information on how to compile and install
- this release of FreeType on your system.
-
-
-********************************************************************
-* *
-* FOR A QUICK INSTALLATION GUIDE, WE STRONGLY RECOMMEND TO READ *
-* THE SYSTEM-SPECIFIC DOCUMENTS LOCATED IN THE `howto' DIRECTORY *
-* INSTEAD OF THIS GENERIC DOCUMENTATION. *
-* *
-********************************************************************
-
-
- This package, known as the FreeType 1.5 Public Release, contains
- several things which are best described by the directories
- containing them:
-
- - `lib'
-
- Contains the 1.5 release of the FreeType library. It is written
- in portable ANSI C and should compile fine with any type of ANSI
- C compiler.
-
- Note however that some system-specific files are provided in the
- `lib/arch' directory, in order to provide enhanced performance.
-
- If you need to include FreeType in a graphics library or an
- embedded system, you will most probably only need to use its
- contents and discard the rest.
-
- - `test'
-
- Contains test and demo programs used during development. Note
- that some of these programs might not compile on all platforms,
- as they need to display graphics.
-
- - `po'
-
- On Unix, all of FreeType test programs support
- internationalization through the use of the `gettext' library.
- This directory contains `po' files, which are used to translate
- the original English text into language-specific one.
-
- Note also that this release contains an extension, called
- `ftxerr18' used to return internationalized strings from the
- usual FreeType error codes. The `po' files also contain
- translations for this extension.
-
- If you don't plan to use `ftxerr18' or internationalization,
- simply ignore it. Note also that even if `gettext' isn't
- available on your system, the test programs will be compiled
- correctly (using the `--disable-nls' configure switch).
-
- - `contrib'
-
- Contains a set of contributed tools and utilities related to
- TrueType or FreeType. Here you can find real situations how to
- use the library.
-
-
- This file explains how to compile the library, and the test
- programs on various platforms.
-
-
-
-II. Compiling the C library
-===========================
-
-
-********************************************************************
-* *
-* NOTE THAT WE STRONGLY RECOMMEND TO READ THE SYSTEM-SPECIFIC *
-* DOCUMENTS LOCATED IN THE `howto' DIRECTORY FOR A *
-* `QUICK'N'EASY' COMPILATION & INSTALLATION GUIDE ON YOUR *
-* PLATFORM. THE FOLLOWING IS A VERY DETAILED EXPLANATION ON HOW *
-* TO COMPILE THE LIBRARY. *
-* *
-********************************************************************
-
-
- The following concepts are important to build the library.
-
-
- 1. Choosing a configuration file
- --------------------------------
-
- The source code for the C library is located in the `lib'
- directory.
-
- It uses a file named `ft_conf.h', which contains the definitions
- of many configuration macros to toggle various engine features,
- as well as tell system-specific information (e.g., the size of
- the `int' type in bytes, etc).
-
- There are several configuration files provided with this
- release. They are located in the `lib/arch/<system>' directory,
- where <system> stands for a given architecture or environment.
-
- For example, the file `lib/arch/ansi/ft_conf.h' can be used to
- build the library with any ANSI-compliant compiler and runtime
- library.
-
- This release also provides configuration files for the following
- systems: MS-DOS, OS/2, Unix, VMS, Win 16, Win 32, Amiga OS, Mac,
- and BeOS.
-
- Make sure, when compiling each source file of the FreeType
- library, to include the path to your configuration file in your
- include directories.
-
-
- 2. Compiling the library
- ------------------------
-
- The library can be quickly compiled by invoking a Makefile, as
- described in the system-specific documents in the `howto'
- directory.
-
- We will now describe how to compile the library by hand.
-
- Traditionally, building a library like FreeType needs the
- following steps:
-
- - Compile each individual `.c' file into the corresponding
- object file, whose extension might be `.o' or `.obj',
- depending on the platform.
-
- - Group all object files into a library (e.g. `libfreetype.a' or
- `freetype.lib'), which is later used at link time to build the
- executables using it.
-
- For example, to build a static FreeType library on an ANSI
- system, with gcc, one should type
-
- cd lib # go to `lib' directory
- gcc -c -I arch/ansi tt*.c # compile base engine sources
- ar -r libfreetype.a tt*.o # create library from objects
-
- Note that we included the path to the configuration file in the
- include list during compilation, by using the `-I' switch on the
- `arch/ansi' directory. This is required to use the
- configuration file named `lib/arch/ansi/ft_conf.h'.
-
- However, we recommend you to build the base FreeType engine as a
- SINGLE OBJECT FILE, i.e., a single `freetype.o' or
- `freetype.obj' file containing all the code for the base engine.
- It works by including all the `.c' files in a single one, and
- has a few advantages over a `traditional build':
-
- - Because all the code is `part' of a single source file, many
- internal functions need not be declared as `extern' anymore.
-
- This means that when compiling the engine as a dynamic
- library, only FreeType external functions will (correctly) be
- exported as entry points.
-
- This also typically allows the compiler to perform more
- aggressive optimizations on the source code, and results in
- somewhat faster and/or smaller overall code size depending on
- your compiler and environment.
-
- - Compilation speed is greatly improved, as the pre-processor
- and compiler need to be called only once, instead of a dozen
- times.
-
- - During development, this allows to detect very easily
- unresolved dependencies regarding the base engine's internal
- symbols.
-
- To compile the engine as a single object file, simply go to the
- `lib' directory and compile the file
- `lib/arch/<system>/freetype.c'.
-
- For example, to compile the ANSI build with gcc in SINGLE OBJECT
- MODE, use
-
- cd lib
- gcc -c -I arch/ansi -I . arch/ansi/freetype.c
-
- This will create a single file called `freetype.o' containing
- the object code for the base TrueType engine.
-
- Note that we did include the paths to the configuration file
- (i.e. `arch/ansi') AND to the current directory (i.e. `.',
- where the included source files are located).
-
- `freetype.o' only contains the base engine. Extensions to the
- engine are located in the `lib/extend' directory and must be
- compiled separately as described later.
-
-
- 3. System-specific builds
- -------------------------
-
- The files `ttfile.c', `ttmemory.c', and `ttmutex.c' are used to
- provide an implementation of i/o access, memory management, and
- thread synchronization for the rest of the library.
-
- These source files, located in the `lib' directory, use the ANSI
- C library for i/o and memory, and simply ignore threads (as the
- C standard doesn't know about threads at all).
-
- However, this release provides, for each supported platform,
- system-specific versions of these files, located in the
- `lib/arch/<system>' hierarchy. Here are a few examples:
-
- lib/arch/os2/os2file.c:
-
- A replacement for `ttfile' which directly uses OS/2 system
- calls for i/o access. This results in slightly better
- performance, but much reduced resource requirements.
-
- lib/arch/unix/ttmmap.c:
-
- A replacement for `ttfile' which uses memory-mapped files
- instead of buffered-based reads on Unix. This increases
- *dramatically* the engine's performance when reading font
- files and loading glyphs.
-
- These files are directly included by the platform specific
- versions of `freetype.c' which are located in
- `lib/arch/<system>'. This means that, by default, the
- single-object build of FreeType always chooses the best
- implementation available for a supported system.
-
- Note that it is also possible to redefine `ttmemory' or
- `ttmutex' with a similar scheme. This is used, for example, by
- the OS/2 font driver based on FreeType (called FreeType/2),
- which uses some special system calls to allocate memory
- shareable among distinct processes.
-
- By providing your own version of `ttfile', `ttmemory', and
- `ttmutex', you are able to tailor the FreeType engine for
- optimal performance and resource usage on your system.
-
-
- 4. Compiling the extensions
- ---------------------------
-
- The base TrueType engine is located in the `lib' directory.
- This release also provides many specific extensions in
- `lib/extend'.
-
- An extension is a simple way to extend FreeType's capabilities.
- It is used to perform any of the following:
-
- - Access some TrueType tables that are not loaded and returned
- by the base engine, like
-
- * the kerning table(s)
- * the `gasp' table
- * the glyph Postscript names
- * the OpenType layout tables (GDEF, GPOS, GSUB)
-
- - Perform some advanced operations on the TrueType data for very
- specific uses, like
-
- * enumerate the contents of a given charmap
- * access a font file's embedded bitmaps (called sbits)
- * return an array containing the dimensions of each glyph in
- the font
-
- The idea is to keep the base engine small (under 60 kByte),
- while providing optional enhancements for specific uses.
-
- Writing an extension is rather easy. And adding a new extension
- to the engine doesn't need any modifications to the base
- engine's source code.
-
- To compile the extensions, simply go to the `lib' directory,
- then compile each file in `lib/extend'. Here is an example with
- gcc:
-
- cd lib # go to `lib'
- gcc -c -I arch/ansi -I . -I extend extend/ftx*.c
- # compile all extensions
-
-
- You can later add each extension object file to the FreeType
- library file. For example, here is how to create the static
- library on Unix:
-
- cd lib
- # .. compile the engine, then the extensions
- ar libfreetype.a *.o # create static library
-
-
- 5. Using a Makefile
- -------------------
-
- This release also provides Makefiles for many systems and
- compilers in the `lib/arch/<system>' hierarchy. For more
- information, please read the documentation in the `howto'
- directory, which contains system-specific instructions on how to
- use them.
-
- Generally, you should go the `lib' directory, then invoke your
- system-specific Makefile from there. Here is an example:
-
- cd lib
- make -farch\msdos\Makefile.TC
-
- to compile the library under DOS with the Turbo C compiler and
- Borland make tool. Or:
-
- cd lib
- wmake -f arch\msdos\Makefile.wat
-
- to compile it under DOS with the Watcom compiler and wmake tool.
-
- The ANSI target does not come with a Makefile, as there is no
- standard make tool available on all platforms. You will have to
- compile the library by hand as described in section I.3.
-
- Finally, note that most of the makefiles will build the library
- in single object mode; for a `traditional compile', try the
- `debug' target (i.e., say `make debug').
-
-
- 6. Building a dynamic library (`so' or `DLL')
- ---------------------------------------------
-
- It is possible to build the engine as a dynamic library. The
- method to do so can vary greatly depending on the platform.
-
- a. Building a shared object on Unix
-
- NOTE THAT THIS RELEASE USES `libtool' TO AUTOMATICALLY CREATE
- A SHARED OBJECT FOR FREETYPE ON UNIX SYSTEMS THAT SUPPORT
- DYNAMIC LIBRARIES. WE STRONGLY RECOMMEND YOU TO READ THE
- `howto/unix.txt' FILE TO KNOW HOW TO USE THE `configure'
- SCRIPT. THIS SUB-SECTION DESCRIBES HOW TO COMPILE THE SHARED
- OBJECT BY HAND.
-
- In order to build a shared object like `libfreetype.so' on
- Unix, one has to compile each object file as
- position-independent code (a.k.a. PIC).
-
- We also strongly recommend to build the base engine as a
- single object, as this prevents internal `extern' functions to
- be exported as entry points (and creating a smaller overall
- .so file).
-
- For example, this with gcc, one can use the `-fPIC' flag when
- compiling the object files. Here is an example:
-
- cd lib # go to `lib'
- gcc -c -fPIC -I arch/ansi -I . \
- arch/ansi/freetype.c # compile engine
- gcc -c -fPIC -I arch/ansi -I . -I extend
- extend/ftx*.c # & extensions
-
- You can now invoke your linker to create the shared object
- from the various object files. See your system's
- documentation for details, or read the Unix-specific howto to
- know how to do it `easily' through the use of `libtool'.
-
- b. Building a DLL on Windows or OS/2
-
- The dynamic linkers of Windows and OS/2 differ greatly from
- Unix ones.
-
- - The first difference is that the object files that make up
- the DLL do not need to be compiled as position-independent
- code.
-
- - The second difference is that the DLL's entry points must
- generally be declared as so in the source file, and/or maybe
- listed in a `definition' file used at link time when
- creating the DLL.
-
- Each FreeType API function is declared with the help of a
- special macro named FT_EXPORT_DEF. For example, here is the
- declaration of the function `FT_Init_FreeType', as written in
- `freetype.h':
-
- FT_EXPORT_DEF( TT_Error )
- TT_Init_FreeType( TT_Engine* engine );
-
- If the configuration file `ft_conf.h' doesn't define
- FT_EXPORT_DEF, it is automatically set to `extern' by default.
-
- In order to build FreeType as a DLL, one might need to define
- FT_EXPORT_DEF in its `ft_conf.h' to the keywords tagging the
- function as a DLL entry point. This keyword varies with
- compilers and platforms; examples are `__system',
- `__dllentry', `_FAR _PASCAL _export' after the type name, etc.
- Note that FT_EXPORT_DEF is a (macro) function, taking the type
- name as argument, in order to allow the last example.
-
- Please refer to your compiler's user guide for instructions.
-
- You can also `grep' for FT_EXPORT_DEF in the `freetype.h'
- source file to obtain the list of exported functions of the
- FreeType API, which could then be used to write a `def' file
- for the DLL. We provide a sample .def file (built with an Unix
- script) for Windows.
-
- Note also that the definition (i.e. its implementation) of
- each exported function is preceded with the FT_EXPORT_FUNC
- macro, as in
-
- FT_EXPORT_FUNC( TT_Error )
- TT_Init_FreeType( TT_Engine* engine )
- {
- TT_Error error;
- ...
- }
-
- (to be found in `ttapi.c').
-
- By default, FT_EXPORT_FUNC converts to an empty string, but it
- can also be redefined if you need to.
-
-
- 7. Internationalization and the `ftxerr18' extension
- ----------------------------------------------------
-
- The engine extension named `ftxerr18' is used to convert a
- FreeType error code into a human-readable string of text.
-
- However, it is able to support internationalization on Unix
- systems through the use of the `gettext' library. This means
- that the error messages will be localized to your system's
- language, provided it is available in this release. The
- currently available languages are
-
- - English (by default)
- - Czech
- - German
- - Spanish
- - French
- - Dutch
-
- One can add a new language by adding a `.po' file in the `po'
- directory. Please read the file `docs/i18n.txt' for more
- details on how to use `gettext'.
-
- In order to enable localization of the `ftxerr18' extension, one
- has to set the macro HAVE_LIBINTL_H at compile time. By
- default, the extension will build with support for the English
- language.
-
- Unix-specific: -------------------------------------------------
-
- Note that the Unix `configure' script that comes with this
- release is able to automatically detect whether your system
- has `gettext' installed and set HAVE_LIBINTL_H in the
- `ft_conf_h' file accordingly.
-
- To disable internationalization, run `configure' with the
- option `--disable-nls' (NLS stands for `National Language
- Support'). Then rebuild the library.
-
- ----------------------------------------------------------------
-
- Note that we do not support internationalization on non-Unix
- platforms, as the `gettext' library isn't available everywhere,
- or does not work in a consistent way in different environments.
-
-
- 8. TrueType patents
- -------------------
-
- We have recently discovered that Apple owns several patents that
- relate to the rendering of TrueType fonts. This could mean that
- the free use and distribution of the FreeType library could be
- illegal in the US, UK, France, and possibly other countries.
-
- For more information, please see the FreeType Patents page at:
-
- http://www.freetype.org/patents.htm
-
- To avoid problems, we have decided to turn off by default the
- compilation of the TrueType bytecode interpreter (which is the
- only part of FreeType that might violate an Apple patent). This
- has two effects:
-
- - saving about 18 kbyte of code in the engine
- - ignoring completely the grid-fitting of vector outlines, which
- results in extremely low quality at small pixel sizes.
-
- Nevertheless, such an engine can be used by font converters
- and/or graphics libraries to display glyphs at high pixel sizes.
-
- If you believe you can go ahead, this section will now explain
- how to build a `complete' engine, at the cost of possible patent
- violation. This is done simply by activating the compilation of
- the TrueType bytecode interpreter. In order to do so, simply
- recompile the library (more exactly, it affects only ttinterp.c)
- while #defin'ing TT_CONFIG_OPTION_BYTECODE_INTERPRETER. Look
- for the following line in your configuration file `ft_conf.h':
-
- #undef FT_CONFIG_OPTION_BYTECODE_INTERPRETER
-
- Then change the `#undef' into a `#define':
-
- #define FT_CONFIG_OPTION_BYTECODE_INTERPRETER
-
- Now rebuild the engine with this new configuration file.
-
-
-
-III. Compiling the test programs
-================================
-
- This section explains how to compile the FreeType test programs
- located in the `test' directory. Note that you should have
- successfully compiled the library, as described in section I
- before proceeding.
-
- WE STRONGLY RECOMMEND TO READ THE SYSTEM-SPECIFIC DOCUMENTS IN THE
- `howto' DIRECTORY FOR A `QUICK'N'EASY' GUIDE ON HOW TO COMPILE AND
- RUN THE TEST PROGRAMS.
-
-
- 1. Compile the graphics sub-system and utility sources
- ------------------------------------------------------
-
- Some of the test programs need to display a graphics window to
- show their results. In order to do so, they use a tiny graphics
- system which was specifically written for FreeType (Note: The
- code isn't really clean there -- you have been warned).
-
- Also, some simple C sources in the `test' directory are utility
- functions used by nearly all test programs, and they should also
- be compiled before them. These are the following files:
-
- gmain.h: the sub-system interface
- gmain.c: the sub-system device-independent implementation
- gevents.h: the definition of the events used by the test
- program
- gdriver.h: the system-specific device interface
- blitter.c: a set of simple bitmap blitting functions
- common.c: common routines used by all test programs
- display.c: some routines dealing with text display
-
- as well as a system-specific `graphics driver' located in the
- `test/arch/<system>' hierarchy. For example:
-
- test/arch/msdos/gfs_dos.c: used to display graphics in a
- full-screen Dos session
- test/arch/os2/gpm_os2.c: used to display graphics in an OS/2
- Presentation Manager window
- test/arch/unix/gwin_x11.c: used to display graphics in an X11
- window.
-
- You must compile the graphics sub-system and utilities before
- compiling the test programs. This can be done simply with gcc
- as:
-
- cd test
- gcc -c -I../lib gmain.c blitter.c common.c display.c
- gcc -c -I../lib -I. arch/<system>/yourdriver.c -o ./gdriver.o
-
- Note that a given test program may require some specific include
- paths (like `/usr/X11/include' with X11 for example).
-
- The resulting object files can be grouped in a library if you
- want to.
-
-
- 2. Internationalization on Unix
- -------------------------------
-
- On Unix and Unix-like systems, the test programs are able to
- support internationalization through the use of the `gettext'
- library and the `ftxerr18' engine extension (see section I.7).
-
- To enable it, one has to compile each test program with the
- macro HAVE_LIBINTL_H set. This is the same macro used to enable
- it in `ftxerr18'.
-
- Note that the Unix `configure' script that comes with this
- release is able to automatically detect whether `gettext' is
- available on your system and set the macro accordingly when
- compiling the test programs.
-
- You can disable internationalisation with the `--disable-nls'
- option when invoking the `configure' script.
-
-
- 3. Compile the test programs
- ----------------------------
-
- All test programs begin with the `ft' prefix in the `test'
- directory, as in `ftzoom', `ftdump', `ftmetric'", etc. are test
- programs.
-
- The easiest way to compile the test programs is compiling each
- source file to an object file, including the path to the
- FreeType engine source and its extensions. You need to use the
- following include paths:
-
- - the path to the engine's public header file, i.e. `freetype.h'
- which normally is `lib'
-
- - the path to the engine's extensions header files, located
- normally in `lib/extend'
-
- - the path to the configuration file `ft_conf.h'. This is only
- required to support internationalisation, as the test programs
- read `ft_conf.h' only to see whether HAVE_LIBINTL_H is
- defined.
-
- When compiling your own programs to FreeType, you shouldn't
- normally need this file and path.
-
- Here is an example, compiling a test program with the ANSI
- build:
-
- cd test
- gcc -c -I../lib -I../lib/extend -I../lib/arch/ansi \
- <program name>.c
-
- Then, link this object file to the FreeType library, utilities
- and graphics sub-system to build an executable.
-
- You can then invoke each program directly.
-
-
- 4. The `fdebug' test program
- ----------------------------
-
- All test programs begin with the `ft' prefix (in the `test'
- directory) as in `ftzoom', `ftdump', `ftmetric', etc.
-
- However, one test program named `fdebug' is used exclusively by
- FreeType developers. It is a very simple TrueType bytecode
- debugger, and was written to inspect the execution of the
- TrueType interpreter.
-
- Note that we rather use the Pascal debugger for real work on the
- interpreter, as it provides a much easier windowed interface
- through the use of the Turbo Vision library. The C debugger is
- mainly used to check that both Pascal and C sources produce the
- same output. The Pascal debugger is available in the `ftpascal'
- package, it is not included with this release.
-
- You will need gcc to compile the debugger. It uses a special
- build of the FreeType engine to work. Follow these steps to
- compile it:
-
- 1. Ensure the bytecode interpreter is not turned off (using
- the debugger with the default build which is patents-compliant
- is not really useful). How to process is explained in part 8
- of chapter II above (but of course you should modify the
- `ft_conf.h' file which is specific to the debugger). This
- implies that you must first be sure that you are really
- allowed to use such a version of FreeType.
-
- 2. Compile the library for the `debugger' system, i.e.
-
- cd freetype/lib
- make -f arch/debugger/Makefile
-
- this will create a file named `libttf.a' in the directory
- `freetype/lib/arch/debugger' which will NOT interfere with
- your normal build (which is located in `freetype/lib').
-
- 3. Compile the debugger:
-
- cd freetype/test
- make -f arch/debugger/Makefile
-
- This will create an executable called `fdebug.exe' or
- `fdebug', which is linked with the version of the library
- found in `freetype/lib/arch/debugger' as described above.
-
- [For old Unix variants like 4.2BSD please uncomment the flag
- HAVE_POSIX_TERMIOS in the makefile.]
-
- You can invoke the debugger in two ways:
-
- a. To debug a given glyph program in a given font, type
-
- fdebug glyph_number pointsize fontfile[.ttf]
-
- b. To debug a given font's CVT program, type
-
- fdebug --cvt pointsize fontfile[.ttf]
-
- Type `?' while running fdebug for a list of key bindings.
-
-
-IV. Compiling the Pascal source
-===============================
-
- The Pascal source code is no longer part of this package. It has
- been moved to another archive (resp. CVS repository). Please
- visit http://www.freetype.org for more information.
-
-
---- end of INSTALL ---