2 * Copyright (C) 2013 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 (** {1 Goaljobs library of useful helper functions.} *)
21 (** {2 Targets and requires}
23 These are used to write goals.
25 Normally you write a goal with one or more [target]s and
26 zero or more [require]s, as the examples below should make
29 In the first example, there are two targets: that [o_file] (object)
30 exists, and that it is newer than [c_file] (source). The rule
31 meets that target by running the C compiler ([cc]) which, if it
32 succeeds, will ensure that the object file exists and is newer
36 let goal compiled c_file =
37 let o_file = change_file_extension "o" c_file in
38 target (more_recent [o_file] [c_file]);
40 sh "cc -c %s -o %s" c_file o_file
43 In the second example, the rule requires that several files
44 have been compiled ([require (compiled ...)]
45 before it can link the final program:
48 let goal built program source =
49 target (more_recent [program] [source]);
51 require (compiled source);
53 let object = change_file_extension "o" source in
54 sh "cc %s -o %s" object program
59 val target : bool -> unit
60 (** [target] {i condition} defines the target condition that {b will}
61 be met once the current rule has run.
63 Goaljobs is much more flexible than [make]. In [make] only a
64 single type of target is possible. The following are roughly
71 let goal compiled () =
72 target (more_recent ["foo.o"] ["foo.c"]);
73 requires (file_exists "foo.c");
77 Targets in goaljobs can be any arbitrary expression, and you
78 can have any number of different targets.
80 Almost every rule should have one or more targets, which should
81 accurately state the outcome once the rule has been run.
83 If you have more than one [target]s then it's as if they have
84 been ORed together ({b not} ANDed which you might expect).
85 You can make this explicit by using a single target and [&&]
86 or [||] between the expressions. See also {!target_all}
89 Normally you put the target(s) early on in the rule, before any
90 running code and before any [require]s. This is not a
91 hard-and-fast rule and it is not enforced, but doing it will
92 ensure the rule runs most efficiently since if the target is met
93 already then the rest of the rule doesn't run. *)
95 val target_all : bool list -> unit
96 (** [target_all [t1; t2; ...]] is the same as writing
97 [target (t1 && t2 && ...)] *)
99 val target_exists : bool list -> unit
100 (** [target_exists [t1; t2; ...]] is the same as writing
101 [target (t1 || t2 || ...)] *)
103 val require : unit -> unit
104 (** [require] {!goal} defines the requirements of this rule, that
105 is, other goals that have to be met before this rule is able to run.
107 In terms of [make], [require]s are roughly equivalent to the
108 right hand side after the [:], but in goaljobs the requirements
109 can be much richer than simply "that file must exist".
111 Some very simple rules don't need any [require]s. Unlike with [make],
112 the requirements of a rule can be placed anywhere within the
113 rule, as long as you put them before they are needed. *)
115 (** {2 File and URL testing}
117 Various functions to test the existence of files, URLs.
120 val file_exists : string -> bool
121 (** Return true if the named file exists.
123 This function also exists as a goal. Writing:
124 {v require (file_exists "somefile");}
125 will die unless ["somefile"] exists. *)
127 val file_newer_than : string -> string -> bool
128 (** [file_newer_than file_a file_b] returns true if [file_a] is
129 newer than [file_b]. Note that if [file_a] does not exist, it
130 returns false. If [file_b] does not exist, it is an error.
132 There is also a goal version of this function. *)
134 val more_recent : string list -> string list -> bool
135 (** [more_recent objects sources] expresses the [make] relationship:
137 {v object(s) ...: source(s) ...}
142 let goal built objects sources =
143 target (more_recent objects sources);
144 ... code to rebuild ...
147 It is roughly equivalent to checking that all the object files
148 exist and are newer than all of the source files.
150 Note that both parameters are lists (since in [make] you can
151 have a list of source files and a list of object files). If you
152 don't want a list, pass a single-element list containing the
153 single the object/source file.
155 There is also a goal version of this function. *)
157 val url_exists : string -> bool
158 (** The URL is tested to see if it exists.
160 There is also a goal version of this function. *)
162 val file_contains_string : string -> string -> bool
163 (** [file_contains_string filename str] checks if the named file
164 contains the given substring [str].
166 There is also a goal version of this function. *)
168 val url_contains_string : string -> string -> bool
169 (** [url_contains_string url str] downloads the URL and checks
170 whether the content contains the given substring [str].
172 There is also a goal version of this function. *)
174 val (//) : string -> string -> string
175 (** Concatenate two paths. *)
177 val quote : string -> string
178 (** Quote the string to make it safe to pass directly to the shell. *)
182 Call out to the Unix shell. [/bin/sh] is used unless you set
183 {!shell} to some other value. Note that the environment variable
184 [SHELL] is {i not} used.
186 {!sh}, {!shout}, {!shlines} work like [printf]. ie. You can
187 substitute variables using [%s], [%d] and so on. For example:
190 sh "rsync foo-%s.tar.gz example.com:/html/" version
193 Each invocation of {!sh} (etc) is a single shell (this is slightly
194 different from how [make] works). For example:
199 tarball=$package.tar.gz
208 The shell error mode is set such that if any single command
209 returns an error then the {!sh} function as a whole exits with
212 to ignore the result of a command.
214 Each shell runs in a new temporary directory. The temporary directory
215 and all its contents is deleted after the shell exits. If you
216 want to save any data, [cd] somewhere. For example you could start
217 the command sequence with:
221 val sh : ('a, unit, string, unit) format4 -> 'a
222 (** Run the command(s). *)
224 val shout : ('a, unit, string, string) format4 -> 'a
225 (** Run the command(s).
227 Anything printed on stdout is returned as a string.
228 The trailing [\n] character, if any, is not returned. *)
230 val shlines : ('a, unit, string, string list) format4 -> 'a
231 (** Run the command(s).
233 Any lines printed to stdout is returned as a list of strings.
234 Trailing [\n] characters are not returned. *)
237 val shell : string ref
238 (** Set this variable to override the default shell ([/bin/sh]). *)
241 (** {2 String functions}
243 Most string functions are provided by the OCaml standard
244 library (see the module [String]). For convenience some
245 extra functions are provided here. *)
248 val replace_substring : string -> string -> string -> string
249 (** [replace_substring patt repl string] replaces all occurrences
250 of [patt] with [repl] in [string]. *)
253 val change_file_extension : string -> string -> string
254 (** [change_file_extension ext filename] changes the file extension
255 of [filename] to [.ext]. For example
256 [change_file_extension "o" "main.c"] returns ["main.o"].
257 If the original filename has no extension, this function
258 adds the extension. *)
261 val filter_file_extension : string -> string list -> string
262 (** [filter_file_extension ext filenames] returns only those
263 filenames in the list which have the given file extension.
264 For example [filter_file_extension "o" ["foo.c"; "bar.o"]]
265 would return [["bar.o"]] (a single element list). *)
268 (** {2 Memory (persistent key/value storage)
270 "The Memory" is key/value storage which persists across goaljobs
271 sessions. It is stored in the file [$HOME/.goaljobs-memory]
272 (which is a binary file, but you can delete it if you want).
274 The Memory is locked during accesses, so it is safe to read
275 or write it from multiple parallel goaljobs sessions.
277 Keys and values are strings. The keys should be globally
278 unique, so it is suggested you use some application-specific
279 prefix. eg: "myapp-key"
284 let goal tested version =
285 let key = "myapp-tested-" ^ version in
286 target (memory_exists key);
288 ... some work to test version ...
293 Note in that example the value ["1"] is arbitrary. You just
294 want to store {i any} value so that a later call to {!memory_exists}
298 val memory_exists : string -> bool
299 (** [memory_exists key] checks that the named [key] exists in
300 the Memory. It doesn't matter what value it has.
302 This is also available as a goal, so you can write
303 [requires (memory_exists key)] *)
305 val memory_set : string -> string -> unit
306 (** Set [key] to [value] in the Memory. *)
308 val memory_get : string -> string option
309 (** Return the current value of [key] in the Memory. Returns [None]
310 if the key has never been set or was deleted. *)
312 val memory_delete : string -> unit
313 (** Delete the [key]. If the key doesn't exist, has no effect. *)
315 (** {2 Publishing goals}
317 To "publish" a goal means it's available on the command line
318 for users to use directly.
320 Goals that have zero arguments are {b automatically published}.
324 let goal clean () = sh "rm *~"
327 can be used on the command line:
331 The special goal called [all] (if it exists) is run implicitly
332 unless the user specifies another goal. Unlike [make], there is
333 nothing special about the first rule in the file.
335 You can also publish goals, especially ones which take a non-zero
336 number of parameters, by calling {!publish}.
339 val publish : string -> (string list -> unit) -> unit
340 (** Publish the named goal.
342 Use this function as in this example:
345 let goal compiled program sources =
346 ... stuff for building the program from sources ...
348 let () = publish "compiled" (
350 let program = List.hd args in
351 let sources = List.tl args in
352 require (compiled program sources)
356 This could be used as follows:
358 {v ./script compiled program main.c utils.c }
360 You will notice you have to write a bit of OCaml code to
361 map the string arguments from the command line on to the
362 goal arguments. In the example it means taking the first
363 string argument as the program name, and the rest of the
364 string arguments as the source filenames. This is also
365 the place to perform string to int conversion, checks, and
366 so on (remember that OCaml is strongly typed). *)
370 (* Goal versions of some common functions. You are using these
371 * versions when you write something like:
372 * require (file_exists "foo");
373 * They work the same way as the regular function, except they die
374 * if the predicate returns false.
376 val goal_file_exists : string -> unit
377 val goal_file_newer_than : string -> string -> unit
378 val goal_more_recent : string list -> string list -> unit
379 val goal_url_exists : string -> unit
380 val goal_file_contains_string : string -> string -> unit
381 val goal_url_contains_string : string -> string -> unit
382 val goal_memory_exists : string -> unit
384 (* A single call to this function is added by the 'goaljobs' script.
385 * It is responsible for parsing the command line and so on.
387 val init : unit -> unit
389 (* Export this so the macros can catch these exceptions. *)
390 type goal_result_t = Goal_OK | Goal_failed of string
391 exception Goal_result of goal_result_t