Module OpamFile.OPAM

OPAM files

type t = private {
opam_version : OpamTypes.opam_version;
name : OpamTypes.name option;
version : OpamTypes.version option;
depends : OpamTypes.filtered_formula;
depopts : OpamTypes.filtered_formula;
conflicts : OpamTypes.filtered_formula;
conflict_class : OpamTypes.name list;
available : OpamTypes.filter;
flags : OpamTypes.package_flag list;
env : OpamTypes.env_update list;
build : OpamTypes.command list;
run_test : OpamTypes.command list;
install : OpamTypes.command list;
remove : OpamTypes.command list;
substs : OpamTypes.basename list;
patches : (OpamTypes.basename * OpamTypes.filter option) list;
build_env : OpamTypes.env_update list;
features : (OpamVariable.t * OpamTypes.filtered_formula * string) list;
extra_sources : (OpamTypes.basename * URL.t) list;
messages : (string * OpamTypes.filter option) list;
post_messages : (string * OpamTypes.filter option) list;
depexts : (string list * OpamTypes.filter) list;
libraries : (string * OpamTypes.filter option) list;
syntax : (string * OpamTypes.filter option) list;
dev_repo : OpamTypes.url option;
pin_depends : (OpamTypes.package * OpamTypes.url) list;
maintainer : string list;
author : string list;
license : string list;
tags : string list;
homepage : string list;
doc : string list;
bug_reports : string list;
extensions : (OpamTypes.pos * OpamTypes.value) OpamStd.String.Map.t;
url : URL.t option;
descr : Descr.t option;
metadata_dir : (OpamTypes.repository_name option * string) option;
extra_files : (OpamFilename.Base.t * OpamHash.t) list option;
format_errors : (string * OpamPp.bad_format) list;
ocaml_version : (OpamFormula.relop * string) OpamFormula.formula option;
os : (bool * string) OpamTypes.generic_formula;
deprecated_build_test : OpamTypes.command list;
deprecated_build_doc : OpamTypes.command list;
}
include IO_FILE with type t := t
type t

File contents

val empty : t

Empty file

val write : t typed_file ‑> t ‑> unit

Write some contents to a file

val read : t typed_file ‑> t

Read file contents. Raise an error if the file does not exist.

val read_opt : t typed_file ‑> t option

Returns None on non-existing file

val safe_read : t typed_file ‑> t

Read file contents. Return empty if the file does not exist.

val read_from_channel : ?⁠filename:t typed_file ‑> Pervasives.in_channel ‑> t
val read_from_string : ?⁠filename:t typed_file ‑> string ‑> t
val write_to_channel : ?⁠filename:t typed_file ‑> Pervasives.out_channel ‑> t ‑> unit
val write_to_string : ?⁠filename:t typed_file ‑> t ‑> string
val empty : t
val create : OpamTypes.package ‑> t

Create an opam file

val effective_part : t ‑> t

Returns the opam value (including url, descr) with all non-effective (i.e. user-directed information that doesn't change opam's view on the package) fields set to their empty values. Useful for comparisons.

val effectively_equal : t ‑> t ‑> bool

Returns true if the effective parts of the two package definitions are equal

val equal : t ‑> t ‑> bool

Compares two package definitions, ignoring the virtual fields bound to file location (metadata_dir...)

val print_errors : ?⁠file:t typed_file ‑> t ‑> unit

Prints the format errors that were found when the file was read

val opam_version : t ‑> OpamTypes.opam_version

Get OPAM version.

val name : t ‑> OpamTypes.name

Package name

val name_opt : t ‑> OpamTypes.name option
val version : t ‑> OpamTypes.version

Package version

val version_opt : t ‑> OpamTypes.version option
val package : t ‑> OpamTypes.package

The informations in both the name and version fields, as a package

val available : t ‑> OpamTypes.filter

Availability formula (OS + compiler constraints)

val maintainer : t ‑> string list

Package maintainer(s)

val substs : t ‑> OpamTypes.basename list

File substitutions

val build_env : t ‑> OpamTypes.env_update list

List of environment variables to set-up for the build

val build : t ‑> OpamTypes.command list

List of command to run for building the package

val install : t ‑> OpamTypes.command list

List of command to run for installing the package

val remove : t ‑> OpamTypes.command list

List of command to run for removing the package

val depends : t ‑> OpamTypes.filtered_formula

Package dependencies

val depopts : t ‑> OpamTypes.filtered_formula

Optional dependencies

