# Module OpamState

    module OpamState: sig .. end

OPAM client state

    module Types: sig .. end

Client state

    type state = Types.t

    val load_state : ?save_cache:bool -> string -> state

Load the client state. The string argument is to identify to call site.

    val rebuild_state_cache : unit -> unit

Rebuild the state cache.

    val remove_state_cache : unit -> unit

Remove the state cache

    val load_env_state : string -> state

Load state associated to env variables. All other fields are left empty.

    val universe : state -> OpamTypes.user_action -> OpamTypes.universe

Create a universe from the current state

## Environment

    val get_full_env : force_path:bool -> ?opam:OpamFile.OPAM.t -> state -> OpamTypes.env

Get the current environment with OPAM specific additions. If `force_path`, the PATH is modified to ensure opam dirs are leading.

    val get_opam_env : force_path:bool -> state -> OpamTypes.env

Get only environment modified by OPAM. If `force_path`, the PATH is modified to ensure opam dirs are leading.

    val add_to_env : state ->
           ?opam:OpamFile.OPAM.t ->
           OpamTypes.env -> (string * string * string) list -> OpamTypes.env

Update an environment.

    val print_env_warning_at_init : state -> OpamTypes.user_config -> unit

Print a warning if the environment is not set-up properly on init.

    val print_env_warning_at_switch : state -> unit

Print a warning if the environment is not set-up properly on switch.

## Initialisation

    val update_setup_interactive : state -> OpamTypes.shell -> OpamTypes.filename -> bool

Update the global and user configuration by asking some questions.

    val display_setup : state -> OpamTypes.shell -> OpamTypes.filename -> unit

Display the global and user configuration for OPAM.

    val update_setup : state ->
           OpamTypes.user_config option -> OpamTypes.global_config option -> unit

Update the user configuration.

## Substitutions

    val contents_of_variable : state ->
           ?opam:OpamFile.OPAM.t ->
           OpamTypes.variable_map ->
           OpamTypes.full_variable -> OpamTypes.variable_contents option

Compute the value of a variable

    val contents_of_variable_exn : state ->
           ?opam:OpamFile.OPAM.t ->
           OpamTypes.variable_map ->
           OpamTypes.full_variable -> OpamTypes.variable_contents

Compute the value of a variable. Raise `Not_found` if the variable is not valid.

    val substitute_string : state ->
           ?opam:OpamFile.OPAM.t -> OpamTypes.variable_map -> string -> string

Substitute a string

    val substitute_file : state ->
           ?opam:OpamFile.OPAM.t -> OpamTypes.variable_map -> OpamTypes.basename -> unit

Substitute file

## Filters

    val global_variable_names : (string * string) list

Lists of available variables and their description

    val package_variable_names : (string * string) list

    val get_env_var : OpamTypes.full_variable -> OpamTypes.variable_contents option

Check for user-defined variable overwrite.

    val eval_filter : state ->
           ?opam:OpamFile.OPAM.t ->
           OpamTypes.variable_map -> OpamTypes.filter option -> bool

Evaluate a filter

    val filter_commands : state ->
           ?opam:OpamFile.OPAM.t ->
           OpamTypes.variable_map -> OpamTypes.command list -> string list list

Filter a list of commands by:

- evaluating the substitution strings; and
- removing the commands with a filter evaluating to "false"

## Helpers

    val opam : state -> OpamTypes.package -> OpamFile.OPAM.t

Return the OPAM file for the given package

    val opam_opt : state -> OpamTypes.package -> OpamFile.OPAM.t option

Return the OPAM file for the given package

    val url : state -> OpamTypes.package -> OpamFile.URL.t option

Return the URL file for the given package

    val descr : state -> OpamTypes.package -> OpamFile.Descr.t

Return the Descr file for the given package

    val descr_opt : state -> OpamTypes.package -> OpamFile.Descr.t option

Return the Descr file for the given package

    val files : state -> OpamTypes.package -> OpamTypes.dirname option

