package topkg

The type for representing a set of install moves.

The type for an install field, a function that describe file moves to a particular installation directory. In the simplest form a call field src simply moves the file src at the root of the install directory of the field.

In general field ~force ~built ~cond ~exts ~dst src generates install move as follows:

• dst is the path were the source is written to. Expressed relative to the install directory of the field. Defaults to Fpath.basename src, i.e. at the root of the install directory. If dst is a directory path, the destination is (dst ^ Fpath.basename src).
• If exts is present and non empty, generates the list of paths List.map (fun e -> src ^ e) and a move for each of these. For example field ~exts:Exts.api "src/m" would generate a move for the files "src/m.mli", "src/m.cmi", "src/m.cmti", "src/m.cmx".

• If cond is false (defaults to true) no file move is generated. This provides a convenient way to conditionalize installation based on the build configuration for example:

  let jsoo = Conf.value jsoo in
  Pkg.mllib ~cond:jsoo "src/mylib_jsoo.mllib"

• If built is true (default), src is expressed relative to the build directory of the distribution and the path src is be given to build system invocation for construction. If false, src is relative to the root of the distribution and is excluded from the build system invocation; this can be used for installing files that don't need to be built.
• If force is true (defaults to false) it disables the automatic src filtering performed by the library. When false, the library automatically disable certain build artefact depending on OCaml's configuration, one such example is filtering native code build artefact if the OCaml install doesn't support native code compilation

The type for fields that install executable files. This is like field except for the additional auto parameter:

• If auto is true (default) then field src dst automatically adds the ".native" suffix to src if Conf.OCaml.native is true and the ".byte" suffix otherwise. Besides it automatically adds Exts.exe to dst, which handles things correctly on the various Windows ports.
• If auto is false you have full control according to field.

bin is a field that installs to a common bin/ directory.

doc is a field that installs to a package specific doc/ directory

etc is a field that installs to a package specific etc/ directory.

lib is a field that installs to a package specific lib/ directory.

libexec is a field that installs to a package specific lib/ directory but with the executable bit set.

man is a field that installs to a common man/ directory. See the OPAM manual for details.

misc is a field that installs to an arbitrary absolute path, the user is prompted for authorization, see the OPAM manual for details.

sbin is a field that installs to a common sbin/ directory.

share is a field that installs to a package specific share/ directory.

share_root is a field that installs to a common share/ directory.

stublibs is a field that install to a common lib/stublibs/ directory. Used for OCaml C stub directory.

toplevel is a field that installs to a common lib/toplevel/ directory.

test is a special executable field: it doesn't install the described executable (as such the dst argument is ignored at the moment). If run is true (default) executes the test with args when ocaml pkg/pkg.ml test is run; this will notably run to test the distribution tarball. If run is false the test needs to be invoked explicitely.

mllib ~field ~cond ~api ~dst_dir mllib installs an OCaml library described by the OCamlbuild .mllib file mllib with:

• field is the field where it gets installed (defaults to lib).
• If cond is false (defaults to true), no move is generated.
• api is the list of modules that defines the public interface of the library, if None all the modules mentioned in mllib are part of the public interface.
• dst_dir is the destination directory of the library in the field. If unspecified this is the root of the field's directory.

clib clib installs C stubs described by the OCamlbuild .clib file clib with:

• dllfield is the field where the C DLL archive gets installed, (defaults to stublibs)
• libfield is the field where the C static archive gets installed (defaults to lib)
• If cond is false (defaults to true), no move is generated.
• lib_dst_dir is the destination directory of the library in the libfield field. If unspecified this is the root of the field's directory. This does not affect the dllfield, DLLs are always installed at the root directory of the dllfield.

The type for package build description.

build ~prepare_on_pin ~dir ~cmd ~pre ~post describes the package build procedure.

