.\"
.\" Copyright (c) 2007-2012 Hypertriton, Inc. <http://www.hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd JULY 19, 2007
.Dt MKCONFIGURE 1
.Os
.ds vT BSDBuild Reference
.ds oS BSDBuild 2.8
.Sh NAME
.Nm mkconfigure
.Nd Compile BSDBuild configure scripts
.Sh SYNOPSIS
.Nm mkconfigure
.Sh DESCRIPTION
The
.Nm
program reads a
.Pa configure.in
source from the standard input and outputs a valid Bourne configure script to
the standard output.
.Pp
The
.Pa configure.in
source can contain a number of special directives, along with Bourne shell
code fragments that will be copied verbatim to the configure script.
Long lines in the input script can be broken with end-of-line backslash
(\\) characters.
.Sh MKCONFIGURE DIRECTIVES
.Nm
directives are case-insensitive.
The following directives are recognized:
.Bl -tag -width "REQUIRE(package[,version[,prefix]]) "
.It Ev PACKAGE(name)
Short name for the software package.
.It Ev VERSION(string)
Specify software version.
.It Ev RELEASE(string)
Specify release name.
.It Ev CHECK(package[,version[,prefix]])
Invoke one of the standard BSDBuild tests (see the BSDBuild website for a list).
Most tests will set the
.Dv HAVE_FOO
(where
.Dv FOO
is the package name in upper-case) variable to indicate the results
of the test.
C/C++ libraries also typically set
.Dv FOO_CFLAGS
and
.Dv FOO_LIBS .
.Pp
If the optional
.Fa version
argument is specified, the version number is verified as well and
.Dv MK_VERSION_OK
is defined to
.Sq yes
if the versions are compatible.
A version argument of 0 indicates that no version checking should be done.
.Pp
If the optional
.Fa prefix
argument is defined, the test will look for the package only under the
specified prefix, and the test will fail if it cannot be found under it.
This is typically set to
.Sq ${prefix_foo},
which returns the value in
.Sq --enable-foo=VALUE
or
.Sq --with-foo=VALUE
options.
.It Ev REQUIRE(package[,version[,prefix]])
Same as the
.Ev CHECK
directive, except that the configure script will fail if the package is
either not found, or if the version is too old.
.It Ev TEST_DIR(path)
Specify an extra directory in which to search for BSDBuild test modules
(.pm files).
.It Ev REGISTER(name,descr)
Describe a configure script argument (for --help).
The
.Fa name
argument is usually of the form
.Ar --with-foo
or
.Ar --enable-foo ) ,
and
.Fa descr
is a description of the option (it is also customary to mention the default
value of this option in the description).
.It Ev REGISTER_SECTION(string)
Describe a section of configure script arguments (for --help).
.It Ev HDEFINE(opt,val)
Define a C preprocessor style header option.
.Fa opt
is an unquoted, usually upper-case string and
.Fa val
is a string enclosed in double quotes.
For example, if
.Fa opt
is
.Sq ENABLE_FOO ,
a file
.Pa config/enable_foo.h
will be generated by configure.
.It Ev HDEFINE_UNQUOTED(opt,val)
Same as
.Ev HDEFINE() ,
except that the value is left unquoted.
.It Ev HUNDEF(opt)
Similar to
.Ev HDEFINE ,
except that
.Pa config/<option>.h
will contain an #undef directive.
.It Ev MDEFINE(opt,val)
Define a
.Xr make 1
variable, which will be visible in the project's makefiles.
.Fa opt
is again an unquoted, usually upper-case string and
.Fa val
is a value enclosed in double quotes.
.It Ev MAPPEND(opt,val)
Same effect as
.Ev MDEFINE() ,
except that the value is appended to the variable (following a space).
.It Ev C_DEFINE(opt)
(C-style compilers only) Specify a global define that will be passed to
the compiler.
This results in the
.Ar -DFOO
flag being used in compiler command lines, but it is also interpreted by
.Xr build.proj.mk 5 .
.It Ev C_INCDIR(dir)
(C-style compilers only) Specify a directory for include files.
This results in the
.Ar -Idir
flag being added to the compiler command line, but it is also interpreted
by
.Xr build.proj.mk 5 .
.It Ev C_INCDIR_CONFIG(dir)
(C-style compilers only) Specify a target directory for individual include
files with configure-script generated statements (i.e.,
.Dv HAVE_FOO
is written to
.Pa have_foo.h
in the specified directory).
Pass an empty argument to disable.
By default,
.Pa ./config
is used.
This directive should be only called once, and may be placed anywhere in
configure.in.
.It Ev C_INCLUDE_CONFIG(file)
(C-style compilers only) Specify a monolithic C include file which will
contain configure-script generated statements (i.e.,
.Dv HAVE_FOO
defines).
Pass an empty argument to disable (default).
This directive should be only called once, and may be placed anywhere in
configure.in.
.It Ev C_INCPREP(dir)
(C-style compilers only) Specify absolute path to directory which will
contain include files.
The configure script provides the user with the option of either generating
preprocessed header files into this directory (--includes=yes, the default),
or create a set of symbolic links to the original include files in the
source directory (--includes=link).
.It Ev C_OPTION
Provide a gcc-style compiler option, such as
.Ar -Wall ,
.Ar -Werror
or
.Ar -Wmissing-prototypes .
For environments using other compilers, BSDBuild will attempt to set
equivalent options.
.It Ev LD_OPTION
Provide a ld-style linker option, such as
.Ar -g
or
.Ar -nostdlib .
.It Ev C_EXTRA_WARNINGS
Request extra compiler warnings.
The exact meaning is compiler specific.
.It Ev C_FATAL_WARNINGS
Request that compilation fail if warnings are encountered.
.It Ev CONFIG_SCRIPT(name[,args])
Generate a standard "foo-config" script.
.Fa name
specifies the name of the script.
For C/C++ style packages, the arguments are usually the
.Sq --cflags
output, followed by the
.Sq --libs
output.
.It Ev CONFIG_CACHE(yes|no)
Enable support for caching of test results (./configure --cache option).
By default, caching is disabled.
.It Ev CONFIG_GUESS(path)
Specify an alternate path to
.Pa config.guess
(default is
.Pa mk/config.guess ) .
.It Ev CHECK_HEADER(header[, ...])
Check whether one or more header files are available under the current
C/C++ compiler settings.
If a header file such as
.Pa sys/foo.h
is found,
.Dv HAVE_SYS_FOO_H
is defined.
.It Ev CHECK_HEADER_OPTS(cflags, libs, header[, ...])
Same as
.Ev CHECK_HEADER() ,
except that the headers are tested using the provided CFLAGS and LIBS.
.It Ev CHECK_FUNC(foofunction[, ...])
Check for the existence of one or more functions.
If a function
.Fn foofunction
is found,
.Dv HAVE_FUNCTION_NAME
is defined.
.It Ev CHECK_FUNC_OPTS(cflags, libs, foofunction[, ...])
Same as
.Ev CHECK_FUNCTION() ,
except that the function is tested using the provided CFLAGS and LIBS.
.It Ev CHECK_PERL_MODULE(modulename)
Check that the specified Perl module is installed and functioning.
For example, if
.Fa modulename
is "Time::Zone", the macro will set the variable "HAVE_TIME_ZONE"
accordingly.
.It Ev REQUIRE_PERL_MODULE(modulename)
Same as
.Ev CHECK_PERL_MODULE ,
except that the configure script will abort if the module is not found.
.It Ev DEFAULT_DIR(dirname, path)
Override one of the standard installation path defaults.
The
.Fa dirname
argument may be one of: PREFIX, BINDIR, LIBDIR, LIBEXECDIR,
DATADIR, STATEDIR, SYSCONFDIR, LOCALEDIR or MANDIR.
.El
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.Sh SEE ALSO
.Xr build.common.mk 5 ,
.Xr build.lib.mk 5 ,
.Xr build.prog.mk 5
.Pp
http://hypertriton.com/bsdbuild/