Return the files/ directory overlay for the given package

    val compiler_comp : state -> OpamTypes.compiler -> OpamFile.Comp.t

Return the compiler description

## Repositories

    val string_of_repositories : OpamFile.Repo_config.t OpamTypes.repository_name_map -> string

Pretty print a map of repositories

    val package_index : state ->
           (OpamTypes.repository_name * string option) OpamTypes.package_map

Builds a map which says in which repository the latest metadata for a given package are. The function respect the bustom priorities given by the order of `priorities`.

    val compiler_index : state ->
           (OpamTypes.repository_name * string option) OpamTypes.compiler_map

Build a map which says in which repository the latest metadata for a given compiler is.

    val sorted_repositories : state -> OpamTypes.repository list

Sort repositories by priority.

    val mem_repository : state -> OpamTypes.repository_name -> bool

Check whether a repository exists.

    val find_repository : state -> OpamTypes.repository_name -> OpamTypes.repository

Find a given repostiory. Exit the program if no such repository name exists.

    val find_repository_opt : state -> OpamTypes.repository_name -> OpamTypes.repository option

Find a given repostiory.

    val redirect : state ->
           OpamTypes.repository ->
           (OpamTypes.repository * OpamTypes.filter option) option

Check the redirections.

## Compilers

    val install_global_config : OpamTypes.dirname -> OpamTypes.switch -> unit

(Re-)install the configuration for a given root and switch

    val install_compiler : state ->
           quiet:bool -> OpamTypes.switch -> OpamTypes.compiler -> unit

Install the given compiler

    val update_switch_config : state -> OpamTypes.switch -> unit

Write the right compiler switch in ~/.opam/config

    val get_compiler_packages : state -> OpamTypes.compiler -> OpamTypes.atom list

Get the packages associated with the given compiler

    val is_compiler_installed : state -> OpamTypes.compiler -> bool

Is a compiler installed ?

    val is_switch_installed : state -> OpamTypes.switch -> bool

Is a switch installed ?

    val compiler_state : state -> OpamTypes.checksums OpamTypes.compiler_map

Global compiler state

    val compiler_repository_state : state -> OpamTypes.checksums OpamTypes.compiler_map

Repository state

    val repository_and_prefix_of_compiler : state ->
           OpamTypes.compiler -> (OpamTypes.repository * string option) option

Return the active repository for a given compiler

## Packages

    val is_name_installed : state -> OpamTypes.name -> bool

Check whether a package name is installed

    val is_package_installed : state -> OpamTypes.package -> bool

Return whether a package is installed

    val find_installed_package_by_name : state -> OpamTypes.name -> OpamTypes.package

Return the installed package with the right name

    val find_packages_by_name : state -> OpamTypes.name -> OpamTypes.package_set option

Return all the packages with the given name

    val installed_map : state -> OpamTypes.version OpamTypes.name_map

Return a map from package names to package installed version

    val base_packages : OpamTypes.name list

Return the base packages

    val all_installed : state -> OpamTypes.package_set

Return all the collection of installed packages, for all the available packages

    val installed_versions : state ->
           OpamTypes.name -> OpamTypes.switch list OpamTypes.package_map

Return a map containing the switch where a given package is installed.

    val installed_timestamp : state -> OpamTypes.name -> float

Returns a timestamp when the given package was last installed

    val unknown_package : state -> OpamTypes.atom -> string

Returns a message about an atom that doesn't exist

    val unavailable_reason : state -> OpamTypes.atom -> string

Returns an explanation why a package is not currently available

    val download_archive : state -> OpamTypes.package -> OpamTypes.filename option

Download the OPAM-package archive ($name.$version+opam.tar.gz)

    val download_upstream : state ->
           OpamTypes.package -> OpamTypes.dirname -> OpamTypes.generic_file option

Download the upstream archive, add the eventual additional files and return the directory..

    val package_state : state -> OpamTypes.checksums OpamTypes.package_map

