Annotation of embedaddon/pcre/INSTALL, revision 1.1.1.2

1.1       misho       1: Installation Instructions
                      2: *************************
                      3: 
1.1.1.2 ! misho       4: Copyright (C) 1994-1996, 1999-2002, 2004-2013 Free Software Foundation,
        !             5: Inc.
1.1       misho       6: 
                      7:    Copying and distribution of this file, with or without modification,
                      8: are permitted in any medium without royalty provided the copyright
                      9: notice and this notice are preserved.  This file is offered as-is,
                     10: without warranty of any kind.
                     11: 
                     12: Basic Installation
                     13: ==================
                     14: 
                     15:    Briefly, the shell commands `./configure; make; make install' should
                     16: configure, build, and install this package.  The following
                     17: more-detailed instructions are generic; see the `README' file for
                     18: instructions specific to this package.  Some packages provide this
                     19: `INSTALL' file but do not implement all of the features documented
                     20: below.  The lack of an optional feature in a given package is not
                     21: necessarily a bug.  More recommendations for GNU packages can be found
                     22: in *note Makefile Conventions: (standards)Makefile Conventions.
                     23: 
                     24:    The `configure' shell script attempts to guess correct values for
                     25: various system-dependent variables used during compilation.  It uses
                     26: those values to create a `Makefile' in each directory of the package.
                     27: It may also create one or more `.h' files containing system-dependent
                     28: definitions.  Finally, it creates a shell script `config.status' that
                     29: you can run in the future to recreate the current configuration, and a
                     30: file `config.log' containing compiler output (useful mainly for
                     31: debugging `configure').
                     32: 
                     33:    It can also use an optional file (typically called `config.cache'
                     34: and enabled with `--cache-file=config.cache' or simply `-C') that saves
                     35: the results of its tests to speed up reconfiguring.  Caching is
                     36: disabled by default to prevent problems with accidental use of stale
                     37: cache files.
                     38: 
                     39:    If you need to do unusual things to compile the package, please try
                     40: to figure out how `configure' could check whether to do them, and mail
                     41: diffs or instructions to the address given in the `README' so they can
                     42: be considered for the next release.  If you are using the cache, and at
                     43: some point `config.cache' contains results you don't want to keep, you
                     44: may remove or edit it.
                     45: 
                     46:    The file `configure.ac' (or `configure.in') is used to create
                     47: `configure' by a program called `autoconf'.  You need `configure.ac' if
                     48: you want to change it or regenerate `configure' using a newer version
                     49: of `autoconf'.
                     50: 
                     51:    The simplest way to compile this package is:
                     52: 
                     53:   1. `cd' to the directory containing the package's source code and type
                     54:      `./configure' to configure the package for your system.
                     55: 
                     56:      Running `configure' might take a while.  While running, it prints
                     57:      some messages telling which features it is checking for.
                     58: 
                     59:   2. Type `make' to compile the package.
                     60: 
                     61:   3. Optionally, type `make check' to run any self-tests that come with
                     62:      the package, generally using the just-built uninstalled binaries.
                     63: 
                     64:   4. Type `make install' to install the programs and any data files and
                     65:      documentation.  When installing into a prefix owned by root, it is
                     66:      recommended that the package be configured and built as a regular
                     67:      user, and only the `make install' phase executed with root
                     68:      privileges.
                     69: 
                     70:   5. Optionally, type `make installcheck' to repeat any self-tests, but
                     71:      this time using the binaries in their final installed location.
                     72:      This target does not install anything.  Running this target as a
                     73:      regular user, particularly if the prior `make install' required
                     74:      root privileges, verifies that the installation completed
                     75:      correctly.
                     76: 
                     77:   6. You can remove the program binaries and object files from the
                     78:      source code directory by typing `make clean'.  To also remove the
                     79:      files that `configure' created (so you can compile the package for
                     80:      a different kind of computer), type `make distclean'.  There is
                     81:      also a `make maintainer-clean' target, but that is intended mainly
                     82:      for the package's developers.  If you use it, you may have to get
                     83:      all sorts of other programs in order to regenerate files that came
                     84:      with the distribution.
                     85: 
                     86:   7. Often, you can also type `make uninstall' to remove the installed
                     87:      files again.  In practice, not all packages have tested that
                     88:      uninstallation works correctly, even though it is required by the
                     89:      GNU Coding Standards.
                     90: 
                     91:   8. Some packages, particularly those that use Automake, provide `make
                     92:      distcheck', which can by used by developers to test that all other
                     93:      targets like `make install' and `make uninstall' work correctly.
                     94:      This target is generally not run by end users.
                     95: 
                     96: Compilers and Options
                     97: =====================
                     98: 
                     99:    Some systems require unusual options for compilation or linking that
                    100: the `configure' script does not know about.  Run `./configure --help'
                    101: for details on some of the pertinent environment variables.
                    102: 
                    103:    You can give `configure' initial values for configuration parameters
                    104: by setting variables in the command line or in the environment.  Here
                    105: is an example:
                    106: 
                    107:      ./configure CC=c99 CFLAGS=-g LIBS=-lposix
                    108: 
                    109:    *Note Defining Variables::, for more details.
                    110: 
                    111: Compiling For Multiple Architectures
                    112: ====================================
                    113: 
                    114:    You can compile the package for more than one kind of computer at the
                    115: same time, by placing the object files for each architecture in their
                    116: own directory.  To do this, you can use GNU `make'.  `cd' to the
                    117: directory where you want the object files and executables to go and run
                    118: the `configure' script.  `configure' automatically checks for the
                    119: source code in the directory that `configure' is in and in `..'.  This
                    120: is known as a "VPATH" build.
                    121: 
                    122:    With a non-GNU `make', it is safer to compile the package for one
                    123: architecture at a time in the source code directory.  After you have
                    124: installed the package for one architecture, use `make distclean' before
                    125: reconfiguring for another architecture.
                    126: 
                    127:    On MacOS X 10.5 and later systems, you can create libraries and
                    128: executables that work on multiple system types--known as "fat" or
                    129: "universal" binaries--by specifying multiple `-arch' options to the
                    130: compiler but only a single `-arch' option to the preprocessor.  Like
                    131: this:
                    132: 
                    133:      ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                    134:                  CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                    135:                  CPP="gcc -E" CXXCPP="g++ -E"
                    136: 
                    137:    This is not guaranteed to produce working output in all cases, you
                    138: may have to build one architecture at a time and combine the results
                    139: using the `lipo' tool if you have problems.
                    140: 
                    141: Installation Names
                    142: ==================
                    143: 
                    144:    By default, `make install' installs the package's commands under
                    145: `/usr/local/bin', include files under `/usr/local/include', etc.  You
                    146: can specify an installation prefix other than `/usr/local' by giving
                    147: `configure' the option `--prefix=PREFIX', where PREFIX must be an
                    148: absolute file name.
                    149: 
                    150:    You can specify separate installation prefixes for
                    151: architecture-specific files and architecture-independent files.  If you
                    152: pass the option `--exec-prefix=PREFIX' to `configure', the package uses
                    153: PREFIX as the prefix for installing programs and libraries.
                    154: Documentation and other data files still use the regular prefix.
                    155: 
                    156:    In addition, if you use an unusual directory layout you can give
                    157: options like `--bindir=DIR' to specify different values for particular
                    158: kinds of files.  Run `configure --help' for a list of the directories
                    159: you can set and what kinds of files go in them.  In general, the
                    160: default for these options is expressed in terms of `${prefix}', so that
                    161: specifying just `--prefix' will affect all of the other directory
                    162: specifications that were not explicitly provided.
                    163: 
                    164:    The most portable way to affect installation locations is to pass the
                    165: correct locations to `configure'; however, many packages provide one or
                    166: both of the following shortcuts of passing variable assignments to the
                    167: `make install' command line to change installation locations without
                    168: having to reconfigure or recompile.
                    169: 
                    170:    The first method involves providing an override variable for each
                    171: affected directory.  For example, `make install
                    172: prefix=/alternate/directory' will choose an alternate location for all
                    173: directory configuration variables that were expressed in terms of
                    174: `${prefix}'.  Any directories that were specified during `configure',
                    175: but not in terms of `${prefix}', must each be overridden at install
                    176: time for the entire installation to be relocated.  The approach of
                    177: makefile variable overrides for each directory variable is required by
                    178: the GNU Coding Standards, and ideally causes no recompilation.
                    179: However, some platforms have known limitations with the semantics of
                    180: shared libraries that end up requiring recompilation when using this
                    181: method, particularly noticeable in packages that use GNU Libtool.
                    182: 
                    183:    The second method involves providing the `DESTDIR' variable.  For
                    184: example, `make install DESTDIR=/alternate/directory' will prepend
                    185: `/alternate/directory' before all installation names.  The approach of
                    186: `DESTDIR' overrides is not required by the GNU Coding Standards, and
                    187: does not work on platforms that have drive letters.  On the other hand,
                    188: it does better at avoiding recompilation issues, and works well even
                    189: when some directory options were not specified in terms of `${prefix}'
                    190: at `configure' time.
                    191: 
                    192: Optional Features
                    193: =================
                    194: 
                    195:    If the package supports it, you can cause programs to be installed
                    196: with an extra prefix or suffix on their names by giving `configure' the
                    197: option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
                    198: 
                    199:    Some packages pay attention to `--enable-FEATURE' options to
                    200: `configure', where FEATURE indicates an optional part of the package.
                    201: They may also pay attention to `--with-PACKAGE' options, where PACKAGE
                    202: is something like `gnu-as' or `x' (for the X Window System).  The
                    203: `README' should mention any `--enable-' and `--with-' options that the
                    204: package recognizes.
                    205: 
                    206:    For packages that use the X Window System, `configure' can usually
                    207: find the X include and library files automatically, but if it doesn't,
                    208: you can use the `configure' options `--x-includes=DIR' and
                    209: `--x-libraries=DIR' to specify their locations.
                    210: 
                    211:    Some packages offer the ability to configure how verbose the
                    212: execution of `make' will be.  For these packages, running `./configure
                    213: --enable-silent-rules' sets the default to minimal output, which can be
                    214: overridden with `make V=1'; while running `./configure
                    215: --disable-silent-rules' sets the default to verbose, which can be
                    216: overridden with `make V=0'.
                    217: 
                    218: Particular systems
                    219: ==================
                    220: 
                    221:    On HP-UX, the default C compiler is not ANSI C compatible.  If GNU
                    222: CC is not installed, it is recommended to use the following options in
                    223: order to use an ANSI C compiler:
                    224: 
                    225:      ./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
                    226: 
                    227: and if that doesn't work, install pre-built binaries of GCC for HP-UX.
                    228: 
1.1.1.2 ! misho     229:    HP-UX `make' updates targets which have the same time stamps as
        !           230: their prerequisites, which makes it generally unusable when shipped
        !           231: generated files such as `configure' are involved.  Use GNU `make'
        !           232: instead.
        !           233: 
