Command line parsing, the concept of publishing goals.
[goaljobs.git] / NOTES
1 ## NB ##
2
3 These notes reflect earlier thinking about the language and may not
4 necessarily accurately describe the current goaljobs language.  Please
5 read the documentation instead.
6
7 ## NB ##
8
9 Like 'make' except:
10  - Predicates can be based on arbitrary expressions, not just
11    "file X is older than file Y".
12  - Rules are more flexible and encourage structuring and reuse
13    through functions.
14  - Goals can be parameterized.
15  - Program can run continuously to implement business rules.
16
17 Differences from 'whenjobs':
18  - Goals instead of variables.
19  - Persistent (across session) variables exist, but are not central.
20  - Doesn't use <<..>> for shell scripts (has a function 'sh' instead).
21  - No daemon.
22
23 Similarities to 'whenjobs':
24  - Each shell script runs in its own temporary directory.
25
26 Example program:
27
28   let package = "foo"
29
30   let rec goal website_updated version =
31     let tarfile = sprintf "%s-%s.tar.gz" package version in
32     let tarpath = getenv "HOME" // "html" // tarfile in
33     let url = sprintf "http://example.com/%s" tarfile in
34
35     target (url_exists url);
36
37     require (tarball_exists version);
38     require (tarball_tested version);
39
40     sh "rsync %s example.com:/html/" tarpath
41
42   and goal tarball_tested version =
43     let tarfile = sprintf "%s-%s.tar.gz" package version in
44     let tarpath = getenv "HOME" // "html" // tarfile in
45     let memkey = package ^ "_tested_" ^ version in
46
47     target (memory_exists memkey);
48
49     require (tarball_exists version);
50
51     sh "
52       tar zxf %s
53       cd %s-%s
54       ./configure
55       make
56       make check
57     " tarpath package version;
58
59     memory_set memkey "1"
60
61   and goal tarball_exists version =
62     let tarpath = getenv "HOME" // "html" // tarfile in
63     target (file_exists tarpath);
64     sh "
65       cd $HOME/repos/%s
66       git fetch
67       git archive --prefix %s-%s/ v%s | gzip > %s-t
68       mv %s-t %s
69     " package package version version tarpath tarpath tarpath
70
71   every 1 hour =
72     let version = shout "
73       cd $HOME/repos/%s
74       git fetch
75       git describe --tags --abbrev=0 --match='v*'
76     " package in
77     require (website_updated version)
78
79 This compiles down to a command line program that can be used like this:
80
81   ./compile [-flags] [goals]
82
83 The goals are not enabled automatically.  You have to do something
84 (simple) to publish a goal and specify how command line arguments get
85 mapped to goal arguments, since the mapping is not likely to be 1-1
86 strings.  In the end you can do stuff like:
87
88   ./compile all
89   ./compile clean
90   ./compile build program  # program is a parameter
91   ./compile -my-flag       # custom flags can be defined