opam-state 2.1.3 · OCaml Package

Loading and querying a switch state

val load : 
  'a OpamStateTypes.lock ->
  'b OpamStateTypes.global_state ->
  'c OpamStateTypes.repos_state ->
  OpamTypes.switch ->
  'a OpamStateTypes.switch_state

val with_ : 
  'a OpamStateTypes.lock ->
  ?rt:[< OpamStateTypes.unlocked ] OpamStateTypes.repos_state ->
  ?switch:OpamTypes.switch ->
  [< OpamStateTypes.unlocked ] OpamStateTypes.global_state ->
  ('a OpamStateTypes.switch_state -> 'b) ->
  'b

Loads the switch state and calls the given function on it, releasing the lock afterwards.

The repository state is automatically loaded if not provided.

The switch is selected, if not set, using OpamStateConfig.get_switch -- which can fail if no switch is configured.

Additionally, in case of a write lock, a backup is saved and a message is printed on restoring if f raised an exception and there were changes.

val load_virtual : 
  ?repos_list:OpamTypes.repository_name list ->
  ?avail_default:bool ->
  'a OpamStateTypes.global_state ->
  'b OpamStateTypes.repos_state ->
  OpamStateTypes.unlocked OpamStateTypes.switch_state

Creates a virtual state with nothing installed. Availability is computed just from the global state, and avail_default (default true) controls the result when the availability can't be computed due to undefined variables. Useful for querying and simulating actions when no switch is yet configured, or querying packages directly from the repos

val load_selections : 
  ?lock_kind:'a OpamStateTypes.lock ->
  'b OpamStateTypes.global_state ->
  OpamTypes.switch ->
  OpamTypes.switch_selections

Load the switch's state file, without constructing the package maps: much faster than loading the full switch state

val compute_available_packages : 
  'a OpamStateTypes.global_state ->
  OpamTypes.switch ->
  OpamFile.Switch_config.t ->
  pinned:OpamTypes.package_set ->
  opams:OpamFile.OPAM.t OpamTypes.package_map ->
  OpamTypes.package_set

Raw function to compute the availability of all packages, in opams, given the switch configuration and the set of pinned packages. (The result is precomputed in global_state.available_packages once the state is loaded)

val get_conflicts_t : 
  (OpamTypes.package -> OpamFilter.env) ->
  OpamTypes.package_set ->
  OpamFile.OPAM.t OpamTypes.package_map ->
  OpamTypes.formula OpamTypes.package_map

Raw function to compute the conflicts for all packages, given the set of available packages and the corresponding opam files. This is useful to populate the `u_conflicts` field when building a universe manually.

val infer_switch_invariant : 'a OpamStateTypes.switch_state -> OpamFormula.t

Infer a switch invariant from a switch state with compiler_packages and roots set, using some heuristics. Useful for migration from pre-2.1 opam

val unlock : 
  'a OpamStateTypes.switch_state ->
  OpamStateTypes.unlocked OpamStateTypes.switch_state

Releases any locks on the given switch_state

val drop : 'a OpamStateTypes.switch_state -> unit

Releases any locks on the given switch state and then ignores it.

Using drop st is equivalent to ignore (unlock st), and safer than other uses of ignore where it is not enforced by the type-system that the value is unlocked before it is lost.