1.1       misho     234:    On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
                    235: parse its `<wchar.h>' header file.  The option `-nodtk' can be used as
                    236: a workaround.  If GNU CC is not installed, it is therefore recommended
                    237: to try
                    238: 
                    239:      ./configure CC="cc"
                    240: 
                    241: and if that doesn't work, try
                    242: 
                    243:      ./configure CC="cc -nodtk"
                    244: 
                    245:    On Solaris, don't put `/usr/ucb' early in your `PATH'.  This
                    246: directory contains several dysfunctional programs; working variants of
                    247: these programs are available in `/usr/bin'.  So, if you need `/usr/ucb'
                    248: in your `PATH', put it _after_ `/usr/bin'.
                    249: 
                    250:    On Haiku, software installed for all users goes in `/boot/common',
                    251: not `/usr/local'.  It is recommended to use the following options:
                    252: 
                    253:      ./configure --prefix=/boot/common
                    254: 
                    255: Specifying the System Type
                    256: ==========================
                    257: 
                    258:    There may be some features `configure' cannot figure out
                    259: automatically, but needs to determine by the type of machine the package
                    260: will run on.  Usually, assuming the package is built to be run on the
                    261: _same_ architectures, `configure' can figure that out, but if it prints
                    262: a message saying it cannot guess the machine type, give it the
                    263: `--build=TYPE' option.  TYPE can either be a short name for the system
                    264: type, such as `sun4', or a canonical name which has the form:
                    265: 
                    266:      CPU-COMPANY-SYSTEM
                    267: 
                    268: where SYSTEM can have one of these forms:
                    269: 
                    270:      OS
                    271:      KERNEL-OS
                    272: 
                    273:    See the file `config.sub' for the possible values of each field.  If
                    274: `config.sub' isn't included in this package, then this package doesn't
                    275: need to know the machine type.
                    276: 
                    277:    If you are _building_ compiler tools for cross-compiling, you should
                    278: use the option `--target=TYPE' to select the type of system they will
                    279: produce code for.
                    280: 
                    281:    If you want to _use_ a cross compiler, that generates code for a
                    282: platform different from the build platform, you should specify the
                    283: "host" platform (i.e., that on which the generated programs will
                    284: eventually be run) with `--host=TYPE'.
                    285: 
                    286: Sharing Defaults
                    287: ================
                    288: 
                    289:    If you want to set default values for `configure' scripts to share,
                    290: you can create a site shell script called `config.site' that gives
                    291: default values for variables like `CC', `cache_file', and `prefix'.
                    292: `configure' looks for `PREFIX/share/config.site' if it exists, then
                    293: `PREFIX/etc/config.site' if it exists.  Or, you can set the
                    294: `CONFIG_SITE' environment variable to the location of the site script.
                    295: A warning: not all `configure' scripts look for a site script.
                    296: 
                    297: Defining Variables
                    298: ==================
                    299: 
                    300:    Variables not defined in a site shell script can be set in the
                    301: environment passed to `configure'.  However, some packages may run
                    302: configure again during the build, and the customized values of these
                    303: variables may be lost.  In order to avoid this problem, you should set
                    304: them in the `configure' command line, using `VAR=value'.  For example:
                    305: 
                    306:      ./configure CC=/usr/local2/bin/gcc
                    307: 
                    308: causes the specified `gcc' to be used as the C compiler (unless it is
                    309: overridden in the site shell script).
                    310: 
                    311: Unfortunately, this technique does not work for `CONFIG_SHELL' due to
