package opam-format

  1. Overview
  2. Docs

Definitions of many types used throughout

type 'a success = [
  1. | `Successful of 'a
]

Error and continuation handling

type 'a error = [
  1. | `Error of 'a
  2. | `Exception of exn
]
type ('a, 'b) status = [
  1. | 'a success
  2. | 'b error
]

Untyped generic file format

include module type of struct include OpamParserTypes end
type relop = [
  1. | `Eq
    (*

    =

    *)
  2. | `Neq
    (*

    !=

    *)
  3. | `Geq
    (*

    >=

    *)
  4. | `Gt
    (*

    >

    *)
  5. | `Leq
    (*

    <=

    *)
  6. | `Lt
    (*

    <

    *)
]

Relational operators

type logop = [
  1. | `And
    (*

    &

    *)
  2. | `Or
    (*

    |

    *)
]

Logical operators

type pfxop = [
  1. | `Not
    (*

    !

    *)
  2. | `Defined
    (*

    ?

    *)
]

Prefix operators

type file_name = string
type pos = file_name * int * int

Source file positions: (filename, line, column)

type env_update_op = OpamParserTypes.env_update_op =
  1. | Eq
    (*

    =

    *)
  2. | PlusEq
    (*

    +=

    *)
  3. | EqPlus
    (*

    =+

    *)
  4. | ColonEq
    (*

    :=

    *)
  5. | EqColon
    (*

    =:

    *)
  6. | EqPlusEq
    (*

    =+=

    *)

Environment variable update operators

type value = OpamParserTypes.value =
  1. | Bool of pos * bool
    (*

    bool atoms

    *)
  2. | Int of pos * int
    (*

    int atoms

    *)
  3. | String of pos * string
    (*

    string atoms

    *)
  4. | Relop of pos * relop * value * value
    (*

    Relational operators with two values (e.g. os != "win32")

    *)
  5. | Prefix_relop of pos * relop * value
    (*

    Relational operators in prefix position (e.g. < "4.07.0")

    *)
  6. | Logop of pos * logop * value * value
    (*

    Logical operators

    *)
  7. | Pfxop of pos * pfxop * value
    (*

    Prefix operators

    *)
  8. | Ident of pos * string
    (*

    Identifiers

    *)
  9. | List of pos * value list
    (*

    Lists of values ([x1 x2 ... x3])

    *)
  10. | Group of pos * value list
    (*

    Groups of values ((x1 x2 ... x3))

    *)
  11. | Option of pos * value * value list
    (*

    Value with optional list (x1 {x2 x3 x4})

    *)
  12. | Env_binding of pos * value * env_update_op * value
    (*

    Environment variable binding (FOO += "bar")

    *)

Base values

type opamfile_section = OpamParserTypes.opamfile_section = {
  1. section_kind : string;
    (*

    Section kind (e.g. extra-source)

    *)
  2. section_name : string option;
    (*

    Section name (e.g. "myfork.patch")

    *)
  3. section_items : opamfile_item list;
    (*

    Content of the section

    *)
}

An opamfile section

and opamfile_item = OpamParserTypes.opamfile_item =
  1. | Section of pos * opamfile_section
    (*

    e.g. kind ["name"] { ... }

    *)
  2. | Variable of pos * string * value
    (*

    e.g. opam-version: "2.0"

    *)

An opamfile is composed of sections and variable definitions

type opamfile = OpamParserTypes.opamfile = {
  1. file_contents : opamfile_item list;
    (*

    Content of the file

    *)
  2. file_name : file_name;
    (*

    Name of the disk file this record was loaded from

    *)
}

A file is a list of items and the filename

Filenames

type basename = OpamFilename.Base.t

Basenames

type dirname = OpamFilename.Dir.t

Directory names (translated to absolute)

type filename = OpamFilename.t

Filenames

type filename_set = OpamFilename.Set.t

Set of files

type 'a filename_map = 'a OpamFilename.Map.t

Map of files

type std_path =
  1. | Prefix
  2. | Lib
  3. | Bin
  4. | Sbin
  5. | Share
  6. | Doc
  7. | Etc
  8. | Man
  9. | Toplevel
  10. | Stublibs

Predefined installation directories within a switch

type 'a download =
  1. | Up_to_date of 'a
  2. | Not_available of string
  3. | Result of 'a

Download result

Packages

type package = private OpamPackage.t = {
  1. name : OpamPackage.Name.t;
  2. version : OpamPackage.Version.t;
}

Packages are (name * version) tuple

type package_set = OpamPackage.Set.t

Set of packages

type 'a package_map = 'a OpamPackage.Map.t

Map of packages

type name = OpamPackage.Name.t

Package names

type name_set = OpamPackage.Name.Set.t

Set of package names

type 'a name_map = 'a OpamPackage.Name.Map.t

Map of package names

type version = OpamPackage.Version.t

Package versions

type version_set = OpamPackage.Version.Set.t

Set of package versions

type opam_version = OpamVersion.t

OPAM versions

Variables

type variable = OpamVariable.t

Variables

type full_variable = OpamVariable.Full.t

Fully qualified variables (ie. with the name of sections/sub-sections they appear in)

type variable_contents = OpamVariable.variable_contents =
  1. | B of bool
  2. | S of string

Content of user-defined variables

A map from variables to their contents (i.e an environment)

type package_flag =
  1. | Pkgflag_LightUninstall
    (*

    The package doesn't require downloading to uninstall

    *)
  2. | Pkgflag_Verbose
    (*

    The package's scripts output is to be displayed to the user

    *)
  3. | Pkgflag_Plugin
    (*

    The package is an opam plugin that will install a opam-<name> exec, and may be auto-installed when doing opam <name>

    *)
  4. | Pkgflag_Compiler
    (*

    Package may be used for 'opam switch'

    *)
  5. | Pkgflag_Conf
    (*

    Virtual package: no source, no install or remove instructions, .install, but likely has depexts

    *)
  6. | Pkgflag_Unknown of string
    (*

    Used for error reporting, otherwise ignored

    *)

Opam package flags

module type GenericPackage = sig ... end

At some point we want to abstract so that the same functions can be used over CUDF and OPAM packages

Formulas

type 'a generic_formula = 'a OpamFormula.formula =
  1. | Empty
  2. | Atom of 'a
  3. | Block of 'a generic_formula
  4. | And of 'a generic_formula * 'a generic_formula
  5. | Or of 'a generic_formula * 'a generic_formula

A generic formula

type atom = OpamFormula.atom

Formula atoms

type formula = OpamFormula.t

Formula over versionned packages

type 'a conjunction = 'a OpamFormula.conjunction

AND formulat

type 'a disjunction = 'a OpamFormula.disjunction

OR formulat

Repositories

type repository_name = OpamRepositoryName.t

Repository names

type 'a repository_name_map = 'a OpamRepositoryName.Map.t

Maps of repository names

type url = OpamUrl.t
type trust_anchors = {
  1. quorum : int;
  2. fingerprints : string list;
}
type repository = {
  1. repo_name : repository_name;
  2. repo_root : dirname;
    (*

    The root of opam's local mirror for this repo

    *)
  3. repo_url : url;
  4. repo_trust : trust_anchors option;
}

Repositories

Variable-based filters

type filter =
  1. | FBool of bool
  2. | FString of string
  3. | FIdent of name option list * variable * (string * string) option
    (*

    packages (or None for self-ref through "_"), variable name, string converter (val_if_true, val_if_false_or_undef)

    *)
  4. | FOp of filter * relop * filter
  5. | FAnd of filter * filter
  6. | FOr of filter * filter
  7. | FNot of filter
  8. | FUndef of filter
    (*

    Returned by reduce functions when the filter could not be resolved to an atom (due to undefined variables or string expansions). The argument contains the partially reduced filter, where strings may still contain expansions (and are otherwise escaped). Used both for partial evaluation, and error messaging. Not allowed as an argument to other filters

    *)

Filtered formulas (to express conditional dependencies)

These are first reduced to only the dependency-flag variables build, doc, dev, test defined in Opam formulas

type 'a filter_or_constraint =
  1. | Filter of filter
  2. | Constraint of relop * 'a

Solver

type 'a atomic_action = [
  1. | `Remove of 'a
  2. | `Install of 'a
]

Used internally when computing sequences of actions

type 'a highlevel_action = [
  1. | 'a atomic_action
  2. | `Change of [ `Up | `Down ] * 'a * 'a
  3. | `Reinstall of 'a
]

Used to compact the atomic actions and display to the user in a more meaningful way

type 'a inst_action = [
  1. | `Install of 'a
  2. | `Change of [ `Up | `Down ] * 'a * 'a
]

Sub-type of highlevel_action corresponding to an installed package that changed state or version

type 'a concrete_action = [
  1. | 'a atomic_action
  2. | `Build of 'a
]

