Command line parsing, the concept of publishing goals.

[goaljobs.git] / goaljobs.mli

diff --git a/goaljobs.mli b/goaljobs.mli
index 752e9b7..8b31abe 100644 (file)
--- a/goaljobs.mli
+++ b/goaljobs.mli
@@ -292,6 +292,59 @@ val memory_get : string -> string option
 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). *)
+
 (**/**)
 
 (* Goal versions of some common functions.  You are using these
@@ -306,6 +359,11 @@ 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