Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Daniel P. Berrange]

On Tue, Sep 22, 2015 at 05:35:59PM +0100, Daniel P. Berrange wrote:
> Developers who are new to QEMU, or have a background familiarity
> with GNU autotools can have trouble getting their head around the
> home-grown QEMU build system. This document attempts to explain
> the structure / design of the configure script and the various
> Makefile pieces that live across the source tree.
> 
> Signed-off-by: Daniel P. Berrange 
> ---
>  docs/build-system.txt | 493 
> ++
>  1 file changed, 493 insertions(+)
>  create mode 100644 docs/build-system.txt

Thanks for all the feedback on this. I won't reply to all the mails
individually, I'll simply address all the feedback given and post a
v2 later.

Regards,
Daniel
-- 
|: http://berrange.com  -o-http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org  -o- http://virt-manager.org :|
|: http://autobuild.org   -o- http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org   -o-   http://live.gnome.org/gtk-vnc :|

Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Laszlo Ersek]

meta review of your review:

On 09/22/15 20:11, John Snow wrote:
> Reviewed from an en_US perspective, though I left alone things that are
> clearly regional (e.g. 'behaviour' vs 'behavior')
> 
> On 09/22/2015 12:35 PM, Daniel P. Berrange wrote:

>> + - Add information to the help output message to report on the new
>> +   feature flag.
>> +
> 
> Remove period, or add to the other list items for consistency. My
> personal preference is to use the period for any sentences with proper
> grammatical structure, omitting it for simple list items.

Then:

>> +which create binaries must include the $(EXESUF) variable on the binary
>> +name. eg
> 
> 'e.g.' here and everywhere subsequent.

Self-contradiction found!!!eleven

:)

Honestly I'm surprised (or not) how many typos you've found that I
blissfully slid over.

>> +Each system/userspace emulation target needs to have a slightly
>> +different set of make rules / variables. Thus, make will be recursively
>> +invoked for each of the emulation targets.
>> +
>> +The recursive invokation will end up processing the toplevel
> 
> invocation again.

Self-contradictory period again! :)

> Thanks for writing this!

Yes!

> Pretending to be Eric,

Yes. :)

Cheers
Laszlo

Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Eric Blake]

On 09/22/2015 12:28 PM, Laszlo Ersek wrote:
> meta review of your review:
> 

> 
>>> +Each system/userspace emulation target needs to have a slightly
>>> +different set of make rules / variables. Thus, make will be recursively
>>> +invoked for each of the emulation targets.
>>> +
>>> +The recursive invokation will end up processing the toplevel
>>
>> invocation again.
> 
> Self-contradictory period again! :)
> 
>> Thanks for writing this!

Heartily seconded - in spite of our review comments, the document looks
very useful.

> 
> Yes!
> 
>> Pretending to be Eric,
> 
> Yes. :)

Don't know if I should be pleased or shocked :)


-- 
Eric Blake   eblake redhat com+1-919-301-3266
Libvirt virtualization library http://libvirt.org



signature.asc
Description: OpenPGP digital signature

Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Laszlo Ersek]

On 09/22/15 20:51, Eric Blake wrote:
> On 09/22/2015 12:28 PM, Laszlo Ersek wrote:
>> meta review of your review:
>>
> 
>>
 +Each system/userspace emulation target needs to have a slightly
 +different set of make rules / variables. Thus, make will be recursively
 +invoked for each of the emulation targets.
 +
 +The recursive invokation will end up processing the toplevel
>>>
>>> invocation again.
>>
>> Self-contradictory period again! :)
>>
>>> Thanks for writing this!
> 
> Heartily seconded - in spite of our review comments, the document looks
> very useful.
> 
>>
>> Yes!
>>
>>> Pretending to be Eric,
>>
>> Yes. :)
> 
> Don't know if I should be pleased or shocked :)

Pleased, certainly. :)

Laszlo

Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Eric Blake]

On 09/22/2015 10:35 AM, Daniel P. Berrange wrote:
> Developers who are new to QEMU, or have a background familiarity
> with GNU autotools can have trouble getting their head around the

s/autotools/autotools,/

> home-grown QEMU build system. This document attempts to explain
> the structure / design of the configure script and the various
> Makefile pieces that live across the source tree.
> 
> Signed-off-by: Daniel P. Berrange 
> ---
>  docs/build-system.txt | 493 
> ++
>  1 file changed, 493 insertions(+)
>  create mode 100644 docs/build-system.txt
> 

