build.awk File Reference

Creates build and link instructions for a given project path. More...

Functions
void	filter118 ()
	This function handles all input and produces the output of the script. More...
void	verbose (var name, var value)
	Print a name/value pair if DEBUG is set. More...
void	verbose_values (var name, var a)
	Print a name and the values of an array if DEBUG is set. More...
void	verbose_keys (var name, var a)
	Print a name and the keys of an array if DEBUG is set. More...
var	esc (var str)
	Escape characters that are special in a regex. More...
var	compact (var path)
	Compress the given path. More...
var	flags (var file, var fmt)
	Generate context specific flags. More...
var	src_to_obj (var file)
	Convert a file name to an object file name. More...
var	src_to_origin (var file)
	Convert a file name to an origin. More...
var	obj_to_bin (var file)
	Convert an object to a binary file name. More...
var	linklist (var obj)
	Recursively get all objects required to link with the given object. More...

Detailed Description

Creates build and link instructions for a given project path.

This script is a wrapper around cpp -MM and has a performance comparable to the mkdep tool.

The easiest way to invoke the script is by calling:

    scripts/build.awk src/

This command outputs build instructions for all C and C++ files found in src/.

It will commonly be necessary to add custom arguments to the CPP call, i.e. because a define, an include directory or a specific version of the C/C++ standard is required:

    scripts/build.awk src/ -I/usr/local/include -DRELEASE -std=c++14

These arguments have to come after the first source directory or the AWK interpreter will treat then as unknown arguments to itself instead of arguments to the script.

The script supports building from multiple sources by providing multiple input directories. In case of multiple objects with the same name the first one encountered wins.

Environment

A number of variables make it possible to steer the behaviour of build.awk, either by setting them in the environment or by providing them explicitly via -vVAR=VALUE:

Variable	Description	Default
DEBUG	Set to enable verbose output	""
CPP	Change to pass flags to cpp	"cpp -MM %s"
FIND	Control find syntax	"find -E %s …"
MKDIR	Command for creating build directories	"mkdir -p %s"
OBJSUFX	Set to control suffix of object files	".o"
BINSUFX	Set to control suffix of binaries	""

The string " -MM %s" is implicitly appended to CPP if it set through the environment.

Special Make Variables

For better portability a set of make variables that evaluate to target local variables are defined. The variables have a default meaning and a BSD make specific fallback:

Variable	Default	BSD Fallback
_IMPSRC	$<	${.ALLSRC:[1]}
_TARGET	$@	${.TARGET}
_ALLSRC	$^	${.ALLSRC}

These can be overridden if needed.

Build Flags

There are some options to influence the build without rerunning build.awk:

Variable	Meaning	Default
CC	C compiler to use	OS defined
CFLAGS	Flags to the C compiler	OS defined
CXX	C++ compiler to use	OS defined
CXXFLAGS	Flags to the C++ compiler	OS defined
LDFLAGS	Linker flags	OS defined
LDLIBS	Libraries to link	OS defined
OBJDIR	Optional build output directory	undefined
COMPFLAGS*	Additional flags for compiling	undefined
LINKFLAGS*	Additional flags for linking	undefined
LINKLIBS*	Additional libraries to link	undefined

If defined the OBJDIR variable must terminate with a /.

The COMPFLAGS*, LINKFLAGS* and LINKLIBS* variables are variable hierarchies. E.g. for the target foo/bar.o the following hierarchy of compile arguments will be created:

    ${COMPFLAGS} ${COMPFLAGS_foo} ${COMPFLAGS_foo_bar_o}

Meta Targets

The output of this script provides two meta targets:

Target	Description
build	Build all binaries
all	Build everything

Function Documentation

filter118()

void filter118

(

)

This function handles all input and produces the output of the script.

In addition to the user-definable globals it uses the following globals to keep state:

Variable	Source	Description
SRCDIRS	Command line arguments	The list of source directories
CPPARGS	Command line arguments	Additional CPP arguments
SRCS	FIND in SRCDIRS	List of source files
INCLUDES	CPP output	Map: object → full sources
OBJSRC	CPP output	Map: object → source
COMPILER	CPP output	Map: object → compiler/flags
ORIGIN	CPP output	Map: origin → object

Precondition

BEGIN  

verbose()

void verbose	(	var	name,
		var	value
	)

Print a name/value pair if DEBUG is set.

Parameters

name	The name to print
value	The value to print

verbose_values()

void verbose_values	(	var	name,
		var	a
	)

Print a name and the values of an array if DEBUG is set.

Note this function assumes the array is indexed in 1 increments starting at 1.

Parameters

name	The name to print
a	An array to print the values of

verbose_keys()

void verbose_keys	(	var	name,
		var	a
	)

Print a name and the keys of an array if DEBUG is set.

Parameters

name	The name to print
a	An array to print the keys of

esc()

var esc

(

var

str

)

Escape characters that are special in a regex.

Parameters

str	The string to escape

Returns

The escaped string

compact()

var compact

(

var

path

)

Compress the given path.

Eliminate ./ and ../ from the given path.

This can be broken by symlink shenanigans.

Parameters

path	The path to change

Returns

The compressed path

flags()

var flags	(	var	file,
		var	fmt
	)

Generate context specific flags.

Parameters

file	The file to generate flags for
fmt	A format string to embed each flag in, e.g. " ${COMPFLAGS%s}"

Returns

A hierarchy of flags for the given file

src_to_obj()

var src_to_obj

(

var

file

)

Convert a file name to an object file name.

The object suffix is taken from the OBJSUFX global.

Parameters

file	The file name to convert

Returns

The corresponding object file name

src_to_origin()

var src_to_origin

(

var

file

)

Convert a file name to an origin.

This can be used in conjunction with ORIGIN to determine whether there is an object for an origin. E.g. src/foo.c and src/foo.h both have the origin src/foo and ORIGIN["src/foo"] points to foo.o.

Parameters

file	The file name to convert

Returns

The file name stripped of its suffix

obj_to_bin()

var obj_to_bin

(

var

file

)

Convert an object to a binary file name.

The object and binary file name suffixes are taken from the OBJSUFX and BINSUFX globals.

Parameters

file	The file name to convert

Returns

The corresponding object file name

linklist()

var linklist

(

var

obj

)

Recursively get all objects required to link with the given object.

Uses ORIGIN and INCLUDES to track dependencies.

Parameters

obj	The object to start from

Returns

A space separated list of object files