Used when applying solutions, separates build from install

type 'a action = [
  1. | 'a atomic_action
  2. | 'a highlevel_action
  3. | 'a concrete_action
]
type 'a cause =
  1. | Use of 'a list
  2. | Required_by of 'a list
  3. | Conflicts_with of 'a list
  4. | Upstream_changes
  5. | Requested
  6. | Unknown

The possible causes of an action.

type solver_result =
  1. | Nothing_to_do
  2. | OK of package action list
    (*

    List of successful actions

    *)
  3. | Aborted
  4. | No_solution
  5. | Partial_error of package action list * package action list * package action list
    (*

    List of successful actions, list of actions with errors, list of remaining undone actions

    *)

Solver result

type ('a, 'b) result =
  1. | Success of 'a
  2. | Conflicts of 'b

Solver result

type solver_criteria = [
  1. | `Default
  2. | `Upgrade
  3. | `Fixup
]
type 'a request = {
  1. criteria : solver_criteria;
  2. wish_install : 'a conjunction;
  3. wish_remove : 'a conjunction;
  4. wish_upgrade : 'a conjunction;
  5. extra_attributes : string list;
}

Solver request

type user_action =
  1. | Install of name_set
    (*

    Just install the requested packages. Add name_set as roots.

    *)
  2. | Upgrade of package_set * name_set
    (*

    Upgrade the requested packages, and reinstall package_set. Also add name_set as roots.

    *)
  3. | Reinstall of package_set
    (*

    Just reinstall package_set

    *)
  4. | Depends
    (*

    Just querying dependencies, no action will be taken

    *)
  5. | Remove
    (*

    Just remove the requested packages

    *)
  6. | Switch of name_set
    (*

    Switch init request, add name_set as roots

    *)
  7. | Import of name_set
    (*

    Switch import request, add name_set as roots

    *)

user request action

type universe = {
  1. u_packages : package_set;
  2. u_installed : package_set;
  3. u_available : package_set;
  4. u_depends : filtered_formula package_map;
  5. u_depopts : filtered_formula package_map;
  6. u_conflicts : formula package_map;
  7. u_action : user_action;
  8. u_installed_roots : package_set;
  9. u_pinned : package_set;
  10. u_dev : package_set;
    (*

    packages with a version-controlled upstream

    *)
  11. u_base : package_set;
  12. u_attrs : (string * package_set) list;
  13. u_test : package_set;
    (*

    Test dependencies should be honored

    *)
  14. u_doc : package_set;
    (*

    Doc dependencies should be honored

    *)
}

Solver universe

Command line arguments

type pin_kind = [
  1. | `version
  2. | OpamUrl.backend
]

