16 files changed, 1215 insertions, 0 deletions
diff --git a/tools/Makefile b/tools/Makefile
new file mode 100644
index 000000000000..13db85769fda
--- /dev/null
+++ b/tools/Makefile
@@ -0,0 +1,14 @@
+# $Id$
+
+TOP=		..
+
+.include "${TOP}/mk/elftoolchain.os.mk"
+
+SUBDIR=
+
+.if defined(MKNOWEB) && ${MKNOWEB} == "yes" && exists(${NOWEB}) && \
+    exists(${PDFLATEX})
+SUBDIR+=		build-automation
+.endif
+
+.include "${TOP}/mk/elftoolchain.subdir.mk"
diff --git a/tools/build-automation/Makefile b/tools/build-automation/Makefile
new file mode 100644
index 000000000000..535e24528ba7
--- /dev/null
+++ b/tools/build-automation/Makefile
@@ -0,0 +1,82 @@
+# $Id: Makefile 2563 2012-09-01 14:31:42Z jkoshy $
+#
+# The same 'source' for a literate program is used to build both
+# documentation and the program itself.
+#
+# Keeping the build rules for program code and documentation in
+# separate Makefiles help to keep each rule set simple.
+
+TOP=		../..
+
+# The literate program input, in order of presentation in the
+# generated text.
+NW_SRCS= 	introduction.nw
+NW_SRCS+= 	userguide.nw
+NW_SRCS+=	implementation.nw
+NW_SRCS+=	slave.nw
+NW_SRCS+=	master.nw
+NW_SRCS+=	utilities.nw
+
+NW_ROOTS!=	noroots ${NW_SRCS} /dev/null | sed -e 's:<<::' -e 's:>>::'
+
+# The name of the document's base file.
+DOC=		build-system
+
+PROGRAMDIRS=	master slave
+
+SUBMAKEFILES=	documentation manuals program
+
+# Declare make targets with special characteristics.
+.MAIN:		all
+.PHONY:		all clean clobber index install test
+
+# Capture actions shared by multiple targets in a macro.
+.dosubmake:	.USE
+.for rules in ${SUBMAKEFILES}
+	@${MAKE} -f Makefile.${rules} ${.TARGET} NW_SRCS="${NW_SRCS}" \
+		DOC=${DOC} TOP="${TOP}"
+.endfor
+
+# Standard targets.
+all:		${PROGRAMDIRS} ${NW_ROOTS} ${DOC}.tex .dosubmake
+install:	all .dosubmake
+clean:		.dosubmake
+	rm -f ${CLEANFILES}
+
+# Create the directories holding the program source code, if needed.
+${PROGRAMDIRS}:	.SILENT
+	[ -d ${.TARGET} ] || mkdir ${.TARGET}
+
+# Extract all program 'root chunks' from the literate program inputs.
+.for n in ${NW_ROOTS}
+$n:	${NW_SRCS}
+	@tmpfile=`mktemp /tmp/mba.XXXXXXX`; \
+	trap "rm $${tmpfile}" 0 1 2 3 15; \
+	notangle -L -R${.TARGET} ${NW_SRCS} > $${tmpfile} || exit $$?; \
+	cpif ${.TARGET} < $${tmpfile}
+CLEANFILES+=	$n
+.endfor
+
+# Create a single TeX file holding the material to be typeset.
+# By passing the complete literate program as input to 'noweave', we
+# avoid noweb's limitation on chunk names having file scope.
+${DOC}.tex:	 ${DOC}.pre.nw ${NW_SRCS} ${DOC}.post.nw
+	cat ${.ALLSRC} | noweave -delay -index | cpif ${.TARGET}
+
+#
+# Special targets.
+#
+
+# The 'index' target only applies to the documentation.
+index:
+	@${MAKE} -f Makefile.documentation ${.TARGET} NW_SRCS="${NW_SRCS}" \
+		TOP="${TOP}"
+
+# The 'test' target only applies to the programs.
+test:
+	@${MAKE} -f Makefile.program ${.TARGET} NW_SRCS="${NW_SRCS}" \
+		TOP="${TOP}"
+
+# Provide a 'clobber' target that goes beyond 'clean'.
+clobber: clean
+	rm -rf ${PROGRAMDIRS}
diff --git a/tools/build-automation/Makefile.documentation b/tools/build-automation/Makefile.documentation
new file mode 100644
index 000000000000..0cb25a2d5ab3
--- /dev/null
+++ b/tools/build-automation/Makefile.documentation
@@ -0,0 +1,12 @@
+# -*- mode: makefile -*-
+#
+# Typeset documentation previously extracted by the invoking Makefile.
+#
+# $Id: Makefile.documentation 2546 2012-08-17 15:43:44Z jkoshy $
+
+DOC?=		build-system
+SRCS=		${DOC}.tex
+
+CLEANFILES+=	${SRCS}
+
+.include "${TOP}/mk/elftoolchain.tex.mk"
diff --git a/tools/build-automation/Makefile.manuals b/tools/build-automation/Makefile.manuals
new file mode 100644
index 000000000000..e2417a6c5639
--- /dev/null
+++ b/tools/build-automation/Makefile.manuals
@@ -0,0 +1,7 @@
+# -*- mode: makefile; -*-
+# $Id: Makefile.manuals 2581 2012-09-14 07:09:42Z jkoshy $
+
+MAN= 		yabs-slave.1    \
+		yabs.1
+
+.include <bsd.man.mk>
diff --git a/tools/build-automation/Makefile.program b/tools/build-automation/Makefile.program
new file mode 100644
index 000000000000..cb86da9c400c
--- /dev/null
+++ b/tools/build-automation/Makefile.program
@@ -0,0 +1,18 @@
+# -*- mode: makefile -*-
+#
+# Build the programs previously extracted from the literate program
+# input.
+#
+# $Id: Makefile.program 2546 2012-08-17 15:43:44Z jkoshy $
+
+SUBDIR=
+
+.if exists(master)
+SUBDIR+=	master
+.endif
+
+.if exists(slave)
+SUBDIR+=	slave
+.endif
+
+.include <bsd.subdir.mk>
diff --git a/tools/build-automation/README b/tools/build-automation/README
new file mode 100644
index 000000000000..300377820c80
--- /dev/null
+++ b/tools/build-automation/README
@@ -0,0 +1,13 @@
+.. -*- mode: rst; -*-
+
+Build Automation
+================
+
+This directory contains a utility to build and test the Elftoolchain
+project's sources on a variety of target operating systems and processor
+architectures.
+
+These tools are written as a literate program, in noweb_ syntax.
+
+.. _noweb: http://www.cs.tufts.edu/~nr/noweb/
+.. $Id: README 2459 2012-03-10 17:17:35Z jkoshy $
diff --git a/tools/build-automation/build-system.post.nw b/tools/build-automation/build-system.post.nw
new file mode 100644
index 000000000000..ce4111a0d30b
--- /dev/null
+++ b/tools/build-automation/build-system.post.nw
@@ -0,0 +1,19 @@
+% $Id: build-system.post.nw 2534 2012-08-04 04:07:20Z jkoshy $
+%
+% The last chunk of input presented to noweb(1).
+
+\backmatter
+
+\part{Appendices}
+
+% Typeset the index.
+\printindex
+
+% Add indices generated by noweb(1).
+% TODO: These need to be merged with the LaTeX index.
+\chapter*{Index of Identifiers}
+\nowebindex
+\chapter*{Index of Code Fragments}
+\nowebchunks
+
+\end{document}
diff --git a/tools/build-automation/build-system.pre.nw b/tools/build-automation/build-system.pre.nw
new file mode 100644
index 000000000000..c0ee09046564
--- /dev/null
+++ b/tools/build-automation/build-system.pre.nw
@@ -0,0 +1,189 @@
+% Copyright (c) 2006-2010 Joseph Koshy.  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 Joseph Koshy ``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 Joseph Koshy 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.
+%
+% $Id: build-system.pre.nw 2561 2012-08-31 02:46:33Z jkoshy $
+
+%
+% A Build Automation system.
+%
+
+\documentclass[a4paper,pdftex]{book}
+\usepackage{amsthm}
+\usepackage{bookmark}
+\usepackage{hyperref}
+\usepackage{makeidx}
+\usepackage{noweb}
+\usepackage{tikz}
+\usepackage{varioref}
+\usepackage{xspace}
+
+% Typesetting requirements.
+\theoremstyle{remark}
+\newtheorem{goal}{Design Goal}
+
+% Add meta-data to the PDF file.
+\hypersetup{
+  pdftitle={A Build Automation System},
+  pdfauthor={Joseph Koshy},
+  pdfsubject={A build automation system},
+  pdfkeywords={%
+    automation,%
+    build,%
+    literate program
+  }
+}
+
+% Fix a bug in the PDF TOC.
+\bookmarksetup{startatroot}
+
+% Document-specific LaTeX macros.
+\makeatletter
+\newcommand{\definition}[1]{\textit{#1}\index{#1!definition~of}\xspace}
+\newcommand{\elftoolchain}{\href{http://elftoolchain.sourceforge.net/}%
+    {ElfToolChain}\xspace}
+\newcommand{\file}[1]{\texttt{#1}\xspace}
+\newcommand{\func}[1]{\texttt{#1()}\xspace}
+\newcommand{\foreignphrase}[1]{\textit{#1}\xspace}
+\newcommand{\protoarg}[1]{\textit{#1}\xspace}
+\newcommand{\protocmd}[1]{\texttt{#1}\xspace}
+\newcommand{\protodef}[2]{\protocmd{#1} #2%
+    \index{#1@\texttt{#1}!protocol~definition}\\}
+\newcommand{\reg}{\textregistered\xspace}
+\newcommand{\term}[1]{\textit{#1}\xspace}
+\newcommand{\tool}[1]{\textbf{#1}\xspace}
+\newcommand{\trade}{\texttrademark\xspace}
+\newcommand{\var}[1]{\texttt{#1}\xspace}
+\makeatother
+
+% Noweb related
+\noweboptions{shift,hideunuseddefs,noidentxref}
+
+% Index related.
+\makeindex
+
+% The main document.
+
+\begin{document}
+
+\frontmatter                    % 
+
+% The title page.
+\title{Yet Another Build System}
+\author{Joseph~Koshy}
+\maketitle
+
+% Typeset a table of contents.
+\tableofcontents
+
+\chapter*{Preface}
+
+This document describes a build automation system being developed at
+the \elftoolchain project on
+\href{http://sourceforge.net/}{SourceForge.Net}.  The original
+motivation for this system was to automate the process of building and
+testing the \elftoolchain project's source tree on a variety of
+operating systems and machine architectures.  However, the design of
+the system is general enough that it can be used in other contexts
+too.
+
+The system has been designed to be easy to use and to frugal in its
+use of computing resources.  For handling non-native platforms, the
+system uses emulators such as \href{http://www.qemu.org}{QEMU},
+\href{http://gxemul.sourceforge.net/}{GXemul} and
+\href{http://www.virtualbox.org}{VirtualBox}.  The system is not tied
+to these specific emulators---it can as well manage physical machines,
+given the appropriate control specifications.
+
+This document itself is a
+\href{http://en.wikipedia.org/wiki/Literate_programming}%
+{literate program}---it is both a human-readable description of the
+system, as well as the source code of the system itself.
+
+\section*{Target Audience}
+
+This document would be useful to two audiences:
+\begin{itemize}
+\item Users of the system would find part~\ref{part.intro}, which
+  contains an overview and a user guide, to be of interest.
+\item For the maintainers of the system,
+  part~\ref{part.implementation} contains the implementation itself.
+\end{itemize}
+
+\section*{Document Overview}
+
+\begin{itemize}
+\item Chapter~\vref{chap.introduction} describes the rationale and the
+  requirements for the system.
+\item Chapter~\vref{chap.userguide} contains a brief user guide
+  showing how the system may be used.
+\item Chapter~\vref{chap.overview} presents an overview of the
+  implementation.
+\item Chapter~\vref{chap.slave} describes the implementation of the
+  build slave.
+\item Chapter~\vref{chap.master} describes the implementation of the
+  build master.
+\end{itemize}
+
+\section*{Legal Notice}
+Copyright \copyright{} 2012 Joseph Koshy.  All rights reserved.
+
+\vskip.8\baselineskip
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+\begin{itemize}
+\item Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+\item 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.
+\end{itemize}
+
+\subsubsection*{Disclaimer}
+
+THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR AND CON\-TRIBUTORS
+``\hskip-0.5ex{}AS~IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MER\-CHANT\-ABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR AND CON\-TRIBUTORS BE LIABLE
+FOR ANY DIRECT, IN\-DIRECT, INCIDENT\-AL, SPECIAL, EX\-EMPLARY, OR
+CON\-SEQUENT\-IAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PRO\-CURE\-MENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHE\-THER IN CONTRACT, STRICT LIA\-BILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHER\-WISE) ARISING IN ANY WAY OUT OF THE
+USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.
+
+\vskip.8\baselineskip
+
+Many of the designations used by manufacturers and sellers to
+distinguish their products are claimed as trademarks. Where those
+designations appear in this document, and the author and contributors
+were aware of the trademark claim, the designations have been followed
+by the ``\raisebox{-.5ex}{\texttrademark}'' or the ``\textregistered'' symbol.
+
+% The rest of the text proper.
+\mainmatter
diff --git a/tools/build-automation/implementation.nw b/tools/build-automation/implementation.nw
new file mode 100644
index 000000000000..b640fecd0b83
--- /dev/null
+++ b/tools/build-automation/implementation.nw
@@ -0,0 +1,89 @@
+% $Id: implementation.nw 2555 2012-08-29 13:16:38Z jkoshy $
+%
+% The implementation itself.
+
+\part{The Implementation}\label{part.implementation}
+
+\chapter{Overview}\label{chap.overview}
+
+\chapter{Protocol}\label{chap.protocol}
+
+From the despatcher to the slave.
+
+\begin{itemize}
+\item \protodef{BYE}{\protoarg{nbytes}}
+
+  Terminate the session.  A human readable message providing the
+  reason for termination follows.
+
+\item \protodef{CLOSE}{\protoarg{token} \protoarg{childfd}}
+
+  Close a file descriptor for a running script.
+
+\item \protodef{CWD}{\protoarg{childfd}}
+
+  Set the current directory for new scripts.
+
+\item \protodef{ENV}{\protoarg{nbytes}}
+
+  Store a default environment for use with subsequent
+  \protodef{SCRIPT} commands.
+
+\item \protodef{ERROR}{\protoarg{severity} \protoarg{nbytes}}
+
+  Receive an error message sent from the despatcher.
+
+\item \protodef{SCRIPT}{\protoarg{token} \protoarg{uid} \protoarg{gid} \protoarg{nbytes} \protoarg{fd}\ldots}
+
+  Execute a script with the given privileges, while monitoring the
+  specified file descriptors.
+
+\item \protodef{SIGNAL}{\protoarg{token} \protoarg{signal}}
+
+  Send a signal to an executing script.
+
+\item \protodef{STATUS}{\protoarg{token}}
+
+  Retrieve the status of a previously issued \protocmd{SCRIPT}
+  command.
+
+\item \protodef{SYSINFO}{}
+
+  Return system information.
+
+\item \protodef{WRITE}{\protoarg{token} \protoarg{fd} \protoarg{nbytes}}
+
+  Write to an executing script on the specified file descriptor.
+\end{itemize}
+
+From the slave to the despatcher:
+
+\begin{itemize}
+\item \protodef{CLOSE}{\protoarg{token} \protoarg{fd}}
+
+  Report the closing of a file descriptor by a script.
+
+\item \protodef{DATA}{\protoarg{token} \protoarg{fd} \protoarg{nbytes}}
+
+  Read data generated by a script.
+
+\item \protodef{ERROR}{\protoarg{args}\ldots}
+
+  Report an error.
+
+\item \protodef{EXIT}{\protoarg{token} \protoarg{exittype} \protoarg{code}}
+
+  Report a script exit.
+
+\item \protodef{HELLO}{\protoarg{identifier} \protoarg{version}}
+
+  Announce presence to the despatcher.
+
+\item \protodef{OK}{\protoarg{args}\ldots}
+
+  Acknowledge successful execution of a command.
+
+\item \protodef{SYSINFO}{\protoarg{nbytes}}
+
+  Return system information.
+\end{itemize}
diff --git a/tools/build-automation/introduction.nw b/tools/build-automation/introduction.nw
new file mode 100644
index 000000000000..9e51864ec4b7
--- /dev/null
+++ b/tools/build-automation/introduction.nw
@@ -0,0 +1,82 @@
+% $Id: introduction.nw 2532 2012-08-03 06:31:47Z jkoshy $
+%
+% The introduction to the build system.
+
+\part{The Build System}\label{part.intro}
+
+\chapter{Introduction}\label{chap.introduction}
+
+\section{Design Goals}
+
+\begin{goal}
+  The system should support build and testing our source tree, on the
+  target operating systems and machine architectures of our interest.
+\end{goal}
+
+This is the primary design goal for the tool, its
+\foreignphrase{raison d'\^etre}.
+
+\begin{goal}
+  The system should support building and testing our source tree on
+  non-native architectures (relative to the build host).
+\end{goal}
+
+Builds on non-native machine architectures and operating systems are
+would involve the use of virtual machines and CPU emulators.  The
+actual build will be done using \tool{make} or equivalent utility.
+
+\begin{goal}
+  The system should be easy to use.
+\end{goal}
+
+Defining a build needs to be intuitive, and should utilize
+pre-existing tools where possible.
+
+The number of new notations and file formats that a user needs to
+learn should be kept to a minimum.
+
+Invoking a build should be simple.  Sensible defaults should be used
+to minimize the need for user input at the time of invocation.
+
+\begin{goal}
+  The system should be able to run entirely on a relatively power and
+  resource constrained system such as a laptop, i.e., without needing
+  a beefy build box, or architecture-specific hardware.
+\end{goal}
+
+The ability to be able to work using a low power compute platform is a
+necessity in the project's current development environment
+
+The need to be frugal in resource consumption rules out the use of
+certain convenient but resource hungry implementation options.
+
+\begin{goal}
+  The system should work in ``offline'' mode, without requiring
+  external network access to function.
+\end{goal}
+
+The intent is to be able to work in ``standalone'' mode, without
+needing to contact a master server on the network.
+
+\begin{goal}
+  The system should allow a source tree that is in-development to be
+  built and tested, prior to a check-in.
+\end{goal}
+
+This system is primarily a development aid, and not primarily a tool
+for implementing continuous integration.
+
+\begin{goal}
+  The system should be easy to deploy, with the minimum of software
+  dependencies.
+\end{goal}
+
+The fewer dependencies on third party packages, the easier it is to
+support target operating systems.
+
+\begin{goal}
+  The utility should be easy to port to a new operating system.
+\end{goal}
+
+This goal is meant to reduce the effort needed to support new
+operating systems.
diff --git a/tools/build-automation/master.nw b/tools/build-automation/master.nw
new file mode 100644
index 000000000000..f929da28b3f3
--- /dev/null
+++ b/tools/build-automation/master.nw
@@ -0,0 +1,13 @@
+% $Id: master.nw 2461 2012-03-11 10:15:00Z jkoshy $
+%
+% The build master.
+
+\chapter{The Build Master}\label{chap.master}
+
+% Stub.
+<<build-master>>=
+def main():
+    print "Hello World\n"
+@ %def main
+
+% End-of-file.
diff --git a/tools/build-automation/slave.nw b/tools/build-automation/slave.nw
new file mode 100644
index 000000000000..bcdfbd8a4aaf
--- /dev/null
+++ b/tools/build-automation/slave.nw
@@ -0,0 +1,340 @@
+% -*- mode: Noweb; -*-
+%
+% $Id: slave.nw 2561 2012-08-31 02:46:33Z jkoshy $
+%
+% The build slave.
+
+\chapter{The Build Slave}\label{chap.slave}
+
+\section{Overview}
+
+\paragraph{File structure}
+
+The implementation of the \tool{yabs} slave is structured along
+conventional lines.
+
+<<slave/slave.c>>=
+<<generated file warning>>
+<<slave: include headers>>
+<<slave: declare types and constants>>
+<<slave: define helper functions>>
+<<slave: define main()>>
+@
+
+\section{Data Types}
+
+The data structures used in the \tool{yabs} slave are:
+
+\begin{itemize}
+\item A data structure to record command-line options
+  ([[struct slave_options]]).
+\item Others...(TBD).
+\end{itemize}
+
+<<slave: declare types and constants>>=
+<<define common constants>>
+<<slave: declare slave options>>
+@
+
+\paragraph{Slave Options}\label{para:slave-options}
+
+The [[slave_options]] structure is used to track the options
+controlling the slave's behavior.
+
+This structure is populated in the \func{main} function.
+
+<<slave: declare slave options>>=
+struct slave_options {
+	char 		*sl_id;
+	unsigned long	sl_port;
+	const char 	*sl_server;
+	enum yabs_server_type sl_servertype;
+	int   		sl_verbose;
+};
+@ %def slave_options
+
+\begin{itemize}
+\item The \var{sl\_id} member specifies the identifier that the slave
+  sends to the \tool{yabs} despatcher at connect time.
+
+  The default identifier is the system's hostname (see chunk
+  [[<<slave: set the slave identifier if not set>>]]).  The ``-i''
+  option is used to change the identifier (see [[<<slave: handle -i>>]]).
+\item The \var{sl\_port} field specifies the TCP port on the server
+  running the \tool{yabs} despatcher that the slave should connect to.
+  This is overrideable by the ``-p'' command-line option (see
+  [[<<slave: handle -p>>]]).
+\item The \var{sl\_server} field specifies the server to connect to.
+  The \var{sc\_servertype} field specifies whether to use a TCP
+  connection, a local socket, or to use standard input and output
+  (see [[enum yabs_server_type]]).
+\item The \var{sl\_verbose} field specifies the verbosity level for
+  the slave.
+\end{itemize}
+
+<<slave: initialize option structure>>=
+options.sl_id = NULL;
+options.sl_port = YABS_DEFAULT_DESPATCHER_PORT;
+options.sl_server = NULL;
+options.sl_servertype = YABS_SERVER_STDIN;
+options.sl_verbose = 0;
+@
+
+\section{The Program Entry Point}
+
+<<slave: define main()>>=
+int
+main(int argc, char **argv)
+{
+	<<slave: main: local variables>>
+	<<slave: initialize option structure>>
+	<<slave: parse options>>
+	<<slave: invoke libevent main loop>>
+	return (0);
+}
+@ %def main
+
+The [[<<slave: main: local variables>>]] chunk declares the local
+variables needed by the function.
+
+\paragraph{Option Parsing}
+
+Option parsing uses the POSIX \func{getopt} API.  The end result of
+the option parsing is an appropriately configured [[slave_options]]
+structure.
+
+<<slave: main: local variables>>=
+struct slave_options options;
+int option;
+@
+
+<<slave: parse options>>=
+while ((option = getopt(argc, argv, "hi:p:vV")) != -1) {
+	switch (option) {
+	case 'h':
+		display_usage_message(); exit(0);
+		break;
+	case 'i':
+                <<slave: handle -i>>
+		break;
+	case 'p':
+		<<slave: handle -p>>
+		break;
+	case 'v':
+		<<slave: handle -v>>
+		break;
+	case 'V':
+		<<slave: handle -V>>
+		break;
+	case '?':
+		display_usage_message(); exit(1);
+		break;
+	default:
+		errx(1, "FATAL: Unrecognized option value %c (%d)",
+		    option, option);
+		break;
+	}
+}
+
+<<slave: set the slave identifier if not set>>
+@
+
+\paragraph{Handling ``-i''}
+The identifier by which the slave identifies itself to the despatcher
+can be set using the ``-i'' option.  If this option is specified
+multiple times, the last one takes precedence.
+
+<<slave: handle -i>>=
+if (options.sl_id)
+    free(options.sl_id);
+options.sl_id = strdup(optarg);
+@
+
+\paragraph{Handling ``-p''}
+The ``-p'' option is used to specify the port the slave should connect
+to.  It is required to be a decimal number: we use the \func{strtoul}
+function to convert the option argument to a number.
+
+<<slave: main: local variables>>=
+char    *end;
+@
+
+<<slave: handle -p>>=
+options.sl_port = strtoul(optarg, &end, 10);
+if (options.sl_port == 0 || *end != '\0')
+	errx(1, "Invalid port number \"%s\"", optarg);
+@
+
+\paragraph{Handling ``-v'''}
+The ``-v'' option increases verbosity.  The current verbosity level is
+recorded in the \var{sc\_verbose} field.
+
+<<slave: handle -v>>=
+options.sl_verbose++;
+@
+
+\paragraph{Handling ``-V''}
+The ``-V'' option prints a version number, and exits.
+
+<<slave: declare types and constants>>=
+#define	YABS_SLAVE_NAME		"yabs-slave"
+@ %def YABS_SLAVE_NAME
+
+<<slave: handle -V>>=
+(void) printf(YABS_SLAVE_NAME " " YABS_SLAVE_VERSION " (Protocol: "
+    YABS_PROTOCOL_VERSION ")\n");
+exit(0);
+@
+
+\paragraph{Setting a default identifier}
+
+If an identifier was not specified by a '-i' command line option, we
+use the name of the host the slave is running on.
+
+<<slave: set the slave identifier if not set>>=
+if (options.sl_id == NULL) {
+	<<slave: allocate space for the slave identifier>>
+        <<slave: retrieve the host name>>
+}
+@
+
+<<slave: allocate space for the slave identifier>>=
+if ((options.sl_id = malloc(HOST_NAME_MAX)) == NULL)
+	err(1, "malloc failed: [%s,%d]", __FILE__, __LINE__);
+@
+
+The system's host name is retrieved using the \func{gethostname} library
+function.   We explicitly NUL-terminate the array after calling \func{gethostname},
+since portable programs cannot assume that function does so for host names
+that are exactly HOST\_NAME\_MAX bytes long.
+
+<<slave: retrieve the host name>>=
+if (gethostname(options.sl_id, HOST_NAME_MAX) < 0)
+	err(1, "gethostname failed: [%s,%d]", __FILE__, __LINE__);
+options.sl_id[HOST_NAME_MAX - 1] = '\0';
+@
+
+\paragraph{Invoking libevent}
+
+<<slave: invoke libevent main loop>>=
+event_base_loop((void *) 0, 0);
+@
+\section{Helper Functions}
+
+<<slave: define helper functions>>=
+void
+display_usage_message(void)
+{
+	(void) printf("usage: " YABS_SLAVE_NAME " [options] [server]\n\n" \
+    	    "Supported options:\n" \
+	    "    -h\t\tPrint a help message and exit.\n" \
+	    "    -i ID\tUse ID as an identifier [host name]\n" \
+	    "    -p PORT\tConnect to port PORT on the server [0x4242].\n" \
+	    "    -v\t\tBe more verbose.\n" \
+	    "    -V\t\tPrint a version identifier and exit.\n");
+}
+@ %def display_usage_message
+
+\section{Header Inclusions}
+
+The use of the \func{errx} family of functions requires the standard
+header \file{err.h}.
+
+<<slave: include headers>>=
+#include <err.h>
+@
+
+The \var{HOST\_NAME\_MAX} constant used in the chunk
+[[<<slave: set the slave identifier if not set>>]] is
+defined by the \file{limits.h} header.
+
+<<slave: include headers>>=
+#include <limits.h>
+@
+
+
+The use of the \func{printf} function requires the use of the system
+header \file{stdio.h}.
+
+<<slave: include headers>>=
+#include <stdio.h>
+@
+
+The header file \file{stdlib.h} is needed for the prototypes for the
+\func{exit}, \func{free} and \func{malloc} functions.
+
+<<slave: include headers>>=
+#include <stdlib.h>
+@
+
+The header file \file{string.h} provides the prototype for
+\func{strdup} used in chunk [[<<Handling ``-i''>>]].
+
+<<slave: include headers>>=
+#include <string.h>
+@
+
+The header file \file{unistd.h} is needed for the prototype for the
+\func{getopt} function used in chunk [[<<slave: parse options>>]].
+
+<<slave: include headers>>=
+#include <unistd.h>
+@
+
+\tool{Libevent} specific headers are needed for the libevent APIs:
+<<slave: include headers>>=
+#include <event2/event.h>
+@
+
+
+\section{Build Rules}
+
+Using the facilities provided by the standard rules in
+\verb|<bsd.prog.mk>|, a simple \file{Makefile} suffices to build the
+slave.
+
+The \file{Makefile} indicates that the generated progam is to be
+called \tool{yabs-slave} and that the file \file{slave.c} is the
+source file to be compiled.  The contents of this source file is
+defined by the chunk [[<<slave/slave.c>>]].
+
+<<slave/Makefile>>=
+PROG=		yabs-slave
+SRCS=		slave.c
+
+CFLAGS+=	-Wall -Wextra -Werror -pedantic
+<<make: libevent related definitions>>
+
+.include <bsd.prog.mk>
+
+<<make: override debug flags during development>>
+@
+
+We look in a set of standard locations to determine where the headers
+and library files for \tool{libevent} are located.
+
+<<make: libevent related definitions>>=
+.if exists(${HOME}/local/include/event2)
+LIBEVENT_INCLUDE= -I ${HOME}/local/include
+LIBEVENT_LIB=     -L ${HOME}/local/lib
+.elif exists(/usr/local/include/event2)
+LIBEVENT_INCLUDE= -I /usr/local/include
+LIBEVENT_LIB=     -L /usr/local/lib
+.endif
+
+CFLAGS+=        ${LIBEVENT_INCLUDE}
+LDADD+=         ${LIBEVENT_LIB} -levent
+@
+
+Debugging is simpler if compiler optimizations are turned off.  We
+thus remove the \term{-O2} flag during development.
+
+<<make: override debug flags during development>>=
+CFLAGS:=    ${CFLAGS:N-O2} -g
+LDFLAGS+=   -g
+@
+
+% Local Variables:
+% noweb-code-mode: c-mode
+% c-electric-flag: nil
+% End:
diff --git a/tools/build-automation/userguide.nw b/tools/build-automation/userguide.nw
new file mode 100644
index 000000000000..8295661821a0
--- /dev/null
+++ b/tools/build-automation/userguide.nw
@@ -0,0 +1,80 @@
+% $Id: userguide.nw 2556 2012-08-29 13:17:07Z jkoshy $
+%
+% A user guide on how to use the system--configuring and running a
+% build.
+
+\chapter{Using The Build System}\label{chap.userguide}
+
+This chapter describes how to use the system.
+
+\section{Terminology}
+
+First, some definitions:
+
+\begin{itemize}
+
+\item A \definition{machine} is hardware that could be invoked during
+  the execution of a job.
+
+  A ``machine'' could be a physical machines that is to be powered up
+  for the job, or a virtual machine that is to be started up.
+
+  The \tool{yabs} utility uses user-provided shell script fragments to
+  control machines.  Hence a ``machine'' could also be an invocation
+  of a remote host via the \tool{ssh} program.
+
+  A machine is expected to execute the ``slave'' program (see below)
+  once it is has booted.
+
+\item A \definition{job definition} specifies the information needed
+  to run a job.   A job definition will specify:
+
+  \begin{itemize}
+
+  \item The list of machines to be invoked.
+  \item The specific commands be run inside each machine.
+  \item The results to retrieved from each machine, after the
+    commands are run.
+  \item The name of a ``job scheduler'' (see below).
+  \end{itemize}
+
+\item A \definition{job} is a particular invocation of a \term{job
+    definition}.
+
+\item A \definition{job scheduler} is a program that implements the
+  logic for starting and stopping individual steps that are part of a
+  job.  The system provides a default scheduler which would suffice
+  for most cases.  Users can override the default scheduler if their
+  jobs have special needs.
+
+\item The \tool{yabs} \definition{slave} is a program that runs
+  inside a booted machine, running the tasks defined in the
+  job definition.
+
+\item A \definition{slave script} is a shell script that lists the
+  actions to be executed inside a particular virtual machine.  Slave
+  scripts are usually written in the shell (\tool{sh}) programming
+  language.
+\end{itemize}
+
+\section{Configuration}
+
+TODO: describe how to configure the tool.
+
+% File locations for $ROOT:
+%     /etc/yabs/default/
+%     /etc/yabs/<job-name>/
+%     $HOME/.yabs/default/
+%     $HOME/.yabs/<job-name>/
+
+
+% $ROOT/build-name/config           -- configuration
+% $ROOT/build-name/scheduler        -- which order to run stuff
+
+% $ROOT/build-name/<machine>.startup -- how to (externally) start the machine
+% $ROOT/build-name/<machine>.shutdown -- how to (externally) stop the machine
+% $ROOT/build-name/<machine>.commands -- the build commands to be issued
+
+% Logs:
+
+% /var/logs/yabs/build-name.NNN
diff --git a/tools/build-automation/utilities.nw b/tools/build-automation/utilities.nw
new file mode 100644
index 000000000000..cb308f89ec22
--- /dev/null
+++ b/tools/build-automation/utilities.nw
@@ -0,0 +1,38 @@
+% $Id$
+%
+% Code chunks containing utility functions.
+
+\chapter{Common Code}\label{chap.utility}
+
+\paragraph{Default despatcher port}
+<<define common constants>>=
+#define	YABS_DEFAULT_DESPATCHER_PORT    0x4242
+@ %def YABS_DEFAULT_DESPATCHER_PORT
+
+\paragraph{Version numbers}
+<<define common constants>>=
+#define YABS_PROTOCOL_VERSION	"1.0"
+#define YABS_SLAVE_VERSION	"1.0"
+@ %def YABS_SLAVE_VERSION YABS_PROTOCOL_VERSION
+
+\paragraph{Slave connection types}
+<<define common constants>>=
+enum yabs_server_type {
+     YABS_SERVER_STDIN,
+     YABS_SERVER_LOCAL,
+     YABS_SERVER_TCP
+};
+@ %def yabs_server_type YABS_SERVER_STDIN YABS_SERVER_LOCAL YABS_SERVER_TCP
+
+\paragraph{Warning Template}
+
+<<generated file warning>>=
+/*
+ * WARNING.   GENERATED CODE.  DO NOT EDIT.
+ *
+ * This file contained generated code.   You should be looking at
+ * its literate program source instead.
+ *
+ * WARNING.   GENERATED CODE.  DO NOT EDIT.
+ */
+@
diff --git a/tools/build-automation/yabs-slave.1 b/tools/build-automation/yabs-slave.1
new file mode 100644
index 000000000000..375b92b25556
--- /dev/null
+++ b/tools/build-automation/yabs-slave.1
@@ -0,0 +1,102 @@
+.\" Copyright (c) 2012 Joseph Koshy.  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 Joseph Koshy ``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 Joseph Koshy 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.
+.\"
+.\" $Id$
+.\"
+.Dd August 31, 2012
+.Os
+.Dt YABS-SLAVE 1
+.Sh NAME
+.Nm yabs-slave
+.Nd the slave program for the Elftoolchain system
+.Sh SYNOPSIS
+.Nm
+.Op Fl h
+.Op Fl i Ar identifier
+.Op Fl p Ar port
+.Op Fl v
+.Op Fl V
+.Op Ar server
+.Sh DESCRIPTION
+The
+.Nm
+utility is part of the
+.Nm yabs
+build automation system.
+It is intended to be executed inside a machine participating in a
+build job.
+The
+.Nm
+utility connects back to a
+.Nm yabs
+job despatcher, receives commands to execute and sends back the
+results of executing these commands.
+.Pp
+The optional argument
+.Ar server
+specifies the
+.Nm yabs
+server to connect to.
+This argument specifies a hostname, an IPv4 or IPv6 address, or a path to
+a local socket.
+If the
+.Ar server
+argument is not specified, then
+.Nm
+will read from standard input and write to standard output.
+.Pp
+The
+.Nm
+utility recognizes the following options:
+.Bl -tag -width indent
+.It Fl h
+Print a help message and exit.
+.It Fl i Ar identifier
+Use the argument
+.Ar identifier
+when connecting to the despatcher.
+The default is to use the hostname of the system.
+.It Fl p Ar port
+Connect to the port specified by the argument
+.Ar port.
+The argument must be a decimal number.
+This option is ignored if the argument
+.Ar server
+is not specified, or if it specifies a local socket.
+.It Fl v
+Increase verbosity.
+This flag may be specified multiple times.
+.It Fl V
+Print a version number and exit.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh SEE ALSO
+.Xr sh 1 ,
+.Xr yabs 1
+.Sh HISTORY
+The
+.Nm
+utility was created by
+.An "Joseph Koshy" Aq jkoshy@users.sourceforge.net
+under the aegis of the Elftoolchain project.
diff --git a/tools/build-automation/yabs.1 b/tools/build-automation/yabs.1
new file mode 100644
index 000000000000..8451dce1de35
--- /dev/null
+++ b/tools/build-automation/yabs.1
@@ -0,0 +1,117 @@
+.\" Copyright (c) 2012 Joseph Koshy.  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 Joseph Koshy ``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 Joseph Koshy 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.
+.\"
+.\" $Id$
+.\"
+.Dd August 29, 2012
+.Os
+.Dt YABS 1
+.Sh NAME
+.Nm yabs
+.Nd yet another job scheduler
+.Sh SYNOPSIS
+.Nm
+.Op Fl c Ar configdir
+.Op Fl d
+.Op Fl v
+.Ar jobname
+.Pp
+.Nm
+.Ar sub-command
+.Op Ar sub-command-options
+.Sh DESCRIPTION
+The
+.Nm
+utility schedules jobs that span multiple machines.
+A typical use for this utility would be to control multi-machine
+software builds.
+.Pp
+The first form of invocation is used to invoke a job.
+The argument
+.Ar jobname
+should specify the name of job description specified in a
+configuration file.
+.Pp
+The second form of invocation is used inside slave and scheduler
+scripts.
+.Pp
+The
+.Nm
+utility recognizes the following options:
+.Bl -tag -width indent
+.It Fl c Ar configdir
+Search for configuration information in directory
+.Ar configdir .
+This option may be specified multiple times.
+The default is to look under
+.Pa $HOME/.yabs
+and the system default directory
+.Pa /etc/yabs .
+.It Fl d
+Enable job debugging.
+.It Fl v
+Be verbose.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh FILES
+.Bl -tag -width indent
+.It Pa /etc/yabs/default/
+System-wide default configuration information.
+.It Pa /etc/yabs/ Ns Ar jobname
+System-wide configuration for job
+.Ar jobname .
+.It Pa $HOME/.yabs/default
+Per-user default configuration information.
+.It Pa $HOME/.yabs/ Ns Ar jobname
+Per-user configuration for job
+.Ar jobname .
+.It Pa /var/log/yabs/ Ns Ar jobname Ns . Ns Ar number Ns /
+Directory containing the log files generated by a job.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width indent
+.It Li YABS_JOB
+(Set by
+.Nm )
+The current job identifier.
+This a string of the form
+.Dq Ar jobname Ns . Ns Ar number .
+.It Li YABS_SLAVE
+(Set by
+.Nm )
+The current slave identifier.
+.El
+.Sh EXAMPLES
+To invoke a job named
+.Sq myjob ,
+use:
+.Dl $ yabs myjob
+.Sh SEE ALSO
+.Xr sh 1
+.Sh HISTORY
+The
+.Nm
+utility was created by
+.An "Joseph Koshy" Aq jkoshy@users.sourceforge.net
+under the aegis of the Elftoolchain project.