• prepare_on_pin if true (default) distribution preparation is performed if a `Pin build context is detected. This means that the checkout is watermarked and the massage hook is invoked, see step 2. of distribution creation.
• dir is the directory where build artefacts are generated, (defaults to "_build"). Note that his value can be overriden from the command line.
• pre is a hook that is invoked with the build context, after distribution preparation if applicable, but before the build command. It can be used to adapt the build setup according to the build configuration. Default is a nop.

• cmd invokes the build system to build the files determined by install moves. It is given the build configuration, an OS specification, the list of files to build relative to the build directory, and build the given files in the build directory. The default is:

  fun c os files ->
    let ocamlbuild = Conf.tool "ocamlbuild" os in
    let build_dir = Conf.build_dir c in
    let debug = Cmd.(on (Conf.debug c) (v "-tag" % "debug")) in
    OS.Cmd.run @@
    Cmd.(ocamlbuild % "-use-ocamlfind" % "-classic-display" %% debug %
                      "-build-dir" % build_dir %% of_list files)

• post is a hook that is invoked with the build context after the build command returned sucessfully. Default is a nop.

• clean is invoked to clean a build. It is given an OS specification and a build directory to clean. The default is:

  let clean os ~build_dir =
    let ocamlbuild = Topkg_conf.tool "ocamlbuild" os in
    OS.Cmd.run @@
    Cmd.(ocamlbuild % "-use-ocamlfind" % "-classic-display" %
                      "-build-dir" % build_dir % "-clean")

Warning. If you are invoking tools in your hooks consider using tool to look them up it helps for cross-compilation.

The type for watermarks. A watermark identifier, e.g. "ID" and its definition:

• `String s, s is the definition.
• `Name, is the name of package.
• `Version, is the version of the distribution.
• `Version_num, is the version of the distribution with a potential leading 'v' or 'V' dropped.
• `Vcs `Commit_id, is the commit identifier (hash) of the distribution. May be post-fixed by "dirty" in pin builds.
• `Opam (file, field, sep), is the values of the field field concatenated with separator sep of the OPAM file file, expressed relative to the distribution root directory, if file is None this is the package's default OPAM file, see describe. Not all fields are supported see the value of Topkg_care.Opam.File.field_names. Warning. In pin builds, `Opam watermarks are only substituted if the package topkg-care is installed.

When a file is watermarked with an identifier "ID", any occurence of the sequence %%ID%% in its content is substituted by its definition.

The type for describing distribution creation.

distrib ~watermarks ~files_to_watermark ~massage ~exclude_paths ~uri () influences the distribution creation process performed by the topkg tool. See the full details about distribution creation.

In the following the distribution build directory is a private clone of the package's source repository's HEAD when topkg distrib is invoked.

• watermarks defines the source watermarks for the distribution, defaults to watermarks.
• files_to_watermark is invoked in the distribution build directory to determine the files to watermark, defaults to files_to_watermark.
• massage is invoked in the distribution build directory, after watermarking, but before archiving. It can be used to generate distribution time build artefacts. Defaults to massage.
• exclude_paths () is invoked in the distribution build directory, after massaging, to determine the paths that are excluded from being added to the distribution archive. Defaults to exclude_paths.

• uri is an URI pattern that specifies the location of the distribution on the WWW. In this string any sub-string "$(NAME)" is replaced by the package name, "$(VERSION)" is replaced by the distribution version string and "$(VERSION_NUM)" by the distribution version string, chopping an initial 'v' or 'V' character if present. This argument is used to generate the url file of an OPAM package for the distribution; it will be deprecated in the future in favour of a x-distrib-uri field in the OPAM file. If the value is unspecified it defaults to:

  PKG_HOMEPAGE/releases/$(NAME)-$(VERSION_NUM).tbz

  where PKG_HOMEPAGE is the package's OPAM file homepage field. As a special case if the hostname of PKG_HOMEPAGE is github the following is used:

  PKG_DEV_REPO/releases/download/$(VERSION)/$(NAME)-$(VERSION_NUM).tbz

  where PKG_DEV_REPO is the package's OPAM file dev-repo field without the .git suffix.

watermarks is the default list of watermarks. It has the following elements:

