1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
\documentclass[letterpaper]{book}
\usepackage{listings}
\begin{document}
\title{Xagasoft Build Manual}
\author{Mike Buland}
\date{November 2012}
\maketitle
\tableofcontents
\chapter{Introduction}
Build is a self-contained, sophisticated tool for performing multi-step
processes. The primary goal is to be able to replace the standard
configure/make or cmake/make systems that have become quite popular.
By default Build will work much as one would expect for compiling software, it
uses file exisistance and timestamps to determine what to build, and every file
has a list of dependant files and input files.
However, this is only the default configuration, you can use anything as the
condition for determining what to build or rebuild, and targets do not have to
be files.
Build boasts a sophisticated system for chaining rules together to take files
through as many steps as necesarry to get them in the desirable foramt for input
to the final step. This may sound a little vague and confusing, but what it
means in the end is that you can list, say, a bison file as on input to an
executable target that requires object (.o) files. In this case build will
automatically figure out that it can get a .c file from the .y input file, and
a .o file from the .c file. It will autogenerate these targets for you and
save a lot of time and effort on your part.
\chapter{Structure of a Build File}
Build files contain build script along with four major types of declerations.
These are the major types that can be decared:
\begin{description}
\item[Targets] \hfill \\
Explicit targets can be defined that represent units of work with a definate
goal and possibly inputs that can be other targets.
\item[Actions] \hfill \\
Actions are triggered from the command line and determine what targets to
build and how.
\item[Rules] \hfill \\
Rules determine both how to build explicit targets to make life easier as
well as how to auto-generate implicit targets. An explicitly defined target
does not need to use a rule, but it can make everything easier.
\item[Functions] \hfill \\
Functions can be defined like in most programming languages, and called
anywhere in the script. Functions can also be used in several key places in
targets to extend the functionality of build.
\end{description}
Build script also allows you to declare and use variables like many other
scripting languages, which can be integers, floats, booleans, strings, lists,
the special value null, and file handles.
\section{A Quick Example}
Let's start with a very basic example. This example is capable of building an
executable from any number of cpp source files:
\begin{lstlisting}
target "myprogram"
{
rule "exe";
input files("src/*.cpp");
}
\end{lstlisting}
This example doesn't set any special compliation or linking flags, but it is a
complete and valid build file. It will find all cpp files in src, generate an
implicit target for each file to compile it into an object (.o) file, and then
use those files as the input to the myprogram target in the end.
\section{Targets}
A target represents a unit of work. This is usually a file in a compilation
process, e.g. an object file, an executable, a library, et cetera. Targets
come in two major flavors: explicit and implicit. Explicit targets are any
targets that you define in a build script with the "target" keyword. Targets
can also be auto-generated by rules when needed, these are known as implicit
targets.
If a target is declared more than once the two targets are merged. You can
think of this as a newer target overriding \emph{parts} of an older target. It
does not replace the previous target.
Targets can be declared inside of any linguistic construct, including if blocks
and loops, this gives you a lot of flexibility, but in addition, you can
specify a list of strings instead of a single string for the name of a target,
this creates a target with the same specs for each name in the list.
Targets can contain the following special keywords:
\begin{description}
\item[input] \hfill \\
You can specify any expression that results in a string or list of strings.
These strings will be added to the list of inputs to this target, and if
they are targets they will be added as dependancies. If you have a rule
specified then the list of inputs will be used to generate implicit targets
to satisfy dependancies.
\item[requires] \hfill \\
\item[profile] \hfill \\
\item[rule] \hfill \\
\item[tag] \hfill \\
\item[display] \hfill \\
\end{description}
\section{Actions}
Actions are the primary interface to build scripts from the command line, when
calling build you specify an action to run. If no action is specified on the
command line the action "default" is run. If the build script doesn't specify
a default action, one is generated for it that will attempt to build all
explicit targets.
Actions can contain almost any build script, plus an extra syntax that allows
you to process a list of targets in a given profile (see the targets section
for details). Basically this means that you have a lot of flexibility
controlling how your targets are processed.
Let's start with an example:
\begin{lstlisting}
action "default"
{
build: "myprogram";
}
\end{lstlisting}
This is as basic as it gets, this example will cause build to process the
target "myprogram" using the profile "build".
\end{document}
|
