gdo

recursive atomic build system

Latest on Hackage:0.1.5

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.

GPL-3 licensed by Sebastian Jordan
#+TITLE: GDO
#+SECTION: 1
#+date: January 07, 2016
* NAME
gdo - atomic build system

* SYNOPSIS
*gdo* [ *--if* mode] [ *-h* ] target ...

* DESCRIPTION
*gdo* is a build system similar to *GNU Make*. It builds files from
sources and recipes.

* RECIPES
Recipes have the suffix *.do*. So for a target *targetfile* the
recipe would be *targetfile.do*.

The recipes are regulare, executable files which build the target.

For a script to work as a do file it must specify the required
interpreter in the magic line of the file.
When using *sh* as an interpreter this would be
#+begin_src sh
#!/usr/bin/env sh
#+end_src
or
#+begin_src sh
#!/bin/sh
#+end_src
where the first method is prefered. To function properly on
different platforms. The script must be marked as executable so
that a call to *exec* can be successful.

It is technically possible to use binaries for that task but is
highly discouraged because a binary format is not understandable by
a human. This is especially harmful to the users security in build
system because a file can hide malicious code.

*gdo* is designed to run recursivly. To signal a dependency for a
target to another file you call *gdo* from inside the targets do
file with the appropriate mode.

A target always implicitly depends on its do file.

** ARGUMENTS
A do script is called with arguments by the *gdo* program. The
first argument that is passed to the do script is the directory
where the target file gets stored in. This can be userful for
defining default do files.

The second argument passed to the do script is the base name of the
target. For the target *targetfile.c* this would be *targetfile*,
for the target *targetfile.c.in* this would be *targetfile.c*.

The third argument passed to the do file the temporary file where
the target should be build to. It is undefined behaviour to build
directly to the target name and can lead errors during the build
process.

** MODES
Modes are only used inside of recipes. They do not work when used
outside of recipes. Modes exist to signal dependencies to other
files that the target (might) depend on.

* Changed :: This mode is used to signal that the target is out of
date if the specified arguments to a *gdo* call are out
of date. An example for this would be an object file
generated by a C compiler that depends on a C source
file.

An example *hello.o.do* file that uses *gdo --if
Changed*:
#+begin_src sh
#!/usr/bin/env sh

gdo --if Changed hello.c

cc -c hello.c -o $3
#+end_src

* Created :: This mode signals that a target is out of date if a
specific file gets created on the file system. This
can be useful when dealing with C header files. This
way you can issue a recompilation when you create a
header file that is used for the linking process of
your program that precedes an already existing header
file with the same name in the compilers search path.

An example *hello.do* file that uses *gdo --if Created*
#+begin_src sh
#!/usr/bin/env sh

gdo --if Changed hello.c
gdo --if Created stdio.h

cc -I. hello.c -o $3
#+end_src

** DEFAULT DO FILES
If there is no recipe for a targetfile, *gdo* will look for a
default rule based on the targets file extension. This only works
for files which have an extension. Default do files are only
searched in the same directory as the target by default. You can
extend the search path via the environment variable *GDO\_DEFAULTS*.
When specified this variable must be a list of paths seperated by
colons. This path is searched for default do files after no
default do files was found in the same directory as the target is
in.

** EXAMPLE
The source code you received with this product should contain a set
of examples for using *gdo*. These examples can be found in the
*examples* directory.

This small example builds the "hello world" program in C. There
are 3 files in this directory: The first one is the source for the
program itself, *test.c*, the other two files are a do script for
the final executable *test.do* and a default do script for building
object files from C sources, *defaults/default.o.do*. To build the
example you have to first point to the defaults directory, so that
*gdo* can find the default do file. We assume that you are already
in the examples file of the gdo source code. Then issue *gdo* to
build the target *test*.
#+begin_src sh
export GDO_DEFAULTS=$PWD/defaults
gdo test
# output:
# redo "test"
# redo "test.o"
# redone "test.o"
# redone "test"
#+end_src
Now the targets should be build. You should take a look at the do
files to see some examples of what *gdo* is capable of.

* COPYRIGHT
Copyright (C) 2016 by Sebastian Jordan. This file is part of *gdo*.

*gdo* is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see
<http://www.gnu.org/licenses/>.
comments powered byDisqus