aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/build-manual.tex73
1 files changed, 72 insertions, 1 deletions
diff --git a/docs/build-manual.tex b/docs/build-manual.tex
index a85c20e..49be977 100644
--- a/docs/build-manual.tex
+++ b/docs/build-manual.tex
@@ -100,12 +100,81 @@ Targets can contain the following special keywords:
100 specified then the list of inputs will be used to generate implicit targets 100 specified then the list of inputs will be used to generate implicit targets
101 to satisfy dependancies. 101 to satisfy dependancies.
102 \item[requires] \hfill \\ 102 \item[requires] \hfill \\
103 \item[profile] \hfill \\ 103 Requires works just like input, except that the items here will not be added
104 to the list of inputs. They will be added as dependancies to figure out
105 when this target needs to be rebuilt, but will not be listed as inputs.
106 This is handy for things like libraries, datafiles, et cetera.
104 \item[rule] \hfill \\ 107 \item[rule] \hfill \\
108 You can optionally specify a single rule name by string. This rule will be
109 applied to this target before processing and used to provide the display,
110 profiles, and potentially additionally inputs and requirements. Rules can
111 also add additional tags.
105 \item[tag] \hfill \\ 112 \item[tag] \hfill \\
113 You can specify any number of tags. These can be used to group targets
114 together to find them easily for use in actions and other places. You can
115 use the handy targets() function to find all targets that match a given tag.
106 \item[display] \hfill \\ 116 \item[display] \hfill \\
117 You can optionally specify a string that will be displayed while this
118 action is being processed. If this action has a rule set or was implicitly
119 generated then the display name is set from the rule name. If a target is
120 explicit and does not have a rule then the default is an empty string.
121 \item[profile] \hfill \\
122 Profiles are in actuality scripts that handle the real work of processing
123 a target. Each target can have multiple profiles, and they can have any
124 name but the names "build" and "clean" have special meaning and life is
125 much easier if you use them. You can specify any number of profiles with
126 any name, another common name is "install".
107\end{description} 127\end{description}
108 128
129\subsection{Explicit Target Example With Rule}
130\begin{lstlisting}
131target "program"
132{
133 input ["input1.cpp", "input2.cpp", "input3.cpp"];
134 rule "exe";
135 tag "programs";
136 display "awesome exe";
137 requires "library.a";
138}
139\end{lstlisting}
140This example shows every option listed above except for profile.
141
142\subsection{Profiles}
143Each profile is basically just a script that is run when the target is
144processed. Unlike other build systems this is not a shell script, but build
145script. You can use any variables, functions, or constructs that you can use
146anywhere else. Very often these will use the execute() function to run
147commands.
148
149There is an extra property that can be set in any profile, and that's condition.
150Specifying a condition will allow you to change how build decides when it's
151appropriate to process that target in that profile. There are four builtin
152conditions: always, never, filetime, and fileexists. In the future it may also
153be possible to use a user-defined function as a condition.
154
155
156\subsection{Explicit Target Example Without Rule}
157\begin{lstlisting}
158target "datafile.zip"
159{
160 input files("data/*");
161 tag "datafile";
162 display "zip";
163 profile "build"
164 {
165 condition filetime;
166 execute("zip -u ${OUTPUT} ${INPUT}");
167 }
168 profile "clean"
169 {
170 condition fileexists;
171 unlink( OUTPUT );
172 }
173}
174\end{lstlisting}
175
176This example shows you how to build and clean a target that is a zipfile from
177it's component pieces.
109 178
110\section{Actions} 179\section{Actions}
111Actions are the primary interface to build scripts from the command line, when 180Actions are the primary interface to build scripts from the command line, when
@@ -131,4 +200,6 @@ action "default"
131This is as basic as it gets, this example will cause build to process the 200This is as basic as it gets, this example will cause build to process the
132target "myprogram" using the profile "build". 201target "myprogram" using the profile "build".
133 202
203
204
134\end{document} 205\end{document}