README

   1 Goals, an experimental tool that generalizes "make"
   2 ======================================================================
   3
   4
   5 Description
   6 -----------
   7
   8 Make is a clever tool for expressing dependencies between files and it
   9 is widely used for building software.  But it has some limitations.
  10 It only knows about files.  It has limited ways to write rules.  And
  11 for a tool whose main job is running shell commands, there are several
  12 gotchas when you actually write shell commands.
  13
  14 Goals is an experimental tool which aims to generalize make beyond
  15 these limitations.  It works for any resource, not just files:
  16
  17   is-url("https://example.com/uploads/software.tar.gz";) : "software.tar.gz" {
  18     scp %< example.com:/web/uploads/
  19   }
  20
  21 (You can write your own "predicates" like is-url in the example above).
  22 Goal recipes can be named, and can be called either by name or by
  23 automatically finding a matching predicate:
  24
  25   goal rebuild (pkg) = "%pkg.o" : "%pkg.c" { %CC %CFLAGS -c %< -o %@ }
  26
  27   goal link () = "prog" : "foo.o", "bar.o", rebuild ("baz") {...}
  28   #                        ▲         ▲       ▲
  29   #                        │         │       │
  30   #                        │         │     called by goal name
  31   #            called by pattern matching
  32
  33 Make has many built in functions, but in goals these can easily be
  34 written in the goals language as shell scripts, making it very
  35 extensible.  In fact goals consists of a core parser written natively,
  36 and a large amount of library code written in the goals language and
  37 shell script.  For example the equivalent of the make built in
  38 $(wildcard) function is:
  39
  40   function wildcard (wc) returning strings = @{
  41     shopt -s nullglob
  42     wc=%wc  ;# needed because of quoting
  43     for f in $wc; do
  44       echo "$f"
  45     done
  46   }
  47
  48 You can combine this into fairly complex recipes.  This is the outline
  49 Goalfile for doing a mass rebuild of Perl packages in dependency order
  50 in the Fedora build system (called Koji):
  51
  52   pure function all-perl-packages () = {
  53     cd %HOME/fedora
  54     echo '['
  55     for f in perl*; do
  56       test -f $f/$f.spec && echo '    is-koji-built("'$f'"),'
  57     done
  58     echo ']'
  59   }
  60
  61   goal rebuild (name) =
  62   is-koji-built ("%name") : build-requires (name) {
  63     cd %HOME/fedora/%name
  64     rpmdev-bumpspec %name.spec
  65     fedpkg commit -c
  66     fedpkg push
  67     fedpkg build
  68   }
  69
  70   pure function build-requires (name) = {
  71     # shell commands to examine spec file and derive list of
  72     # source BuildRequires
  73   }
  74
  75   predicate is-koji-built (name) = {
  76     # shell commands to check if latest NVR of %name from the spec
  77     # file matches the latest successful build in Koji
  78   }
  79
  80   goal all () = : all-perl-packages ()
  81
  82 The tool aims to retain some of the good properties of make, such as
  83 relative ease of use for simple things, and being interruptible.
  84
  85
  86 Compiling and running from source
  87 ---------------------------------
  88
  89 Requirements:
  90
  91  - OCaml compiler
  92
  93  - ocamllex (usually included with the OCaml compiler)
  94
  95  - ocaml findlib
  96
  97  - menhir (an OCaml-based parser generator)
  98
  99  - pod2man and pod2text (part of Perl, for generating documentation)
 100
 101  - autoconf and automake
 102
 103 To build from git:
 104
 105 $ ./autogen.sh
 106 $ make depend
 107 $ make
 108
 109 You don't need to install goals if you don't want to.  You can run it
 110 from the source directory using the ‘run’ script in the top level
 111 directory, eg:
 112
 113 some-project$ ../goals/run goals all
 114
 115 Note that goals uses itself to bootstrap.  This can cause problems
 116 when developing if you break goals so it can no longer parse its own
 117 files.  If you get into this situation then do:
 118
 119 $ rm src/goals
 120 $ make src/goals
 121
 122
 123 Development, bugs, patches, feedback
 124 ------------------------------------
 125
 126 Git repo is:
 127 http://git.annexia.org/?p=goals.git
 128
 129 List of known bugs or missing features is in the TODO file.
 130
 131 There is no bug tracker yet.  For the moment, email rjones@redhat.com