<!--  vim: set sw=2 sts=2 et ft=docbk:

  Part of the A-A-P recipe executive: automatic configuration

  Copyright (C) 2002-2003 Stichting NLnet Labs
  Permission to copy and use this file is specified in the file COPYING.
  If this file is missing you can find it here: http://www.a-a-p.org/COPYING

-->

<para>
  The <link linkend="cmd-conf">:conf</link> command is used to discover
  properties of the compiler and the system.  With this information a program
  can be compiled to work on many different systems without the user to
  manually specify the properties.
  For Unix systems an alternative is using Autoconf, see
  <xref linkend="user-autoconf"/>.
</para>

<para>
  TODO  The ":conf" command is still under development.
</para>

<programlisting>

  :conf init        Clean the configuration environment.  Only needed when
                    configure checks were done before.

  :conf language lang
                    Use "lang" as the language for tests that do not have a
                    {language} attribute.
                    Only "C" and "C++" are currently supported. "C" is the
                    default.
                    A test will be done if the compiler for the language
                    works.  If not all tests for the language will fail.
                    Example:
                           :conf language C++

  :conf header [mainoptions] headername [itemoptions] ...
                    Check for C or C++ header file(s) "headername".
                    Uses current value of INCLUDE.
                    Defines HAVE_headername if "headername" is available.
                    mainptions:
                        oneof        first of the items that works is used, at
                                     least one is required
                        required     all items are required to exist
                    itemoptions:
                        header       text included in the test program
                        language     C or C++
                    Examples:
                        :conf header X11/Shell.h
                        :conf header {oneof} sys/time.h times.h

  :conf function [mainoptions] functionname [itemoptions] ...
                    Check for C or C++ function(s) "functionname".
                    Uses the current value of $LIBS.
                    Defines HAVE_functionname if "functionname" is available.
                    Options: see ":conf header"
                    Example:
                        :conf function bcopy

  :conf type [mainoptions] typename [itemoptions] ...
                    Check for C or C++ type(s) "typename".
                    Uses the current value of $LIBS.
                    Defines HAVE_typename if type "typename" is available.
                    Options: see ":conf header".
                    Additional itemoption:
                        fallback     type definition to use for the type when
                                     it is not available
                    Example:
                           :conf type size_t {fallback = unsigned long}

  :conf lib [mainoptions] libname,funcname [itemoptions] ...
                    Check for library/libraries by testing if "funcname"
                    exists when using the "libname" library.
                    Uses the current value of $LIBS and appends "-llibname"
                    if the test succeeds.  Also appends to $_conf.LIBS.
                    Defines HAVE_libname if library "libname" is available.
                    Options: see ":conf header".
                    Example:
                           :conf lib iconv,iconv_open

  :conf write header filename
                    Write the HAVE_ and other symbols collected so far into
                    "filename".
                    Example:
                           :conf write header $BDIR/config.h

  :conf write recipe filename
                    Write the settings in the _conf scope into "filename".
                    Example:
                           :conf write recipe $BDIR/config.aap


The _conf scope stores variables set by configure tests.  For example,
$_conf.LIBS the libraries that ":conf lib" found.  The _conf scope is used in
the tree of scopes just before the toplevel scope, after all callstack and
recipe tree scopes.

Special characters in header, function and type names are changed to an
underscore before defining the HAVE_ symbol.  Lowercase characters are changed
to uppercase.

The preprocessor symbols that are gathered from the tests are available in
the $_conf.have dictionary.  Example:
  	:conf header sys/time.h
	@if _conf.have["HAVE_SYS_TIME_H"]:
	   :print we have time
	@else:
	   :print sorry, no time.

":conf write recipe" writes the variables in the _conf scope.  You can remove
variables you do not want to be written.  Example:
  	saveLIBS = $?_conf.LIBS
	_conf.LIBS =
	:conf lib foo,foobar
	_conf.FOOLIB = $_conf.LIBS
	_conf.LIBS = $saveLIBS

</programlisting>