> +Stage 1: configure

> +
> +In contrast to autoconf scripts, QEMU's configure is expected to be
> +silent while it is checking for features. It will only display output
> +when an error occurrs, or to show the final feature enablement summary

s/occurrs/occurs/

> +on completion.
> +
> +Adding new checks to the configure script usually comprises the
> +following tasks
> +
> + - Initialize one or more variables with the default feature state.
> +
> +   Ideally features should auto-detect whether they are present,
> +   so try to avoid hardcoding the initial state to either enabled
> +   or disabled, as that forces the user to pass a --{dis,en}able-XXX
> +   flag on every invokation of configure

s/invokation/invocation/


> +Stage 2: makefiles
> +==
> +
> +Although the source code is spread across multiple subdirectories, the
> +build system should be considered largely non-recursive in nature, in
> +contrast to common practices seen with automake. There is some recursive
> +invokation of make, but this is related to the things being built,
> +rather than the source directory structure.

s/invokation/invocation/

Mention that we require GNU make.

> +Module structure
> +
> +
> +There are a number of key outputs of the QEMU build system
> +
> + - Tools - qemu-img, qemu-nbd, qga (guest agent), etc
> + - System emulators - qemu-system-$ARCH
> + - Userspace emulators - qemu-$ARCH
> + - Unit tests
> +
> +The source code is highly modularized, split across many files to
> +facilitate building of all of these components with as little duplicated
> +compilation as possible. There can be considered to be two distinct
> +groups of files, those which are independant of the QEMU emulation
> +target and those which are dependant on the QEMU emulation target.

Throughout this section: s/(in)?dependant/dependent/

> +
> +Statically defined files
> +

> +The recursive invokation will end up processing the toplevel

s/invokation/invocation/


> +
> +Dynamically created files
> +-
> +
> +The following files are generated dynamically by configure in order to
> +control the behaviour of the staticaly defined makefiles. This avoids

s/staticaly/statically/


> +
> +It is also used as a dependancy checking mechanism. If make sees that

s/dependancy/dependency/

-- 
Eric Blake   eblake redhat com+1-919-301-3266
Libvirt virtualization library http://libvirt.org



signature.asc
Description: OpenPGP digital signature

Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Paolo Bonzini]

On 22/09/2015 20:11, John Snow wrote:
>> +such as error handling infrastructure, standard data structures,
>> +platform portability wrapper functions, etc. This code can be compiled
>> +once only and the .o files linked into all output binaries.
>> +
>> +In the target dependant set lives CPU emulation, device emulation and
>> +much glue code. This code is generally compiled multiple times, once for

s/is generally compiled/sometimes also has to be compiled/

>> +each target architecture being built.

... while in other cases can be compiled once for each architecture.

Do not use "target architecture", since you're using "target" to mean a
Makefile target, i.e. binary.

>> +The target independant code that is used by all binaries is built into a

s/The target independant/Utlity/

>> +static archive called libqemuutil.a, which is then linked to all the
>> +binaries. Due to ongoing incomplete refactoring, some of the code in

s/Due to ongoing incomplete refactoring/In order to provide hooks that
are only needed by some of the binaries/

>> +libqemuutil.a depends on other functions that are not available in all

s/available in/fully implemented by/

>> +QEMU binaries. To deal with this there is a second library called
>> +libqemustub.a which provide dummy stubs for all these functions. These
>> +will get lazy linked into the binary if the real implementation is not
>> +present. Thus any time a binary links to libqemuutil.a, it should also
>> +be made to link libqemustub.a. eg
>> +
>> + qemu-img$(EXESUF): qemu-img.o ..snip.. libqemuutil.a libqemustub.a

Really all binaries should link libqemustub.a.

Perhaps add a note that libqemustub symbols effectively work as weak
symbols, but a static library is more portable?

