{v
let goal compiled c_file =
let o_file = change_file_extension "o" c_file in
- target (file_exists o_file);
- target (file_newer_than o_file c_file);
+ target (more_recent [o_file] [c_file]);
sh "cc -c %s -o %s" c_file o_file
}
before it can link the final program:
{v
- let goal built program sources =
- target (file_exists program);
- target (file_newer_than program sources);
+ let goal built program source =
+ target (more_recent [program] [source]);
- List.iter (fun s -> require (compiled s)) sources;
+ require (compiled source);
- let objects = List.map (change_file_extension "o") sources in
- sh "cc %s -o %s" (String.concat " " objects) program
+ let object = change_file_extension "o" source in
+ sh "cc %s -o %s" object program
}
*)
val target : bool -> unit
- (** [target] {i predicate} defines the target condition that will
+ (** [target] {i condition} defines the target condition that {b will}
be met once the current rule has run.
Goaljobs is much more flexible than [make]. In [make] only a
...
let goal compiled () =
- target (file_exists "foo.o");
- target (file_newer_than "foo.o" "foo.c");
+ target (more_recent ["foo.o"] ["foo.c"]);
+ requires (file_exists "foo.c");
...
}
can have any number of different targets.
Almost every rule should have one or more targets, which should
- accurately state the outcome once the rule has been run
+ accurately state the outcome once the rule has been run.
+
+ If you have more than one [target]s then it's as if they have
+ been ORed together ({b not} ANDed which you might expect).
+ You can make this explicit by using a single target and [&&]
+ or [||] between the expressions. See also {!target_all}
+ and {!target_exists}.
Normally you put the target(s) early on in the rule, before any
running code and before any [require]s. This is not a
ensure the rule runs most efficiently since if the target is met
already then the rest of the rule doesn't run. *)
+val target_all : bool list -> unit
+ (** [target_all [t1; t2; ...]] is the same as writing
+ [target (t1 && t2 && ...)] *)
+
+val target_exists : bool list -> unit
+ (** [target_exists [t1; t2; ...]] is the same as writing
+ [target (t1 || t2 || ...)] *)
+
val require : unit -> unit
(** [require] {!goal} defines the requirements of this rule, that
is, other goals that have to be met before this rule is able to run.
right hand side after the [:], but in goaljobs the requirements
can be much richer than simply "that file must exist".
- Some simple rules don't need any [require]s. Unlike with [make],
+ Some very simple rules don't need any [require]s. Unlike with [make],
the requirements of a rule can be placed anywhere within the
rule, as long as you put them before they are needed. *)
newer than [file_b]. Note that if [file_a] does not exist, it
returns false. If [file_b] does not exist, it is an error. *)
+val more_recent : string list -> string list -> bool
+ (** [more_recent objects sources] expresses the [make] relationship:
+
+ {v object(s) ...: source(s) ...}
+
+ in a convenient way:
+
+ {v
+ let goal built objects sources =
+ target (more_recent objects sources);
+ ... code to rebuild ...
+ }
+
+ It is roughly equivalent to checking that all the object files
+ exist and are newer than all of the source files.
+
+ Note that both parameters are lists (since in [make] you can
+ have a list of source files and a list of object files). If you
+ don't want a list, pass a single-element list containing the
+ single the object/source file. *)
+
val url_exists : string -> bool
(** The URL is tested to see if it exists.
{v cd $HOME/data/ }
*)
-val sh : ('a, unit, string, unit) format4 -> 'a -> unit
+val sh : ('a, unit, string, unit) format4 -> 'a
(** Run the command(s). *)
-(*
-val shout : ('a, unit, string) format -> 'a
- (** Run the command(s). Anything printed on stdout is returned
- as a single string (the trailing [\n] character, if any,
- is not returned). *)
+val shout : ('a, unit, string, string) format4 -> 'a
+ (** Run the command(s).
-val shlines : ('a, unit, string) format -> 'a
- (** Run the command(s). Any lines printed to stdout are returned
- as a list of strings. Trailing [\n] characters not returned. *)
+ Anything printed on stdout is returned as a string.
+ The trailing [\n] character, if any, is not returned. *)
+val shlines : ('a, unit, string, string list) format4 -> 'a
+ (** Run the command(s).
+
+ Any lines printed to stdout is returned as a list of strings.
+ Trailing [\n] characters are not returned. *)
+
+(*
val shell : string ref
(** Set this variable to override the default shell ([/bin/sh]). *)
*)
library (see the module [String]). For convenience some
extra functions are provided here. *)
+(*
val replace_substring : string -> string -> string -> string
(** [replace_substring patt repl string] replaces all occurrences
of [patt] with [repl] in [string]. *)
+*)
val change_file_extension : string -> string -> string
(** [change_file_extension ext filename] changes the file extension
If the original filename has no extension, this function
adds the extension. *)
+(*
val filter_file_extension : string -> string list -> string
(** [filter_file_extension ext filenames] returns only those
filenames in the list which have the given file extension.
For example [filter_file_extension "o" ["foo.c"; "bar.o"]]
would return [["bar.o"]] (a single element list). *)
+*)
+
+(** {2 Memory (persistent key/value storage)
+
+ "The Memory" is key/value storage which persists across goaljobs
+ sessions. It is stored in the file [$HOME/.goaljobs-memory]
+ (which is a binary file, but you can delete it if you want).
+
+ The Memory is locked during accesses, so it is safe to read
+ or write it from multiple parallel goaljobs sessions.
+
+ Keys and values are strings. The keys should be globally
+ unique, so it is suggested you use some application-specific
+ prefix. eg: "myapp-key"
+
+ A common pattern is:
+
+ {v
+ let goal tested version =
+ let key = "myapp-tested-" ^ version in
+ target (memory_exists key);
+
+ ... some work to test version ...
+
+ memory_set key "1"
+ }
+
+ Note in that example the value ["1"] is arbitrary. You just
+ want to store {i any} value so that a later call to {!memory_exists}
+ will succeed.
+*)
+
+val memory_exists : string -> bool
+ (** [memory_exists key] checks that the named [key] exists in
+ the Memory. It doesn't matter what value it has.
+
+ This is also available as a goal, so you can write
+ [requires (memory_exists key)] *)
+
+val memory_set : string -> string -> unit
+ (** Set [key] to [value] in the Memory. *)
+
+val memory_get : string -> string option
+ (** Return the current value of [key] in the Memory. Returns [None]
+ if the key has never been set or was deleted. *)
+
+val memory_delete : string -> unit
+ (** Delete the [key]. If the key doesn't exist, has no effect. *)
+
+(** {2 Publishing goals}
+
+ To "publish" a goal means it's available on the command line
+ for users to use directly.
+
+ Goals that have zero arguments are {b automatically published}.
+ So for example:
+
+ {v
+ let goal clean () = sh "rm *~"
+ }
+
+ can be used on the command line:
+
+ {v ./script clean }
+
+ The special goal called [all] (if it exists) is run implicitly
+ unless the user specifies another goal. Unlike [make], there is
+ nothing special about the first rule in the file.
+
+ You can also publish goals, especially ones which take a non-zero
+ number of parameters, by calling {!publish}.
+*)
+
+val publish : string -> (string list -> unit) -> unit
+ (** Publish the named goal.
+
+ Use this function as in this example:
+
+ {v
+ let goal compiled program sources =
+ ... stuff for building the program from sources ...
+
+ let () = publish "compiled" (
+ fun args ->
+ let program = List.hd args in
+ let sources = List.tl args in
+ require (compiled program sources)
+ )
+ }
+
+ This could be used as follows:
+
+ {v ./script compiled program main.c utils.c }
+
+ You will notice you have to write a bit of OCaml code to
+ map the string arguments from the command line on to the
+ goal arguments. In the example it means taking the first
+ string argument as the program name, and the rest of the
+ string arguments as the source filenames. This is also
+ the place to perform string to int conversion, checks, and
+ so on (remember that OCaml is strongly typed). *)
(**/**)
*)
val goal_file_exists : string -> unit
val goal_file_newer_than : string -> string -> unit
+val goal_more_recent : string list -> string list -> unit
val goal_url_exists : string -> unit
+val goal_memory_exists : string -> unit
+
+(* A single call to this function is added by the 'goaljobs' script.
+ * It is responsible for parsing the command line and so on.
+ *)
+val init : unit -> unit
+
+(* Export this so the macros can catch these exceptions. *)
+type goal_result_t = Goal_OK | Goal_failed of string
+exception Goal_result of goal_result_t
git.annexia.org / goaljobs.git / blobdiff