Global package state.

    val package_partial_state : state ->
           OpamTypes.package -> archive:bool -> bool * OpamTypes.checksums

Global & partial package state.

    val package_repository_state : state -> OpamTypes.checksums OpamTypes.package_map

Repository state

    val package_repository_partial_state : state ->
           OpamTypes.package -> archive:bool -> bool * OpamTypes.checksums

Repository & partial package state.

    val repository_of_package : state -> OpamTypes.package -> OpamTypes.repository option

Get the active repository for a given package

    val repository_and_prefix_of_package : state ->
           OpamTypes.package -> (OpamTypes.repository * string option) option

Get the active repository for a given package

    val add_to_reinstall : state -> all:bool -> OpamTypes.package_set -> unit

Add the given packages to the set of package to reinstall. If `all` is set, this is done for ALL the switches (useful when a package change upstream for instance). If not, only the reinstall state of the current switch is changed.

    val copy_files : state -> OpamTypes.package -> OpamTypes.dirname -> unit

Return the files for a given package

    val install_metadata : state -> OpamTypes.package -> unit

Copy the repository metadata into the global state.

    val remove_metadata : state -> OpamTypes.package_set -> unit

Remove some metadata from the global state if they are not used anymore.

## Development packages

    val dev_packages : state -> OpamTypes.package_set

Get all the development packages. This include the one locally pinned (for the current switch) and the global dev packages.

    val update_dev_packages : state -> OpamTypes.package_set -> OpamTypes.package_set

`update_dev_packages t` checks for upstream changes for packages first in the switch cache and then in the global cache. Return the packages whose contents have changed upstream. Side-effect: update the reinstall files.

    val update_dev_package : state -> OpamTypes.package -> bool

Updates a dev or pinned package from its upstream; returns true if changed, false otherwise

    val is_dev_package : state -> OpamTypes.package -> bool

Check whether a package is a development package

    val has_empty_opam : state -> OpamTypes.package -> bool

May be used to check if a given package metadata has just been initialised. Also returns `true` if there is no opam overlay.

## Configuration files

    val dot_config : state -> OpamTypes.name -> OpamFile.Dot_config.t

Return the .config file for the given package

## Locks

    val check : OpamTypes.lock -> unit

Apply a function while taking the right locks

## Pinned packages

    val is_pinned : state -> OpamTypes.name -> bool

Is the package name pinned ?

    val is_locally_pinned : state -> OpamTypes.name -> bool

Is the package locally pinned ? (ie. not a version pinning)

    val pinned : state -> OpamTypes.name -> OpamTypes.package

Returns the versionned pinned package.
Raises `Not_found` if not pinned

    val pinned_opt : state -> OpamTypes.name -> OpamTypes.package option

Returns the versionned pinned package, or `None` if not pinned

    val pinned_packages : state -> OpamTypes.package_set

The set of pinned packages in the state (warning: costly)

    val url_of_locally_pinned_package : state -> OpamTypes.name -> OpamFile.URL.t

Return the URL file associated with a locally pinned package.

## Overlays

    val add_pinned_overlay : ?template:bool ->
           ?version:OpamTypes.version -> state -> OpamTypes.name -> unit

Add overlay files for a pinned package. If no definition is found use a minimal OPAM file unless `template` is set to `true`.

    val remove_overlay : state -> OpamTypes.name -> unit

Remove all overlay files

## System compilers

    val create_system_compiler_description : OpamTypes.dirname -> OpamTypes.compiler_version option -> unit

Create $opam/compilers/system.com. Take the global root and the new system compiler version as arguments.

    val jobs : state -> int

## Jobs

    val dl_jobs : state -> int

## Download Jobs

    val check_base_packages : state -> unit

Consistency checks: do the base package for the current compiler are installed ?
/ *

    val switch_reinstall_hook : (OpamTypes.switch -> unit) Pervasives.ref

Switch reinstall hook.

    val fix_descriptions_hook : (?save_cache:bool -> state -> verbose:bool -> unit) Pervasives.ref

Update hook