>> +
>> +Windows platform portability
>> +
>> +
>> +On Windows all binaries have a .exe suffix, so all the Makefile rules
> 
> I guess you pronounce the 'dot' :)
> 
>> +which create binaries must include the $(EXESUF) variable on the binary
>> +name. eg
> 
> 'e.g.' here and everywhere subsequent.
> 
>> +
>> + qemu-img$(EXESUF): qemu-img.o ..snip..
>> +
>> +This expands to '.exe' on Windows, or '' on other platforms.
>> +
>> +A further complication for the system and userspace emulator binaries is
>> +that two separate binaries need to be generated.
>> +
>> +The main binary (eg qemu-system-x86_64.exe) is linked against the
>> +Windows console runtime subsystem. These are expected to be run from a
>> +command prompt window, and so will print stderr to the console that
>> +launched them.
>> +
>> +The second binary generated has a 'w' on the end of its name (eg
>> +qemu-system-x86_64w.exe) and is linked against the Windows graphical
>> +runtime subsystem. These are expected to be run directly from the
>> +desktop and will open up a dedicated console window for stderr output.
>> +
>> +The Makefile.target will generate the binary for the graphical subsystem
>> +first, and then use objcopy to relink it against the console subsystem
>> +to generate the second binary.
>> +
>> +
>> +Object variable naming
>> +--
>> +
>> +The QEMU convention is to define variables to list different groups of
>> +object files. These are named with the convention $PREFIX-y. For example

$PREFIX-obj-y

>> +the libqemuutil.a file will be linked with all objects listed in a
>> +variable 'util-y'.

util-obj-y.

>> +- */Makefile.objs
>> +
>> +Since the source code is spread across multiple directories, the rules
>> +for each file are similarly modularized. Thus each subdirectory
>> +containing .c files will usually also contain a Makefile.objs file.
>> +These files are not directly invoked by a recursive make, but instead
>> +they are imported by the top level Makefile and/or Makefile.target
>> +
>> +Each Makefile.objs usually just declares a set of variables listing the
>> +.o files that need building from the source files in the directory. They
>> +will also define any custom linker or compiler flags. For example in
>> +block/Makefile.objs
>> +
>> +  block-obj-$(CONFIG_LIBISCSI) += iscsi.o
>> +  block-obj-$(CONFIG_CURL) += curl.o
>> +
>> +  ..snip...
>> +
>> +  iscsi.o-cflags := $(LIBISCSI_CFLAGS)
>> +  iscsi.o-libs   := $(LIBISCSI_LIBS)
>> +  curl.o-cflags  := $(CURL_CFLAGS)
>> +  curl.o-libs:= $(CURL_LIBS)

You may want to mention that rules in */Makefile.objs should use $(obj)
as a prefix to the target, for example:

$(obj)/generated-tcg-tracers.h: $(obj)/generated-tcg-tracers.h-timestamp

I'll join the choir: awesome job.

Paolo

Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[John Snow]

Reviewed from an en_US perspective, though I left alone things that are
clearly regional (e.g. 'behaviour' vs 'behavior')

On 09/22/2015 12:35 PM, Daniel P. Berrange wrote:
> Developers who are new to QEMU, or have a background familiarity
> with GNU autotools can have trouble getting their head around the
> home-grown QEMU build system. This document attempts to explain
> the structure / design of the configure script and the various
> Makefile pieces that live across the source tree.
> 
> Signed-off-by: Daniel P. Berrange 
> ---
>  docs/build-system.txt | 493 
> ++
>  1 file changed, 493 insertions(+)
>  create mode 100644 docs/build-system.txt
> 
> diff --git a/docs/build-system.txt b/docs/build-system.txt
> new file mode 100644
> index 000..2209261
> --- /dev/null
> +++ b/docs/build-system.txt
> @@ -0,0 +1,493 @@
> +The QEMU build system architecture
> +==
> +
> +This document aims to help developers understand the architecture of the
> +QEMU build system. As with projects using GNU autotools, the QEMU build
> +system has two stages, first the developer runs the "configure" script
> +to determine the local build environment characteristics, then they run
> +"make" to build the project. There is about where the similarities with
> +GNU autotools end, so try to forget what you know about them.
> +
> +
> +Stage 1: configure
> +==
> +
> +The QEMU configure script is written directly in shell, and should be
> +compatible with any POSIX shell, hence it uses #!/bin/sh. An important
> +implication of this is that it is important to avoid using bash-isms on
> +development platforms where bash is the primary host.
> +
> +In contrast to autoconf scripts, QEMU's configure is expected to be
> +silent while it is checking for features. It will only display output
> +when an error occurrs, or to show the final feature enablement summary

occurs.

