opam-format 2.2.1 · OCaml Package

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.spf_unresolved, OpamTypes.euok_writeable) 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.spf_unresolved, OpamTypes.euok_writeable) 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 : (OpamSysPkg.Set.t * 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 : OpamParserTypes.FullPos.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;
locked : string 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

val format_version : OpamVersion.t

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 -> Stdlib.in_channel -> t

val read_from_string : ?filename:t typed_file -> string -> t

val write_to_channel : 
  ?filename:t typed_file ->
  Stdlib.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 : ?modulo_state:bool -> 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.

parameter ?modulo_state
if true, eliminates the fields relying on the state of the switch (depends, available, …). This is false by default.

val effectively_equal : ?modulo_state:bool -> t -> t -> bool

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

parameter ?modulo_state
if true, considers the fields relying on the state of the switch (depends, available, …) equal. This is false by default

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.spf_unresolved, [> OpamTypes.euok_writeable ])
    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 -> (OpamSysPkg.Set.t * OpamTypes.filter) list

External dependencies

val extra_sources : t -> (OpamTypes.basename * URL.t) list

val extensions : t -> OpamParserTypes.FullPos.value OpamStd.String.Map.t

All extended "x-" fields as a map

val extended : 
  t ->
  string ->
  (OpamParserTypes.FullPos.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.spf_unresolved, [> OpamTypes.euok_writeable ])
    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 locked : t -> string option

From locked opam file

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.spf_unresolved, OpamTypes.euok_writeable) 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 : (OpamSysPkg.Set.t * 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.spf_unresolved, OpamTypes.euok_writeable) 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 : 
  OpamParserTypes.FullPos.value OpamStd.String.Map.t ->
  t ->
  t

val add_extension : t -> string -> OpamParserTypes.FullPos.value -> t

val remove_extension : t -> string -> 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_locked_opt : string 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 : (t, OpamParserTypes.FullPos.value) OpamFormat.I.fields_def

val sections : 
  (t, (string option * OpamParserTypes.FullPos.opamfile_item list) list)
    OpamFormat.I.fields_def

val pp_raw_fields : (OpamParserTypes.FullPos.opamfile_item list, t) OpamPp.t

Doesn't handle package name encoded in directory name

val contents : ?filename:'a typed_file -> t -> OpamParserTypes.FullPos.opamfile

Returns the raw print-AST contents of the file

val to_list : 
  ?filename:'a typed_file ->
  t ->
  (string * OpamParserTypes.FullPos.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 -> OpamParserTypes.FullPos.value option

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

val rewrite_xfield : string

x-field name for path rewriting on windows

package opam-format