First published version.

[goaljobs.git] / goaljobs.mli

(* goaljobs
 * Copyright (C) 2013 Red Hat Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 *)

(** {1 Goaljobs library of useful helper functions.} *)

(** {2 Targets and requires}

    These are used to write goals.

    Normally you write a goal with one or more [target]s and
    zero or more [require]s, as the examples below should make
    clear.

    In the first example, there are two targets: that [o_file] (object)
    exists, and that it is newer than [c_file] (source).  The rule
    meets that target by running the C compiler ([cc]) which, if it
    succeeds, will ensure that the object file exists and is newer
    than the source file.

    {v
    let goal compiled c_file =
        let o_file = change_file_extension "o" c_file in
        target (more_recent [o_file] [c_file]);

        sh "cc -c %s -o %s" c_file o_file
    }

    In the second example, the rule requires that several files
    have been compiled ([require (compiled ...)]
    before it can link the final program:

    {v
    let goal built program source =
        target (more_recent [program] [source]);

        require (compiled source);

        let object = change_file_extension "o" source in
        sh "cc %s -o %s" object program
    }

*)

val target : bool -> unit
  (** [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
      single type of target is possible.  The following are roughly
      equivalent:

      {v
      foo.o: foo.c
        ...

      let goal compiled () =
        target (more_recent ["foo.o"] ["foo.c"]);
        requires (file_exists "foo.c");
        ...
      }

      Targets in goaljobs can be any arbitrary expression, and you
      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.

      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
      hard-and-fast rule and it is not enforced, but doing it will
      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.

      In terms of [make], [require]s are roughly equivalent to the
      right hand side after the [:], but in goaljobs the requirements
      can be much richer than simply "that file must exist".

      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. *)

(** {2 File and URL testing}

    Various functions to test the existence of files, URLs.
*)

val file_exists : string -> bool
  (** Return true if the named file exists.

      This function also exists as a goal.  Writing:
      {v require (file_exists "somefile");}
      will die unless ["somefile"] exists. *)

val file_newer_than : string -> string -> bool
  (** [file_newer_than file_a file_b] returns true if [file_a] is
      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.

      This function also exists as a goal.  Writing:
      {v require (url_exists "http://example.com");}
      will die unless the given URL exists. *)

(** {2 Shell}

    Call out to the Unix shell.  [/bin/sh] is used unless you set
    {!shell} to some other value.  Note that the environment variable
    [SHELL] is {i not} used.

    {!sh}, {!shout}, {!shlines} work like [printf].  ie. You can
    substitute variables using [%s], [%d] and so on.  For example:

    {v
      sh "rsync foo-%s.tar.gz example.com:/html/" version
    }

    Each invocation of {!sh} (etc) is a single shell (this is slightly
    different from how [make] works).  For example:

    {v
      sh "
        package=foo-%s
        tarball=$package.tar.gz
        cp $HOME/$tarball .
        tar zxf $tarball
        cd $package
        ./configure
        make
     " version
    }

    The shell error mode is set such that if any single command
    returns an error then the {!sh} function as a whole exits with
    an error.  Write:
    {v command ||: }
    to ignore the result of a command.

    Each shell runs in a new temporary directory.  The temporary directory
    and all its contents is deleted after the shell exits.  If you
    want to save any data, [cd] somewhere.  For example you could start
    the command sequence with:
    {v cd $HOME/data/ }
*)

val sh : ('a, unit, string, unit) format4 -> 'a
  (** Run the command(s). *)

val shout : ('a, unit, string, string) format4 -> 'a
  (** Run the command(s).

      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]). *)
*)

(** {2 String functions}

    Most string functions are provided by the OCaml standard
    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
      of [filename] to [.ext].  For example
      [change_file_extension "o" "main.c"] returns ["main.o"].
      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. *)

(**/**)

(* Goal versions of some common functions.  You are using these
 * versions when you write something like:
 *   require (file_exists "foo");
 * They work the same way as the regular function, except they die
 * if the predicate returns false.
 *)
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

(* 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