mkconfig Manual Page

[ di - disk information utility ] [ mkconfig - build configuration utility ]

[ mkconfig manual ] [ mkconfig_c manual ] [ mkconfig_d manual ]

Name
mkconfig - build configuration utilities

Synopsis
mkconfig.sh [-C] [-c ] [-L ] [-o ]
config-file

The -C option clears any cache file before processing the units.

cache-file defaults to 'mkconfig.cache'.

log-file defaults to 'mkconfig.log'.

option-file defaults to 'options.dat'.

config-file is a file containing a list of mkconfig directives.

runtests.sh tests-dir [test1, ...]

tests-dir is a directory containing test scripts.

The tests to be run may be specified on the command line.

mkc.sh -reqlib [-c ] [-o ] input-file

cache-file defaults to 'mkconfig.cache'.

output-file defaults to 'mkconfig.reqlibs'.

input-file is the C/C++ output-file created by mkconfig.sh.

mkc.sh -setopt [-o ] option value

option-file defaults to 'options.dat'.

mkc.sh -staticlib [-e] lib-name object-file [...]

The -e option echos the command line.

mkc.sh -sharedlib [-e] lib-name object-file [...] [-L lib-path ...] [-l
lib ...]

The -e option echos the command line.

mkc.sh -complink -c [-e] [-o |-o ] [-r
required-lib-file] -- [ ...] [ ...] [ ...] [-L ] [-l ]

The -e option echos the command line.

Description
mkconfig.sh is a build configuration utility. It is written in porta‐
ble shell script and designed to be extensible for any configuration
use. Most Bourne Shell compatible shells will work.

mkconfig.sh is intended to generate a file that can be used as an
included file, a shell script, a configuration file, or any other use.
If the _MKCONFIG_SHELL environment variable is set to a particular
shell, mkconfig.sh will restart itself using that shell.

runtests.sh is a simple test harness for mkconfig. It is intended as a
simple, portable test harness. There are better test harnesses avail‐
able.

mkc.sh -setopt is used to change the value of the options in the option
file.

mkc.sh -complink compiles to an executable or object file given source
or object files, compiler options, link options and a list of library
paths and libraries.

mkc.sh -reqlib is used in conjunction with the c-main language unit or
d-main language unit to output the libraries required for linking. See
the description for the 'lib' check routine for the c-main language
unit.

mkc.sh -link

mkc.sh -staticlib creates a static library given a library name and a
list of object files.

mkc.sh -sharedlib creates a shared library given a library name, a list
of object files, a list of library paths and libraries.

Basic Directives (mkconfig.sh)
# comment
Comments begin with a '#' in column 1. Blank lines are ignored.

output file-name (required)
Specify the name of the output file. This command may be
included multiple times in the mkconfig configuration file to
output multiple files.

option-file file-name
Specify the name of the options file. The options file can also
be specified on the command line with the -o option.

loadunit unit-name
Include a mkconfig unit for testing. Units include specific
check routines that may be performed.

command name-of-command [alternate-cmd...]
Check if command exists in the path. When listing alternate
commands, specify the list from least wanted to best.

e.g.
command awk nawk gawk
command sed
Output:
#define _command_sed 1 /* C */
#define _cmd_loc_sed "/bin/sed" /* C */
enum bool _command_sed = true; /* D */
enum string _cmd_loc_sed = "/bin/sed"; /* D */

grep tag pattern filename
Searches filename for pattern. tag is used for naming and dis‐
play purposes.

e.g.
grep mysearch root /etc/passwd
Output:
#define _grep_mysearch 1 /* C */
enum bool _grep_mysearch = true; /* D */

ifoption option-name ... [else ...] endif

ifnotoption option-name ... [else ...] endif
The ifoption and ifnotoption statements check the options set in
the options file and process the appropriate block of state‐
ments.

If there is no options file, or the option does not exist, both
ifoption and ifnotoption will return a false return.

The ifoption, ifnotoption and if statements may be nested.

if label if-statement ... [else ...] endif
The if statement is a combination of check variables, &&, ||, !
(not) and parentheses. It is recommended that parentheses be
used copiously to avoid any possible precedence differences
between different shells. The label is used for display output.

The equality operator is supported in prefix notation as:

if label == check-variable value

The value may be enclosed in quotes, but preservation of extra
spaces will not work.

