ucw/doc/configure.txt

   1 How to Configure Sherlock libraries
   2 ===================================
   3
   4 What can be configured
   5 ----------------------
   6 There are two different levels of configuring/customizing program
   7 based on sherlock libraries:
   8
   9   - runtime configuration in configuration files (see <<config:>>)
  10
  11   - compile-time configuration of the libraries: config switches set
  12     before compiling, selecting optional features.
  13
  14 Where to build
  15 --------------
  16 If you run configure in the source directory, it prepares for compilation inside
  17 the source tree. In this case, an `obj` subdirectory is created to hold all generated
  18 files (object files, binaries, generated source files etc.) and all final files
  19 are linked to the `run` subdirectory. No other parts of the source tree are written into.
  20
  21 Alternatively, you can compile in a separate object tree (which is useful when you
  22 want to build several different configurations from a single source tree). In order
  23 to do that, switch to the destination directory and issue `<source-dir>/configure ...`.
  24 This way, configure will create the `obj` and `run` directories locally and set up
  25 a Makefile which refers to the original source tree.
  26
  27 How to configure
  28 ----------------
  29 To set up compilation, possibly overriding default compile-time
  30 options, just run:
  31
  32         ./configure [<option> | -<option> | <option>=<value> ...]
  33
  34 The default values of feature options are taken from `default.cfg`.
  35 Compiler flags and options dependent on compiler, OS and CPU type
  36 are set in `ucw/perl/UCW/Configure/C.pm`. Everything can be overriden by
  37 options specified on the configure's command line, which have the highest
  38 priority.
  39
  40 If you want to see the resulting set of options, take a look at
  41 `obj/config.mk`.
  42
  43 Options specifying compiler/linker/debugger options can be also overriden
  44 during compilation by `make <option>=<value>`. While it's also possible
  45 to specify the other options in this way, it probably won't have the desired
  46 effect, because configure also generates C include files containing the
  47 options.
  48
  49 Installation options
  50 --------------------
  51 By default, the package is compiled to be installed and it chooses a
  52 place where it will install. If you want to place it somewhere else,
  53 set the `PREFIX` option:
  54
  55         ./configure PREFIX=/where/to/install
  56
  57 [[local_build]]
  58 You can create a local compilation, which does not need to be
  59 installed. All paths are set relative to a `run` directory and
  60 programs expect to have current working directory set to it. However,
  61 you can move the `run` directory around your filesystem as you like.
  62 To compile it that way, turn on the `CONFIG_LOCAL` option (and do not
  63 set `PREFIX`):
  64
  65         ./configure CONFIG_LOCAL
  66
  67 Examples
  68 --------
  69   - `./configure -CONFIG_SHARED` will build the libraries statically.
  70   - `./configure -CONFIG_IMAGES` avoids building the image library.
  71   - `./configure CONFIG_UCW_ONLY -CONFIG_UCW_UTILS` compiles only the
  72     libucw library without its util programs.
  73   - `./configure CONFIG_XML PREFIX=$HOME/sherlock` includes a xml
  74     library and installs into your home directory.