From c5d1304f04273b579e00f967ec564a8de3ea0e69 Mon Sep 17 00:00:00 2001 From: Mike Buland Date: Thu, 8 Nov 2012 20:38:56 +0000 Subject: Packaging updates, started on the manual, too. --- docs/build-manual.tex | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 docs/build-manual.tex (limited to 'docs') 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 @@ +\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} -- cgit v1.2.3