e.g.
if mylabel _hdr_header1 && ( ! (_lib_func3 || _lib_func4)) && _setint_my_var
...
endif
if quotactl_pos_1 == _c_arg_1_quotactl 'char *'
...
endif

The ifoption, ifnotoption and if statements may be nested.

include endinclude
Include all of the code between these two tags in the output
file. Backslashes must be escaped with a backslash. Note that
the included text is only output at the end of the output-file,
not inline with the directive output.

option option-name default-value
Set option-name specified to default-value. The option-file is
checked for option-name, and if present, the value in the
option-file is used.

For use in if statements, the check variable is named
_opt_option-name.

set check-variable value
Set a check-variable to value.

e.g.
lib quotactl
set _lib_quotactl 0

setint check-variable-name value
Set an integer variable to a value. The check variable name
will be output as specified, but when used in if statements, the
check variable is named _setint_.

e.g.
setint _enable_nls 1

setstr check-variable-name value
Set a string variable to a value. The check variable name will
be output as specified, but when used in if statements, the
check variable is named _setstr_.

e.g.
setstr _my_lib_path /lib

standard
Perform any standard checks for the unit that was loaded. See
the description of the other units to see what the standard
check does.

substitute pattern1 pattern2
Substitute pattern2 for pattern1. pattern1 and pattern2 are
passed to 'sed' and may be regular expressions. Using back‐
slashes in the patterns may be problematical due to quoting by
the executing shell.

The substitute directive is not available with the perl version
of mkconfig.

Environment Units
The environment units create an output file that can be used as shell
script input to set your environment.

See mkconfig_env(7).

C Language Units
The C language units create an include file for C programs.

See mkconfig_c(7).

D Language Units
The D language units create an import file for D programs.

See mkconfig_d(7).

Tests (runtests.sh)
The test directory contains shell scripts that are executed by
runtests.sh. If a 'test_order' file exists in the test directory, it
indicates the order the tests are run in. The 'test_order' file con‐
sists of a pass number followed by the test name (no trailing .sh). If
the 'test_order' file exists, only those tests in the file will be run.

If there is a test failure, testing will continue until a change in
pass number occurs.

Writing a mkconfig Unit (mkconfig.sh)
mkconfig.sh reads the mkconfig configuration file and processes each
line sequentially. The output-file command specifies the output file
(e.g. config.h for the c-main language unit). A language unit is
loaded with the loadunit command.

Each language unit script is executed with the unix shell source (.)
command, so it has all of the general shell functions from mkconfig.sh
available for use.

The following functions from mkconfig.sh are used by the language
units: printlabel, checkcache, checkcache_val, checkcache_actual,
printyesno, printyesno_val, printyesno_actual, getdata, setdata,
require_unit, dosubst, doappend, domath, toupper, tolower, and locate‐
cmd.

A language unit must provide the following functions: preconfigfile,
output_item, stdconfigfile, postconfigfile, output_other.

mkconfig.sh provides the following generic checks: command,
include/endinclude, ifoption, ifnotoption, if, set, setint, setstr, and
option. The set, setint, setstr and option commands will execute the
output_item function from the current unit. Any other unrecognized
commands will be passed on to the language unit that has been loaded.

The flow of control by mkconfig.sh is:
process the commands from the mkconfig configuration file
set the output-file name.
load any units as specified by the loadunit commands from the
mkconfig.units directory.
execute the directives as specified by the mkconfig configuration
file.
save the cache file.
execute preconfigfile from the language unit.
execute output_item for each configuration item.
execute stdconfigfile from the language unit.
output any include text from the mkconfig configuration file.
execute postconfigfile from the language unit.
execute output_other from the language unit.

A language unit must define the functions listed above. It may also
define other functions for use by other units for that language.

The main language unit must set the following shell variables:
_MKCONFIG_PREFIX is set to a language unit specific prefix. This
prefix is used internally and in the cache files to create a unique
name.

_MKCONFIG_HASEMPTY is set to T or F. If true, the language unit may
set check variables to empty values. This modifies certain process‐
ing in mkconfig.sh. It is faster to have non-empty check variables.

_MKCONFIG_EXPORT is set to T or F. If true, the check variable is
set and exported so that it can be accessed in the shell environ‐
ment.

Language units may need other functions as defined in other units. The
require_unit function makes sure that the a particular language unit is
loaded for use by the calling unit.