> +on completion.
> +
> +Adding new checks to the configure script usually comprises the
> +following tasks
> +

colon for consistency with other lists below

> + - Initialize one or more variables with the default feature state.
> +
> +   Ideally features should auto-detect whether they are present,
> +   so try to avoid hardcoding the initial state to either enabled
> +   or disabled, as that forces the user to pass a --{dis,en}able-XXX
> +   flag on every invokation of configure
> +

invocation?

> + - Add support to the command line arg parser to handle any new
> +   --{dis,en}able-XXX flags required by the feature XXX
> +
> + - Add information to the help output message to report on the new
> +   feature flag.
> +

Remove period, or add to the other list items for consistency. My
personal preference is to use the period for any sentences with proper
grammatical structure, omitting it for simple list items.

> + - Add code to perform the actual feature check. As noted above, try to
> +   be fully dynamic in checking enablement/disablement
> +
> + - Add code to print out the feature status in the configure summary
> +   upon completion
> +
> + - Add any new makefile variables to $config_host_mak on completion
> +
> +
> +Taking (a simplified version of) the probe for gnutls from configure,
> +we have the following pieces:
> +
> +  # Initial variable state
> +  gnutls=""
> +
> +  ..snip..
> +
> +
> +  # Configure flag processing
> +  --disable-gnutls) gnutls="no"
> +  ;;
> +  --enable-gnutls) gnutls="yes"
> +  ;;
> +
> +  ..snip..
> +
> +
> +  # Help output feature message
> +  gnutls  GNUTLS cryptography support
> +
> +  ..snip..
> +
> +
> +  # Test for gnutls
> +  if test "$gnutls" != "no"; then
> + if ! $pkg_config --exists "gnutls"; then
> +gnutls_cflags=`$pkg_config --cflags gnutls`
> +gnutls_libs=`$pkg_config --libs gnutls`
> +libs_softmmu="$gnutls_libs $libs_softmmu"
> +libs_tools="$gnutls_libs $libs_tools"
> +QEMU_CFLAGS="$QEMU_CFLAGS $gnutls_cflags"
> +gnutls="yes"
> + elif test "$gnutls" = "yes"; then
> +feature_not_found "gnutls" "Install gnutls devel"
> + else
> +gnutls="no"
> + fi
> +  fi
> +
> +  ..snip..
> +
> +
> +  # Completion feature summary
> +  echo "GNUTLS support$gnutls"
> +
> +  ..snip..
> +
> +
> +  # Define make variables
> +  if test "$gnutls" = "yes" ; then
> + echo "CONFIG_GNUTLS=y" >> $config_host_mak
> +  fi
> +
> +
> +Helper functions
> +
> +
> +The configure script provides a variety of helper functions to assist
> +developers in checking for system features:
> +
> + - do_cc $ARGS...
> +
> +   Attempt to run the system C compiler passing it $ARGS...
> +
> + - do_cxx $ARGS...
> +
> +   Attempt to run the system C++ compiler passing it $ARGS...
> +
> + - compile_object $CFLAGS
> +
> +   Attempt to compile a test program with the system C compiler using
> +   $CFLAGS. The test program must have been 

Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Laszlo Ersek]

On 09/22/15 18:35, Daniel P. Berrange wrote:
> Developers who are new to QEMU, or have a background familiarity
> with GNU autotools can have trouble getting their head around the
> home-grown QEMU build system. This document attempts to explain
> the structure / design of the configure script and the various
> Makefile pieces that live across the source tree.
> 
> Signed-off-by: Daniel P. Berrange 
> ---
>  docs/build-system.txt | 493 
> ++
>  1 file changed, 493 insertions(+)
>  create mode 100644 docs/build-system.txt

Wow, this is awesome. Just a few comments (I'm rather a happy student of
this document than an expert on the build system):

