+++ /dev/null
-Configuration files
-===================
-
-This document describes the language of the run-time configuration
-files, which are parsed by libucw. For compile-time configuration,
-see doc/configure.
-
-Terminology :
--------------
-
-Configuration items are organized into sections. The sections form a tree
-structure with top-level sections corresponding to program modules.
-
-Each configuration item belongs to one of the following classes:
-
- 1. single value or a fixed-length array of values
- 2. variable-length array of values
- 3. subsection with several nested attributes
- 4. list of nodes, each being an instance of a subsection
- 5. bitmap of small integers (0..31) or fixed list of strings
- 6. exceptions (items with irregular syntax; however, they always
- appear as a sequence of strings, only the semantics differ)
-
-Both fixed- and variable-length arrays consist of items of the same
-type. The basic types supported by the configuration mechanism are:
-
- 1. 32-bit integer
- 2. 64-bit integer
- 3. floating point number
- 4. IP address
- 5. string
- 6. choice (one of a fixed list of strings)
-
-Program modules can define their own special types (such as network
-masks or attribute names) and decide how are they parsed.
-
-Format of configuration files :
--------------------------------
-
-Configuration files are text files that usually set one attribute per
-line, though it is possible to split one assignment into multiple lines
-and/or assign several attributes in one line. The basic format of an
-assignment command is
-
- name value1 value2 ... valueN
-
-or
-
- name=value1 value2 ... valueN
-
-The end of line means also end of a command unless it is preceded by a
-backslash. On the other hand, a semicolon terminates the command and
-another command can start after the semicolon. A hash starts a comment
-that lasts until the end of the line. A value can be enclosed in
-apostrophes or quotation marks and then it can contain spaces and/or
-control characters, otherwise the first space or control character
-denotes the end of the value. Values enclosed in quotation marks are
-interpreted as C-strings. For example, the following are valid
-assignment commands:
-
- Database "main db\x2b"; Directory='index/'; Weights 100 20 30 \
- 40 50 80 # a comment that is ignored
-
-Numerical values can be succeeded by a unit. The following units are
-supported:
-
- d=86400 k=1000 K=1024
- h=3600 m=1000000 M=1048576
- %=0.01 g=1000000000 G=1073741824
-
-Attributes of a section or a list node can be set in two ways. First,
-you can write the name of the section or list, open a bracket, and then
-set the attributes inside the section. For example,
-
- Section1 {
- Attr1 value1
- Attr2 value2
- ListNode { #creates a list and adds its first node
- Attr3 value3
- Attr4 value4
- }
- ListNode { Attr3=value5; Attr4=value6 }
- #appends a new node; this is still the same syntax
- }
-
-The second possibility is using a shorter syntax when all attributes of a
-section are set on one line in a fixed order. The above example could
-be as well written as
-
- Section1 {
- Attr1 value1
- Attr2 value2
- ListNode value3 value4
- ListNode value5 value6
- }
-
-Of course, you cannot use the latter syntax when the attributes allow
-variable numbers of parameters. The parser of the configuration files
-checks this possibility.
-
-If you want to set a single attribute in some section, you can also
-refer to the attribute as Section.Attribute.
-
-Lists support several operations besides adding a new node. You just
-have to write a colon immediately after the attribute name, followed by
-the name of the operation. The following operations are supported:
-
- List:clear # removes all nodes
- List:append { attr1=value1; ... } # adds a new node at the end
- List:prepend { attr1=value1; ... } # adds a new node at the beginning
- List:remove { attr1=search1 } # find a node and delete it
- List:edit { attr1=search1 } { attr1=value1; ... }
- # find a node and edit it
- List:after { attr1=search1 } { ... } # insert a node after a found node
- List:before { attr1=search1 } { ... } # insert a node before a found node
- List:copy { attr1=search1 } { ... } # duplicate a node and edit the copy
-
-You can specify several attributes in the search condition and the nodes
-are tested for equality in all these attributes. In the editing
-commands, you can either open a second block with overridden attributes,
-or specify the new values using the shorter one-line syntax.
-
-The commands :clear, :append, and :prepend are also supported by var-length
-arrays. The command :clear can also be used on string values. The following
-operations can be used on bitmaps: :set, :remove, :clear, and :all.
-
-Configuration files :
----------------------
-
-The default configuration file is stored in cf/sherlock and it uses
-the include directive to load nested configuration files:
-
- include another/file
-
-(Beware that this command has to be the last one on the line.)
-
-If you want to modify the configuration, the preferred form is by editing
-the file cf/local, which is included at the end of cf/sherlock, so you
-can override anything there.
-
-Command-line parameters :
--------------------------
-
-The default configuration file (cf_def_file possibly overriden
-by environment variable cf_env_file) is read before the program is started.
-You can use a -C option to override the name of the configuration file.
-If you use this parameter several times, then all those files are loaded
-consecutively. A parameter -S can be used to execute a configuration
-command directly (after loading the default or specified configuration
-file). Example:
-
- bin/program -Ccf/my-config -S'module.trace=2;module.logfile:clear' ...
-
-If the program is compiled with debugging information, then one more
-parameter --dumpconfig is supported. It prints all parsed configuration
-items and exits.
-
-All these switches must be used before any other parameters of the
-program.
-
-Preprocessing :
----------------
-
-During compilation, all configuration files are pre-processed by a simple
-C-like preprocessor, which supports #ifdef, #ifndef, #if, #elsif, #else and #endif
-directives referring to compile-time configuration variables. #if and #elsif
-can contain any Perl expression where each CONFIG_xyz configuration variable
-is substituted to 0 or 1 depending on its value.
-
-The preprocessor also substitutes `@VARIABLE@' by the value of the variable,
-which must be defined.
-
-Caveats :
----------
-
-Trying to access an unknown attribute causes an error, but unrecognized
-top-level sections are ignored. The reason is that a common config file
-is used for a lot of programs which recognize only their own sections.
-
-Names of sections, attributes and choices are case-insensitive. Units are
-case-sensitive.
+++ /dev/null
-How to Configure Sherlock FIXME: update for stand-alone libucw
-*************************
-
-1. What can be configured
-~~~~~~~~~~~~~~~~~~~~~~~~~
-There are three different levels of configuring/customizing Sherlock:
-
- - runtime configuration in cf/sherlock and cf/local (see doc/config)
-
- - compile-time configuration: config switches set before compiling, selecting
- optional features (see sherlock/default.cfg)
-
- - customization: a set of C declarations and functions, which define word
- types, attributes and the ways to match them. In most cases, you should
- use the "free" customization designed for searching in web pages and similar
- documents. If you want just a simple search engine for indexing databases,
- the "customs/bare" customization can be better. If you want to extend Sherlock
- beyond that, you will probably need to write your own customization -- just
- follow the structure of the "free" customization and the comments there.
-
-
-2. How to configure
-~~~~~~~~~~~~~~~~~~~
-To set up compilation for a given customization, possibly overriding its default
-compile-time options, just run
-
- ./configure <customization> [<option> | -<option> | <option>=<value> ...]
-
-The default values of feature options are taken from sherlock/default.cfg and modified
-by <customization>/config. Compiler flags and options dependent on compiler, OS and
-CPU type are set in ucw/perl/UCW/Configure/C.pm. Everything can be overriden by options specified
-on the configure's command line, which have the highest priority.
-
-If you want to see the resulting set of options, take a look at obj/config.mk.
-
-Options specifying compiler/linker/debugger options can be also overriden during
-compilation by `make <option>=<value>'. While it's also possible to specify the other
-options in this way, it probably won't have the desired effect, because configure
-also generates C include files containing the options.
-
-
-3. Where to build
-~~~~~~~~~~~~~~~~~
-If you run configure in the source directory, it prepares for compilation inside
-the source tree. In this case, an `obj' subdirectory is created to hold all generated
-files (object files, binaries, generated source files etc.) and all final files
-are linked to the `run' subdirectory. No other parts of the source tree are written into.
-
-Alternatively, you can compile in a separate object tree (which is useful when you
-want to build several different configurations from a single source tree). In order
-to do that, switch to the destination directory and issue `<source-dir>/configure ...'.
-This way, configure will create the `obj' and `run' directories locally and set up
-a Makefile which refers to the original source tree.
projects / libucw.git / commitdiff