gdo-0.1.2: README.org

#+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/>.