[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[freetype2] gsoc-anurag-docs-2023 658eec4ca 1/3: [docs] Migrate all INST
|
From: |
Werner Lemberg |
|
Subject: |
[freetype2] gsoc-anurag-docs-2023 658eec4ca 1/3: [docs] Migrate all INSTALL files to Markdown |
|
Date: |
Fri, 30 Jun 2023 10:00:15 -0400 (EDT) |
branch: gsoc-anurag-docs-2023
commit 658eec4cab9bbd8f792ba37febec8540d039faa1
Author: Anurag Thakur <anurag105csec21@bpitindia.edu.in>
Commit: Anurag Thakur <anurag105csec21@bpitindia.edu.in>
[docs] Migrate all INSTALL files to Markdown
---
docs/.gitignore | 6 ++
docs/INSTALL.CROSS | 177 ---------------------------------
docs/INSTALL.GNU | 181 ----------------------------------
docs/INSTALL.UNIX | 139 --------------------------
docs/{INSTALL.ANY => INSTALL_ANY.md} | 121 +++++++++++------------
docs/INSTALL_CROSS.md | 183 ++++++++++++++++++++++++++++++++++
docs/INSTALL_GNU.md | 184 +++++++++++++++++++++++++++++++++++
docs/{INSTALL.MAC => INSTALL_MAC.md} | 14 ++-
docs/INSTALL_UNIX.md | 141 +++++++++++++++++++++++++++
docs/{INSTALL.VMS => INSTALL_VMS.md} | 21 ++--
10 files changed, 593 insertions(+), 574 deletions(-)
diff --git a/docs/.gitignore b/docs/.gitignore
index 24dffcbc7..d7777e70c 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -6,6 +6,12 @@ reference/
*.md
!INSTALL.md
+!INSTALL_ANY.md
+!INSTALL_CROSS.md
+!INSTALL_GNU.md
+!INSTALL_MAC.md
+!INSTALL_UNIX.md
+!INSTALL_VMS.md
# MkDocs Config file
mkdocs.yml
diff --git a/docs/INSTALL.CROSS b/docs/INSTALL.CROSS
deleted file mode 100644
index 21f4c3182..000000000
--- a/docs/INSTALL.CROSS
+++ /dev/null
@@ -1,177 +0,0 @@
-This document contains instructions on how to cross-build the FreeType
-library on Unix systems, for example, building binaries for Linux/MIPS
-on FreeBSD/i386. Before reading this document, please consult the
-file `INSTALL.UNIX' for required tools and the basic self-building
-procedure.
-
-
- 1. Required Tools
- -----------------
-
- For self-building the FreeType library on a Unix system, GNU Make
- 3.81 or newer is required. `INSTALL.UNIX' contains hints how to
- check the installed `make'.
-
- The GNU C compiler to cross-build the target system is required.
- Currently, using a non-GNU cross compiler is untested. The cross
- compiler is expected to be installed with a system prefix. For
- example, if your building system is FreeBSD/i386 and the target
- system is Linux/MIPS, the cross compiler should be installed with
- the name `mips-ip22-linuxelf-gcc'.
-
- A C compiler for a self-build is required also, to build a tool
- (`apinames') that is executed during the build procedure. Non-GNU
- self compilers are acceptable, but such a setup is untested.
-
-
- 2. Configuration
- ----------------
-
- 2.1. Building and target system
-
- To configure a cross-build, the options `--host=<system>' and
- `--build=<system>' must be passed to the `configure' script.
- For example, if your build system is FreeBSD/i386 and the target
- system is Linux/MIPS, say
-
- ./configure \
- --build=i386-unknown-freebsd \
- --host=mips-ip22-linuxelf \
- [other options]
-
- It should be noted that `--host=<system>' specifies the system
- where the built binaries will be executed, not the system where
- the build actually happens. Older versions of GNU autoconf use
- the option pair `--host=' and `--target='. This is broken and
- doesn't work. Similarly, an explicit CC specification like
-
- env CC=mips-ip22-linux-gcc ./configure # BAD
-
- or
-
- env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure # BAD
-
- doesn't work either; such a configuration confuses the
- `configure' script while trying to find the cross and native C
- compilers.
-
-
- 2.2. The prefix to install FreeType2
-
- Setting `--prefix=<prefix>' properly is important. The prefix
- to install FreeType2 is written into the `freetype-config'
- script and `freetype2.pc' configuration file.
-
- If the built FreeType 2 library is used as a part of the
- cross-building system, the prefix is expected to be different
- from the self-building system. For example, a configuration
- with `--prefix=/usr/local' installs binaries into the
- system-wide `/usr/local' directory, which then can't be executed
- due to the incorrect architecture. This causes confusion in
- configuration of all applications that use FreeType2. Instead,
- use a prefix to install the cross-build into a separate system
- tree, for example, `--prefix=/usr/local/mips-ip22-linux/'.
-
- On the other hand, if the built FreeType 2 library is used as a
- part of the target system, the prefix to install should reflect
- the file system structure of the target system.
-
-
- 2.3. Library dependencies
-
- FreeType normally depends on external libraries like `libpng' or
- `libharfbuzz'. The easiest case is to deactivate all such
- dependencies using the `--without-XXX' configuration options.
- However, if you want to use those libraries, you should ensure
- that they are available both on the target system and as
- (cross-compiled) libraries on the build system.
-
- FreeType uses `pkg-config' to find most of the libraries; the
- other libraries it links to are expected in the standard system
- directories. Since the default pkg-config's meta-information
- files (like `harfbuzz.pc') of the build platform don't work, use
- one of the two possible solutions below.
-
- o Use pkg-config's meta-information files that are adjusted to
- cross-compile and cross-link with the target platform's
- libraries. Make sure those files are found before the build
- system's default files. Example:
-
- ./configure \
- --build=i386-unknown-freebsd \
- --host=mips-ip22-linuxelf \
- PKG_CONFIG_LIBDIR="/usr/local/mips-ip22-linux/lib/pkgconfig" \
- [other options]
-
- See the manpage of `pkg-config' for more details.
-
- o Set variables like LIBPNG_LIBS as additional options to the
- `configure' script, overriding the values `pkg-config' would
- provide. `configure --help' shows the available environment
- variables. Example:
-
- ./configure \
- --build=i386-unknown-freebsd \
- --host=mips-ip22-linuxelf \
- LIBPNG_CFLAGS="-I/usr/local/mips-ip22-linux/include" \
- LIBPNG_LIBS="-L/usr/local/mips-ip22-linux/lib -lpng12" \
- [other options]
-
-
- 3. Building command
- -------------------
-
- If the configuration finishes successfully, invoking GNU make
- builds FreeType2. Just say
-
- make
-
- or
-
- gmake
-
- depending on the name the GNU make binary actually has.
-
-
- 4. Installation
- ---------------
-
- Saying
-
- make install
-
- as usual to install FreeType2 into the directory tree specified by
- the argument of the `--prefix' option.
-
- As noted in section 2.2, FreeType2 is sometimes configured to be
- installed into the system directory of the target system, and
- should not be installed in the cross-building system. In such
- cases, the make variable `DESTDIR' is useful to change the root
- directory in the installation. For example, after
-
- make DESTDIR=/mnt/target_system_root/ install
-
- the built FreeType2 library files are installed into the directory
- `/mnt/target_system_root/<prefix_in_configure>/lib'.
-
-
- 5. TODO
- -------
-
- Cross building between Cygwin (or MSys) and Unix must be tested.
-
-
-----------------------------------------------------------------------
-
-Copyright (C) 2006-2023 by
-suzuki toshiya, David Turner, Robert Wilhelm, and Werner Lemberg.
-
-
-This file is part of the FreeType project, and may only be used,
-modified, and distributed under the terms of the FreeType project
-license, LICENSE.TXT. By continuing to use, modify, or distribute
-this file you indicate that you have read the license and understand
-and accept it fully.
-
-
---- end of INSTALL.CROSS ---
diff --git a/docs/INSTALL.GNU b/docs/INSTALL.GNU
deleted file mode 100644
index 7517d9c7c..000000000
--- a/docs/INSTALL.GNU
+++ /dev/null
@@ -1,181 +0,0 @@
-This document contains instructions how to build the FreeType library
-on non-Unix systems with the help of GNU Make. Note that if you are
-running Cygwin or MinGW/MSYS in Windows, you should follow the
-instructions in the file `INSTALL.UNIX' instead.
-
-
- FreeType 2 includes a powerful and flexible build system that allows
- you to easily compile it on a great variety of platforms from the
- command line. To do so, just follow these simple instructions.
-
- 1. Install GNU Make
- -------------------
-
- The FreeType 2 build system relies on many features special to GNU
- Make.
-
- NEARLY ALL OTHER MAKE TOOLS FAIL, INCLUDING `BSD MAKE', SO REALLY
- INSTALL A RECENT VERSION OF GNU MAKE ON YOUR SYSTEM!
-
- Note that make++, a make tool written in Perl, supports enough
- features of GNU make to compile FreeType. See
-
- https://makepp.sourceforge.net
-
- for more information; you need version 2.0 or newer, and you must
- pass option `--norc-substitution'.
-
- Make sure that you are invoking GNU Make from the command line, by
- typing something like:
-
- make -v
-
- to display its version number.
-
- VERSION 3.81 OR NEWER IS NEEDED!
-
-
- 2. Invoke `make'
- ----------------
-
- Go to the root directory of FreeType 2, then simply invoke GNU
- Make from the command line. This will launch the FreeType 2 host
- platform detection routines. A summary will be displayed, for
- example, on Win32.
-
-
- ==============================================================
- FreeType build system -- automatic system detection
-
- The following settings are used:
-
- platform windows
- compiler gcc
- configuration directory .\builds\windows
- configuration rules .\builds\windows\w32-gcc.mk
-
- If this does not correspond to your system or settings please
- remove the file 'config.mk' from this directory then read the
- INSTALL file for help.
-
- Otherwise, simply type 'make' again to build the library
- or 'make refdoc' to build the API reference (the latter needs
- Python >= 3.5).
- =============================================================
-
-
- If the detected settings correspond to your platform and compiler,
- skip to step 5. Note that if your platform is completely alien to
- the build system, the detected platform will be `ansi'.
-
-
- 3. Configure the build system for a different compiler
- ------------------------------------------------------
-
- If the build system correctly detected your platform, but you want
- to use a different compiler than the one specified in the summary
- (for most platforms, gcc is the default compiler), invoke GNU Make
- with
-
- make setup <compiler>
-
- Examples:
-
- to use Visual C++ on Win32, type: `make setup visualc'
- to use Borland C++ on Win32, type `make setup bcc32'
- to use Watcom C++ on Win32, type `make setup watcom'
- to use Intel C++ on Win32, type `make setup intelc'
- to use LCC-Win32 on Win32, type: `make setup lcc'
- to use Watcom C++ on OS/2, type `make setup watcom'
- to use VisualAge C++ on OS/2, type `make setup visualage'
-
- The <compiler> name to use is platform-dependent. The list of
- available compilers for your system is available in the file
- `builds/<system>/detect.mk'.
-
- If you are satisfied by the new configuration summary, skip to
- step 5.
-
-
- 3a. Use clang instead of gcc
- ----------------------------
-
- The `clang' compiler can use FreeType's setup for `gcc'; it is
- sufficient to set the `CC' variable, for example
-
- make CC=clang
-
-
- 3b. Compiling with a C++ compiler
- ---------------------------------
-
- FreeType can be built with a C++ compiler, for example
-
- make CC="g++"
-
- If `clang++' should be used it is necessary to also override the
- `ANSIFLAGS' variable:
-
- make CC="clang++" ANSIFLAGS=""
-
-
- 4. Configure the build system for an unknown platform/compiler
- --------------------------------------------------------------
-
- The auto-detection/setup phase of the build system copies a file
- to the current directory under the name `config.mk'.
-
- For example, on OS/2+gcc, it would simply copy
- `builds/os2/os2-gcc.mk' to `./config.mk'.
-
- If for some reason your platform isn't correctly detected, copy
- manually the configuration sub-makefile to `./config.mk' and go to
- step 5.
-
- Note that this file is a sub-Makefile used to specify Make
- variables for compiler and linker invocation during the build.
- You can easily create your own version from one of the existing
- configuration files, then copy it to the current directory under
- the name `./config.mk'.
-
-
- 5. Build the library
- --------------------
-
- The auto-detection/setup phase should have copied a file in the
- current directory, called `./config.mk'. This file contains
- definitions of various Make variables used to invoke the compiler
- and linker during the build. [It has also generated a file called
- `ftmodule.h' in the objects directory (which is normally
- `<toplevel>/objs/'); please read the file `docs/CUSTOMIZE' for
- customization of FreeType.]
-
- To launch the build, simply invoke GNU Make again: The top
- Makefile will detect the configuration file and run the build with
- it. If you have used variables in step 3, you must use the same
- variables here, too.
-
-
- Final note
-
- The above instructions build a _statically_ linked library of the
- font engine in the `objs' directory. On Windows, you can build a
- DLL either with MinGW (within an MSYS shell, following the
- instructions in `INSTALL.UNIX'), or you use one of the Visual C++
- project files; see the subdirectories of `builds/windows'. For
- everything else, you are on your own, and you might follow the
- instructions in `INSTALL.ANY' to create your own Makefiles.
-
-----------------------------------------------------------------------
-
-Copyright (C) 2003-2023 by
-David Turner, Robert Wilhelm, and Werner Lemberg.
-
-This file is part of the FreeType project, and may only be used,
-modified, and distributed under the terms of the FreeType project
-license, LICENSE.TXT. By continuing to use, modify, or distribute
-this file you indicate that you have read the license and understand
-and accept it fully.
-
-
---- end of INSTALL.GNU ---
diff --git a/docs/INSTALL.UNIX b/docs/INSTALL.UNIX
deleted file mode 100644
index 659f3a21f..000000000
--- a/docs/INSTALL.UNIX
+++ /dev/null
@@ -1,139 +0,0 @@
-This document contains instructions on how to build the FreeType
-library on Unix systems. This also works for emulations like Cygwin
-or MSys on Win32:
-
-
- 1. Ensure that you are using GNU Make
- -------------------------------------
-
- The FreeType build system _exclusively_ works with GNU Make. You
- will not be able to compile the library with the instructions
- below using any other alternative (including BSD Make).
-
- Check that you have GNU make by running the command:
-
- make -v
-
- This should dump some text that begins with:
-
- GNU Make <version number>
- Copyright (C) <year> Free Software Foundation Inc.
-
- Note that version 3.81 or higher is *required* or the build will
- fail.
-
- It is also fine to have GNU Make under another name (e.g. 'gmake')
- if you use the MAKE variable as described below.
-
- As a special exception, 'makepp' can also be used to build
- FreeType 2. See the file docs/MAKEPP for details.
-
- For builds with `cmake' please check file `CMakeLists.txt'; this
- is a contributed file not directly supported by the FreeType team.
-
-
- 2. Regenerate the configure script if needed
- --------------------------------------------
-
- This only applies if you are building a git snapshot or checkout,
- *not* if you grabbed the sources of an official release.
-
- You need to invoke the `autogen.sh' script in the top-level
- directory in order to create the `configure' script for your
- platform. Normally, this simply means typing:
-
- sh autogen.sh
-
- In case of problems, you may need to install or upgrade Automake,
- Autoconf or Libtool. See `README.git' in the top-level directory
- for more information.
-
-
- 3. Build and install the library
- --------------------------------
-
- Say
-
- ./configure --help
-
- to see the list of possible configuration options and important
- environment variables. The ./configure script will detect some
- prerequisite system libraries (libpng, brotli, etc.) if their
- headers are available at the default locations.
-
- The following should work on all Unix systems where the `make'
- command invokes GNU Make:
-
- ./configure [options]
- make
- make install (as root)
-
- The default installation path is `/usr/local'. It can be changed
- with the `--prefix=<path>' option. Example:
-
- ./configure --prefix=/usr
-
- When using a different command to invoke GNU Make, use the MAKE
- variable. For example, if `gmake' is the command to use on your
- system, do something like:
-
- MAKE=gmake ./configure [options]
- gmake
- gmake install (as root)
-
- If this still doesn't work, there must be a problem with your
- system (e.g., you are using a very old version of GNU Make).
-
- For library identification, FreeType's `configure' script uses the
- `pkg-config' interface: Assuming it needs library `foo', it calls
- the `pkg-config' program to find information on library `foo',
- which in turn looks for a `foo.pc' file installed at the system.
- Some platforms, however, don't come with `pkg-support'; you then
- have to use environment variables as described by `configure
- --help'. Example:
-
- LIBPNG_CFLAGS="-I/path/to/libpng/include/directory" \
- LIBPNG_LIBS="-L/path/to/libpng/lib/directory" \
- configure ...
-
- It is possible to compile FreeType in a different directory.
- Assuming the FreeType source files in directory `/src/freetype' a
- compilation in directory `foo' works as follows:
-
- cd foo
- /src/freetype/configure [options]
- make
- make install
-
-
- 3.1 Interdependency with HarfBuzz
- .................................
-
- Note that there is a chicken-and-egg problem currently since the
- HarfBuzz library (used by the auto-hinter to improve support of
- OpenType fonts) depends on FreeType, which can be solved as
- follows in case HarfBuzz is not yet installed on your system.
-
- 1. Call FreeType's `configure' script with option
- `--without-harfbuzz', then compile and install FreeType.
-
- 2. Compile and install HarfBuzz.
-
- 3. Call FreeType's `configure' script without option
- `--without-harfbuzz' (after executing `make distclean'), then
- compile and install FreeType again.
-
-
-----------------------------------------------------------------------
-
-Copyright (C) 2003-2023 by
-David Turner, Robert Wilhelm, and Werner Lemberg.
-
-This file is part of the FreeType project, and may only be used,
-modified, and distributed under the terms of the FreeType project
-license, LICENSE.TXT. By continuing to use, modify, or distribute
-this file you indicate that you have read the license and understand
-and accept it fully.
-
-
---- end of INSTALL.UNIX ---
diff --git a/docs/INSTALL.ANY b/docs/INSTALL_ANY.md
similarity index 51%
rename from docs/INSTALL.ANY
rename to docs/INSTALL_ANY.md
index bb77b1b9c..8b19a596f 100644
--- a/docs/INSTALL.ANY
+++ b/docs/INSTALL_ANY.md
@@ -1,33 +1,32 @@
-Instructions on how to build FreeType with your own build tool
-==============================================================
+# Instructions on how to build FreeType with your own build tool
-See the file `CUSTOMIZE' to learn how to customize FreeType to
-specific environments.
+See the file [docs/CUSTOMIZE][CUSTOMIZE] to learn how to
+customize FreeType to specific environments.
-I. Standard procedure
----------------------
- * If you use macro names for FreeType header files (while mandatory
- in earlier versions, this is now optional since FreeType version
- 2.6.1) it is necessary to disable pre-compiled headers. This is
- very important for Visual C++, because lines like
+## A. Standard procedure
+
+* If you use macro names for FreeType header files (while mandatory
+ in earlier versions, this is now optional since FreeType version
+ 2.6.1) it is necessary to disable pre-compiled headers. This is
+ very important for Visual C++, because lines like
#include FT_FREETYPE_H
- are not correctly supported by this compiler while being ISO C
- compliant!
+ are not correctly supported by this compiler while being ISO C
+ compliant!
- * You need to add the directory `include' to your include path when
- compiling the library.
+* You need to add the directory `include` to your include path when
+ compiling the library.
- * FreeType 2 is made of several components; each of them is located
- in a subdirectory of `freetype/src'. For example,
- `freetype/src/truetype/' contains the TrueType font driver.
+* FreeType 2 is made of several components; each of them is located
+ in a subdirectory of `freetype/src`. For example,
+ `freetype/src/truetype/` contains the TrueType font driver.
- * DO NOT COMPILE ALL C FILES! Rather, compile the following ones.
+* DO NOT COMPILE ALL C FILES! Rather, compile the following ones.
- -- base components (required)
+ ### base components (required):
src/base/ftsystem.c
src/base/ftinit.c
@@ -55,7 +54,7 @@ I. Standard procedure
src/base/ftmac.c -- only on the Macintosh
- -- font drivers (optional; at least one is needed)
+ ### font drivers (optional; at least one is needed)
src/bdf/bdf.c -- BDF font driver
src/cff/cff.c -- CFF/OpenType font driver
@@ -69,14 +68,13 @@ I. Standard procedure
src/type42/type42.c -- Type 42 font driver
src/winfonts/winfnt.c -- Windows FONT / FNT font driver
- -- rasterizers (optional; at least one is needed for vector
- formats)
+ ### rasterizers (optional; at least one is needed for vector formats)
src/raster/raster.c -- monochrome rasterizer
src/sdf/sdf.c -- Signed Distance Field driver
src/smooth/smooth.c -- anti-aliasing rasterizer
- -- auxiliary modules (optional)
+ ### auxiliary modules (optional)
src/autofit/autofit.c -- auto hinting module
src/cache/ftcache.c -- cache sub-system (in beta)
@@ -90,60 +88,58 @@ I. Standard procedure
src/psnames/psnames.c -- PostScript glyph names support
- Notes:
+ ## Notes:
- `ftcache.c' needs `ftglyph.c'
- `ftfstype.c' needs `fttype1.c'
- `ftglyph.c' needs `ftbitmap.c'
- `ftstroke.c' needs `ftglyph.c'
- `ftsynth.c' needs `ftbitmap.c'
+ `ftcache.c` needs `ftglyph.c`
+ `ftfstype.c` needs `fttype1.c`
+ `ftglyph.c` needs `ftbitmap.c`
+ `ftstroke.c` needs `ftglyph.c`
+ `ftsynth.c` needs `ftbitmap.c`
- `cff.c' needs `sfnt.c', `pshinter.c', and `psnames.c'
- `truetype.c' needs `sfnt.c' and `psnames.c'
- `type1.c' needs `psaux.c' `pshinter.c', and `psnames.c'
- `type1cid.c' needs `psaux.c', `pshinter.c', and `psnames.c'
- `type42.c' needs `truetype.c'
+ `cff.c` needs `sfnt.c`, `pshinter.c`, and `psnames.c`
+ `truetype.c` needs `sfnt.c` and `psnames.c`
+ `type1.c` needs `psaux.c` `pshinter.c`, and `psnames.c`
+ `type1cid.c` needs `psaux.c`, `pshinter.c`, and `psnames.c`
+ `type42.c` needs `truetype.c`
- Please consult the central `include/freetype/config/ftoption.h'
- configuration file for details on additional libraries necessary
- for some optional features.
+ Please consult the central `include/freetype/config/ftoption.h`
+ configuration file for details on additional libraries necessary
+ for some optional features.
- Read the file `CUSTOMIZE' in case you want to compile only a subset
- of the drivers, renderers, and optional modules; a detailed
- description of the various base extension is given in the top-level
- file `modules.cfg'.
+Read the file `CUSTOMIZE` in case you want to compile only a subset
+of the drivers, renderers, and optional modules; a detailed
+description of the various base extension is given in the top-level
+file `modules.cfg`.
- You are done. In case of problems, see the archives of the FreeType
- development mailing list.
+You are done. In case of problems, see the archives of the FreeType
+development mailing list.
-II. Support for flat-directory compilation
-------------------------------------------
+## B. Support for flat-directory compilation
- It is possible to put all FreeType 2 source files into a single
- directory, with the *exception* of the `include' hierarchy.
+It is possible to put all FreeType 2 source files into a single
+directory, with the *exception* of the `include` hierarchy.
- 1. Copy all files in current directory
+1. Copy all files in current directory
- cp freetype/src/base/*.[hc] .
- cp freetype/src/raster1/*.[hc] .
- cp freetype/src/smooth/*.[hc] .
- etc.
+ cp freetype/src/base/*.[hc] .
+ cp freetype/src/raster1/*.[hc] .
+ cp freetype/src/smooth/*.[hc] .
+ etc.
- 2. Compile sources
+2. Compile sources
- cc -c -Iinclude -DFT2_BUILD_LIBRARY ftsystem.c
- cc -c -Iinclude -DFT2_BUILD_LIBRARY ftinit.c
- cc -c -Iinclude -DFT2_BUILD_LIBRARY ftdebug.c
- cc -c -Iinclude -DFT2_BUILD_LIBRARY ftbase.c
- etc.
+ cc -c -Iinclude -DFT2_BUILD_LIBRARY ftsystem.c
+ cc -c -Iinclude -DFT2_BUILD_LIBRARY ftinit.c
+ cc -c -Iinclude -DFT2_BUILD_LIBRARY ftdebug.c
+ cc -c -Iinclude -DFT2_BUILD_LIBRARY ftbase.c
+ etc.
You don't need to define the FT_FLAT_COMPILATION macro (as this
was required in previous releases of FreeType 2).
-----------------------------------------------------------------------
-
+```
Copyright (C) 2003-2023 by
David Turner, Robert Wilhelm, and Werner Lemberg.
@@ -152,6 +148,7 @@ modified, and distributed under the terms of the
FreeType project
license, LICENSE.TXT. By continuing to use, modify, or distribute
this file you indicate that you have read the license and understand
and accept it fully.
+```
-
---- end of INSTALL.ANY ---
+<!---->
+[CUSTOMIZE]: ./CUSTOMIZE
diff --git a/docs/INSTALL_CROSS.md b/docs/INSTALL_CROSS.md
new file mode 100644
index 000000000..00e8dd85e
--- /dev/null
+++ b/docs/INSTALL_CROSS.md
@@ -0,0 +1,183 @@
+# Cross-Compiling FreeType
+
+This document contains instructions on how to cross-build the FreeType
+library on Unix systems, for example, building binaries for Linux/MIPS
+on FreeBSD/i386. Before reading this document, please consult the
+file [INSTALL_UNIX.md] for required tools and the basic self-building
+procedure.
+
+
+## 1. Required Tools
+
+ For self-building the FreeType library on a Unix system, GNU Make
+ 3.81 or newer is required. [INSTALL_UNIX.md contains hints how to
+ check the installed `make`.
+
+ The GNU C compiler to cross-build the target system is required.
+ Currently, using a non-GNU cross compiler is untested. The cross
+ compiler is expected to be installed with a system prefix. For
+ example, if your building system is FreeBSD/i386 and the target
+ system is Linux/MIPS, the cross compiler should be installed with
+ the name `mips-ip22-linuxelf-gcc`.
+
+ A C compiler for a self-build is required also, to build a tool
+ (`apinames`) that is executed during the build procedure. Non-GNU
+ self compilers are acceptable, but such a setup is untested.
+
+
+## 2. Configuration
+
+ ### 2.1 Building and target system
+
+ To configure a cross-build, the options `--host=<system>` and
+ `--build=<system>` must be passed to the `configure` script.
+ For example, if your build system is FreeBSD/i386 and the target
+ system is Linux/MIPS, say
+
+ ```bash
+ ./configure \
+ --build=i386-unknown-freebsd \
+ --host=mips-ip22-linuxelf \
+ [other options]
+ ```
+
+ It should be noted that `--host=<system>` specifies the system
+ where the built binaries will be executed, not the system where
+ the build actually happens. Older versions of GNU autoconf use
+ the option pair `--host=` and `--target=`. This is broken and
+ doesn't work. Similarly, an explicit CC specification like
+
+ ```bash
+ env CC=mips-ip22-linux-gcc ./configure # BAD
+ ```
+ or
+
+ ```bash
+ env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure # BAD
+ ```
+
+ doesn't work either; such a configuration confuses the
+ `configure` script while trying to find the cross and native C
+ compilers.
+
+
+ ### 2.2. The prefix to install FreeType2
+
+ Setting `--prefix=<prefix>` properly is important. The prefix
+ to install FreeType2 is written into the `freetype-config`
+ script and `freetype2.pc` configuration file.
+
+ If the built FreeType 2 library is used as a part of the
+ cross-building system, the prefix is expected to be different
+ from the self-building system. For example, a configuration
+ with `--prefix=/usr/local` installs binaries into the
+ system-wide `/usr/local` directory, which then can't be executed
+ due to the incorrect architecture. This causes confusion in
+ configuration of all applications that use FreeType2. Instead,
+ use a prefix to install the cross-build into a separate system
+ tree, for example, `--prefix=/usr/local/mips-ip22-linux/`.
+
+ On the other hand, if the built FreeType 2 library is used as a
+ part of the target system, the prefix to install should reflect
+ the file system structure of the target system.
+
+
+ ### 2.3. Library dependencies
+
+ FreeType normally depends on external libraries like `libpng` or
+ `libharfbuzz`. The easiest case is to deactivate all such
+ dependencies using the `--without-XXX` configuration options.
+ However, if you want to use those libraries, you should ensure
+ that they are available both on the target system and as
+ (cross-compiled) libraries on the build system.
+
+ FreeType uses `pkg-config` to find most of the libraries; the
+ other libraries it links to are expected in the standard system
+ directories. Since the default pkg-config's meta-information
+ files (like `harfbuzz.pc`) of the build platform don't work, use
+ one of the two possible solutions below.
+
+ - Use pkg-config's meta-information files that are adjusted to
+ cross-compile and cross-link with the target platform's
+ libraries. Make sure those files are found before the build
+ system's default files. Example:
+ ```bash
+ ./configure \
+ --build=i386-unknown-freebsd \
+ --host=mips-ip22-linuxelf \
+ PKG_CONFIG_LIBDIR="/usr/local/mips-ip22-linux/lib/pkgconfig" \
+ [other options]
+ ```
+
+ See the manpage of `pkg-config` for more details.
+
+ - Set variables like LIBPNG_LIBS as additional options to the
+ `configure` script, overriding the values `pkg-config` would
+ provide. `configure --help` shows the available environment
+ variables. Example:
+ ```bash
+ ./configure \
+ --build=i386-unknown-freebsd \
+ --host=mips-ip22-linuxelf \
+ LIBPNG_CFLAGS="-I/usr/local/mips-ip22-linux/include" \
+ LIBPNG_LIBS="-L/usr/local/mips-ip22-linux/lib -lpng12" \
+ [other options]
+ ```
+
+
+## 3. Building command
+
+ If the configuration finishes successfully, invoking GNU make
+ builds FreeType2. Just say
+
+ make
+
+ or
+
+ gmake
+
+ depending on the name the GNU make binary actually has.
+
+
+## 4. Installation
+
+ Saying
+
+ make install
+
+ as usual to install FreeType2 into the directory tree specified by
+ the argument of the `--prefix` option.
+
+ As noted in section 2.2, FreeType2 is sometimes configured to be
+ installed into the system directory of the target system, and
+ should not be installed in the cross-building system. In such
+ cases, the make variable `DESTDIR` is useful to change the root
+ directory in the installation. For example, after
+
+ ```bash
+ make DESTDIR=/mnt/target_system_root/ install
+ ```
+
+ the built FreeType2 library files are installed into the directory
+ `/mnt/target_system_root/<prefix_in_configure>/lib`.
+
+
+5. TODO
+
+ Cross building between Cygwin (or MSys) and Unix must be tested.
+
+
+```
+Copyright (C) 2006-2023 by
+suzuki toshiya, David Turner, Robert Wilhelm, and Werner Lemberg.
+
+
+This file is part of the FreeType project, and may only be used,
+modified, and distributed under the terms of the FreeType project
+license, LICENSE.TXT. By continuing to use, modify, or distribute
+this file you indicate that you have read the license and understand
+and accept it fully.
+```
+
+<!---->
+[INSTALL_UNIX.md]: ./INSTALL_UNIX.md
diff --git a/docs/INSTALL_GNU.md b/docs/INSTALL_GNU.md
new file mode 100644
index 000000000..7cbfe7d89
--- /dev/null
+++ b/docs/INSTALL_GNU.md
@@ -0,0 +1,184 @@
+# Compiling FreeType with GNU Make
+
+This document contains instructions how to build the FreeType library
+on non-Unix systems with the help of GNU Make. Note that if you are
+running Cygwin or MinGW/MSYS in Windows, you should follow the
+instructions in the file [INSTALL_UNIX.md] instead.
+
+
+FreeType 2 includes a powerful and flexible build system that allows
+you to easily compile it on a great variety of platforms from the
+command line. To do so, just follow these simple instructions.
+
+## 1. Install GNU Make
+
+ The FreeType 2 build system relies on many features special to GNU
+ Make.
+
+ NEARLY ALL OTHER MAKE TOOLS FAIL, INCLUDING `BSD MAKE`, SO REALLY
+ INSTALL A RECENT VERSION OF GNU MAKE ON YOUR SYSTEM!
+
+ Note that make++, a make tool written in Perl, supports enough
+ features of GNU make to compile FreeType. See
+
+ https://makepp.sourceforge.net
+
+ for more information; you need version 2.0 or newer, and you must
+ pass option `--norc-substitution`.
+
+ Make sure that you are invoking GNU Make from the command line, by
+ typing something like:
+
+ make -v
+
+ to display its version number.
+
+ VERSION 3.81 OR NEWER IS NEEDED!
+
+
+## 2. Invoke `make`
+
+ Go to the root directory of FreeType 2, then simply invoke GNU
+ Make from the command line. This will launch the FreeType 2 host
+ platform detection routines. A summary will be displayed, for
+ example, on Win32.
+
+
+ FreeType build system -- automatic system detection
+
+ The following settings are used:
+
+ platform windows
+ compiler gcc
+ configuration directory .\builds\windows
+ configuration rules .\builds\windows\w32-gcc.mk
+
+ If this does not correspond to your system or settings please
+ remove the file 'config.mk' from this directory then read the
+ INSTALL file for help.
+
+ Otherwise, simply type 'make' again to build the library
+ or 'make refdoc' to build the API reference (the latter needs
+ Python >= 3.5).
+
+
+ If the detected settings correspond to your platform and compiler,
+ skip to step 5. Note that if your platform is completely alien to
+ the build system, the detected platform will be `ansi`.
+
+
+## 3. Configure the build system for a different compiler
+
+ If the build system correctly detected your platform, but you want
+ to use a different compiler than the one specified in the summary
+ (for most platforms, gcc is the default compiler), invoke GNU Make
+ with
+
+ ```
+ make setup <compiler>
+ ```
+
+ Examples:
+
+ to use Visual C++ on Win32, type: `make setup visualc`
+
+ to use Borland C++ on Win32, type `make setup bcc32`
+
+ to use Watcom C++ on Win32, type `make setup watcom`
+
+ to use Intel C++ on Win32, type `make setup intelc`
+
+ to use LCC-Win32 on Win32, type: `make setup lcc`
+
+ to use Watcom C++ on OS/2, type `make setup watcom`
+
+ to use VisualAge C++ on OS/2, type `make setup visualage`
+
+
+ The `<compiler>` name to use is platform-dependent. The list of
+ available compilers for your system is available in the file
+ `builds/<system>/detect.mk`.
+
+ If you are satisfied by the new configuration summary, skip to
+ step 5.
+
+
+ ### 3a. Use clang instead of gcc
+
+ The `clang` compiler can use FreeType's setup for `gcc`; it is
+ sufficient to set the `CC` variable, for example
+
+ make CC=clang
+
+
+ ### 3b. Compiling with a C++ compiler
+
+ FreeType can be built with a C++ compiler, for example
+
+ make CC="g++"
+
+ If `clang++` should be used it is necessary to also override the
+ `ANSIFLAGS` variable:
+
+ make CC="clang++" ANSIFLAGS=""
+
+
+## 4. Configure the build system for an unknown platform/compiler
+
+ The auto-detection/setup phase of the build system copies a file
+ to the current directory under the name `config.mk`.
+
+ For example, on OS/2+gcc, it would simply copy
+ `builds/os2/os2-gcc.mk` to `./config.mk`.
+
+ If for some reason your platform isn't correctly detected, copy
+ manually the configuration sub-makefile to `./config.mk` and go to
+ step 5.
+
+ Note that this file is a sub-Makefile used to specify Make
+ variables for compiler and linker invocation during the build.
+ You can easily create your own version from one of the existing
+ configuration files, then copy it to the current directory under
+ the name `./config.mk`.
+
+
+## 5. Build the library
+
+ The auto-detection/setup phase should have copied a file in the
+ current directory, called `./config.mk`. This file contains
+ definitions of various Make variables used to invoke the compiler
+ and linker during the build. [It has also generated a file called
+ `ftmodule.h` in the objects directory (which is normally
+ `<toplevel>/objs/`); please read the file [docs/CUSTOMIZE][CUSTOMIZE] for
+ customization of FreeType.]
+
+ To launch the build, simply invoke GNU Make again: The top
+ Makefile will detect the configuration file and run the build with
+ it. If you have used variables in step 3, you must use the same
+ variables here, too.
+
+
+Final note
+
+ The above instructions build a _statically_ linked library of the
+ font engine in the `objs` directory. On Windows, you can build a
+ DLL either with MinGW (within an MSYS shell, following the
+ instructions in `INSTALL.UNIX`), or you use one of the Visual C++
+ project files; see the subdirectories of `builds/windows`. For
+ everything else, you are on your own, and you might follow the
+ instructions in `INSTALL.ANY` to create your own Makefiles.
+
+```
+Copyright (C) 2003-2023 by
+David Turner, Robert Wilhelm, and Werner Lemberg.
+
+This file is part of the FreeType project, and may only be used,
+modified, and distributed under the terms of the FreeType project
+license, LICENSE.TXT. By continuing to use, modify, or distribute
+this file you indicate that you have read the license and understand
+and accept it fully.
+```
+
+<!---->
+[INSTALL_UNIX.md]: ./INSTALL_UNIX.md
+[CUSTOMIZE]: ./CUSTOMIZE
diff --git a/docs/INSTALL.MAC b/docs/INSTALL_MAC.md
similarity index 79%
rename from docs/INSTALL.MAC
rename to docs/INSTALL_MAC.md
index 2587e24a6..f79b03ddc 100644
--- a/docs/INSTALL.MAC
+++ b/docs/INSTALL_MAC.md
@@ -1,28 +1,34 @@
+# Compiling FreeType on Mac OS X
+
Please follow the instructions in INSTALL.UNIX to install FreeType on
Mac OS X.
Currently FreeType2 functions based on some deprecated Carbon APIs
-return `FT_Err_Unimplemented_Feature' always, even if FreeType2 is
+return `FT_Err_Unimplemented_Feature` always, even if FreeType2 is
configured and built on the system that deprecated Carbon APIs are
available. To enable deprecated FreeType2 functions as far as
-possible, replace `src/base/ftmac.c' by `builds/mac/ftmac.c'.
+possible, replace `src/base/ftmac.` by `builds/mac/ftmac.c`.
Starting with Mac OS X 10.5, gcc defaults the deployment target to
10.5. In previous versions of Mac OS X, this defaulted to 10.1. If
you want your built binaries to run only on 10.5, this change does not
concern you. If you want them to also run on older versions of Mac
OS X, then you must either set the MACOSX_DEPLOYMENT_TARGET
-environment variable or pass `-mmacosx-version-min' to gcc. You
+environment variable or pass `-mmacosx-version-min` to gcc. You
should specify the oldest version of Mac OS you want the code to run
on. For example, if you use Bourne shell:
+```bash
export MACOSX_DEPLOYMENT_TARGET=10.2
+```
or, if you use C shell:
+```bash
setenv MACOSX_DEPLOYMENT_TARGET 10.2
+```
-Alternatively, you could pass `-mmacosx-version-min=10.2' to gcc.
+Alternatively, you could pass `-mmacosx-version-min=10.2` to gcc.
Here the number 10.2 is the lowest version that the built binaries can
run on. In the above cases, the built binaries will run on Mac OS X
diff --git a/docs/INSTALL_UNIX.md b/docs/INSTALL_UNIX.md
new file mode 100644
index 000000000..f32a06582
--- /dev/null
+++ b/docs/INSTALL_UNIX.md
@@ -0,0 +1,141 @@
+# Building FreeType on Unix Systems
+
+This also works for emulations like Cygwin or MSys on Win32:
+
+
+## 1. Ensure that you are using GNU Make
+
+ The FreeType build system _exclusively_ works with GNU Make. You
+ will not be able to compile the library with the instructions
+ below using any other alternative (including BSD Make).
+
+ Check that you have GNU make by running the command:
+ ```bash
+ make -v
+ ```
+
+ This should dump some text that begins with:
+
+ GNU Make <version number>
+ Copyright (C) <year> Free Software Foundation Inc.
+
+ Note that version 3.81 or higher is *required* or the build will
+ fail.
+
+ It is also fine to have GNU Make under another name (e.g. 'gmake')
+ if you use the MAKE variable as described below.
+
+ As a special exception, 'makepp' can also be used to build
+ FreeType 2. See the file `docs/MAKEPP` for details.
+
+ For builds with `cmake` please check file `CMakeLists.txt`; this
+ is a contributed file not directly supported by the FreeType team.
+
+
+## 2. Regenerate the configure script if needed
+
+ This only applies if you are building a git snapshot or checkout,
+ *not* if you grabbed the sources of an official release.
+
+ You need to invoke the `autogen.sh` script in the top-level
+ directory in order to create the `configure` script for your
+ platform. Normally, this simply means typing:
+ ```bash
+ sh autogen.sh
+ ```
+
+ In case of problems, you may need to install or upgrade Automake,
+ Autoconf or Libtool. See [INSTALL.md] for more information.
+
+
+## 3. Build and install the library
+
+ Say
+ ```bash
+ ./configure --help
+ ```
+
+ to see the list of possible configuration options and important
+ environment variables. The `./configure` script will detect some
+ prerequisite system libraries (libpng, brotli, etc.) if their
+ headers are available at the default locations.
+
+ The following should work on all Unix systems where the `make`
+ command invokes GNU Make:
+ ```bash
+ ./configure [options]
+ make
+ make install (as root)
+ ```
+
+ The default installation path is `/usr/local`. It can be changed
+ with the `--prefix=<path>` option. Example:
+ ```bash
+ ./configure --prefix=/usr
+ ```
+
+ When using a different command to invoke GNU Make, use the MAKE
+ variable. For example, if `gmake` is the command to use on your
+ system, do something like:
+ ```bash
+ MAKE=gmake ./configure [options]
+ gmake
+ gmake install (as root)
+ ```
+
+ If this still doesn't work, there must be a problem with your
+ system (e.g., you are using a very old version of GNU Make).
+
+ For library identification, FreeType's `configure` script uses the
+ `pkg-config` interface: Assuming it needs library `foo`, it calls
+ the `pkg-config` program to find information on library `foo`,
+ which in turn looks for a `foo.pc` file installed at the system.
+ Some platforms, however, don't come with `pkg-support`; you then
+ have to use environment variables as described by `configure
+ --help`. Example:
+ ```bash
+ LIBPNG_CFLAGS="-I/path/to/libpng/include/directory" \
+ LIBPNG_LIBS="-L/path/to/libpng/lib/directory" \
+ configure ...
+ ```
+ It is possible to compile FreeType in a different directory.
+ Assuming the FreeType source files in directory `/src/freetype` a
+ compilation in directory `foo` works as follows:
+ ```bash
+ cd foo
+ /src/freetype/configure [options]
+ make
+ make install
+ ```
+
+
+ ### 3.1 Interdependency with HarfBuzz
+
+ Note that there is a chicken-and-egg problem currently since the
+ HarfBuzz library (used by the auto-hinter to improve support of
+ OpenType fonts) depends on FreeType, which can be solved as
+ follows in case HarfBuzz is not yet installed on your system.
+
+ 1. Call FreeType's `configure` script with option
+ `--without-harfbuzz`, then compile and install FreeType.
+
+ 2. Compile and install HarfBuzz.
+
+ 3. Call FreeType's `configure` script without option
+ `--without-harfbuzz` (after executing `make distclean`), then
+ compile and install FreeType again.
+
+
+```
+Copyright (C) 2003-2023 by
+David Turner, Robert Wilhelm, and Werner Lemberg.
+
+This file is part of the FreeType project, and may only be used,
+modified, and distributed under the terms of the FreeType project
+license, LICENSE.TXT. By continuing to use, modify, or distribute
+this file you indicate that you have read the license and understand
+and accept it fully.
+```
+
+<!---->
+[INSTALL.md]: ./INSTALL.md
diff --git a/docs/INSTALL.VMS b/docs/INSTALL_VMS.md
similarity index 88%
rename from docs/INSTALL.VMS
rename to docs/INSTALL_VMS.md
index 4f8c3ac33..024291665 100644
--- a/docs/INSTALL.VMS
+++ b/docs/INSTALL_VMS.md
@@ -1,8 +1,7 @@
-How to build the FreeType library on VMS
-----------------------------------------
+# How to build the FreeType library on VMS
It is actually very straightforward to install the FreeType library.
-Just execute `vms_make.com from` the toplevel directory to build the
+Just execute `vms_make.com` from the toplevel directory to build the
library. This procedure currently accepts the following options:
* `DEBUG`
@@ -25,18 +24,21 @@ To rebuild the sources it is necessary to have MMS/MMK
installed on
the system.
The library is available in the directory
-
+```
[.LIB]
+```
To compile applications using FreeType you have to define the logical
`FREETYPE` pointing to the directory
-
+```
[.INCLUDE.FREETYPE]
+```
i.e., if the directory in which this `INSTALL.VMS` file is located is
`$disk:[freetype.docs]`, then define the logical with
-
+```
define freetype $disk:[freetype.include.freetype]
+```
See http://nchrem.tnw.tudelft.nl/openvms/software2.html#Freetype for
the packages FreeType depends on.
@@ -54,8 +56,7 @@ Orginal version of the build procedures was created by
Martin P.J. Zinser <zinser@zinser.no-ip.info>
-------------------------------------------------------------------------
-
+```
Copyright (C) 2000-2023 by
David Turner, Robert Wilhelm, and Werner Lemberg.
@@ -64,6 +65,4 @@ modified, and distributed under the terms of the
FreeType project
license, LICENSE.TXT. By continuing to use, modify, or distribute this
file you indicate that you have read the license and understand and
accept it fully.
-
-
---- end of INSTALL.VMS ---
+```
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [freetype2] gsoc-anurag-docs-2023 658eec4ca 1/3: [docs] Migrate all INSTALL files to Markdown,
Werner Lemberg <=