val depexts : t ‑> (string list * OpamTypes.filter) list

External dependencies

val extra_sources : t ‑> (OpamTypes.basename * URL.t) list
val extensions : t ‑> OpamTypes.value OpamStd.String.Map.t

All extended "x-" fields as a map

val extended : t ‑> string ‑> (OpamTypes.value ‑> 'a) ‑> 'a option

Parse a single extended field (reports proper file position)

val with_messages : (string * OpamTypes.filter option) list ‑> t ‑> t
val with_post_messages : (string * OpamTypes.filter option) list ‑> t ‑> t
val conflicts : t ‑> OpamTypes.filtered_formula

Package conflicts

val conflict_class : t ‑> OpamTypes.name list
val features : t ‑> (OpamVariable.t * OpamTypes.filtered_formula * string) list

Contents of the 'features' field

val libraries : t ‑> (string * OpamTypes.filter option) list

List of exported libraries

val syntax : t ‑> (string * OpamTypes.filter option) list

List of exported syntax extensions

val patches : t ‑> (OpamTypes.basename * OpamTypes.filter option) list

Patches

val homepage : t ‑> string list

Homepage(s)

val author : t ‑> string list

Author(s)

val license : t ‑> string list

License(s)

val doc : t ‑> string list

API documentation

val tags : t ‑> string list

Classification tags

val run_test : t ‑> OpamTypes.command list

Commands to build and run the tests

val deprecated_build_doc : t ‑> OpamTypes.command list

Commands to build the documentation

val deprecated_build_test : t ‑> OpamTypes.command list

Commands to build the tests

val messages : t ‑> (string * OpamTypes.filter option) list

Messages to display before taking action

val post_messages : t ‑> (string * OpamTypes.filter option) list

Messages to display at end of install

val bug_reports : t ‑> string list

Where to post bug reports.

val flags : t ‑> OpamTypes.package_flag list

The package flags that are present for this package.

val has_flag : OpamTypes.package_flag ‑> t ‑> bool

Check the package for the given flag. Allows flags specified through tags for compatibility

val env : t ‑> OpamTypes.env_update list

The environment variables that this package exports

val descr : t ‑> Descr.t option
val synopsis : t ‑> string option
val descr_body : t ‑> string option
val url : t ‑> URL.t option
val get_url : t ‑> OpamTypes.url option
val metadata_dir : t ‑> (OpamTypes.repository_name option * string) option

Related metadata directory (either repository name + relative path, or absolute path; not an actual field of the file, linked to the file location). This can be used to locate e.g. the files/ overlays

val get_metadata_dir : repos_roots:(OpamTypes.repository_name ‑> OpamTypes.dirname) ‑> t ‑> OpamTypes.dirname option

Gets the resolved metadata dir, given a mapping of repository names to their roots

val extra_files : t ‑> (OpamFilename.Base.t * OpamHash.t) list option

Names and hashes of the files below files/

val get_extra_files : repos_roots:(OpamTypes.repository_name ‑> OpamTypes.dirname) ‑> t ‑> (OpamTypes.filename * OpamTypes.basename * OpamHash.t) list

Looks up the extra files, and returns their full paths, relative path to the package source, and hash. Doesn't check the hashes.

val format_errors : t ‑> (string * OpamPp.bad_format) list

Returns the errors that were found when parsing the file, associated to their fields (that were consequently ignored)

val with_opam_version : OpamTypes.opam_version ‑> t ‑> t

Sets the opam version

val dev_repo : t ‑> OpamTypes.url option

The package source repository address

val pin_depends : t ‑> (OpamTypes.package * OpamTypes.url) list
val with_name : OpamTypes.name ‑> t ‑> t

construct as name

val with_name_opt : OpamTypes.name option ‑> t ‑> t
val with_version : OpamTypes.version ‑> t ‑> t

construct as version

val with_version_opt : OpamTypes.version option ‑> t ‑> t
val with_depends : OpamTypes.filtered_formula ‑> t ‑> t

Construct as depends

val with_depopts : OpamTypes.filtered_formula ‑> t ‑> t

Construct as depopts

val with_conflicts : OpamTypes.filtered_formula ‑> t ‑> t
val with_conflict_class : OpamTypes.name list ‑> t ‑> t
val with_features : (OpamVariable.t * OpamTypes.filtered_formula * string) list ‑> t ‑> t
val with_build : OpamTypes.command list ‑> t ‑> t

Construct as build

val with_run_test : OpamTypes.command list ‑> t ‑> t
val with_install : OpamTypes.command list ‑> t ‑> t
val with_remove : OpamTypes.command list ‑> t ‑> t

Construct as remove

val with_libraries : (string * OpamTypes.filter option) list ‑> t ‑> t

Construct as libraries

val with_syntax : (string * OpamTypes.filter option) list ‑> t ‑> t

Replace the syntax field of the given OPAM file.

val with_substs : OpamTypes.basename list ‑> t ‑> t

Construct as substs

val with_build_env : OpamTypes.env_update list ‑> t ‑> t
val with_available : OpamTypes.filter ‑> t ‑> t
val with_maintainer : string list ‑> t ‑> t

Construct as maintainer

val with_author : string list ‑> t ‑> t
val with_homepage : string list ‑> t ‑> t
val with_license : string list ‑> t ‑> t
val with_patches : (OpamTypes.basename * OpamTypes.filter option) list ‑> t ‑> t

Construct as patches

val with_bug_reports : string list ‑> t ‑> t

Construct using bug_reports

val with_depexts : (string list * OpamTypes.filter) list ‑> t ‑> t

Construct using depexts

val with_flags : OpamTypes.package_flag list ‑> t ‑> t
val add_flags : OpamTypes.package_flag list ‑> t ‑> t
val with_tags : string list ‑> t ‑> t
val with_env : OpamTypes.env_update list ‑> t ‑> t
val with_dev_repo : OpamTypes.url ‑> t ‑> t
val with_dev_repo_opt : OpamTypes.url option ‑> t ‑> t
val with_pin_depends : (OpamTypes.package * OpamTypes.url) list ‑> t ‑> t
val with_extra_sources : (OpamTypes.basename * URL.t) list ‑> t ‑> t
val with_extensions : OpamTypes.value OpamStd.String.Map.t ‑> t ‑> t
val add_extension : t ‑> string ‑> OpamTypes.value ‑> t
val with_deprecated_build_doc : OpamTypes.command list ‑> t ‑> t
val with_deprecated_build_test : OpamTypes.command list ‑> t ‑> t
val with_descr : Descr.t ‑> t ‑> t
val with_descr_opt : Descr.t option ‑> t ‑> t
val with_synopsis : string ‑> t ‑> t
val with_descr_body : string ‑> t ‑> t

If synopsis is not already set, split the string and use the first line as synopsis.

val with_url : URL.t ‑> t ‑> t
val with_url_opt : URL.t option ‑> t ‑> t
val with_metadata_dir : (OpamTypes.repository_name option * string) option ‑> t ‑> t
val with_extra_files : (OpamFilename.Base.t * OpamHash.t) list ‑> t ‑> t
val with_extra_files_opt : (OpamFilename.Base.t * OpamHash.t) list option ‑> t ‑> t
val with_format_errors : (string * OpamPp.bad_format) list ‑> t ‑> t
val to_string_with_preserved_format : ?⁠format_from:t typed_file ‑> ?⁠format_from_string:string ‑> t typed_file ‑> t ‑> string

Prints to a string, while keeping the format of the original file as much as possible. The original format is read from the given format_from_string, the file format_from, or the output file if it exists

val write_with_preserved_format : ?⁠format_from:t typed_file ‑> ?⁠format_from_string:string ‑> t typed_file ‑> t ‑> unit

Writes an opam file, but preserving the existing formatting as much as possible. The original format is read from the given format_from_string, the file format_from, or the output file if it exists

Low-level values used for linting and similar processing

val flag_of_tag : string ‑> OpamTypes.package_flag option

Allow 'flag:xxx' tags as flags, for compat

val fields : (tOpamTypes.valueOpamFormat.I.fields_def
val sections : (t, (string option * OpamTypes.opamfile_item list) list) OpamFormat.I.fields_def
val pp_raw_fields : (OpamTypes.opamfile_item list, tOpamPp.t

Doesn't handle package name encoded in directory name

val contents : ?⁠filename:'a typed_file ‑> t ‑> OpamTypes.opamfile

Returns the raw print-AST contents of the file

val to_list : ?⁠filename:'a typed_file ‑> t ‑> (string * OpamTypes.value) list

Returns all fields of the file as print-AST. Fields within sections are accessed through dot-separated paths (e.g. url.checksum)

val print_field_as_syntax : string ‑> t ‑> OpamTypes.value option

Gets the print-AST for a single field in the file structure. Fields within sections can be accessed through section.field.