val with_write_lock : 
  ?dontblock:bool ->
  'a OpamStateTypes.switch_state ->
  (OpamStateTypes.rw OpamStateTypes.switch_state ->
    'b * OpamStateTypes.rw OpamStateTypes.switch_state) ->
  'b * 'a OpamStateTypes.switch_state

Calls the provided function, ensuring a temporary write lock on the given switch state

Helpers to access state data

val repos_list : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.repository_name list

Returns the repositories configured in the current switch or, if none, the globally set default. highest priority first.

val selections : 'a OpamStateTypes.switch_state -> OpamTypes.switch_selections

val opam : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamFile.OPAM.t

Return the OPAM file for the given package.

raises Not_found
when appropriate

val opam_opt : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamFile.OPAM.t option

Return the OPAM file, including URL and descr, for the given package, if any

val url : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamFile.URL.t option

Return the URL field for the given package

val primary_url : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamTypes.url option

Returns the primary URL from the URL field of the given package

val primary_url_with_subpath : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamTypes.url option

val descr : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamFile.Descr.t

Return the descr field for the given package (or an empty descr if none)

val descr_opt : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamFile.Descr.t option

Return the descr field for the given package

val files : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamTypes.filename list

Returns the full paths of overlay files under the files/ directory

val package_config : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.name ->
  OpamFile.Dot_config.t

Return the installed package's local configuration

val is_name_installed : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.name ->
  bool

Check whether a package name is installed

val find_installed_package_by_name : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.name ->
  OpamTypes.package

Return the installed package with the right name

raises Not_found
when appropriate

val packages_of_atoms : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.atom list ->
  OpamTypes.package_set

Return all packages satisfying one of the given atoms from a state

val get_package : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.name ->
  OpamTypes.package

Gets the current version of package name: pinned version, installed version, max available version or max existing version, tried in this order.

raises Not_found
only if there is no package by this name

val is_dev_package : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  bool

"dev packages" are any package with an upstream that isn't the usual HTTP, and without an archive checksum. These need to be updated from upstream independently when installed. It's generally only the case of source-pinned packages, but no rule enforces it in opam itself.

val is_pinned : 'a OpamStateTypes.switch_state -> OpamTypes.name -> bool

Checks if the given package name is pinned

val is_version_pinned : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.name ->
  bool

Checks if the given package is version-pinned, i.e. pinned without overlay metadata, and relying on the repo's data

val dev_packages : 'a OpamStateTypes.switch_state -> OpamTypes.package_set

The set of all "dev packages" (see is_dev_package for a definition)

val source_dir : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamTypes.dirname

Returns the local source mirror for the given package (OpamPath.Switch.sources or OpamPath.Switch.pinned_package, depending on wether it's pinned).

val depexts : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamSysPkg.Set.t

Returns the set of active external dependencies for the package, computed from the values of the system-specific variables

val depexts_status_of_packages : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package_set ->
  OpamSysPkg.status OpamTypes.package_map

Returns required system packages of each of the given packages (elements are not added to the map if they don't have system dependencies)

val depexts_unavailable : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package ->
  OpamSysPkg.Set.t option

Returns not found depexts for the package

val conflicts_with : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.package_set ->
  OpamTypes.package_set ->
  OpamTypes.package_set

conflicts_with st subset pkgs returns all packages declared in conflict with at least one element of subset within pkgs, through forward or backward conflict definition or common conflict-class. Packages in subset (all their versions) are excluded from the result.

val universe : 
  'a OpamStateTypes.switch_state ->
  ?test:bool ->
  ?doc:bool ->
  ?force_dev_deps:bool ->
  ?reinstall:OpamTypes.package_set ->
  requested:OpamTypes.name_set ->
  OpamTypes.user_action ->
  OpamTypes.universe

Put the package data in a form suitable for the solver, pre-computing some maps and sets. Packages in the requested set are the ones that will get affected by the global build_test and build_doc flags. test and doc, if unspecified, are taken from OpamStateConfig.r. reinstall marks package not considered current in the universe, and that should therefore be reinstalled. If unspecified, it is the packages marked in switch_state.reinstall that are present in requested.

val dump_pef_state : 
  'a OpamStateTypes.switch_state ->
  Stdlib.out_channel ->
  unit

Dumps the current switch state in PEF format, for interaction with Dose tools

Updating

val update_package_metadata : 
  OpamTypes.package ->
  OpamFile.OPAM.t ->
  'a OpamStateTypes.switch_state ->
  'a OpamStateTypes.switch_state

Sets the given opam file for the given package, updating the other related fields along the way

val remove_package_metadata : 
  OpamTypes.package ->
  'a OpamStateTypes.switch_state ->
  'a OpamStateTypes.switch_state

Removes the metadata associated to the given package, also updating the packages and available sets.

val update_pin : 
  OpamTypes.package ->
  OpamFile.OPAM.t ->
  'a OpamStateTypes.switch_state ->
  'a OpamStateTypes.switch_state

Like update_package_metadata, but also ensures the package is pinned to the given version. The version specified in the opam file, if any, takes precedence over the version of package. Also marks it for reinstall if changed.

val update_repositories : 
  'a OpamStateTypes.global_state ->
  (OpamTypes.repository_name list -> OpamTypes.repository_name list) ->
  OpamTypes.switch ->
  unit

Updates the selected repositories in the given switch (does not load the full switch state, but takes a transient write lock on the switch, so make sure not to hold other locks to avoid deadlocks). Sets the switch repositories in any case, even if unchanged from the defaults.

User interaction and reporting

val is_switch_globally_set : 'a OpamStateTypes.switch_state -> bool

Returns true if the switch of the state is the one set in $OPAMROOT/config, false otherwise. This doesn't imply that the switch is current w.r.t. either the process or the shell, for that you need to check OpamStateConfig.(!r.switch_from)

val not_found_message : 
  'a OpamStateTypes.switch_state ->
  OpamTypes.atom ->
  string

Returns a message about a package or version that couldn't be found

val unavailable_reason_raw : 
  'a OpamStateTypes.switch_state ->
  (OpamTypes.name * OpamFormula.version_formula) ->
  [ `UnknownVersion
  | `UnknownPackage
  | `NoDefinition
  | `Pinned of OpamPackage.t
  | `Unavailable of string
  | `ConflictsBase
  | `ConflictsInvariant of string
  | `MissingDepexts of string list
  | `Default ]

val unavailable_reason : 
  'a OpamStateTypes.switch_state ->
  ?default:string ->
  (OpamTypes.name * OpamFormula.version_formula) ->
  string

Returns a printable explanation why a package is not currently available (pinned to an incompatible version, unmet available: constraints...). default is returned if no reason why it wouldn't be available was found (empty string if unspecified).

val can_upgrade_to_avoid_version : 
  OpamPackage.Name.t ->
  'a OpamStateTypes.switch_state ->
  bool

Returns whether or not the package can be upgraded to a version tagged with avoid-version

module Installed_cache : sig ... end

Handle a cache of the opam files of installed packages

package opam-state

Helpers to access state data

Updating

User interaction and reporting