.\"
.\" Copyright (c) 2007-2024 Julien Nadeau Carriere <vedge@csoft.net>
.\" 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 March 1, 2024
.Dt MKCONFIGURE 1
.Os BSDBuild 3.2
.Sh NAME
.Nm mkconfigure
.Nd Compile BSDBuild configure scripts
.Sh SYNOPSIS
.Nm
.Op Fl \-verbose
.Op Fl \-output-lua Ns = Ns Ar file
.Op Fl \-output-cmake Ns = Ns Ar file
.Sh DESCRIPTION
The
.Nm
program reads a BSDBuild
.Pa configure.in
source from the standard input and produces a portable Bourne configure script.
.Pp
The
.Pa configure.in
source may include valid Bourne shell script, along with special directives
interpreted by
.Nm .
.Pp
Directives are case-insensitive.
Long lines can be wrapped with a terminating \\ character.
.Sh COMMAND-LINE OPTIONS
The
.Fl \-verbose
option prints extra debugging output during the generation of the script.
.Pp
The
.Fl \-output-lua
option arranges for the configure script to write definitions in the Lua language
to the given output
.Fa file .
Lua definitions are used when generating project files with the Premake method
(deprecated).
.Pp
The
.Fl \-output-cmake
option arranges for a Cmake macro package to be generated under the given output
.Fa file .
The Cmake macro package will include macros named "Check_Foo" and
"Disable_Foo" for every BSDBuild test which supports Cmake.
.Sh INFORMATION DIRECTIVES
The following directives provide information about the package:
.Bl -tag -width "register_env_var(name, desc) "
.It Fn package "name"
Short name for the package.
Included in generated messages and comments.
.It Fn version "string"
Specify current package version.
.It Fn release "string"
Specify a release codename.
.It Fn register "name, desc"
Describe a configure script argument to show in ./configure --help.
.Fa name
is the name of the
.Xr getopt_long 3
style argument (e.g.,
.Ar --with-foo ,
.Ar --enable-foo )
and
.Fa desc
is a one-line description.
.It Fn register_env_var "name, desc"
Describe an influential environment variable to show in ./configure --help.
.Fa name
is the name of the environment variable and
.Fa desc
is a one-line description.
.It Fn register_section "text"
Provide a title for a section of arguments in ./configure --help.
.El
.Sh CONFIGURE SCRIPT DIRECTIVES
The following directives alter the operation of the configure script.
.Bl -tag -width "default_dir(dirname, path) "
.It Fn config_cache "bool"
Enable support for caching of test results (./configure --cache option).
Set to "yes" (enable caching) or "no" (the default).
.It Fn config_guess "path"
Specify an alternate path to
.Pa config.guess
(default is
.Pa mk/config.guess ) .
.It Fn success_fn "fname"
Instead of printing the default "Configuration successful" message at the
end of the script, run the indicated Bourne shell function
.Fa fname
instead.
.El
.Sh DEFINITION OUTPUT DIRECTIVES
The following directives generate
.Xr make 1
definitions as well as definitions accessible from C / C++.
.Bl -tag -width "default_dir(dirname, path) "
.It Fn mappend "opt, val"
Append a space and
.Fa val
to the exported
.Xr make 1
variable
.Fa opt .
.It Fn mdefine "opt, val"
Define an exported
.Xr make 1
variable
.Fa opt
with value
.Fa val .
.It Fn default_dir "dirname, path"
Override one of the standard installation path defaults.
.Fa dirname
may be one of: PREFIX, BINDIR, LIBDIR, LIBEXECDIR,
DATADIR, STATEDIR, SYSCONFDIR, LOCALEDIR or MANDIR.
The
.Fa path
argument may include variable references such as "${PREFIX}".
.It Fn hdefine "opt, val"
Define a C preprocessor style header option.
.Fa opt
is an unquoted string (uppercase by convention), and the value
.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 Fn hdefine_unquoted "opt, val"
Variant of
.Fn hdefine
which keeps
.Fa val
unquoted instead of interpreting it as a string.
.It Fn hdefine_if "condition, opt"
If
.Fa condition
evaluates true, then generate a define with
.Fn hdefine "opt"
otherwise call
.Fn hundef "opt" .
to generate an #undef.
.It Fn hundef "opt"
Write an #undef directive to
which writes an #undef directive to
.Pa config/<option>.h
(the opposite of
.Fn hdefine ) .
.It Fn hundef_if "condition, opt"
If
.Fa condition
evaluates true, then call
.Fn hundef "opt" .
.El
.Sh BSDBUILD MODULE DIRECTIVES
The following directives invoke installed BSDBuild test modules.
Modules generate Bourne script for performing tests and returning results
as variables.
For instance, a test for a package "foo" would set variable
.Dv HAVE_FOO
to "yes" or "no" and return detected compilation flags under
.Dv FOO_CFLAGS
and
.Dv FOO_LIBS .
.Pp
.Bl -tag -width "REQUIRE(pkg[,ver[,pfx]]) "
.It Fn check "pkg[,ver[,pfx]]"
Invoke the BSDBuild module called
.Fa pkg .
A
.Pa <pkg>.pm
module file should exist under
.Pa ${PREFIX}/share/bsdbuild/BSDBuild/ .
.Pp
If
.Fa ver
is given and non-zero, check the version and set
.Dv MK_VERSION_OK
to "yes" if the installed version is compatible with
.Fa ver .
.Pp
If
.Fa pfx
is given, look under that installation prefix (and fail if it is not installed
there).
Typically, the value "${prefix_foo}" (from user-given
.Sq --enable-foo=VALUE
or
.Sq --with-foo=VALUE )
is used here.
.It Fn require "pkg[,ver[,pfx]]"
Variant of
.Fn check
which implicitely terminates the script with an error message if
.Fa pkg
is not found or the
.Fa ver
is incompatible.
.It Fn disable "pkg"
Short-circuit a test module.
Emit the defines that would have resulted from a failed test, without
actually running any tests.
.It Fn test_dir "path"
Specify an extra directory in which to search for BSDBuild test modules
(.pm files).
The default module path is
.Pa ${PREFIX}/share/bsdbuild/BSDBuild/ .
.El
.Sh ADA LANGUAGE DIRECTIVES
The following directives deal with Ada code compilation.
.Bl -tag -width "ADA_OPTION(option) "
.It Fn ada_option "option"
Append an option to the
.Dv ADAFLAGS
which will be passed to the Ada compiler.
.It Fn ada_bflag "option"
Append an option to the
.Dv ADABFLAGS
which will be passed to the Ada binder.
.El
.Sh C/C++ LANGUAGE DIRECTIVES
The following directives apply to C, C++ and other C-like languages.
.Bl -tag -width "CHECK_HEADER(name[, ...]) "
.It Fn c_define "optname"
Specify a C preprocessor definition.
For example, an
.Fa optname
of "FOO" would result in the
.Ar -DFOO
flag being passed to the C compiler.
.It Fn cxx_define "optname"
Specify a C++ preprocessor definition.
For example, an
.Fa optname
of "FOO" would result in the
.Ar -DFOO
flag being passed to the C++ compiler.
.It Fn c_incdir "dir"
Specify a directory containing C include files.
For example, if
.Fa dir
is
.Pa /usr/include
then the
.Ar -I/usr/include
option would be passed to the C preprocessor.
.It Fn cxx_incdir "dir"
Specify a directory containing C++ include files.
For example, if
.Fa dir
is
.Pa /usr/include
then the
.Ar -I/usr/include
option would be passed to the C++ preprocessor.
.It Fn c_incdir_config "dir"
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.
.It Fn c_include_config "file"
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).
.It Fn c_incprep "dir"
Specify a target directory for preprocessed C header files.
The ./configure option
.Sq --includes
is a BSDBuild extension which gives the user the option of either generating
preprocessed headers in the working directory ("--includes=yes", the default)
or alternatively, to create a set of symbolic links to the original headers
in the source directory ("--includes=link").
.It Fn c_option "option"
Pass a general command-line option to the C compiler.
.It Fn cxx_option "option"
Pass a general command-line option to the C++ compiler.
.It Fn check_c_func "fn[, ...]"
Check for the existence of one or more C functions.
If a function
.Fa fn
called
.Fn foo
exists, then
.Dv HAVE_FUNCTION_FOO
will be set.
.It Fn check_cxx_func "fn[, ...]"
Check for the existence of one or more C++ functions.
If a function
.Fa fn
called
.Fn foo
exists, then
.Dv HAVE_FUNCTION_FOO
will be set.
.It Fn check_c_func_opts "cflags, libs, fn[, ...]"
Variant of
.Fn check_c_func
with additional
.Ev CFLAGS
and
.Ev LIBS .
.It Fn check_cxx_func_opts "cxxflags, libs, fn[, ...]"
Variant of
.Fn check_cxx_func
with additional
.Ev CXXFLAGS
and
.Ev LIBS .
.It Fn check_c_header "name[, ...]"
Check for the existence of one or more C header files.
For example, if 
.Pa sys/foo.h
exists then
.Dv HAVE_SYS_FOO_H
will be set.
.It Fn check_cxx_header "name[, ...]"
Check for the existence of one or more C++ header files.
For example, if 
.Pa sys/foo.h
exists then
.Dv HAVE_SYS_FOO_H
will be set.
.It Fn check_c_header_opts "cflags, libs, header[, ...]"
Variant of
.Fn check_c_header
with additional
.Ev CFLAGS
and
.Ev LIBS .
.It Fn check_cxx_header_opts "cflags, libs, header[, ...]"
Variant of
.Fn check_cxx_header
with additional
.Ev CXXFLAGS
and
.Ev LIBS .
.It Fn ld_option "option"
Provide a ld-style linker option, such as
.Ar -g
or
.Ar -nostdlib .
.El
.Sh PERL LANGUAGE DIRECTIVES
The following directives deal with the installation of Perl modules.
.Bl -tag -width "REQUIRE_PERL_MODULE(mod) "
.It Fn check_perl_module "mod"
Check that the specified Perl module is installed and functioning.
For example, if
.Fa mod
is "Time::Zone", the macro will set the variable "HAVE_TIME_ZONE"
accordingly.
.It Fn require_perl_module "mod"
Variant of
.Fn check_perl_module
which aborts the configure script if the module is not found.
.El
.Sh CONFIGURATION OUTPUT DIRECTIVES
The following directives produce output scripts and modules for integration
by external packages.
.Bl -tag -width "CONFIG_SCRIPT(name[,args]) "
.It Fn 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 Fn pkgconfig_module "name, desc, req, confl, cflags, libs, pvtLibs"
Output a
.Xr pkgconf 1
compatible
.Xr pc 5
file to "name.pc" (which may be then installed into
.Dv PKGCONFIG_LIBDIR ) .
.Va desc
is the "Description" string,
.Va req
is the "Required" modules list (space-separated),
.Va confl
is the "Conflicts" list,
.Va cflags
is the "Cflags" field,
.Va libs
is Libs (for --libs) and
.Va pvtLibs
is Libs.private (for --static --libs).
.El
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.Sh SEE ALSO
.Xr build.common.mk 5 ,
.Xr build.lib.mk 5 ,
.Xr build.prog.mk 5
.Pp
.Lk https://bsdbuild.hypertriton.com/