package opam-format

  1. Overview
  2. Docs
package opam-format
Legend:
Library
Module
Module type
Parameter
Class
Class type

OPAM files

type t = private {
  1. opam_version : OpamTypes.opam_version;
  2. name : OpamTypes.name option;
  3. version : OpamTypes.version option;
  4. depends : OpamTypes.filtered_formula;
  5. depopts : OpamTypes.filtered_formula;
  6. conflicts : OpamTypes.filtered_formula;
  7. conflict_class : OpamTypes.name list;
  8. available : OpamTypes.filter;
  9. flags : OpamTypes.package_flag list;
  10. env : OpamTypes.env_update list;
  11. build : OpamTypes.command list;
  12. run_test : OpamTypes.command list;
  13. install : OpamTypes.command list;
  14. remove : OpamTypes.command list;
  15. substs : OpamTypes.basename list;
  16. patches : (OpamTypes.basename * OpamTypes.filter option) list;
  17. build_env : OpamTypes.env_update list;
  18. features : (OpamVariable.t * OpamTypes.filtered_formula * string) list;
  19. extra_sources : (OpamTypes.basename * URL.t) list;
  20. messages : (string * OpamTypes.filter option) list;
  21. post_messages : (string * OpamTypes.filter option) list;
  22. depexts : (OpamSysPkg.Set.t * OpamTypes.filter) list;
  23. libraries : (string * OpamTypes.filter option) list;
  24. syntax : (string * OpamTypes.filter option) list;
  25. dev_repo : OpamTypes.url option;
  26. pin_depends : (OpamTypes.package * OpamTypes.url) list;
  27. maintainer : string list;
  28. author : string list;
  29. license : string list;
  30. tags : string list;
  31. homepage : string list;
  32. doc : string list;
  33. bug_reports : string list;
  34. extensions : OpamParserTypes.FullPos.value OpamStd.String.Map.t;
  35. url : URL.t option;
  36. descr : Descr.t option;
  37. metadata_dir : (OpamTypes.repository_name option * string) option;
  38. extra_files : (OpamFilename.Base.t * OpamHash.t) list option;
  39. locked : string option;
  40. format_errors : (string * OpamPp.bad_format) list;
  41. ocaml_version : (OpamFormula.relop * string) OpamFormula.formula option;
  42. os : (bool * string) OpamTypes.generic_formula;
  43. deprecated_build_test : OpamTypes.command list;
  44. 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.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.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.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.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.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct