diff --git a/.ocamlformat b/.ocamlformat index ff04ee2..4a84cb0 100644 --- a/.ocamlformat +++ b/.ocamlformat @@ -1,3 +1,3 @@ profile = conventional -version = 0.26.2 +version = 0.27.0 ocaml-version = 4.08 diff --git a/CHANGES.md b/CHANGES.md index 2f705eb..ef98636 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,3 +1,8 @@ +unreleased +---------- + +- Add Alpine 3.21, deprecate Alpine 3.20. (@MisterDA, #225) + v8.2.4 2024-11-18 ----------------- diff --git a/src-cmd/dockerfile_cmd.mli b/src-cmd/dockerfile_cmd.mli index e2996e8..10a39ec 100644 --- a/src-cmd/dockerfile_cmd.mli +++ b/src-cmd/dockerfile_cmd.mli @@ -18,10 +18,10 @@ (** Command invocation library to help with Docker builds. This module primarily exposes utility functions to glue together - Docker-based scripts for (e.g.) continuous integration systems - like the ocaml-ci. The interface is fairly domain-specific and - does not expose all the functionality of the underlying tools. - Feel free to contribute more functions if you need them. *) + Docker-based scripts for (e.g.) continuous integration systems like the + ocaml-ci. The interface is fairly domain-specific and does not expose all + the functionality of the underlying tools. Feel free to contribute more + functions if you need them. *) type cmd_log = { command : string; @@ -39,8 +39,8 @@ val run_log : string -> Bos.Cmd.t -> (unit, [> `Msg of string ]) result -(** [runlog log_dir name cmd] will run [cmd] with label [name] - and log the results in [/.sxp]. *) +(** [runlog log_dir name cmd] will run [cmd] with label [name] and log the + results in [/.sxp]. *) (** Docker command invocation *) module Docker : sig diff --git a/src-cmd/gen.mli b/src-cmd/gen.mli index bb41aeb..ec5e16c 100644 --- a/src-cmd/gen.mli +++ b/src-cmd/gen.mli @@ -23,8 +23,8 @@ val generate_dockerfile : Fpath.t -> Dockerfile.t -> (unit, [> `Msg of string ]) result -(** [generate_dockerfile output_dir docker] will output Dockerfile inside - the [output_dir] subdirectory. +(** [generate_dockerfile output_dir docker] will output Dockerfile inside the + [output_dir] subdirectory. The [crunch] argument defaults to true and applies the {!Dockerfile.crunch} optimisation to reduce the number of layers; disable it if you really want @@ -35,9 +35,9 @@ val generate_dockerfiles : Fpath.t -> (string * Dockerfile.t) list -> (unit, [> `Msg of string ]) result -(** [generate_dockerfiles output_dir (name * docker)] will - output a list of Dockerfiles inside the [output_dir/] subdirectory, - with each Dockerfile named as [Dockerfile.]. +(** [generate_dockerfiles output_dir (name * docker)] will output a list of + Dockerfiles inside the [output_dir/] subdirectory, with each Dockerfile + named as [Dockerfile.]. The [crunch] argument defaults to true and applies the {!Dockerfile.crunch} optimisation to reduce the number of layers; disable it if you really want @@ -48,9 +48,9 @@ val generate_dockerfiles_in_directories : Fpath.t -> (string * Dockerfile.t) list -> (unit, [> `Msg of string ]) result -(** [generate_dockerfiles_in_directories output_dir (name * docker)] will - output a list of Dockerfiles inside the [output_dir/name] subdirectory, - with each directory containing the Dockerfile specified by [docker]. +(** [generate_dockerfiles_in_directories output_dir (name * docker)] will output + a list of Dockerfiles inside the [output_dir/name] subdirectory, with each + directory containing the Dockerfile specified by [docker]. The [crunch] argument defaults to true and applies the {!Dockerfile.crunch} optimisation to reduce the number of layers; disable it if you really want @@ -63,12 +63,12 @@ val generate_dockerfiles_in_git_branches : (string * Dockerfile.t) list -> (unit, [> `Msg of string ]) result (** [generate_dockerfiles_in_git_branches output_dir (name * docker)] will - output a set of git branches in the [output_dir] Git repository. - Each branch will be named [name] and contain a single [docker] file. - The contents of these branches will be reset, so this should be - only be used on an [output_dir] that is a dedicated Git repository - for this purpose. If [readme] is specified, the contents will be - written to [README.md] in that branch. + output a set of git branches in the [output_dir] Git repository. Each branch + will be named [name] and contain a single [docker] file. The contents of + these branches will be reset, so this should be only be used on an + [output_dir] that is a dedicated Git repository for this purpose. If + [readme] is specified, the contents will be written to [README.md] in that + branch. The [crunch] argument defaults to true and applies the {!Dockerfile.crunch} optimisation to reduce the number of layers; disable it if you really want diff --git a/src-opam/distro.ml b/src-opam/distro.ml index 1ff8eca..66b2018 100644 --- a/src-opam/distro.ml +++ b/src-opam/distro.ml @@ -39,7 +39,8 @@ type distro = | `V3_17 | `V3_18 | `V3_19 - | `V3_20 ] + | `V3_20 + | `V3_21 ] | `Archlinux of [ `Latest ] | `CentOS of [ `V6 | `V7 | `V8 ] | `Debian of [ `V12 | `V11 | `V10 | `V9 | `V8 | `V7 | `Testing | `Unstable ] @@ -126,6 +127,7 @@ type t = | `V3_18 | `V3_19 | `V3_20 + | `V3_21 | `Latest ] | `Archlinux of [ `Latest ] | `CentOS of [ `V6 | `V7 | `V8 | `Latest ] @@ -252,6 +254,7 @@ let distros : t list = `Alpine `V3_18; `Alpine `V3_19; `Alpine `V3_20; + `Alpine `V3_21; `Alpine `Latest; `Archlinux `Latest; `CentOS `V6; @@ -343,7 +346,7 @@ let distros : t list = let resolve_alias (d : t) : distro = match d with - | `Alpine `Latest -> `Alpine `V3_20 + | `Alpine `Latest -> `Alpine `V3_21 | `CentOS `Latest -> `CentOS `V7 | `Debian `Stable -> `Debian `V12 | `Fedora `Latest -> `Fedora `V41 @@ -357,7 +360,7 @@ let resolve_alias (d : t) : distro = | ( `Alpine ( `V3_3 | `V3_4 | `V3_5 | `V3_6 | `V3_7 | `V3_8 | `V3_9 | `V3_10 | `V3_11 | `V3_12 | `V3_13 | `V3_14 | `V3_15 | `V3_16 | `V3_17 | `V3_18 - | `V3_19 | `V3_20 ) + | `V3_19 | `V3_20 | `V3_21 ) | `Archlinux `Latest | `CentOS (`V6 | `V7 | `V8) | `Debian (`V7 | `V8 | `V9 | `V10 | `V11 | `V12 | `Testing | `Unstable) @@ -387,9 +390,9 @@ let distro_status (d : t) : status = | `Alpine ( `V3_3 | `V3_4 | `V3_5 | `V3_6 | `V3_7 | `V3_8 | `V3_9 | `V3_10 | `V3_11 | `V3_12 | `V3_13 | `V3_14 | `V3_15 | `V3_16 | `V3_17 | `V3_18 - | `V3_19 ) -> + | `V3_19 | `V3_20 ) -> `Deprecated - | `Alpine `V3_20 -> `Active `Tier1 + | `Alpine `V3_21 -> `Active `Tier1 | `Archlinux `Latest -> `Active `Tier3 | `CentOS `V7 -> `Active `Tier3 | `CentOS (`V6 | `V8) -> `Deprecated @@ -462,7 +465,8 @@ let distro_arches ov (d : t) = [ `I386; `X86_64; `Aarch64; `Aarch32 ] | ( `Alpine ( `V3_6 | `V3_7 | `V3_8 | `V3_9 | `V3_10 | `V3_11 | `V3_12 | `V3_13 - | `V3_14 | `V3_15 | `V3_16 | `V3_17 | `V3_18 | `V3_19 | `V3_20 ), + | `V3_14 | `V3_15 | `V3_16 | `V3_17 | `V3_18 | `V3_19 | `V3_20 | `V3_21 + ), ov ) when OV.(compare Releases.v4_05_0 ov) = -1 -> [ `X86_64; `Aarch64 ] @@ -576,6 +580,7 @@ let builtin_ocaml_of_distro (d : t) : string option = | `Alpine `V3_18 -> Some "4.14.1" | `Alpine `V3_19 -> Some "4.14.1" | `Alpine `V3_20 -> Some "4.14.2" + | `Alpine `V3_21 -> Some "4.14.2" | `Archlinux `Latest -> Some "5.1.0" | `Fedora `V21 -> Some "4.01.0" | `Fedora `V22 -> Some "4.02.0" @@ -704,6 +709,7 @@ let tag_of_distro (d : t) = | `Alpine `V3_18 -> "alpine-3.18" | `Alpine `V3_19 -> "alpine-3.19" | `Alpine `V3_20 -> "alpine-3.20" + | `Alpine `V3_21 -> "alpine-3.21" | `Alpine `Latest -> "alpine" | `Archlinux `Latest -> "archlinux" | `OpenSUSE `V42_1 -> "opensuse-42.1" @@ -920,6 +926,7 @@ let human_readable_string_of_distro (d : t) = | `Alpine `V3_18 -> "Alpine 3.18" | `Alpine `V3_19 -> "Alpine 3.19" | `Alpine `V3_20 -> "Alpine 3.20" + | `Alpine `V3_21 -> "Alpine 3.21" | `Archlinux `Latest -> "Archlinux" | `OpenSUSE `V42_1 -> "OpenSUSE 42.1" | `OpenSUSE `V42_2 -> "OpenSUSE 42.2" @@ -1071,7 +1078,8 @@ let bubblewrap_version (t : t) = | `Alpine `V3_17 -> Some (0, 7, 0) | `Alpine `V3_18 -> Some (0, 8, 0) | `Alpine `V3_19 -> Some (0, 8, 0) - | `Alpine `V3_20 -> Some (0, 9, 0) + | `Alpine `V3_20 -> Some (0, 10, 0) + | `Alpine `V3_21 -> Some (0, 11, 0) | `Archlinux `Latest -> Some (0, 8, 0) | `OpenSUSE `V42_1 -> None (* Not actually checked *) | `OpenSUSE `V42_2 -> None (* Not actually checked *) @@ -1111,6 +1119,7 @@ let base_distro_tag ?(arch = `X86_64) d = | `V3_18 -> "3.18" | `V3_19 -> "3.19" | `V3_20 -> "3.20" + | `V3_21 -> "3.21" in match arch with `I386 -> ("i386/alpine", tag) | _ -> ("alpine", tag)) | `Archlinux `Latest -> ("archlinux", "latest") diff --git a/src-opam/distro.mli b/src-opam/distro.mli index 6b13215..e061ea4 100644 --- a/src-opam/distro.mli +++ b/src-opam/distro.mli @@ -15,10 +15,9 @@ * *) -(** Run Opam commands across a matrix of Docker containers. - Each of these containers represents a different version of - OCaml, Opam and an OS distribution (such as Debian or Alpine). - *) +(** Run Opam commands across a matrix of Docker containers. Each of these + containers represents a different version of OCaml, Opam and an OS + distribution (such as Debian or Alpine). *) (** {2 Known distributions and OCaml variants} *) @@ -41,7 +40,8 @@ type distro = | `V3_17 | `V3_18 | `V3_19 - | `V3_20 ] + | `V3_20 + | `V3_21 ] | `Archlinux of [ `Latest ] | `CentOS of [ `V6 | `V7 | `V8 ] | `Debian of [ `V12 | `V11 | `V10 | `V9 | `V8 | `V7 | `Testing | `Unstable ] @@ -128,6 +128,7 @@ type t = | `V3_18 | `V3_19 | `V3_20 + | `V3_21 | `Latest ] | `Archlinux of [ `Latest ] | `CentOS of [ `V6 | `V7 | `V8 | `Latest ] @@ -207,20 +208,19 @@ val os_family_of_distro : t -> os_family (** [os_family_of_distro t] returns the OS family of the distro. *) val os_family_to_string : os_family -> string -(** [os_family_to_string os] returns a string representing the OS - family. *) +(** [os_family_to_string os] returns a string representing the OS family. *) val opam_repository : os_family -> string -(** [opam_repository os_family] returns the git URL to the default - Opam repository. *) +(** [opam_repository os_family] returns the git URL to the default Opam + repository. *) val personality : os_family -> Ocaml_version.arch -> string option -(** [personality os_family arch] returns the personality associated to - the architecture, if [os_family] is [`Linux]. *) +(** [personality os_family arch] returns the personality associated to the + architecture, if [os_family] is [`Linux]. *) val is_same_distro : t -> t -> bool -(** [is_same_distro d1 d2] returns whether [d1] is the same distro as - [d2], regardless of their respective versions. *) +(** [is_same_distro d1 d2] returns whether [d1] is the same distro as [d2], + regardless of their respective versions. *) val compare : t -> t -> int (** [compare a b] is a lexical comparison function for {!t}. *) @@ -236,21 +236,20 @@ val latest_distros : t list (** Enumeration of the latest stable (ideally LTS) supported distributions. *) val master_distro : t -(** The distribution that is the top-level alias for the [latest] tag - in the [ocaml/opam2] Docker Hub build. *) +(** The distribution that is the top-level alias for the [latest] tag in the + [ocaml/opam2] Docker Hub build. *) val builtin_ocaml_of_distro : t -> string option -(** [builtin_ocaml_of_distro t] will return the OCaml version - supplied with the distribution packaging, and [None] if there - is no supported version. *) +(** [builtin_ocaml_of_distro t] will return the OCaml version supplied with the + distribution packaging, and [None] if there is no supported version. *) val human_readable_string_of_distro : t -> string -(** [human_readable_string_of_distro t] returns a human readable - version of the distribution tag, including version information. *) +(** [human_readable_string_of_distro t] returns a human readable version of the + distribution tag, including version information. *) val human_readable_short_string_of_distro : t -> string -(** [human_readable_short_string_of_distro t] returns a human readable - short version of the distribution tag, excluding version information. *) +(** [human_readable_short_string_of_distro t] returns a human readable short + version of the distribution tag, excluding version information. *) type package_manager = [ `Apk (** Alpine Apk *) @@ -278,59 +277,56 @@ val tag_of_distro : t -> string (** [tag_of_distro t] convert a distribution [t] to a Docker Hub tag. *) val distro_of_tag : string -> t option -(** [distro_of_tag s] parses [s] into a {!t} distribution, and - [None] otherwise. *) +(** [distro_of_tag s] parses [s] into a {!t} distribution, and [None] otherwise. +*) val latest_tag_of_distro : t -> string -(** [latest_tag_of_distro distro] will generate a Docker Hub - tag that is a convenient short form for the latest stable - release of a particular distribution. This tag will be - regularly rewritten to point to any new releases of the - distribution. *) +(** [latest_tag_of_distro distro] will generate a Docker Hub tag that is a + convenient short form for the latest stable release of a particular + distribution. This tag will be regularly rewritten to point to any new + releases of the distribution. *) val base_distro_tag : ?arch:Ocaml_version.arch -> t -> string * string (** [base_distro_tag ?arch t] will return a tuple of a Docker Hub - user/repository and tag for which the base image of a distribution - can be found (e.g. [opensuse/leap],[15.0] which maps to [opensuse/leap:15.0] - on the Docker Hub). This base image is in turn can be used to generate opam - and other OCaml tool Dockerfiles. [arch] defaults to [x86_64] and can vary - the base user/repository since some architecture are built elsewhere. *) + user/repository and tag for which the base image of a distribution can be + found (e.g. [opensuse/leap],[15.0] which maps to [opensuse/leap:15.0] on the + Docker Hub). This base image is in turn can be used to generate opam and + other OCaml tool Dockerfiles. [arch] defaults to [x86_64] and can vary the + base user/repository since some architecture are built elsewhere. *) (** {2 CPU architectures} *) val distro_arches : Ocaml_version.t -> t -> Ocaml_version.arch list -(** [distro_arches ov t] returns the list of architectures that - distribution [t] is supported on for OCaml compiler version [ov] *) +(** [distro_arches ov t] returns the list of architectures that distribution [t] + is supported on for OCaml compiler version [ov] *) val distro_supported_on : Ocaml_version.arch -> Ocaml_version.t -> t -> bool -(** [distro_supported_on arch ov distro] returns [true] if the - combination of CPU [arch], compiler version [ov] is available - on the distribution [distro]. *) +(** [distro_supported_on arch ov distro] returns [true] if the combination of + CPU [arch], compiler version [ov] is available on the distribution [distro]. +*) (** {2 Opam build infrastructure support} *) val active_distros : Ocaml_version.arch -> t list -(** [active_distros arch] returns the list of currently supported - distributions in the opam build infrastructure. Distributions - that are end-of-life upstream will rotate out of this list - regularly. *) +(** [active_distros arch] returns the list of currently supported distributions + in the opam build infrastructure. Distributions that are end-of-life + upstream will rotate out of this list regularly. *) val active_tier1_distros : Ocaml_version.arch -> t list -(** Tier 1 distributions are those supported for the full matrix - of compiler versions in the opam build infrastructure. - The {{:https://github.com/ocurrent/docker-base-images}Docker base images} - will compile a base image for every OCaml version, so this - list should be added to sparingly. *) +(** Tier 1 distributions are those supported for the full matrix of compiler + versions in the opam build infrastructure. The + {{:https://github.com/ocurrent/docker-base-images}Docker base images} will + compile a base image for every OCaml version, so this list should be added + to sparingly. *) val active_tier2_distros : Ocaml_version.arch -> t list -(** Tier 2 distributions are those supported for a limited set - of compiler versions in the opam build infrastructure. The - distros in this list are also tested for packages in the - opam repository. *) +(** Tier 2 distributions are those supported for a limited set of compiler + versions in the opam build infrastructure. The distros in this list are also + tested for packages in the opam repository. *) val active_tier3_distros : Ocaml_version.arch -> t list -(** Tier 3 distributions are those supported for a limited set - of compiler versions in the opam build infrastructure. While - these distros will have base images compiled for them, they - are not widely tested. Distros maybe here as they are on the - way to being deprecated, or new and still experimental. *) +(** Tier 3 distributions are those supported for a limited set of compiler + versions in the opam build infrastructure. While these distros will have + base images compiled for them, they are not widely tested. Distros maybe + here as they are on the way to being deprecated, or new and still + experimental. *) diff --git a/src-opam/dockerfile_opam.ml b/src-opam/dockerfile_opam.ml index f66f783..ac7d8a1 100644 --- a/src-opam/dockerfile_opam.ml +++ b/src-opam/dockerfile_opam.ml @@ -17,8 +17,8 @@ (** Rules for generating Dockerfiles involving OPAM. - These are deployed at {{:https://hub.docker.com/r/ocaml/opam}ocaml/opam} - on the Docker Hub. The interfaces here may change as the production deployments + These are deployed at {{:https://hub.docker.com/r/ocaml/opam}ocaml/opam} on + the Docker Hub. The interfaces here may change as the production deployments there change, so please contact [anil@recoil.org] if you depend on these functions for your own infrastructure. *) diff --git a/src-opam/linux.mli b/src-opam/linux.mli index 0105aac..026d537 100644 --- a/src-opam/linux.mli +++ b/src-opam/linux.mli @@ -41,17 +41,18 @@ module RPM : sig on the supplied package list. ver selects the appropriate syntax *) val add_user : ?uid:int -> ?gid:int -> ?sudo:bool -> string -> t - (** [add_user username] will install a new user with name [username] and a locked - password. If [sudo] is true then root access with no password will also be - configured. The default value for [sudo] is [false]. *) + (** [add_user username] will install a new user with name [username] and a + locked password. If [sudo] is true then root access with no password will + also be configured. The default value for [sudo] is [false]. *) val dev_packages : ?extra:string -> unit -> t - (** [dev_packages ?extra ()] will install the base development tools and [sudo], - [passwd] and [git]. Extra packages may also be optionally supplied via [extra]. *) + (** [dev_packages ?extra ()] will install the base development tools and + [sudo], [passwd] and [git]. Extra packages may also be optionally supplied + via [extra]. *) val ocaml_depexts : Ocaml_version.t -> string option - (** [ocaml_depexts v] returns packages that are required by the - OCaml distribution at version [v]. *) + (** [ocaml_depexts v] returns packages that are required by the OCaml + distribution at version [v]. *) val install_system_ocaml : t (** Install the system OCaml packages via Yum *) @@ -60,23 +61,26 @@ end (** Rules for Apt-based distributions *) module Apt : sig val update : t - (** [update] will run [apt-get update && apt-get upgrade] non-interactively. *) + (** [update] will run [apt-get update && apt-get upgrade] non-interactively. + *) val install : ('a, unit, string, t) format4 -> 'a - (** [install fmt] will [apt-get update && apt-get install] the packages specified by the [fmt] format string. *) + (** [install fmt] will [apt-get update && apt-get install] the packages + specified by the [fmt] format string. *) val add_user : ?uid:int -> ?gid:int -> ?sudo:bool -> string -> t - (** [add_user username] will install a new user with name [username] and a locked - password. If [sudo] is true then root access with no password will also be - configured. The default value for [sudo] is [false]. *) + (** [add_user username] will install a new user with name [username] and a + locked password. If [sudo] is true then root access with no password will + also be configured. The default value for [sudo] is [false]. *) val dev_packages : ?extra:string -> unit -> t - (** [dev_packages ?extra ()] will install the base development tools and [sudo], - [passwd] and [git] and X11. Extra packages may also be optionally supplied via [extra]. *) + (** [dev_packages ?extra ()] will install the base development tools and + [sudo], [passwd] and [git] and X11. Extra packages may also be optionally + supplied via [extra]. *) val ocaml_depexts : Ocaml_version.t -> string option - (** [ocaml_depexts v] returns packages that are required by the - OCaml distribution at version [v]. *) + (** [ocaml_depexts v] returns packages that are required by the OCaml + distribution at version [v]. *) val install_system_ocaml : t (** Install the system OCaml packages via [apt-get] *) @@ -88,20 +92,22 @@ module Apk : sig (** [update] will run [apk update && apk upgrade] non-interactively. *) val install : ('a, unit, string, t) format4 -> 'a - (** [install fmt] will [apk add] the packages specified by the [fmt] format string. *) + (** [install fmt] will [apk add] the packages specified by the [fmt] format + string. *) val dev_packages : ?extra:string -> unit -> t - (** [dev_packages ?extra ()] will install the base development tools and [sudo], - [passwd] and [git]. Extra packages may also be optionally supplied via [extra]. *) + (** [dev_packages ?extra ()] will install the base development tools and + [sudo], [passwd] and [git]. Extra packages may also be optionally supplied + via [extra]. *) val ocaml_depexts : Ocaml_version.t -> string option - (** [ocaml_depexts v] returns packages that are required by the - OCaml distribution at version [v]. *) + (** [ocaml_depexts v] returns packages that are required by the OCaml + distribution at version [v]. *) val add_user : ?uid:int -> ?gid:int -> ?sudo:bool -> string -> t - (** [add_user username] will install a new user with name [username] and a locked - password. If [sudo] is true then root access with no password will also be - configured. The default value for [sudo] is [false]. *) + (** [add_user username] will install a new user with name [username] and a + locked password. If [sudo] is true then root access with no password will + also be configured. The default value for [sudo] is [false]. *) val install_system_ocaml : t (** Install the system OCaml packages via Apk *) @@ -110,7 +116,8 @@ module Apk : sig (** [add_repository ~tag url] adds "@tag url" to "/etc/apk/repositories". *) val add_repositories : (string option * string) list -> t - (** [add_repositories repos] adds a list of "@tag url" to "/etc/apk/repositories". *) + (** [add_repositories repos] adds a list of "@tag url" to + "/etc/apk/repositories". *) end (** Rules for Zypper-based distributions such as OpenSUSE *) @@ -119,20 +126,22 @@ module Zypper : sig (** [update] will run [zypper update] non-interactively. *) val install : ('a, unit, string, t) format4 -> 'a - (** [install fmt] will [zypper update && zypper install] the packages specified by the [fmt] format string. *) + (** [install fmt] will [zypper update && zypper install] the packages + specified by the [fmt] format string. *) val add_user : ?uid:int -> ?gid:int -> ?sudo:bool -> string -> t - (** [add_user username] will install a new user with name [username] and a locked - password. If [sudo] is true then root access with no password will also be - configured. The default value for [sudo] is [false]. *) + (** [add_user username] will install a new user with name [username] and a + locked password. If [sudo] is true then root access with no password will + also be configured. The default value for [sudo] is [false]. *) val dev_packages : ?extra:string -> unit -> t - (** [dev_packages ?extra ()] will install the base development tools and [sudo], - [passwd] and [git]. Extra packages may also be optionally supplied via [extra]. *) + (** [dev_packages ?extra ()] will install the base development tools and + [sudo], [passwd] and [git]. Extra packages may also be optionally supplied + via [extra]. *) val ocaml_depexts : Ocaml_version.t -> string option - (** [ocaml_depexts v] returns packages that are required by the - OCaml distribution at version [v]. *) + (** [ocaml_depexts v] returns packages that are required by the OCaml + distribution at version [v]. *) val install_system_ocaml : t (** Install the system OCaml packages via [zypper] *) @@ -144,20 +153,22 @@ module Pacman : sig (** [update] will run [pacman -Syu] non-interactively. *) val install : ('a, unit, string, t) format4 -> 'a - (** [install fmt] will [pacman -Syu] the packages specified by the [fmt] format string. *) + (** [install fmt] will [pacman -Syu] the packages specified by the [fmt] + format string. *) val add_user : ?uid:int -> ?gid:int -> ?sudo:bool -> string -> t - (** [add_user username] will install a new user with name [username] and a locked - password. If [sudo] is true then root access with no password will also be - configured. The default value for [sudo] is [false]. *) + (** [add_user username] will install a new user with name [username] and a + locked password. If [sudo] is true then root access with no password will + also be configured. The default value for [sudo] is [false]. *) val dev_packages : ?extra:string -> unit -> t - (** [dev_packages ?extra ()] will install the base development tools and [sudo], - [passwd] and [git]. Extra packages may also be optionally supplied via [extra]. *) + (** [dev_packages ?extra ()] will install the base development tools and + [sudo], [passwd] and [git]. Extra packages may also be optionally supplied + via [extra]. *) val ocaml_depexts : Ocaml_version.t -> string option - (** [ocaml_depexts v] returns packages that are required by the - OCaml distribution at version [v]. *) + (** [ocaml_depexts v] returns packages that are required by the OCaml + distribution at version [v]. *) val install_system_ocaml : t (** Install the system OCaml packages via [pacman] *) diff --git a/src-opam/opam.ml b/src-opam/opam.ml index 5663928..85ebbe2 100644 --- a/src-opam/opam.ml +++ b/src-opam/opam.ml @@ -270,7 +270,7 @@ let create_opam_branches_windows opam_hashes = (* Note this is a lexicographic comparison * branches are "2.0", "2.1", "2.2" and "master" * Select "master" and 2.2 and later *) - (fun { branch; _ } -> branch >= "2.2") + (fun { branch; _ } -> branch >= "2.2") branches ) let install_opams ?prefix opam_master_hash opam_branches = @@ -280,7 +280,8 @@ let install_opams ?prefix opam_master_hash opam_branches = shell/bootstrap-ocaml.sh && make -C src_ext cache-archives" opam_master_hash @@ List.fold_left - (fun acc { branch; hash; enable_0install_solver; with_vendored_deps; _ } -> + (fun acc { branch; hash; enable_0install_solver; with_vendored_deps; _ } + -> acc @@ install_opam_from_source ~add_default_link:false ?prefix ~enable_0install_solver ~with_vendored_deps ~branch ~hash ()) @@ -294,7 +295,8 @@ let install_opams_windows ?cyg ?prefix ?msvs opam_master_hash opam_branches = opam_master_hash (if Option.value ~default:false msvs then "OCAML_PORT=msvc64" else "") @@ List.fold_left - (fun acc { branch; hash; enable_0install_solver; with_vendored_deps; _ } -> + (fun acc { branch; hash; enable_0install_solver; with_vendored_deps; _ } + -> acc @@ install_opam_from_source_windows ?cyg ?prefix ?msvs ~enable_0install_solver ~with_vendored_deps ~branch ~hash ()) @@ -744,7 +746,8 @@ let multiarch_manifest ~target ~platforms = \ image: %s\n\ \ platform:\n\ \ architecture: %s\n\ - \ os: linux" image arch) + \ os: linux" + image arch) platforms |> String.concat "\n" in diff --git a/src-opam/opam.mli b/src-opam/opam.mli index 7c85180..23680e6 100644 --- a/src-opam/opam.mli +++ b/src-opam/opam.mli @@ -18,8 +18,8 @@ (** OPAM-specific Dockerfile rules. *) val run_as_opam : ('a, unit, string, Dockerfile.t) format4 -> 'a -(** [run_as_opam fmt] runs the command specified by the [fmt] - format string as the [opam] user. *) +(** [run_as_opam fmt] runs the command specified by the [fmt] format string as + the [opam] user. *) val install_opam_from_source : ?add_default_link:bool -> @@ -30,16 +30,15 @@ val install_opam_from_source : hash:string -> unit -> Dockerfile.t -(** Commands to install OPAM via a source code checkout from GitHub. - The [branch] can be a git tag or branch (e.g. [2.0] for opam 2.0.x or [2.1] for - the opam 2.1.x). - The binaries are installed under [/bin/opam-], - defaulting to [/usr/local/bin]. - If [add_default_link] is true (the default), then the [opam-] - binary is hardlinked to [opam]. Set it to false if you want to install - multiple opam binaries from different branches in the same container. - If [enable_0install_solver] is true (false by default), then the [builtin-0install] - solver should be accessible in the resulting opam binary. +(** Commands to install OPAM via a source code checkout from GitHub. The + [branch] can be a git tag or branch (e.g. [2.0] for opam 2.0.x or [2.1] for + the opam 2.1.x). The binaries are installed under + [/bin/opam-], defaulting to [/usr/local/bin]. If + [add_default_link] is true (the default), then the [opam-] binary is + hardlinked to [opam]. Set it to false if you want to install multiple opam + binaries from different branches in the same container. If + [enable_0install_solver] is true (false by default), then the + [builtin-0install] solver should be accessible in the resulting opam binary. Configure opam build [with_vendored_deps]. Required for opam 2.2. *) type opam_hashes = { @@ -58,35 +57,34 @@ val gen_opam2_distro : opam_hashes:opam_hashes -> Distro.t -> string * Dockerfile.t -(** [gen_opam2_distro ~opam_hashes d] will generate a Dockerfile - for Linux distribution [d] with opam 2.0, opam 2.1, opam 2.2 and opam master, - per hash given in parameter. - @return a tuple of the Docker tag and the Dockerfile. - If [clone_opam_repo] is true (the default) then the Dockerfile will also git - clone the official opam-repository into [/home/opam/opam-repository]. - If [arch] is not specified, it defaults to the base image that is assumed - to be multiarch (the main exception to this is i386, which requires different - base images from amd64). - For native Windows distributions, if [winget] is omitted, then winget - will be build in an prepended build stage. If specified, then - winget will be pulled from the [winget] external image. *) +(** [gen_opam2_distro ~opam_hashes d] will generate a Dockerfile for Linux + distribution [d] with opam 2.0, opam 2.1, opam 2.2 and opam master, per hash + given in parameter. + @return + a tuple of the Docker tag and the Dockerfile. If [clone_opam_repo] is true + (the default) then the Dockerfile will also git clone the official + opam-repository into [/home/opam/opam-repository]. If [arch] is not + specified, it defaults to the base image that is assumed to be multiarch + (the main exception to this is i386, which requires different base images + from amd64). For native Windows distributions, if [winget] is omitted, + then winget will be build in an prepended build stage. If specified, then + winget will be pulled from the [winget] external image. *) val ocaml_depexts : Distro.t -> Ocaml_version.t -> Dockerfile.t -(** [ocaml_depexts distro version] returns packages that are - required under [distro] by the OCaml distribution at version - [version]. *) +(** [ocaml_depexts distro version] returns packages that are required under + [distro] by the OCaml distribution at version [version]. *) val all_ocaml_compilers : string -> Ocaml_version.arch -> Distro.t -> string * Dockerfile.t -(** [all_ocaml_compilers hub_id arch distro] will generate an opam2 - container that has all the recent OCaml compilers installed into a - distribution [distro] on architecture [arch]. *) +(** [all_ocaml_compilers hub_id arch distro] will generate an opam2 container + that has all the recent OCaml compilers installed into a distribution + [distro] on architecture [arch]. *) val separate_ocaml_compilers : string -> Ocaml_version.arch -> Distro.t -> (string * Dockerfile.t) list (** [separate_ocaml_compilers hub_id arch distro] will install a list of - Dockerfiles that build individual OCaml compiler versions and their - variants (e.g. flambda) in separate containers. *) + Dockerfiles that build individual OCaml compiler versions and their variants + (e.g. flambda) in separate containers. *) val deprecated : Dockerfile.t (** [deprecated] is a minimal container that outputs a deprecation error. This @@ -95,5 +93,6 @@ val deprecated : Dockerfile.t val multiarch_manifest : target:string -> platforms:(string * string) list -> string -(** [multiarch_manifest ~target ~platforms] will generate a manifest-tool compliant yaml file to - build a [target] on the given multiarch [platforms]. *) +(** [multiarch_manifest ~target ~platforms] will generate a manifest-tool + compliant yaml file to build a [target] on the given multiarch [platforms]. +*) diff --git a/src-opam/windows.mli b/src-opam/windows.mli index 75d2820..c6dab5a 100644 --- a/src-opam/windows.mli +++ b/src-opam/windows.mli @@ -26,18 +26,18 @@ val run_powershell : ?escape:(string -> string) -> ('a, unit, string, t) format4 -> 'a (** [run_powershell fmt] will execute [powershell -Command "fmt"]. - @param escape (defaults to {!Fun.id}) allows to escape [fmt] - because the calling shell (usually [cmd]) might interpret - unwanted things in [fmt]. This might help embedding readable - powershell code. *) + @param escape + (defaults to {!Fun.id}) allows to escape [fmt] because the calling shell + (usually [cmd]) might interpret unwanted things in [fmt]. This might help + embedding readable powershell code. *) val run_vc : arch:Ocaml_version.arch -> ('a, unit, string, t) format4 -> 'a -(** [run_vc ~arch fmt] will execute [run fmt] with Visual - Compiler for [~arch] loaded in the environment. *) +(** [run_vc ~arch fmt] will execute [run fmt] with Visual Compiler for [~arch] + loaded in the environment. *) val run_ocaml_env : string list -> ('a, unit, string, t) format4 -> 'a -(** [run_ocaml_env args fmt] will execute [fmt] in the environment - loaded by [ocaml-env exec] with [args]. *) +(** [run_ocaml_env args fmt] will execute [fmt] in the environment loaded by + [ocaml-env exec] with [args]. *) val sanitize_reg_path : unit -> t [@@ocaml.doc @@ -54,14 +54,16 @@ val sanitize_reg_path : unit -> t val install_vc_redist : ?vs_version:string -> ?arch:Ocaml_version.arch -> unit -> t (** Install Microsoft Visual C++ Redistributable. - @see *) + @see +*) val install_visual_studio_build_tools : ?vs_version:string -> string list -> t (** Install Visual Studio Build Tools components. @see @see - @see *) + @see +*) val ocaml_for_windows_package_exn : switch:Ocaml_version.t -> @@ -69,12 +71,12 @@ val ocaml_for_windows_package_exn : arch:Ocaml_version.arch -> string * string (** [ocaml_for_windows_variant ~port ~arch] returns the - [(package_name, package_version)] of the OCaml compiler - package in OCaml for Windows, if applicable. *) + [(package_name, package_version)] of the OCaml compiler package in OCaml for + Windows, if applicable. *) val remove_system_attribute : ?recurse:bool -> string -> t -(** Remove the system attribute on a path. Might be useful to copy - data across images when building Docker images. *) +(** Remove the system attribute on a path. Might be useful to copy data across + images when building Docker images. *) val header : ?alias:string -> override_tag:string option -> Distro.t -> t (** A Dockerfile header for multi-staged builds. *) @@ -86,7 +88,8 @@ module Cygwin : sig site : string; (** Download site URL *) args : string list; } - (** List of arguments to give to Cygwin's setup, except [--root] and [--site]. *) + (** List of arguments to give to Cygwin's setup, except [--root] and [--site]. + *) val default : cyg (** The default Cygwin root, mirror, and arguments. *) @@ -98,9 +101,9 @@ module Cygwin : sig ?extra:string list -> unit -> Dockerfile.t - (** Install Cygwin with CygSymPathy and optionally msvs-tools, - and [extra] Cygwin packages (first in a separate Docker image). - Sets the [CYGWIN=winsymlinks:native] environment variable. + (** Install Cygwin with CygSymPathy and optionally msvs-tools, and [extra] + Cygwin packages (first in a separate Docker image). Sets the + [CYGWIN=winsymlinks:native] environment variable. @see @see *) @@ -115,22 +118,21 @@ module Cygwin : sig (** Update Cygwin packages. *) val cygwin_packages : ?flexdll_version:string -> unit -> string list - (** [cygwin_packages ?extra ()] is the list of the base development - tools for the OCaml Cygwin port. *) + (** [cygwin_packages ?extra ()] is the list of the base development tools for + the OCaml Cygwin port. *) val mingw_packages : string list - (** [mingw_packages] is the list of base development tools for the - Caml mingw port. *) + (** [mingw_packages] is the list of base development tools for the Caml mingw + port. *) val msvc_packages : string list - (** [msvc_packages] is the list of base development tools for the - Caml MSVC port. *) + (** [msvc_packages] is the list of base development tools for the Caml MSVC + port. *) val install_ocaml_for_windows : ?cyg:cyg -> ?version:string -> unit -> string list * t - (** [install_ocaml_for_windows ()] returns the list of Cygwin - packages dependencies, and the installation instructions for - OCaml for Windows. + (** [install_ocaml_for_windows ()] returns the list of Cygwin packages + dependencies, and the installation instructions for OCaml for Windows. @see *) val run_sh : ?cyg:cyg -> ('a, unit, string, t) format4 -> 'a @@ -139,8 +141,8 @@ module Cygwin : sig val run_sh_ocaml_env : ?cyg:cyg -> string list -> ('a, unit, string, t) format4 -> 'a - (** [run_cmd_ocaml_env args fmt] will execute [fmt] in the environment - loaded by [ocaml-env cygwin exec] with [args]. *) + (** [run_cmd_ocaml_env args fmt] will execute [fmt] in the environment loaded + by [ocaml-env cygwin exec] with [args]. *) (** Rules for Git. *) module Git : sig @@ -153,9 +155,9 @@ module Cygwin : sig t (** Configure the git name and email variables to sensible defaults. - @param repos A list of paths to Git repos to mark as safe - directories. Defaults to the default location of the - opam-repository. *) + @param repos + A list of paths to Git repos to mark as safe directories. Defaults to + the default location of the opam-repository. *) end end @@ -163,8 +165,8 @@ end @see *) module Winget : sig val install_from_release : ?winget_version:string -> unit -> t - (** Install winget from a released build (first in a separate Docker - image). The optional [winget_version] specifies a Git tag. *) + (** Install winget from a released build (first in a separate Docker image). + The optional [winget_version] specifies a Git tag. *) val setup : ?from:string -> unit -> t (** Setup winget, optionally copied from the [from] Docker image. Disable @@ -174,16 +176,16 @@ module Winget : sig (** [install packages] will install the supplied winget package list. *) val dev_packages : distro:Distro.t -> ?extra:string list -> unit -> t - (** [dev_packages distro ?extra ()] will install the base development - tools. Extra packages may also be optionally supplied via [extra]. *) + (** [dev_packages distro ?extra ()] will install the base development tools. + Extra packages may also be optionally supplied via [extra]. *) (** Rules for Git. *) module Git : sig val init : ?name:string -> ?email:string -> ?repos:string list -> unit -> t (** Configure the git name and email variables to sensible defaults. - @param repos A list of paths to Git repos to mark as safe - directories. Defaults to the default location of the - opam-repository. *) + @param repos + A list of paths to Git repos to mark as safe directories. Defaults to + the default location of the opam-repository. *) end end diff --git a/src/dockerfile.mli b/src/dockerfile.mli index 36a746b..b6a84f5 100644 --- a/src/dockerfile.mli +++ b/src/dockerfile.mli @@ -28,8 +28,8 @@ val sexp_of_t : t -> Sexplib.Sexp.t (** [sexp_of_t t] converts a Dockerfile into a s-expression representation. *) val t_of_sexp : Sexplib.Sexp.t -> t -(** [t_of_sexp s] converts the [s] s-expression representation into a {!t}. - The s-expression should have been generated using {!sexp_of_t}. *) +(** [t_of_sexp s] converts the [s] s-expression representation into a {!t}. The + s-expression should have been generated using {!sexp_of_t}. *) val string_of_t : t -> string (** [string_of_t t] converts a {!t} into a Dockerfile format entry *) @@ -56,8 +56,7 @@ type parser_directive = [ `Syntax of string | `Escape of char ] [@@deriving sexp] val parser_directive : parser_directive -> t -(** A parser directive. If used, needs to be the first line of the - Dockerfile. +(** A parser directive. If used, needs to be the first line of the Dockerfile. @see @see *) @@ -78,18 +77,19 @@ val heredoc : ('a, unit, string, heredoc) format4 -> 'a (** [heredoc ~word here_document] creates a {!type:heredoc} value with - [here_document] as content and [word] () as opening delimiter. If - [word] is quoted, then [delimiter] (unquoted [word]) needs to be - specified. Quoting affects expansion in the here-document. - Requires 1.4 {!val:buildkit_syntax}. + [here_document] as content and [word] () as opening delimiter. If [word] is + quoted, then [delimiter] (unquoted [word]) needs to be specified. Quoting + affects expansion in the here-document. Requires 1.4 {!val:buildkit_syntax}. @param strip Whether to strip leading tab characters. Defaults to false. @param word The opening delimiter, possibly quoted. Defaults to [EOF]. - @param delimiter The closing delimiter, unquoted. Defaults to the - content of [word]. + @param delimiter + The closing delimiter, unquoted. Defaults to the content of [word]. - @see POSIX 2.7.4 Here-Document - @see BuildKit Here-Documents *) + @see + POSIX 2.7.4 Here-Document + @see + BuildKit Here-Documents *) val from : ?alias:string -> ?tag:string -> ?platform:string -> string -> t (** The [from] instruction sets the base image for subsequent instructions. @@ -98,24 +98,23 @@ val from : ?alias:string -> ?tag:string -> ?platform:string -> string -> t can be any valid image. - [from] must be the first non-comment instruction in the Dockerfile. - [from] can appear multiple times within a single Dockerfile in order to - create multiple images. Multiple FROM commands will result in a multi-stage - build, and the [?from] argument to the {!copy} and {!add} functions - can move artefacts across stages. + create multiple images. Multiple FROM commands will result in a + multi-stage build, and the [?from] argument to the {!copy} and {!add} + functions can move artefacts across stages. - By default, the stages are not named, and you refer to them by their - integer number, starting with 0 for the first [FROM] instruction. However, - you can name your stages, by supplying an [?alias] argument. The alias - can be supplied to the [?from] parameter to {!copy} or {!add} to refer - to this particular stage by name. + By default, the stages are not named, and you refer to them by their integer + number, starting with 0 for the first [FROM] instruction. However, you can + name your stages, by supplying an [?alias] argument. The alias can be + supplied to the [?from] parameter to {!copy} or {!add} to refer to this + particular stage by name. If no [tag] is supplied, [latest] is assumed. If the used tag does not exist, an error will be returned. The optional [platform] flag can be used to specify the platform of the - image in case the [from] references a multi-platform image. For example, + image in case the [from] references a multi-platform image. For example, [linux/386] could be used. By default, the target platform of the build - request is ued if this is not specified. -*) + request is ued if this is not specified. *) val maintainer : ('a, unit, string, t) format4 -> 'a (** [maintainer] sets the author field of the generated images. *) @@ -135,15 +134,18 @@ val run : committed image will be used for the next step in the Dockerfile. The string result of formatting [arg] will be passed as a [/bin/sh -c] invocation. - @param mounts A list of filesystem mounts that the build can access. Requires + @param mounts + A list of filesystem mounts that the build can access. Requires {!val:buildkit_syntax} 1.2. - @param network Control which networking environment the command is run in. - Requires {!val:buildkit_syntax} 1.1. - Requires BuildKit {{!val:parser_directive}syntax} 1.1. + @param network + Control which networking environment the command is run in. Requires + {!val:buildkit_syntax} 1.1. Requires BuildKit + {{!val:parser_directive}syntax} 1.1. - @param security Control which security mode the command is run in. - Requires BuildKit {{!val:parser_directive}syntax} 1-labs. *) + @param security + Control which security mode the command is run in. Requires BuildKit + {{!val:parser_directive}syntax} 1-labs. *) val run_exec : ?mounts:mount list -> @@ -157,14 +159,17 @@ val run_exec : form makes it possible to avoid shell string munging, and to run commands using a base image that does not contain [/bin/sh]. - @param mounts A list of filesystem mounts that the build can access. Requires + @param mounts + A list of filesystem mounts that the build can access. Requires {!val:buildkit_syntax} 1.2. - @param network Control which networking environment the command is run in. - Requires {!val:buildkit_syntax} 1.1. + @param network + Control which networking environment the command is run in. Requires + {!val:buildkit_syntax} 1.1. - @param security Control which security mode the command is run in. Requires - BuildKit {{!val:parser_directive}syntax} 1-labs. *) + @param security + Control which security mode the command is run in. Requires BuildKit + {{!val:parser_directive}syntax} 1-labs. *) val run_heredoc : ?mounts:mount list -> @@ -177,15 +182,18 @@ val run_heredoc : committed image will be used for the next step in the Dockerfile. The string result of formatting [arg] will be passed as a [/bin/sh -c] invocation. - @param mounts A list of filesystem mounts that the build can access. Requires + @param mounts + A list of filesystem mounts that the build can access. Requires {!val:buildkit_syntax} 1.2. - @param network Control which networking environment the command is run in. - Requires {!val:buildkit_syntax} 1.1. Requires BuildKit + @param network + Control which networking environment the command is run in. Requires + {!val:buildkit_syntax} 1.1. Requires BuildKit {{!val:parser_directive}syntax} 1.1. - @param security Control which security mode the command is run in. Requires - BuildKit {{!val:parser_directive}syntax} 1-labs. *) + @param security + Control which security mode the command is run in. Requires BuildKit + {{!val:parser_directive}syntax} 1-labs. *) val mount_bind : target:string -> @@ -194,17 +202,24 @@ val mount_bind : ?readwrite:bool -> unit -> mount -(** [mount_bind ~target ?source ?from ?readwrite ()] Creates a bind mount for {!run}. +(** [mount_bind ~target ?source ?from ?readwrite ()] Creates a bind mount for + {!run}. Requires {!buildkit_syntax}. - @param target the target of the mount inside the container. Usually a path, but for 'podman' it can also contain SELinux flags like ',z' or ',Z' + @param target + the target of the mount inside the container. Usually a path, but for + 'podman' it can also contain SELinux flags like ',z' or ',Z' @param from a build stage to bind mount from (if absent: bind mount host) - @param source path to mount. When [from] is absent this is relative to the build context on the host. When [source] is absent it defaults to root of [from]. - @param readwrite enables writing to the mount (default: read-only). The data written is not persisted, [source] always remains unchanged. + @param source + path to mount. When [from] is absent this is relative to the build context + on the host. When [source] is absent it defaults to root of [from]. + @param readwrite + enables writing to the mount (default: read-only). The data written is not + persisted, [source] always remains unchanged. - @see Docker --mount=type=bind reference -*) + @see + Docker --mount=type=bind reference *) val mount_cache : ?id:string -> @@ -218,28 +233,34 @@ val mount_cache : ?gid:int -> unit -> mount -(** [mount_cache ?id ~target ?readonly ?sharing ?from ?source ?mode ?uid ?gid ()] Creates a cache mount for {!run}. +(** [mount_cache ?id ~target ?readonly ?sharing ?from ?source ?mode ?uid ?gid + ()] Creates a cache mount for {!run}. Requires {!buildkit_syntax}. - @param id the cache id: all container builds with same cache id (even from other unrelated builds) will get the same writable directory mounted. - Defaults to [target] when absent. - @param target where to mount the cache inside the container. The [RUN] - command needs to cope with a completely empty cache, and with files from the - cache being deleted by the container runtime's GC in arbitrary order. - E.g. a download cache would be suitable here, an entire git repository wouldn't. - Also make sure that your RUN commands doesn't inadvertently wipe the cache - (e.g. apt inside a container by default would). + @param id + the cache id: all container builds with same cache id (even from other + unrelated builds) will get the same writable directory mounted. Defaults + to [target] when absent. + @param target + where to mount the cache inside the container. The [RUN] command needs to + cope with a completely empty cache, and with files from the cache being + deleted by the container runtime's GC in arbitrary order. E.g. a download + cache would be suitable here, an entire git repository wouldn't. Also make + sure that your RUN commands doesn't inadvertently wipe the cache (e.g. apt + inside a container by default would). @param readonly whether the cache is read-only (by default it is writable) - @param sharing how to share the cache between concurrent builds. The default is [`Shared] which doesn't use any locking. + @param sharing + how to share the cache between concurrent builds. The default is [`Shared] + which doesn't use any locking. @param from the stage to use for the initial contents of the cache. @param source the initial contents of the cache, default is empty. @param mode file mode for cache directory @param uid UID of cache directory, default 0. @param gid GID of cache directory, default 0. - @see Docker --mount=type=cache reference -*) + @see + Docker --mount=type=cache reference *) val mount_tmpfs : target:string -> ?size:int -> unit -> mount (** [mount_tmpfs ~target ?size ())] Creates a tmpfs mount for {!run}. @@ -249,11 +270,12 @@ val mount_tmpfs : target:string -> ?size:int -> unit -> mount @param target mounts a [tmpfs] at [target] @param size maximum size of [tmpfs] (only supported by Docker) - Note that the directory seems to be completely removed from the image, so once you start using [tmpfs] for a dir, - it is recommended that all further [RUN] commands use it too to avoid ENOENT errors. + Note that the directory seems to be completely removed from the image, so + once you start using [tmpfs] for a dir, it is recommended that all further + [RUN] commands use it too to avoid ENOENT errors. - @see Docker --mount=type=tmpfs reference -*) + @see + Docker --mount=type=tmpfs reference *) val mount_secret : ?id:string -> @@ -264,12 +286,13 @@ val mount_secret : ?gid:int -> unit -> mount -(** [mount_secret ?id ?target ?required ?mode ?uid ?gid] Creates a secret mount for {!run}. +(** [mount_secret ?id ?target ?required ?mode ?uid ?gid] Creates a secret mount + for {!run}. Requires {!buildkit_syntax}. - @see Docker --mount=type=secret reference -*) + @see + Docker --mount=type=secret reference *) val mount_ssh : ?id:string -> @@ -280,52 +303,53 @@ val mount_ssh : ?gid:int -> unit -> mount -(** [mount_ssh ?id ?target ?required ?mode ?uid ?gid] Creates an ssh mount for {!run}. +(** [mount_ssh ?id ?target ?required ?mode ?uid ?gid] Creates an ssh mount for + {!run}. Requires {!buildkit_syntax}. Seems to be only supported by Docker at the moment. - @see Docker --mount=type=ssh reference -*) + @see + Docker --mount=type=ssh reference *) val cmd : ('a, unit, string, t) format4 -> 'a -(** [cmd args] provides defaults for an executing container. These defaults - can include an executable, or they can omit the executable, in which case - you must specify an {!entrypoint} as well. The string result of formatting - [arg] will be passed as a [/bin/sh -c] invocation. +(** [cmd args] provides defaults for an executing container. These defaults can + include an executable, or they can omit the executable, in which case you + must specify an {!entrypoint} as well. The string result of formatting [arg] + will be passed as a [/bin/sh -c] invocation. - There can only be one [cmd] in a Dockerfile. If you list more than one - then only the last [cmd] will take effect. *) + There can only be one [cmd] in a Dockerfile. If you list more than one then + only the last [cmd] will take effect. *) val cmd_exec : string list -> t (** [cmd_exec args] provides defaults for an executing container. These defaults can include an executable, or they can omit the executable, in which case - you must specify an {!entrypoint} as well. The first argument to the [args] + you must specify an {!entrypoint} as well. The first argument to the [args] list must be the full path to the executable. - There can only be one [cmd] in a Dockerfile. If you list more than one - then only the last [cmd] will take effect. *) + There can only be one [cmd] in a Dockerfile. If you list more than one then + only the last [cmd] will take effect. *) val expose_port : int -> t (** [expose_port] informs Docker that the container will listen on the specified network port at runtime. *) val expose_ports : int list -> t -(** [expose_ports] informs Docker that the container will listen on the specified - network ports at runtime. *) +(** [expose_ports] informs Docker that the container will listen on the + specified network ports at runtime. *) val arg : ?default:string -> string -> t -(** [arg ~default name] defines a variable that users can pass at - build-time to the builder with the docker build command using the - [--build-arg =] flag. It can optionally include a - default value. *) +(** [arg ~default name] defines a variable that users can pass at build-time to + the builder with the docker build command using the + [--build-arg =] flag. It can optionally include a default + value. *) val env : (string * string) list -> t -(** [env] sets the list of environment variables supplied with the - (, ) tuple. This value will be passed to all future {!run} - instructions. This is functionally equivalent to prefixing a shell - command with [=]. *) +(** [env] sets the list of environment variables supplied with the (, + ) tuple. This value will be passed to all future {!run} instructions. + This is functionally equivalent to prefixing a shell command with + [=]. *) val add : ?link:bool -> @@ -338,47 +362,48 @@ val add : dst:string -> unit -> t -(** [add ?link ?chown ?chmod ?from ~src ~dst ()] copies new files, - directories or remote file URLs from [src] and adds them to the - filesystem of the container at the [dst] path. +(** [add ?link ?chown ?chmod ?from ~src ~dst ()] copies new files, directories + or remote file URLs from [src] and adds them to the filesystem of the + container at the [dst] path. Multiple [src] resource may be specified but if they are files or - directories then they must be relative to the source directory that - is being built (the context of the build). - - Each [src] may contain wildcards and matching will be done using - Go's filepath.Match rules. - - All new files and directories are created with a UID and GID of 0. - In the case where [src] is a remote file URL, the destination will - have permissions of 600. If the remote file being retrieved has an - HTTP Last-Modified header, the timestamp from that header will be - used to set the mtime on the destination file. Then, like any other - file processed during an ADD, mtime will be included in the - determination of whether or not the file has changed and the cache - should be updated. - - @param link Add files with enhanced semantics where your files - remain independent on their own layer and don’t get invalidated - when commands on previous layers are changed. - Requires 1.4 {!val:buildkit_syntax}. - - @param chown Specify a given username, groupname, or UID/GID - combination to request specific ownership of the copied - content. - - @param chmod Specify permissions on the files. Only supported on - Linux, with Dockerfile syntax 1.3. - - @param from Allows artefacts to be retrieved from multiple - stages. It can either be an integer number (starting with 0 for - the first {!from} stage, or a named stage (supplied via [?alias] - to the {!from} command). + directories then they must be relative to the source directory that is being + built (the context of the build). + + Each [src] may contain wildcards and matching will be done using Go's + filepath.Match rules. + + All new files and directories are created with a UID and GID of 0. In the + case where [src] is a remote file URL, the destination will have permissions + of 600. If the remote file being retrieved has an HTTP Last-Modified header, + the timestamp from that header will be used to set the mtime on the + destination file. Then, like any other file processed during an ADD, mtime + will be included in the determination of whether or not the file has changed + and the cache should be updated. + + @param link + Add files with enhanced semantics where your files remain independent on + their own layer and don’t get invalidated when commands on previous layers + are changed. Requires 1.4 {!val:buildkit_syntax}. + + @param chown + Specify a given username, groupname, or UID/GID combination to request + specific ownership of the copied content. + + @param chmod + Specify permissions on the files. Only supported on Linux, with Dockerfile + syntax 1.3. + + @param from + Allows artefacts to be retrieved from multiple stages. It can either be an + integer number (starting with 0 for the first {!from} stage, or a named + stage (supplied via [?alias] to the {!from} command). @param checksum Verify a remote file checksum. - @param keep_git_dir When cloning a Git repository, the flag adds - the [.git] directory. This flag defaults to false. *) + @param keep_git_dir + When cloning a Git repository, the flag adds the [.git] directory. This + flag defaults to false. *) val copy : ?link:bool -> @@ -389,110 +414,108 @@ val copy : dst:string -> unit -> t -(** [copy ?link ?chown ?from ~src ~dst ()] copies new files or - directories from [src] and adds them to the filesystem of the - container at the path [dst]. See {!add} for more detailed - documentation. +(** [copy ?link ?chown ?from ~src ~dst ()] copies new files or directories from + [src] and adds them to the filesystem of the container at the path [dst]. + See {!add} for more detailed documentation. - @param link Copy files with enhanced semantics where your files - remain independent on their own layer and don’t get invalidated - when commands on previous layers are changed. - Requires 1.4 {!val:buildkit_syntax}. + @param link + Copy files with enhanced semantics where your files remain independent on + their own layer and don’t get invalidated when commands on previous layers + are changed. Requires 1.4 {!val:buildkit_syntax}. - @param chown Specify a given username, groupname, or UID/GID - combination to request specific ownership of the copied content. + @param chown + Specify a given username, groupname, or UID/GID combination to request + specific ownership of the copied content. - @param chmod Specify permissions on the files. Only supported on - Linux, with Dockerfile syntax 1.3. + @param chmod + Specify permissions on the files. Only supported on Linux, with Dockerfile + syntax 1.3. - @param from Allows artefacts to be retrieved from multiple - stages. It can either be an integer number (starting with 0 for - the first {!from} stage, or a named stage (supplied via [?alias] - to the {!from} command). *) + @param from + Allows artefacts to be retrieved from multiple stages. It can either be an + integer number (starting with 0 for the first {!from} stage, or a named + stage (supplied via [?alias] to the {!from} command). *) val copy_heredoc : ?chown:string -> ?chmod:int -> src:heredoc list -> dst:string -> unit -> t -(** [copy_heredoc src dst] creates the file [dst] using the content of - the here-documents [src]. - Requires 1.4 {!val:buildkit_syntax}. +(** [copy_heredoc src dst] creates the file [dst] using the content of the + here-documents [src]. Requires 1.4 {!val:buildkit_syntax}. - @see *) + @see +*) val user : ('a, unit, string, t) format4 -> 'a -(** [user fmt] sets the user name or UID to use when running the image - and for any {!run}, {!cmd}, {!entrypoint} commands that follow it in - the Dockerfile. *) +(** [user fmt] sets the user name or UID to use when running the image and for + any {!run}, {!cmd}, {!entrypoint} commands that follow it in the Dockerfile. +*) val workdir : ('a, unit, string, t) format4 -> 'a -(** [workdir fmt] sets the working directory for any {!run}, {!cmd} - and {!entrypoint} instructions that follow it in the Dockerfile. +(** [workdir fmt] sets the working directory for any {!run}, {!cmd} and + {!entrypoint} instructions that follow it in the Dockerfile. - It can be used multiple times in the one Dockerfile. If a relative - path is provided, it will be relative to the path of the previous - {!workdir} instruction. *) + It can be used multiple times in the one Dockerfile. If a relative path is + provided, it will be relative to the path of the previous {!workdir} + instruction. *) val volume : ('a, unit, string, t) format4 -> 'a -(** [volume fmt] will create a mount point with the specified name - and mark it as holding externally mounted volumes from native host - or other containers. The value can be a JSON array or a plain string - with multiple arguments that specify several mount points. *) +(** [volume fmt] will create a mount point with the specified name and mark it + as holding externally mounted volumes from native host or other containers. + The value can be a JSON array or a plain string with multiple arguments that + specify several mount points. *) val volumes : string list -> t -(** [volumes mounts] will create mount points with the specified names - in [mounts] and mark them as holding externally mounted volumes - from native host or other containers. *) +(** [volumes mounts] will create mount points with the specified names in + [mounts] and mark them as holding externally mounted volumes from native + host or other containers. *) val entrypoint : ('a, unit, string, t) format4 -> 'a -(** [entrypoint fmt] allows you to configure a container that will - run as an executable. The [fmt] string will be executed using - a [/bin/sh] subshell. - - The shell form prevents any {!cmd} or {!run} command line arguments - from being used, but has the disadvantage that your {!entrypoint} - will be started as a subcommand of [/bin/sh -c], which does not pass - signals. This means that the executable will not be the container's - PID 1 - and will not receive Unix signals - so your executable will - not receive a SIGTERM from [docker stop ]. - - To get around this limitation, use the {!entrypoint_exec} command - to directly execute an argument list without a subshell. -*) +(** [entrypoint fmt] allows you to configure a container that will run as an + executable. The [fmt] string will be executed using a [/bin/sh] subshell. + + The shell form prevents any {!cmd} or {!run} command line arguments from + being used, but has the disadvantage that your {!entrypoint} will be started + as a subcommand of [/bin/sh -c], which does not pass signals. This means + that the executable will not be the container's PID 1 - and will not receive + Unix signals - so your executable will not receive a SIGTERM from + [docker stop ]. + + To get around this limitation, use the {!entrypoint_exec} command to + directly execute an argument list without a subshell. *) val entrypoint_exec : string list -> t -(** [entrypoint fmt] allows you to configure a container that will - run as an executable. You can use the exec form here to set fairly - stable default commands and arguments and then use either {!cmd} or - {!cmd_exec} to set additional defaults that are more likely to be changed - by the user starting the Docker container. *) +(** [entrypoint fmt] allows you to configure a container that will run as an + executable. You can use the exec form here to set fairly stable default + commands and arguments and then use either {!cmd} or {!cmd_exec} to set + additional defaults that are more likely to be changed by the user starting + the Docker container. *) val shell : string list -> t -(** [shell t] allows the default shell used for the shell form of - commands to be overridden. The default shell on Linux is - ["/bin/sh"; "-c"], and on Windows is ["cmd"; "/S"; "/C"]. - The [shell] instruction can appear multiple times. Each [shell] - instruction overrides all previous [shell] instructions, and +(** [shell t] allows the default shell used for the shell form of commands to be + overridden. The default shell on Linux is ["/bin/sh"; "-c"], and on Windows + is ["cmd"; "/S"; "/C"]. The [shell] instruction can appear multiple times. + Each [shell] instruction overrides all previous [shell] instructions, and affects all subsequent instructions. *) val onbuild : t -> t -(** [onbuild t] adds to the image a trigger instruction [t] to be - executed at a later time, when the image is used as the base for - another build. The trigger will be executed in the context of the - downstream build, as if it had been inserted immediately after the - {!from} instruction in the downstream Dockerfile. +(** [onbuild t] adds to the image a trigger instruction [t] to be executed at a + later time, when the image is used as the base for another build. The + trigger will be executed in the context of the downstream build, as if it + had been inserted immediately after the {!from} instruction in the + downstream Dockerfile. Any build instruction can be registered as a trigger. - This is useful if you are building an image which will be used as a - base to build other images, for example an application build environment - or a daemon which may be customized with user-specific configuration. *) + This is useful if you are building an image which will be used as a base to + build other images, for example an application build environment or a daemon + which may be customized with user-specific configuration. *) val label : (string * string) list -> t -(** [label l] adds metadata to an image via a list of key-value pairs. - To include spaces within a label value, use quotes and backslashes as - you would in command-line parsing. An image can have more than one label. - To specify multiple labels, Docker recommends combining labels into a - single label instruction where possible. Each label instruction produces - a new layer which can result in an inefficient image if you use many labels. +(** [label l] adds metadata to an image via a list of key-value pairs. To + include spaces within a label value, use quotes and backslashes as you would + in command-line parsing. An image can have more than one label. To specify + multiple labels, Docker recommends combining labels into a single label + instruction where possible. Each label instruction produces a new layer + which can result in an inefficient image if you use many labels. Labels are additive including [LABEL]s in [FROM] images. If Docker encounters a label/key that already exists, the new value overrides any @@ -508,28 +531,31 @@ val healthcheck : ?retries:int -> ('a, unit, string, t) format4 -> 'a -(** [healthcheck cmd] checks container health by running a command - inside the container. See {!cmd} for additional details. +(** [healthcheck cmd] checks container health by running a command inside the + container. See {!cmd} for additional details. - @param interval The health check will first run [interval] seconds - after the container is started, and then again [interval] seconds - after each previous check completes. + @param interval + The health check will first run [interval] seconds after the container is + started, and then again [interval] seconds after each previous check + completes. - @param timeout If a single run of the check takes longer than - [timeout] seconds then the check is considered to have failed. + @param timeout + If a single run of the check takes longer than [timeout] seconds then the + check is considered to have failed. - @param start_period provides initialization time for containers that - need time to bootstrap. Probe failure during that period will not - be counted towards the maximum number of retries. However, if a - health check succeeds during the start period, the container is - considered started and all consecutive failures will be counted - towards the maximum number of retries. + @param start_period + provides initialization time for containers that need time to bootstrap. + Probe failure during that period will not be counted towards the maximum + number of retries. However, if a health check succeeds during the start + period, the container is considered started and all consecutive failures + will be counted towards the maximum number of retries. - @param start_interval is the time between health checks during - the start period. + @param start_interval + is the time between health checks during the start period. - @param retries It takes [retries] consecutive failures of the health - check for the container to be considered {i unhealthy}. *) + @param retries + It takes [retries] consecutive failures of the health check for the + container to be considered {i unhealthy}. *) val healthcheck_exec : ?interval:string -> @@ -539,23 +565,21 @@ val healthcheck_exec : ?retries:int -> string list -> t -(** [healthcheck_exec cmd] checks container health by running a - command inside the container. See {!cmd_exec} and {!healthcheck} - for additional details. -*) +(** [healthcheck_exec cmd] checks container health by running a command inside + the container. See {!cmd_exec} and {!healthcheck} for additional details. *) val healthcheck_none : unit -> t -(** [healthcheck_none] disables any healthcheck inherited from the - base image. *) +(** [healthcheck_none] disables any healthcheck inherited from the base image. +*) val stopsignal : string -> t -(** [stopsignal signal] sets the system call signal that will be - sent to the container to exit. *) +(** [stopsignal signal] sets the system call signal that will be sent to the + container to exit. *) val crunch : t -> t -(** [crunch t] will reduce coincident {!run} commands into a single - one that is chained using the shell [&&] operator. This reduces the - number of layers required for a production image. +(** [crunch t] will reduce coincident {!run} commands into a single one that is + chained using the shell [&&] operator. This reduces the number of layers + required for a production image. - @raise Invalid_argument if mounts or networks or security modes differ for - each run command. *) + @raise Invalid_argument + if mounts or networks or security modes differ for each run command. *)