Source file sig.ml

(* This file is part of the Catala build system, a specification language for
   tax and social benefits computation rules. Copyright (C) 2020-2025 Inria,
   contributors: Denis Merigoux <denis.merigoux@inria.fr>, Emile Rolley
   <emile.rolley@tuta.io>, Louis Gesbert <louis.gesbert@inria.fr>

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

(** All backend implementations should provide an implementation of [Spec], and
    expose the application of [Common.Make_Backend] to it ; the functor will
    also register the backend in a global table. *)

open Clerk_utils
open Catala_utils
module Nj = Ninja_utils

module type Spec = sig
  val name : string

  val src_extensions : string list
  (** source files for this backend, as generated by Catala. File extensions,
      dot excluded *)

  val module_extensions : string list
  (** possibly compiled interface files: this is the requirement for building
      dependent modules, e.g. [.h] for C, [.cmi] for OCaml. File extensions, dot
      excluded *)

  val obj_extension : string
  (** the main target extension (dot excluded) of objects for this backend.
      building this should make linking the program possible *)

  val all_obj_extensions : string list
  (** extensions for all compiled objects by this backend, dot excluded *)

  val var_defs :
    variables:(string * string list) list ->
    autotest:bool ->
    use_default_flags:bool ->
    test_flags:string list ->
    include_dirs:string list ->
    Var.bindings
  (** Returns a list of variables assigned for the Ninja file generated. Those
      variables can be the compiler exec of your backends, flags for a specific
      command, include ...
      - [~variables] is the list of already defined variables, if a variables is
        already defined it will takes this value instead of the one given
      - [~autotest] if the flag is activated, add the autotest flag to the
        catala command, each call to the catala command will come with autotest
      - [~use_default_flags] flag to tell if the catala command should only use
        the default flag or could had some more. The default flag being -O for
        optimize
      - [~test_flags] is a list of tests that will be passed to the catala
        interpreter tests if called
      - [~include_dirs] the list of the different direcory to include each time,
        usually this comes from the config in the clerk.toml file. *)

  val rules : Nj.def list
  (** List of base Ninja rules needed by the backend *)

  val build_runtime : config:Clerk_cli.config -> stdbase:string -> Nj.def list
  (** Returns a set of Ninja rules, in charge of building
      ["@<name>/runtime/src"] and ["@<name>/runtime/obj"] *)

  val catala :
    ?vars:Var.bindings ->
    is_stdlib:bool ->
    inputs:Nj.Expr.t ->
    implicit_in:Nj.Expr.t ->
    has_scope_tests:bool ->
    Nj.def Seq.t
  (** This functions returns the Ninja build statements that call the catala
      compiler to create the target file in the backend language. *)

  val build_object : Scan.item -> Nj.def Seq.t
  (** Returns a set of rules that generate the [obj_extensions] compiled form of
      a the target from the [src_extensions] generated by the [catala] rule,
      using the backend compiler. Returns an empty sequence on non-compiled
      languages. *)

  val runtime_dir : File.t Lazy.t
  (** Origin directory for the runtime source on the system (based on
      [Poll.runtime_dir]) *)

  val stdlib_subdir : File.t
  (** Subdirectory of the backend directory in "_build/libcatala" that holds the
      standard library files. Usually just the empty string. *)

  val install_runtime : config:Clerk_cli.config -> unit
  (** Sets up the runtime and stdlib to the appropriate target dir *)

  val install_target :
    config:Clerk_cli.config ->
    info:Module_graph.info ->
    Clerk_config.target ->
    unit
  (** Installs the files for the given target below
      config.file.global.target_dir, and adds any relevant specification files
      for that target *)

  val write_project_def :
    config:Clerk_cli.config -> info:Module_graph.info -> unit
  (** Writes a backend-specific (Makefile, dune-project, pom.xml...) project
      definition file to the backend-specific target dir *)

  val linking_command :
    build_dir:string ->
    var_bindings:Var.bindings ->
    ('a -> Scan.item list) ->
    'a ->
    string ->
    string list
  (** Returns a list of arguments that represents a command to link all the
      files that were generated by the Ninja file. *)

  val run_artifact :
    config:Clerk_cli.config ->
    var_bindings:Var.bindings ->
    test:bool ->
    trace:bool ->
    ?scope:string ->
    ?quiet:bool ->
    string ->
    int * string list
  (** Runs the executable that was generated by the execution of the command
      [linking_command]. *)
end

module type S = sig
  include Spec

  type Clerk_config.backend += T

  val config_backend : Clerk_config.backend

  val current_target : Scan.item -> string -> Nj.Expr.elt
  (** Returns the current target (in the Clerk file context) with the given
      extension *)

  val runtime_targets : only_source:bool -> string list

  val interface_dep : string -> Nj.Expr.elt
  (** Returns the pseudo-target for generated interface of the given module,
      possibly compiled (ie. [.cmi] in the case of OCaml) *)

  val src_dep : string -> Nj.Expr.elt
  (** Returns the pseudo-target for generated source of the given module *)

  val obj_dep : Scan.item -> Nj.Expr.elt
  (** Returns the pseudo-target for the compiled object of the given item *)

  val external_copy : Scan.item -> Nj.def Seq.t
  (** [external_copy item] is the set of rules to handle a catala module marked
      as external in [item], most of the time the [external_copy] function
      verifies if the implementation of the external module exists and then
      copies it in the build directory along others modules *)
end