catala/build_system/ninja_utils.mli

(* This file is part of the Catala build system, a specification language for
   tax and social benefits computation rules. Copyright (C) 2020 Inria,
   contributor: Emile Rolley <emile.rolley@tuta.io>

   Licensed under the Apache License, Version 2.0 (the "License"); you may not
   use this file except in compliance with the License. You may obtain a copy of
   the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   License for the specific language governing permissions and limitations under
   the License. *)

(** This library contains the implementations of utility functions used to
    generate {{:https://ninja-build.org} Ninja} build files in OCaml with almost
    no dependencies -- it only depends on
    {{:https://v3.ocaml.org/p/re/1.10.3/doc/Re/index.html} Re}. It's currently
    developed to be used by
    {{:https://github.com/CatalaLang/catala/tree/master/build_system} Clerk},
    the {{:https://catala-lang.org} Catala} build system. Therefore, the library
    {b supports only very basic features} required by Clerk. *)

(** {2 What is Ninja?} *)

(** {{:https://ninja-build.org} Ninja} is a low-level build system. It's
    designed to have its input files ({i build.ninja}) generated by a
    higher-level build system, and to run builds as fast as possible by
    supporting native cross-platform (Windows and Unix) parallel builds.

    See the {{:https://ninja-build.org/manual.html} manual} for more details. *)

(** {1 Ninja expressions} *)

(** Ninja variable names, distinguishing binding name ("x") from references in
    expressions ("$x") *)
module Var : sig
  type t

  val make : string -> t

  val name : t -> string
  (** Var base name, used when binding it *)

  val v : t -> string
  (** Var reference with a preceding "$", for use in expressoins *)
end

(** Helper module to build ninja expressions. *)
module Expr : sig
  type t = string list
  (** Ninja expressions are represented as raw string lists, which may contain
      variables or "$-escapes" *)

  val format : Format.formatter -> t -> unit
  (** [format fmt exp] outputs in [fmt] the string representation of the ninja
      expression [exp]. Spaces in individual elements are escaped (but no check
      is made for e.g. newlines) *)
end

module Binding : sig
  type t = Var.t * Expr.t

  val make : Var.t -> Expr.t -> t
  val format : global:bool -> Format.formatter -> t -> unit
end

(** {1 Ninja rules} *)

(** Helper module to build
    {{:https://ninja-build.org/manual.html#_rules} ninja rules}. *)
module Rule : sig
  type t
  (** Represents the minimal ninja rule representation for Clerk:

      {[
        rule <name>
          command = <command>
          [description = <description>]
      ]} *)

  val make :
    ?vars:Binding.t list -> string -> command:Expr.t -> description:Expr.t -> t
  (** [make name ~command ~description] returns the corresponding ninja
      {!type:Rule.t}. *)

  val format : Format.formatter -> t -> unit
  (** [format fmt rule] outputs in [fmt] the string representation of the ninja
      [rule]. *)
end

(** {1 Ninja builds} *)

(** Helper module to build ninja
    {{:https://ninja-build.org/manual.html#_build_statements} build statements}. *)
module Build : sig
  type t
  (** Represents the minimal ninja build statement representation for Clerk:

      {[
        build <outputs>: <rule> [<inputs>]
          [<vars>]
      ]}*)

  val make :
    ?inputs:Expr.t ->
    ?implicit_in:Expr.t ->
    outputs:Expr.t ->
    ?implicit_out:Expr.t ->
    ?vars:(Var.t * Expr.t) list ->
    string ->
    t
  (** [make ~outputs rule] returns the corresponding ninja {!type:Build.t}. *)

  val empty : t
  (** [empty] is the minimal ninja {!type:Build.t} with ["empty"] as
      {!field:outputs} and ["phony"] as {!field: rule}. *)

  val unpath : ?sep:string -> string -> string
  (** [unpath ~sep path] replaces all [/] occurences with [sep] in [path] to
      avoid ninja writing the corresponding file and use it as sub command. By
      default, [sep] is set to ["-"]. *)

  val format : Format.formatter -> t -> unit
  (** [format fmt build] outputs in [fmt] the string representation of the ninja
      [build]. *)
end

module Default : sig
  type t

  val make : Expr.t -> t
  val format : Format.formatter -> t -> unit
end

type def =
  | Comment of string
  | Binding of Binding.t
  | Rule of Rule.t
  | Build of Build.t
  | Default of Default.t

val comment : string -> def
val binding : Var.t -> Expr.t -> def

val rule :
  ?vars:Binding.t list -> string -> command:Expr.t -> description:Expr.t -> def

val build :
  ?inputs:Expr.t ->
  ?implicit_in:Expr.t ->
  outputs:Expr.t ->
  ?implicit_out:Expr.t ->
  ?vars:(Var.t * Expr.t) list ->
  string ->
  def

val default : Expr.t -> def
val format_def : Format.formatter -> def -> unit

type ninja = def Seq.t

val format : Format.formatter -> ninja -> unit