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. --- README.md | 92 ++++++++++++++++++++++++++++++++++ default.bld | 60 ++++++++++++++++++++++ docs/build-manual.tex | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++ pkg.bld | 6 ++- src/build.l | 4 +- 5 files changed, 293 insertions(+), 3 deletions(-) create mode 100644 README.md create mode 100644 docs/build-manual.tex diff --git a/README.md b/README.md new file mode 100644 index 0000000..3b055fb --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# Build + +Xagasoft Build is a comprehensive build tool for nearly any multi-step +automation process, but is intended primarily for compiling source code. + +Features: + + * Does _NOT_ rely on make of any sort. + * Can auto-generate targets based on builtin and user proided rules. + * Contains it's own turing complete scripting language. + * Provides a variety of output modes to make errors easier to see. + * Supports plugins. + * Write much, much less and do more. + * Builtin understanding of dependancy tracking. + +## Requirements + +There are different requirements depending on how you got your source code and +what you intend to do with it. If you just want to use build, then I recommend +getting one of the release tarballs. They include most of the dependancies and +are the easiest to use. + +### Tarball Releases + +To compile a tarball release you need: + + * bash (or similar) + * C++ compiler (gcc is the primary development target) + * libc with pthreads and libdl support (glibc and most compatibles) + +### SCM Checkouts + +If you're getting the code from source control or want to do more there are +these additional requirements: + + * flex + * bison + +The flex and bison source code are pre-processed into C source code for the +tarballs, so you do not need these programs in order to compile. + +Build also relies on libbu++, but the shell script 'build.sh' will check out +the files it needs from libbu++ SVN. These files are also included in the +tarball release. + +Build also builds the easiest when using build. Once you have a working +version of build it's very easy to keep working on build. + +# Example Build Scripts + +Just to give you a taste, here are some real, simple build scripts. + + target "filescan" + { + rule "exe"; + input files("src/*.cpp"); + CXXFLAGS += "-ggdb"; + LDFLAGS += "-lbu++"; + } + +Build has sensible defaults for many things, this creates an explicit target +named filescan that relies on the source code in the directory src. It adds +debugging flags, and it links libbu++. + +The build system uses a variation on a standard boolean transitive closure +algorithm to provide "path-finding" between the .cpp files and the inputs the +"exe" rule needs to create output. In this case it will automatically create +targets needed to produce all of the object code. + + CXXFLAGS += "-ggdb -I. -Ilibgats"; + LDFLAGS += "-ggdb"; + + target "libjove.a" + { + rule "lib"; + input files("src/libjove/*.cpp"); + } + + target "joved" + { + rule "exe"; + input files("src/joved/*.cpp"); + requires "libjove.a"; + + LDFLAGS += "-L. -ljove -lbu++ -Llibgats -lgats -lcryptopp -lpthread"; + } + +This example is slightly more complex. It sets some flags that all targets will +use, then creates two explicit targets. The second target, joved, also +requires that libjove.a is up to date, but it is not treated as an input. This +is enough to determine order of building, all source files, targets, and even +provides full dependancy tracking. diff --git a/default.bld b/default.bld index d88f3cd..467274b 100644 --- a/default.bld +++ b/default.bld @@ -9,6 +9,11 @@ CXXFLAGS += "-ggdb -W -Wall"; CC = CXX; // We actually want to use c++ to compile our c files. +if PREFIX == null then +{ + PREFIX = "/usr/local"; +} + action "default" { build: ["build", targets("plugins")]; @@ -24,6 +29,11 @@ action "clean" clean: "build"; } +action "docs" +{ + build: targets("docs"); +} + action "devinstall" { if "$(id -u)" != "0" then @@ -106,3 +116,53 @@ for vimdir in dirs("/usr/share/vim/vim*") do } } +target "docs/build-manual.pdf" +{ + display "pdflatex"; + tag "docs"; + profile "build" + { + condition always; + execute("mkdir -p docs/pdf"); + // You have to do this multiple times to get the TOC right. + for j in range(1,3) do + { + notice "Pass ${j}..."; + execute("cd docs/pdf; pdflatex ../build-manual.tex > /dev/null"); + } + execute("mv docs/pdf/build-manual.pdf docs"); + execute("rm -Rf docs/pdf"); + } +} + +target "docs/html-single/build-manual.html" +{ + display "htlatex"; + tag "docs"; + profile "build" + { + condition always; + execute("mkdir -p docs/html-single"); + execute("cd docs/html-single; htlatex ../build-manual.tex > /dev/null"); + } + profile "clean" + { + execute("rm -Rf docs/html-single"); + } +} + +target "docs/html-multi" +{ + display "htlatex"; + tag "docs"; + profile "build" + { + condition always; + execute("mkdir -p docs/html-multi"); + execute("cd docs/html-multi; htlatex ../build-manual.tex \"html,3\" > /dev/null"); + } + profile "clean" + { + execute("rm -Rf docs/html-multi"); + } +} 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} diff --git a/pkg.bld b/pkg.bld index 1f0e8f3..30c9668 100644 --- a/pkg.bld +++ b/pkg.bld @@ -22,6 +22,9 @@ target PKG_BASE files("*.bld"), "docs/build.1", "docs/build.7", + files("docs/build-manual.*"), + files("docs/html-multi/*"), + files("docs/html-single/*"), "build.sh", "version", "support/vim/syntax/build.vim", @@ -79,7 +82,8 @@ target PKG_BASE + ".xz" rule "tarball" { input matches("*.cpp", "*.h", "*.c", "*.y", "*.l", "*.bld", "Doxyfile", - "*.1", "*.7", "*.vim", "*.sh", "version"); + "*.1", "*.7", "*.vim", "*.sh", "version", "*.tex", "*.pdf", "*.html", + "*.css"); profile "build" { OUTDIR = OUTPUT.replace(".tar",""); diff --git a/src/build.l b/src/build.l index 30c79a6..7a77bfc 100644 --- a/src/build.l +++ b/src/build.l @@ -140,12 +140,12 @@ int iStrDepth = 0; return LTR_UNDEF; } --?([1-9][0-9]*)|(0) { +([1-9][0-9]*)|(0) { yylval->iVal = strtol( yytext, NULL, 10 ); return LTR_INT; } -(0\.0+)|(-?(([1-9][0-9]*)|(0))\.[0-9]*) { +(0\.0+)|((([1-9][0-9]*)|(0))\.[0-9]*) { yylval->fVal = strtof( yytext, NULL ); return LTR_FLOAT; } -- cgit v1.2.3