1.1.1.2 ! misho     312: an Autoconf limitation.  Until the limitation is lifted, you can use
        !           313: this workaround:
1.1       misho     314: 
1.1.1.2 ! misho     315:      CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash
1.1       misho     316: 
                    317: `configure' Invocation
                    318: ======================
                    319: 
                    320:    `configure' recognizes the following options to control how it
                    321: operates.
                    322: 
                    323: `--help'
                    324: `-h'
                    325:      Print a summary of all of the options to `configure', and exit.
                    326: 
                    327: `--help=short'
                    328: `--help=recursive'
                    329:      Print a summary of the options unique to this package's
                    330:      `configure', and exit.  The `short' variant lists options used
                    331:      only in the top level, while the `recursive' variant lists options
                    332:      also present in any nested packages.
                    333: 
                    334: `--version'
                    335: `-V'
                    336:      Print the version of Autoconf used to generate the `configure'
                    337:      script, and exit.
                    338: 
                    339: `--cache-file=FILE'
                    340:      Enable the cache: use and save the results of the tests in FILE,
                    341:      traditionally `config.cache'.  FILE defaults to `/dev/null' to
                    342:      disable caching.
                    343: 
                    344: `--config-cache'
                    345: `-C'
                    346:      Alias for `--cache-file=config.cache'.
                    347: 
                    348: `--quiet'
                    349: `--silent'
                    350: `-q'
                    351:      Do not print messages saying which checks are being made.  To
                    352:      suppress all normal output, redirect it to `/dev/null' (any error
                    353:      messages will still be shown).
                    354: 
                    355: `--srcdir=DIR'
                    356:      Look for the package's source code in directory DIR.  Usually
                    357:      `configure' can determine that directory automatically.
                    358: 
                    359: `--prefix=DIR'
                    360:      Use DIR as the installation prefix.  *note Installation Names::
                    361:      for more details, including other options available for fine-tuning
                    362:      the installation locations.
                    363: 
                    364: `--no-create'
                    365: `-n'
                    366:      Run the configure checks, but stop before creating any output
                    367:      files.
                    368: 
                    369: `configure' also accepts some other, not widely useful, options.  Run
                    370: `configure --help' for more details.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>