Pin kind

type shell = [
  1. | `fish
  2. | `csh
  3. | `zsh
  4. | `sh
  5. | `bash
]

Shell compatibility modes

Generic command-line definitions with filters

type simple_arg =
  1. | CString of string
  2. | CIdent of string

A command argument

type arg = simple_arg * filter option

Command argument

type command = arg list * filter option

Command

Switches

type switch = OpamSwitch.t

Compiler switches

type switch_set = OpamSwitch.Set.t

Set of compiler switches

type 'a switch_map = 'a OpamSwitch.Map.t

Map of compile switches

type switch_selections = {
  1. sel_installed : package_set;
  2. sel_roots : package_set;
  3. sel_compiler : package_set;
  4. sel_pinned : package_set;
}

Misc

type lock =
  1. | Read_lock of unit -> unit
    (*

    The function does not modify anything, but it needs the state not to change while it is running.

    *)
  2. | Global_lock of unit -> unit
    (*

    Take the global lock, all subsequent calls to OPAM are blocked.

    *)
  3. | Switch_lock of unit -> switch * unit -> unit
    (*

    Take a global read lock and a switch lock. The first function is called with the read lock, then the second function is called with the returned switch write-locked.

    *)
  4. | Global_with_switch_cont_lock of unit -> switch * (unit -> unit)
    (*

    Call the function in a global lock, then relax to a switch lock and call the function it returned

    *)

The different kinds of locks

type file_attribute = OpamFilename.Attribute.t

A line in urls.tx

type file_attribute_set = OpamFilename.Attribute.Set.t

All the lines in urls.txt

type 'a optional = {
  1. c : 'a;
    (*

    Contents

    *)
  2. optional : bool;
    (*

    Is the contents optional

    *)
}

Optional contents

type stats = {
  1. s_install : int;
  2. s_reinstall : int;
  3. s_upgrade : int;
  4. s_downgrade : int;
  5. s_remove : int;
}

Upgrade statistics

type env = (string * string * string option) list

Environement variables: var name, value, optional comment

type env_update = string * env_update_op * string * string option

Environment updates

var, update_op, value, comment

Tags

Repository and global states

type checksums = string list

Checksums

type json = OpamJson.t

JSON

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