diff options
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/INSTALL')
-rw-r--r-- | Build/source/libs/freetype/freetype-1.5/INSTALL | 733 |
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 --- |