> 
> diff --git a/docs/build-system.txt b/docs/build-system.txt
> new file mode 100644
> index 000..2209261
> --- /dev/null
> +++ b/docs/build-system.txt
> @@ -0,0 +1,493 @@
> +The QEMU build system architecture
> +==
> +
> +This document aims to help developers understand the architecture of the
> +QEMU build system. As with projects using GNU autotools, the QEMU build
> +system has two stages, first the developer runs the "configure" script
> +to determine the local build environment characteristics, then they run
> +"make" to build the project. There is about where the similarities with
> +GNU autotools end, so try to forget what you know about them.
> +
> +
> +Stage 1: configure
> +==
> +
> +The QEMU configure script is written directly in shell, and should be
> +compatible with any POSIX shell, hence it uses #!/bin/sh. An important
> +implication of this is that it is important to avoid using bash-isms on
> +development platforms where bash is the primary host.
> +
> +In contrast to autoconf scripts, QEMU's configure is expected to be
> +silent while it is checking for features. It will only display output
> +when an error occurrs, or to show the final feature enablement summary
> +on completion.
> +
> +Adding new checks to the configure script usually comprises the
> +following tasks
> +
> + - Initialize one or more variables with the default feature state.
> +
> +   Ideally features should auto-detect whether they are present,
> +   so try to avoid hardcoding the initial state to either enabled
> +   or disabled, as that forces the user to pass a --{dis,en}able-XXX
> +   flag on every invokation of configure
> +
> + - Add support to the command line arg parser to handle any new
> +   --{dis,en}able-XXX flags required by the feature XXX

Suggest to spell out --disable-XXX and --enable-XXX separately, so that
they be the first hits when someone searches this file for "--enable"
and "--disable".

> +
> + - Add information to the help output message to report on the new
> +   feature flag.
> +
> + - Add code to perform the actual feature check. As noted above, try to
> +   be fully dynamic in checking enablement/disablement
> +
> + - Add code to print out the feature status in the configure summary
> +   upon completion
> +
> + - Add any new makefile variables to $config_host_mak on completion
> +
> +
> +Taking (a simplified version of) the probe for gnutls from configure,
> +we have the following pieces:
> +
> +  # Initial variable state
> +  gnutls=""
> +
> +  ..snip..
> +
> +

suggest to add only one empty line after "..snip..".

> +  # Configure flag processing
> +  --disable-gnutls) gnutls="no"
> +  ;;
> +  --enable-gnutls) gnutls="yes"
> +  ;;
> +
> +  ..snip..
> +
> +
> +  # Help output feature message
> +  gnutls  GNUTLS cryptography support
> +
> +  ..snip..
> +
> +
> +  # Test for gnutls
> +  if test "$gnutls" != "no"; then
> + if ! $pkg_config --exists "gnutls"; then
> +gnutls_cflags=`$pkg_config --cflags gnutls`
> +gnutls_libs=`$pkg_config --libs gnutls`
> +libs_softmmu="$gnutls_libs $libs_softmmu"
> +libs_tools="$gnutls_libs $libs_tools"
> +QEMU_CFLAGS="$QEMU_CFLAGS $gnutls_cflags"
> +gnutls="yes"
> + elif test "$gnutls" = "yes"; then
> +feature_not_found "gnutls" "Install gnutls devel"
> + else
> +gnutls="no"
> + fi
> +  fi
> +
> +  ..snip..
> +
> +
> +  # Completion feature summary
> +  echo "GNUTLS support$gnutls"
> +
> +  ..snip..
> +
> +
> +  # Define make variables
> +  if test "$gnutls" = "yes" ; then
> + echo "CONFIG_GNUTLS=y" >> $config_host_mak
> +  fi
> +
> +
> +Helper functions
> +
> +
> +The configure script provides a variety of helper functions to assist
> +developers in checking for system features:
> +
> + - do_cc $ARGS...
> +
> +   Attempt to run the system C compiler passing it $ARGS...
> +
> + - do_cxx $ARGS...
> +
> +   Attempt to run the system C++ compiler passing it $ARGS...
> +
> + - compile_object $CFLAGS
> +
> +   Attempt to compile a test program with the system C compiler using
> +   $CFLAGS. The test program must have been previously written to a file
> +   called $TMPC.
> +
> + - 

[Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Daniel P. Berrange]

Developers who are new to QEMU, or have a background familiarity
with GNU autotools can have trouble getting their head around the
home-grown QEMU build system. This document attempts to explain
the structure / design of the configure script and the various
Makefile pieces that live across the source tree.

Signed-off-by: Daniel P. Berrange 
---
 docs/build-system.txt | 493 ++
 1 file changed, 493 insertions(+)
 create mode 100644 docs/build-system.txt

