Grecs README
Copyright (C) 2011-2025 Sergey Poznyakoff
See the end of file for copying conditions.

* Introduction

This file contains brief information about configuring, testing
and installing Grecs library. It is *not* intended as a replacement
for the documentation, and is provided as a brief reference only.
The complete documentation for Grecs is available in the
doc/ subdirectory, both as a set of manpages and as texinfo
documents. To access the latter without installing the package
run `info -f doc/grecs.info'. After the package is installed
the documentation can be accessed by running `info grecs'. 

An online copy of the documentation in various formats is available
at http://grecs.man.gnu.org.ua.

* Overview

Grecs is a library for parsing structured configuration files from
C programs. A structured configuration file has hierarchical
structure, with block statements enclosing lower-level
statements. Such configurations files are used by many programs, such
as, e.g. Bind or Dico.

Grecs provides primitives for parsing such files into an internal
tree-like structure and for basic operations on such structures. These
operations include value lookups by keyword paths, traversing trees
recursively, joining several trees together, reductions, etc.

* Usage

Grecs is primarily intended for use as a git submodule in a larger
project, although it can also be built as a standalone library.

** Submodule

The following instructions apply if you plan to use grecs as a
submodule in your project.

*** Adding a submodule

First, add grecs as a submodule.  From your top-level source
directory, do

  git submodule add git://git.gnu.org.ua/grecs.git grecs

You can use https://git.gnu.org.ua/grecs.git as the URL, if you
prefer.  The last argument specifies the name of the directory where
grecs sources will be located.  Obviously, you can select whatever
name and on whatever directory nesting level you find suitable.

*** Bootstrapping

Grecs comes with a number of additional parsers, supporting various
configuration file syntaxes.  Quite possibly you won't need all of
them.  To avoid bloating the hosting project with unused sources, the
library needs to be bootstrapped.  This step selects the necessary
optional components and creates several infrastructure files for use
by autoconf and automake.  From your top-level source directory, run

   ./grecs/bootstrap [COMPONENTS...]

(if you selected another directory name when adding the module, use it
instead of "grecs" in the above example).

Optional COMPONENT arguments to bootstrap specify the components you want
to include.  Valid names are:

  bind             Include parser for BIND configuration files.
  dhcpd            Include parser for DCHPD configuration files.
  getopt           Include legacy getopt code.  See "Command Line
                   Parsing", below.
  git              Include parser for git config format.
  json             Include parser for JSON format.
  meta1            Include parser for MeTA1 configuration files.
  sockaddr-list    Include code for managing lists of network
                   addresses.

Two meta-components can be used as shortcuts to select several
components.  To select all configuration file parsers, use
"all-parsers".  To select all optional components (except deprecated
"getopt"), specify "all".

Grecs library can be build in three distinct ways, called "build
types".  First, "static" build type means that the static library
libgrecs.a is built.  This is the default if Grecs is used as a git
submodule.  It can also be requested explicitly, using the "-t static"
option.

Another build type can be requested by the "-t shared" option.  In
this build, a shared convenience (i.e. non-installable) library is
built using libtool.  The library name is libgrecs.la.

Finally, libgrecs can be built as a regular installable library.  This
is requested using the "-t install" option.  This is the default if
bootstrap determines that grecs is not a submodule of another project.

Normally, bootstrap works silently.  If you wish to see its progress,
use the -v option.

Upon successful termination, bootstrap prints a short instruction on
further steps.  These are covered below.

*** Modifying autoconf files

After bootstrapping, modify your configure.ac file.  You will need to
add two lines:

   AC_CONFIG_MACRO_DIR([grecs/am])
   GRECS_SETUP()

The first line tells autoconf where it can find Grecs Autoconf macros.
The second one initializes various autoconf variables and creates
Makefile.in files.  It can take one or more arguments indicating
optional features to compile:

  no-preproc
     Disable the use of preprocessor.

     By default, Grecs preprocesses its configuration files using
     m4(1).  Specifying this option disables it.
     
  pp-setup[=FILE]
     Install a preprocessor setup file.
     
     Grecs comes with a file pp-setup which contains various
     initializations for m4(1).  By supplying this option, you
     instruct Grecs to install this file to the directory

           $(pkgdatadir)/$(VERSION)/include

     where $(pkgdatadir) is the package data directory, selected when
     running configure (by default, /usr/local/share/PROJECT, where
     PROJECT is your project name), and $(VERSION) is the version
     number of your project.

     If FILE is supplied, it will be used instead of pp-setup.

  pp-setup-option
     Add the --with-pp-setup-file option to the configuration file.

     This option allows user to select at compile time, whether to
     install the preprocessor setup file.

  tests
     Build the testsuite.

     To start the Grecs testsuite, run "make check" in its directory,
     or in the superproject top-level directory.
     
  git2chg
     Add git2chg.awk to the distribution.

     This is a simple AWK program that converts git log to GNU
     ChangeLog format.

  syntax-doc
     Add the file doc/grecs-syntax.texi to the distribution.

     This is useful if the supeproject documentation is written in
     Texinfo.  You can "@include doc/grecs-syntax.texi" to your
     documentation in a convenient place to provide a detailed
     discussion of the configuration file syntax.
     
  install-headers
     Install Grecs headers to GRECS_INCLUDE_DIR.  This option is valid
     only in "shared" build type.
     
  tree-api
     Use new calling sequence of callback functions.

     In the new calling sequence, each callback receives a pointer to
     grecs_node_t as an argument, instead of two pointers to the value
     and locus.

*** Modifying Makefile.am

In your Makefile.am, add @GRECS_INCLUDES@ (or $(GRECS_INCLUDES))
to the AM_CPPFLAGS value, and @GRECS_LDADD@ (or $(GRECS_LDADD))
to LDADD, e.g.:

   AM_CPPFLAGS = @GRECS_INCLUDES@
   LDADD = @GRECS_LDADD@

*** Include grecs.h

Add

  #include <grecs.h>

to source files that call Grecs functions.  Depending on the
additional feature you have selected, you may need to include other
files.  In particular, if you enables json parser, add this to
access JSON structure definitions and function prototypes:

  #include <grecs/jsonparse.h>

* Command Line Parsing

Historically, Grecs included support for writing command line parsers
in a domain-specific language designed for that purpose.  Such files
would be processed by m4, which would create C sources that could
finally be included to your program.  This approach has been
discontinued and is not included to the library by default.  Projects
that still rely on it, can use the "getopt" option to GRECS_SETUP in
order to include the corresponding code.  Otherwise, we suggest to use
the following module:

  https://git.gnu.org.ua/parseopt.git

* Bug reporting.		

Send bug reports to <gray@gnu.org.ua>. 


* Copyright information:

Copyright (C) 2011-2025 Sergey Poznyakoff

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.

Local Variables:
mode: outline
paragraph-separate: "[ 	]*$"
version-control: never
End:
