mirror of
https://github.com/CatalaLang/catala.git
synced 2024-09-20 00:41:05 +03:00
docs(clerk): add documentation about clerk and the Ninja_utils module
This commit is contained in:
parent
3c7f2dbaea
commit
da6ed6b044
@ -134,6 +134,8 @@ options available. To get the development version of the help, run `make help_cl
|
|||||||
after `make build`. The `clerk` binary corresponds to the Catala build system,
|
after `make build`. The `clerk` binary corresponds to the Catala build system,
|
||||||
responsible for testing among other things.
|
responsible for testing among other things.
|
||||||
|
|
||||||
|
To get more information about Clerk, see [the dedicated readme](https://github.com/CatalaLang/catala/tree/master/build_system/README.md)
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
### Syntax cheat sheet
|
### Syntax cheat sheet
|
||||||
|
@ -2,14 +2,12 @@
|
|||||||
|
|
||||||
The build system for Catala built on top of [ninja](https://ninja-build.org/).
|
The build system for Catala built on top of [ninja](https://ninja-build.org/).
|
||||||
|
|
||||||
## Build
|
|
||||||
|
|
||||||
* to build: `dune build`
|
|
||||||
* to run: `dune exec ./clerk.exe`
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
See the manpage -- accessible with `clerk --help`.
|
Use `clerk --help` if you have installed it to get more information about the command line
|
||||||
|
options available. To get the development version of the help, run `make help_clerk`
|
||||||
|
after `make build`. The `clerk` binary corresponds to the Catala build system,
|
||||||
|
responsible for testing among other things.
|
||||||
|
|
||||||
## Under the hood
|
## Under the hood
|
||||||
|
|
||||||
|
@ -565,6 +565,12 @@ let collect_in_file (ctx : ninja_building_context) (tested_file : string) (ninja
|
|||||||
all_failed_names = tested_file :: ctx.all_failed_names;
|
all_failed_names = tested_file :: ctx.all_failed_names;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
(** {1 Return code values} *)
|
||||||
|
|
||||||
|
let return_ok = 0
|
||||||
|
|
||||||
|
let return_err = 1
|
||||||
|
|
||||||
let driver (files_or_folders : string list) (command : string) (catala_exe : string option)
|
let driver (files_or_folders : string list) (command : string) (catala_exe : string option)
|
||||||
(catala_opts : string option) (debug : bool) (scope : string option) (reset_test_outputs : bool)
|
(catala_opts : string option) (debug : bool) (scope : string option) (reset_test_outputs : bool)
|
||||||
: int =
|
: int =
|
||||||
@ -597,7 +603,7 @@ let driver (files_or_folders : string list) (command : string) (catala_exe : str
|
|||||||
|> Printf.sprintf "No test case found for %s"
|
|> Printf.sprintf "No test case found for %s"
|
||||||
|> Cli.warning_print)
|
|> Cli.warning_print)
|
||||||
ctx.all_failed_names;
|
ctx.all_failed_names;
|
||||||
if 0 = List.compare_lengths ctx.all_failed_names files_or_folders then 0
|
if 0 = List.compare_lengths ctx.all_failed_names files_or_folders then return_ok
|
||||||
else
|
else
|
||||||
let out = open_out "build.ninja" in
|
let out = open_out "build.ninja" in
|
||||||
Cli.debug_print "writing build.ninja...";
|
Cli.debug_print "writing build.ninja...";
|
||||||
@ -613,7 +619,7 @@ let driver (files_or_folders : string list) (command : string) (catala_exe : str
|
|||||||
(fun ret f -> ret + run_file f catala_exe catala_opts scope)
|
(fun ret f -> ret + run_file f catala_exe catala_opts scope)
|
||||||
0 files_or_folders
|
0 files_or_folders
|
||||||
in
|
in
|
||||||
if 0 <> res then 1 else 0
|
if 0 <> res then return_err else return_ok
|
||||||
| None ->
|
| None ->
|
||||||
Cli.error_print "Please provide a scope to run with the -s option";
|
Cli.error_print "Please provide a scope to run with the -s option";
|
||||||
1)
|
1)
|
||||||
|
@ -7,5 +7,6 @@
|
|||||||
|
|
||||||
(library
|
(library
|
||||||
(name ninja_utils)
|
(name ninja_utils)
|
||||||
|
(public_name ninja_utils)
|
||||||
(modules ninja_utils)
|
(modules ninja_utils)
|
||||||
(libraries re))
|
(libraries re))
|
||||||
|
@ -13,7 +13,7 @@
|
|||||||
the License. *)
|
the License. *)
|
||||||
|
|
||||||
module Expr = struct
|
module Expr = struct
|
||||||
type t = Seq of t list | Lit of string | Var of string
|
type t = Lit of string | Var of string | Seq of t list
|
||||||
|
|
||||||
let rec to_string = function
|
let rec to_string = function
|
||||||
| Lit s -> s
|
| Lit s -> s
|
||||||
@ -54,7 +54,7 @@ module Build = struct
|
|||||||
|
|
||||||
let empty = make ~outputs:[ Expr.Lit "empty" ] ~rule:"phony"
|
let empty = make ~outputs:[ Expr.Lit "empty" ] ~rule:"phony"
|
||||||
|
|
||||||
let unpath path = Re.Pcre.(substitute ~rex:(regexp "/") ~subst:(fun _ -> "-")) path
|
let unpath ?(sep = "-") path = Re.Pcre.(substitute ~rex:(regexp "/") ~subst:(fun _ -> sep)) path
|
||||||
|
|
||||||
let to_string build =
|
let to_string build =
|
||||||
Printf.sprintf "build %s: %s" (Expr.list_to_string build.outputs) build.rule
|
Printf.sprintf "build %s: %s" (Expr.list_to_string build.outputs) build.rule
|
||||||
|
@ -12,19 +12,41 @@
|
|||||||
or implied. See the License for the specific language governing permissions and limitations under
|
or implied. See the License for the specific language governing permissions and limitations under
|
||||||
the License. *)
|
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} *)
|
(** {1 Ninja expressions} *)
|
||||||
|
|
||||||
(** Helper module to build ninja expressions. *)
|
(** Helper module to build ninja expressions. *)
|
||||||
module Expr : sig
|
module Expr : sig
|
||||||
(** Represents a ninja expression. Which could be either a literal, a variable references ($_) or
|
(** Represents a ninja expression. Which could be either a literal, a {{:
|
||||||
a sequence of sub-expressions. *)
|
https://ninja-build.org/manual.html#_variables}variable references} ($_) or
|
||||||
|
a sequence of sub-expressions.
|
||||||
|
|
||||||
|
{b Note:} for now, there are no visible differences between an [Expr.Seq]
|
||||||
|
and a list of {!type: Expr.t}, indeed, in both cases, one space is added
|
||||||
|
between each expression -- resp. sub-expression. The difference only comes from the semantic:
|
||||||
|
an [Expr.Seq] is {b a unique} Ninja expression. *)
|
||||||
type t =
|
type t =
|
||||||
(* Sequence of sub-expressions. *)
|
|
||||||
| Seq of t list
|
|
||||||
(* Literal string. *)
|
|
||||||
| Lit of string
|
| Lit of string
|
||||||
(* Variable reference. *)
|
(* Literal string. *)
|
||||||
| Var of string
|
| Var of string
|
||||||
|
(* Variable reference. *)
|
||||||
|
| Seq of t list
|
||||||
|
(* Sequence of sub-expressions. *)
|
||||||
|
|
||||||
|
|
||||||
val to_string : t -> string
|
val to_string : t -> string
|
||||||
(** [to_string exp] returns the string representation of an ninja expression [exp]. *)
|
(** [to_string exp] returns the string representation of an ninja expression [exp]. *)
|
||||||
@ -36,21 +58,22 @@ end
|
|||||||
|
|
||||||
(** {1 Ninja rules} *)
|
(** {1 Ninja rules} *)
|
||||||
|
|
||||||
(** Helper module to build ninja rules. *)
|
(** Helper module to build {{:https://ninja-build.org/manual.html#_rules}ninja rules}. *)
|
||||||
module Rule : sig
|
module Rule : sig
|
||||||
(* NOTE: is name is really needed despite the use of Map? *)
|
|
||||||
type t = {
|
type t = {
|
||||||
(* Name of the rule: `rule <name>`. *)
|
|
||||||
name : string;
|
name : string;
|
||||||
(* Command of the rule: ` command = <command>. *)
|
|
||||||
command : Expr.t;
|
command : Expr.t;
|
||||||
(* Description of the rule: ` description = <description>. *)
|
|
||||||
description : Expr.t option;
|
description : Expr.t option;
|
||||||
}
|
}
|
||||||
(** Represents the minimal ninja rule representation for clerk. *)
|
(** Represents the minimal ninja rule representation for Clerk:
|
||||||
|
{[
|
||||||
|
rule <name>
|
||||||
|
command = <command>
|
||||||
|
[description = <description>]
|
||||||
|
]} *)
|
||||||
|
|
||||||
val make : string -> command:Expr.t -> description:Expr.t -> t
|
val make : string -> command:Expr.t -> description:Expr.t -> t
|
||||||
(** [make name ~command ~description] returns the corresponding ninja rule [Rule.t]. *)
|
(** [make name ~command ~description] returns the corresponding ninja {!type: Rule.t}. *)
|
||||||
|
|
||||||
val to_string : t -> string
|
val to_string : t -> string
|
||||||
(** [to_string rule] returns the string representation of the [rule]. *)
|
(** [to_string rule] returns the string representation of the [rule]. *)
|
||||||
@ -58,33 +81,40 @@ end
|
|||||||
|
|
||||||
(** {1 Ninja builds} *)
|
(** {1 Ninja builds} *)
|
||||||
|
|
||||||
(** Helper module to build ninja build statements. *)
|
(** Helper module to build ninja {{: https://ninja-build.org/manual.html#_build_statements}build statements}. *)
|
||||||
module Build : sig
|
module Build : sig
|
||||||
type t = {
|
type t = {
|
||||||
outputs : Expr.t list;
|
outputs : Expr.t list;
|
||||||
(* NOTE: what's the difference between [Expr.t list] and [Expr.Seq]? => [Expr.Seq] is a unique
|
|
||||||
expression with possible variable references => no space in its string representation. *)
|
|
||||||
rule : string;
|
rule : string;
|
||||||
inputs : Expr.t list option;
|
inputs : Expr.t list option;
|
||||||
vars : (string * Expr.t) list;
|
vars : (string * Expr.t) list;
|
||||||
}
|
}
|
||||||
(** @note Currently, nothing nothing forces to build valid {!: Expr.t} for the variables. *)
|
(** Represents the minimal ninja build statement representation for Clerk:
|
||||||
|
{[
|
||||||
|
build <outputs>: <rule> [<inputs>]
|
||||||
|
[<vars>]
|
||||||
|
]}*)
|
||||||
|
|
||||||
val make : outputs:Expr.t list -> rule:string -> t
|
val make : outputs:Expr.t list -> rule:string -> t
|
||||||
|
(** [make ~outputs ~rule] returns the corresponding ninja {!type: Build.t} with no {!field: inputs}
|
||||||
|
or {!field: vars}. *)
|
||||||
|
|
||||||
val make_with_vars : outputs:Expr.t list -> rule:string -> vars:(string * Expr.t) list -> t
|
val make_with_vars : outputs:Expr.t list -> rule:string -> vars:(string * Expr.t) list -> t
|
||||||
|
(** [make_with_vars ~outputs ~rule ~vars] returns the corresponding ninja {!type: Build.t} with no {!field: inputs}. *)
|
||||||
|
|
||||||
val make_with_inputs : outputs:Expr.t list -> rule:string -> inputs:Expr.t list -> t
|
val make_with_inputs : outputs:Expr.t list -> rule:string -> inputs:Expr.t list -> t
|
||||||
|
(** [make_with_vars ~outputs ~rule ~inputs] returns the corresponding ninja {!type: Build.t} with no {!field: vars}. *)
|
||||||
|
|
||||||
val make_with_vars_and_inputs :
|
val make_with_vars_and_inputs :
|
||||||
outputs:Expr.t list -> rule:string -> inputs:Expr.t list -> vars:(string * Expr.t) list -> t
|
outputs:Expr.t list -> rule:string -> inputs:Expr.t list -> vars:(string * Expr.t) list -> t
|
||||||
|
(** [make_with_vars ~outputs ~rule ~inputs ~vars] returns the corresponding ninja {!type: Build.t}. *)
|
||||||
|
|
||||||
val empty : t
|
val empty : t
|
||||||
(** [empty] is the minimal ninja build. *)
|
(** [empty] is the minimal ninja {!type: Build.t} with ["empty"] as {!field: outputs} and ["phony"] as {!field: rule}. *)
|
||||||
|
|
||||||
val unpath : string -> string
|
val unpath : ?sep:string -> string -> string
|
||||||
(** [unpath path] replaces all '/' occurences with '-' in [path] to avoid ninja writing the
|
(** [unpath ~sep path] replaces all [/] occurences with [sep] in [path] to avoid ninja writing the
|
||||||
corresponding file. *)
|
corresponding file and use it as sub command. By default, [sep] is set to ["-"]. *)
|
||||||
|
|
||||||
val to_string : t -> string
|
val to_string : t -> string
|
||||||
end
|
end
|
||||||
@ -98,7 +128,7 @@ module BuildMap : Map.S with type key = String.t
|
|||||||
(** {1 Ninja} *)
|
(** {1 Ninja} *)
|
||||||
|
|
||||||
type ninja = { rules : Rule.t RuleMap.t; builds : Build.t BuildMap.t }
|
type ninja = { rules : Rule.t RuleMap.t; builds : Build.t BuildMap.t }
|
||||||
(** Represents the minimal ninja architectures (list of rule and build statements) needed for clerk. *)
|
(** Represents the minimal ninja architecture (list of rule and build statements) needed for clerk. *)
|
||||||
|
|
||||||
val empty : ninja
|
val empty : ninja
|
||||||
(** [empty] returns the empty empty ninja structure. *)
|
(** [empty] returns the empty empty ninja structure. *)
|
||||||
|
Loading…
Reference in New Issue
Block a user