diff --git a/docs/build-system.txt b/docs/build-system.txt
new file mode 100644
index 000..2209261
--- /dev/null
+++ b/docs/build-system.txt
@@ -0,0 +1,493 @@
+The QEMU build system architecture
+==
+
+This document aims to help developers understand the architecture of the
+QEMU build system. As with projects using GNU autotools, the QEMU build
+system has two stages, first the developer runs the "configure" script
+to determine the local build environment characteristics, then they run
+"make" to build the project. There is about where the similarities with
+GNU autotools end, so try to forget what you know about them.
+
+
+Stage 1: configure
+==
+
+The QEMU configure script is written directly in shell, and should be
+compatible with any POSIX shell, hence it uses #!/bin/sh. An important
+implication of this is that it is important to avoid using bash-isms on
+development platforms where bash is the primary host.
+
+In contrast to autoconf scripts, QEMU's configure is expected to be
+silent while it is checking for features. It will only display output
+when an error occurrs, or to show the final feature enablement summary
+on completion.
+
+Adding new checks to the configure script usually comprises the
+following tasks
+
+ - Initialize one or more variables with the default feature state.
+
+   Ideally features should auto-detect whether they are present,
+   so try to avoid hardcoding the initial state to either enabled
+   or disabled, as that forces the user to pass a --{dis,en}able-XXX
+   flag on every invokation of configure
+
+ - Add support to the command line arg parser to handle any new
+   --{dis,en}able-XXX flags required by the feature XXX
+
+ - Add information to the help output message to report on the new
+   feature flag.
+
+ - Add code to perform the actual feature check. As noted above, try to
+   be fully dynamic in checking enablement/disablement
+
+ - Add code to print out the feature status in the configure summary
+   upon completion
+
+ - Add any new makefile variables to $config_host_mak on completion
+
+
+Taking (a simplified version of) the probe for gnutls from configure,
+we have the following pieces:
+
+  # Initial variable state
+  gnutls=""
+
+  ..snip..
+
+
+  # Configure flag processing
+  --disable-gnutls) gnutls="no"
+  ;;
+  --enable-gnutls) gnutls="yes"
+  ;;
+
+  ..snip..
+
+
+  # Help output feature message
+  gnutls  GNUTLS cryptography support
+
+  ..snip..
+
+
+  # Test for gnutls
+  if test "$gnutls" != "no"; then
+ if ! $pkg_config --exists "gnutls"; then
+gnutls_cflags=`$pkg_config --cflags gnutls`
+gnutls_libs=`$pkg_config --libs gnutls`
+libs_softmmu="$gnutls_libs $libs_softmmu"
+libs_tools="$gnutls_libs $libs_tools"
+QEMU_CFLAGS="$QEMU_CFLAGS $gnutls_cflags"
+gnutls="yes"
+ elif test "$gnutls" = "yes"; then
+feature_not_found "gnutls" "Install gnutls devel"
+ else
+gnutls="no"
+ fi
+  fi
+
+  ..snip..
+
+
+  # Completion feature summary
+  echo "GNUTLS support$gnutls"
+
+  ..snip..
+
+
+  # Define make variables
+  if test "$gnutls" = "yes" ; then
+ echo "CONFIG_GNUTLS=y" >> $config_host_mak
+  fi
+
+
+Helper functions
+
+
+The configure script provides a variety of helper functions to assist
+developers in checking for system features:
+
+ - do_cc $ARGS...
+
+   Attempt to run the system C compiler passing it $ARGS...
+
+ - do_cxx $ARGS...
+
+   Attempt to run the system C++ compiler passing it $ARGS...
+
+ - compile_object $CFLAGS
+
+   Attempt to compile a test program with the system C compiler using
+   $CFLAGS. The test program must have been previously written to a file
+   called $TMPC.
+
+ - compile_prog $CFLAGS $LDFLAGS
+
+   Attempt to compile a test program with the system C compiler using
+   $CFLAGS and link it with the system linker using $LDFLAGS. The test
+   program must have been previously written to a file called $TMPC.
+
+ - has $COMMAND
+
+   Determine if $COMMAND exists in the current environment, either as a
+   shell builtin, or executable binary, returning 0 on success.
+
+ - path_of $COMMAND
+
+   Return the fully qualified path of $COMMAND, printing it to stdout,
+   and returning 0 on success.
+
+ - check_define $NAME
+
+   Determine if the macro $NAME is defined by the system C compiler
+
+ - check_include $NAME
+
+   Determine if the