• ("NAME", `Name)
• ("VERSION", `Version)
• ("VERSION_NUM", `Version_num)
• ("VCS_COMMIT_ID", `Vcs [`Commit_id])
• ("PKG_MAINTAINER", `Opam (None, "maintainer", ", "))
• ("PKG_AUTHORS", `Opam (None, "authors", ", ")
• ("PKG_HOMEPAGE", `Opam (None, "homepage", " ")
• ("PKG_ISSUES", `Opam (None, "bug-reports", " ")
• ("PKG_DOC", `Opam (None, "doc", " "))
• ("PKG_LICENSE", `Opam (None, "license", ", ")
• ("PKG_REPO", `Opam (None, "dev-repo", " "))

Prepending to the list overrides default definitions.

files_to_watermark () is the default list of files to watermark. It is invoked in the distribution build directory and gets the set of tracked files of this directory from which it removes the files that end with .flv, .gif, .ico, .jpeg, .jpg, .mov, .mp3, .mp4, .otf, .pdf, .png, .ttf, .woff.

massage is the default distribution massaging function. It is invoked in the distribution build directory and does nothing.

exclude_paths () is the default list of paths to exclude from the distribution archive. It is invoked in the distribution build directory and returns the following static set of files.

fun () -> Ok [".git"; ".gitignore"; ".gitattributes"; ".hg"; ".hgignore";
              "build"; "Makefile"; "_build"]

The type for describing distribution publication.

publish ~artefacts () influences the distribution publication process performed by the topkg tool:

• artefacts defines which artefacts are published by an invocation of topkg publish without arguments (defaults to [`Doc;`Distrib]).

The type for specifying a standard file.

std_file ~install p is a standard file p expressed relative to the distribution root directory. The file is automatically installed if install is true (default).

The type for specifying an OCamlfind META file.

meta_file ~lint ~install p is a META file p expressed relative to the distribution root directory. The file is automatically installed in the lib field if install is true (default). If lint is true (default), it is OCamlfind linted.

The type for specifying an opam file.

opam_file ~lint ~lint_deps_excluding ~install p is an OPAM file p expressd relative to the distribution root directory such that:

• If install is true (default), it is automatically installed in the lib field.
• If lint is true (default), it is OPAM linted.

• If lint_deps_excluding is Some excludes, topkg checks that each of the OPAM package dependencies is mentioned as a root package in the OCamlbuild _tags file and vice-versa. The following package names are excluded from this test:

  • The packages names mentioned in excludes.
  • Package names that start with "conf-"
  • Topkg_care.OCamlfind.base_packages
  • Topkg_care.Opam.ocaml_base_packages

  If None the dependency check is disabled.

describe name install describes a package named name with:

• delegate, the package delegate command to use. If unspecfied determined by the delegate lookup procedure, see topkg help delegate for more information.
• readmes are readme files, defaults to [std_file "README.md"]. Automatic install is in the doc field.
• licenses are license files, defaults to [std_file "LICENSE.md"]. Automatic install is in the doc field.
• change_logs are change logs, defaults to [std_file "CHANGES.md"]. The first file of the list is the one that is acted upon by the topkg log command. Automatic install is in the doc field.
• metas the package's ocamlfind META files, defaults to [ meta_file "pkg/META" ].
• opams the package's OPAM package files, defaults to [opam_file "opam"]. The default OPAM file used by a package description depends on the package name (which can be overriden from the command line). The OPAM file lookup procedure selects the first path in opams whose filename is (name ^ ".opam") and, failing to do so, it fallbacks to an "opam" file at the root of the distribution.
• lint_files if Some files, ensures that all files mentioned in readme, license, change_log, metas, opams and files are present in the distribution. Defaults to Some []. If None disables the file existence tests (including readme, change_log, license, metas, opams, metas.)
• lint_custom defines a custom linting process run with the current directory set at the root of the distribution. Successes and errors in the returned list are reported as such and any error in the list makes the lint fail. Defaults to None.
• distrib, specifies the distribution process, defaults to distrib ().
• publish, specifies the publication process, defaults to publish ().
• build, specifies the build process, defaults to build ().
• install given a build configuration specifies the install moves. Note that some of standard files are automatically installed and don't need to be specified, see std_file, meta_file and opam_file.