A typical directive in a language unit will be structured as follows:
check_somecheck () {
chktype=$1
checkarg=$2

name="_somecheck_${checkarg}"
printlabel $name "somecheck: ${checkarg}"
checkcache ${_MKCONFIG_PREFIX} $name
if [ $rc -eq 0 ]; then return; fi # found it in cache
# do processing for check here
retval=1
printyesno $name $retval
setdata ${_MKCONFIG_PREFIX} $name $retval
}
The check function's arguments will be the same values read from the
mkconfig configuration file. The name should be set to __ as appropriate to be a unique name that is a valid
unix shell variable name.

Internal Function Definitions (mkconfig.sh)
checkcache prefix name

checkcache_val prefix name

checkcache_actual prefix name
checkcache checks the cache to see if the check variable already
has a value. If so, the check variable is set to the value and
a return code of 0 is returned. prefix is normally $_MKCON‐
FIG_PREFIX and name is the name of the check variable. The dif‐
ferent variants of checkcache correspond to the variants of
printyesno for displaying the check variable to the user.

dosubst shellvar pattern repl [pattern repl ...]
Substitutes repl for pattern globally throughout shellvar. Mul‐
tiple patterns and replacement strings may be specified. pat‐
tern may be any regular expression recognized by 'sed'. Note
that modern 'sed' regular expressions will not be supported on
all systems.

doappend shellvar value
Appends value to shellvar.

domath shellvar "math-expr"
Executes the math-expr and assigns the returned value to shell‐
var. math-expr must be quoted and should have spaces around all
arguments.
e.g. count=1; domath count "$count + 1"; echo $count # 2

getdata shellvar prefix name
In some cases, the check function may need to retrieve the value
of a check variable. The getdata function returns the value of
the check variable name in the shell variable shellvar. prefix
is normally ${_MKCONFIG_PREFIX}.

locatecmd shellvar command
Locates a command in the path. Sets shellvar to the full path
of the command.

printlabel name display-data
printlabel displays display-data to the screen followed by an
ellipsis. The name and display-data is also logged to the log
file.

printyesno name value

printyesno_val name value

printyesno_actual name value
printyesno is used in conjunction with printlabel. printlabel
displays the first part of the output for the user and print‐
yesno displays the result. printyesno is used for boolean (0 or
1) values. It will display 'yes' or 'no'. printyesno_val is
used for values that are non-zero or a string. It will display
the value, or 'no' if set to 0. printyesno_actual is used for
values that should be displayed intact. It will display the
actual value (0 or otherwise).

require_unit unit-name
require_unit loads another unit file that is needed by the call‐
ing unit.

setdata prefix name value
setdata is used in a check function to set the value of a check
variable. prefix is normally ${_MKCONFIG_PREFIX}. name is the
name of the check variable. value is the value the check vari‐
able is set to. value should be enclosed in quotation marks if
it has spaces or other special shell characters.

toupper shellvar
Converts a shell variable to upper case.

tolower shellvar
Coverts a shell variable to lower case.

Environment Variables (mkconfig.sh)
_MKCONFIG_DIR
The directory where mkconfig.sh is installed.

File Descriptors (mkconfig.sh)
The file descriptors are allocated as follows:
9 - The mkconfig log file
8 - Used by mkconfig.sh; not available for mkconfig unit scripts.
7 - Used by mkconfig.sh; not available for mkconfig unit scripts.
6 - Used by c-main.sh and mkconfig.sh; not available for c language
unit scripts.
4 - Used by c-main.sh; not available for c language unit scripts.

Writing a test script (runtests.sh)
To be completed.

Environment Variables (runtests.sh)
_MKCONFIG_DIR
The directory where mkconfig.sh is installed.

_MKCONFIG_RUNTOPDIR
The original directory where the tests were started.

_MKCONFIG_RUNTSTDIR
The directory containing the test scripts and associated files.

_MKCONFIG_RUNTMPDIR
The top level temporary directory. Sub-directories are created
for each test that is run.

_MKCONFIG_TSTRUNTMPDIR
The temporary directory in which the test is run.

shelllist
A list of valid shells installed on the system.

See Also
iffe(1) autoconf(1) dist(7) mkconfig_env(7) mkconfig_c(7) mkconfig_d(7)

Bugs
Send bug reports to: brad.lanam.di_at_gmail.com

Website
http://www.gentoo.com/di/mkconfig.html

Brad Lanam, Walnut Creek, CA (brad.lanam.di_at_gmail.com)