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