1OPAM-VAR(1) Opam Manual OPAM-VAR(1)
2
6 opam-var - Display and update the value associated with a given
7 variable
8
10 opam var [OPTION]… [VAR[=[VALUE]]]
11
13 Without argument, lists the opam variables currently defined. With a
14 VAR argument, prints the value associated with VAR. Otherwise, sets or
15 updates VAR's value. If no scope is given, it acts on switch variables
16 by default. This command does not perform any variable expansion.
17
19 VAR[=[VALUE]]
20 If only VAR is given, displays its associated value. If VALUE is
21 absent, VAR's value is removed. Otherwise, its value is
22 overwritten.
23
25 --global
26 Act on global configuration
27 --no
29 Answer no to all opam yes/no questions without prompting. See also
30 --confirm-level. This is equivalent to setting $OPAMNO to "true".
31 --package=PACKAGE
33 List all variables defined for the given package
34 -y, --yes
36 Answer yes to all opam yes/no questions without prompting. See also
37 --confirm-level. This is equivalent to setting $OPAMYES to "true".
38
40 These options are common to all commands.
41 --best-effort
43 Don't fail if all requested packages can't be installed: try to
44 install as many as possible. Note that not all external solvers may
45 support this option (recent versions of aspcud or mccs should).
46 This is equivalent to setting $OPAMBESTEFFORT environment variable.
47 --cli=MAJOR.MINOR (absent=2.1)
49 Use the command-line interface syntax and semantics of MAJOR.MINOR.
50 Intended for any persistent use of opam (scripts, blog posts,
51 etc.), any version of opam in the same MAJOR series will behave as
52 for the specified MINOR release. The flag was not available in opam
53 2.0, so to select the 2.0 CLI, set the OPAMCLI environment variable
54 to 2.0 instead of using this parameter.
55 --color=WHEN
57 Colorize the output. WHEN must be one of always, never or auto.
58 --confirm-level=LEVEL
60 Confirmation level, LEVEL must be one of ask, no, yes or
61 unsafe-yes. Can be specified more than once. If --yes or --no are
62 also given, the value of the last --confirm-level is taken into
63 account. This is equivalent to setting $OPAMCONFIRMLEVEL`.
64 --criteria=CRITERIA
66 Specify user preferences for dependency solving for this run.
67 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
68 on the supported language, and the external solvers available, see
69 http://opam.ocaml.org/doc/External_solvers.html. A general guide to
70 using solver preferences can be found at
71 http://www.dicosmo.org/Articles/usercriteria.pdf.
72 --cudf=FILENAME
74 Debug option: Save the CUDF requests sent to the solver to
75 FILENAME-<n>.cudf.
76 --debug
78 Print debug message to stderr. This is equivalent to setting
79 $OPAMDEBUG to "true".
80 --debug-level=LEVEL
82 Like --debug, but allows specifying the debug level (--debug sets
83 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
84 --git-version
86 Print the git version of opam, if set (i.e. you are using a
87 development version), and exit.
88 --help[=FMT] (default=auto)
90 Show this help in format FMT. The value FMT must be one of auto,
91 pager, groff or plain. With auto, the format is pager or plain
92 whenever the TERM env var is dumb or undefined.
93 --ignore-pin-depends
95 Ignore extra pins required by packages that get pinned, either
96 manually through opam pin or through opam install DIR. This is
97 equivalent to setting IGNOREPINDEPENDS=true.
98 --json=FILENAME
100 Save the results of the opam run in a computer-readable file. If
101 the filename contains the character `%', it will be replaced by an
102 index that doesn't overwrite an existing file. Similar to setting
103 the $OPAMJSON variable.
104 --no-aspcud
106 Removed in 2.1.
107 --no-auto-upgrade
109 When configuring or updating a repository that is written for an
110 earlier opam version (1.2), opam internally converts it to the
111 current format. This disables this behaviour. Note that
112 repositories should define their format version in a 'repo' file at
113 their root, or they will be assumed to be in the older format. It
114 is, in any case, preferable to upgrade the repositories manually
115 using opam admin upgrade [--mirror URL] when possible.
116 --no-self-upgrade
118 Opam will replace itself with a newer binary found at OPAMROOT/opam
119 if present. This disables this behaviour.
120 -q, --quiet
122 Disables --verbose.
123 --root=ROOT
125 Use ROOT as the current root path. This is equivalent to setting
126 $OPAMROOT to ROOT.
127 --safe, --readonly
129 Make sure nothing will be automatically updated or rewritten.
130 Useful for calling from completion scripts, for example. Will fail
131 whenever such an operation is needed ; also avoids waiting for
132 locks, skips interactive questions and overrides the $OPAMDEBUG
133 variable. This is equivalent to set environment variable $OPAMSAFE.
134 --solver=CMD
136 Specify the CUDF solver to use for resolving package installation
137 problems. This is either a predefined solver (this version of opam
138 supports builtin-mccs+lp(), builtin-mccs+glpk,
139 builtin-dummy-z3-solver, builtin-dummy-0install-solver, aspcud,
140 mccs, aspcud-old, packup), or a custom command that should contain
141 the variables %{input}%, %{output}%, %{criteria}%, and optionally
142 %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
143 --strict
145 Fail whenever an error is found in a package definition or a
146 configuration file. The default is to continue silently if
147 possible.
148 --switch=SWITCH
150 Use SWITCH as the current compiler switch. This is equivalent to
151 setting $OPAMSWITCH to SWITCH.
152 --use-internal-solver
154 Disable any external solver, and use the built-in one (this
155 requires that opam has been compiled with a built-in solver). This
156 is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
157 -v, --verbose
159 Be more verbose. One -v shows all package commands, repeat to also
160 display commands called internally (e.g. tar, curl, patch etc.)
161 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
162 --version
164 Show version information.
165 -w, --working-dir
167 Whenever updating packages that are bound to a local,
168 version-controlled directory, update to the current working state
169 of their source instead of the last committed state, or the ref
170 they are pointing to. As source directory is copied as it is, if it
171 isn't clean it may result on a opam build failure.This only affects
172 packages explicitly listed on the command-line.It can also be set
173 with $OPAMWORKINGDIR.
174
176 Opam makes use of the environment variables listed here. Boolean
177 variables should be set to "0", "no", "false" or the empty string to
178 disable, "1", "yes" or "true" to enable.
179 OPAMALLPARENS surround all filters with parenthesis.
181 OPAMASSUMEDEPEXTS see option `--assume-depexts'.
183 OPAMAUTOREMOVE see remove option `--auto-remove'.
185 OPAMBESTEFFORT see option `--best-effort'.
187 OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
189 the criteria when the `--best-effort' option is set, and is expected to
190 maximise the `opam-query' property in the solution.
191 OPAMBUILDDOC Removed in 2.1.
193 OPAMBUILDTEST Removed in 2.1.
195 OPAMCLI see option `--cli'.
197 OPAMCOLOR when set to always or never, sets a default value for the
199 `--color' option.
200 OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
202 priority over OPAMYES and OPAMNO.
203 OPAMCRITERIA specifies user preferences for dependency solving. The
205 default value depends on the solver version, use `config report' to
206 know the current setting. See also option --criteria.
207 OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
209 OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
211 preprocessing.
212 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
214 for more options.
215 OPAMDEBUG see options `--debug' and `--debug-level'.
217 OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
219 list of sections. Sections can optionally have a specific debug level
220 (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
221 `--debug-level'.
222 OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
224 CUDF preprocessing is.
225 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
227 OPAMDROPWORKINGDIR overrides packages previously updated with
229 --working-dir on update. Without this variable set, opam would keep
230 them unchanged unless explicitly named on the command-line.
231 OPAMDRYRUN see option `--dry-run'.
233 OPAMEDITOR sets the editor to use for opam file editing, overrides
235 $EDITOR and $VISUAL.
236 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
238 fails. 0 to print all.
239 OPAMEXTERNALSOLVER see option `--solver'.
241 OPAMFAKE see option `--fake'.
243 OPAMFETCH specifies how to download files: either `wget', `curl' or a
245 custom command where variables %{url}%, %{out}%, %{retry}%,
246 %{compress}% and %{checksum}% will be replaced. Overrides the
247 'download-command' value from the main config file.
248 OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
250 OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
252 OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
254 OPAMINPLACEBUILD see option `--inplace-build'.
256 OPAMJOBS sets the maximum number of parallel workers to run.
258 OPAMJSON log json output to the given file (use character `%' to index
260 the files).
261 OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
263 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
265 some backups. This skips some finalisers and may also help to get more
266 reliable backtraces.
267 OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
269 OPAMLOGS logdir sets log directory, default is a temporary directory in
271 /tmp
272 OPAMMAKECMD set the system make command to use.
274 OPAMMERGEOUT merge process outputs, stderr on stdout.
276 OPAMNO answer no to any question asked, see options `--no` and
278 `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
279 OPAMYES is set.
280 OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
282 OPAMNOASPCUD Deprecated.
284 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
286 in an earlier format to the current one, on 'update' or 'init'.
287 OPAMNOCHECKSUMS enables option --no-checksums when available.
289 OPAMNODEPEXTS disables system dependencies handling, see option
291 `--no-depexts'.
292 OPAMNOENVNOTICE Internal.
294 OPAMNOSELFUPGRADE see option `--no-self-upgrade'
296 OPAMPINKINDAUTO sets whether version control systems should be detected
298 when pinning to a local path. Enabled by default since 1.3.0.
299 OPAMPRECISETRACKING fine grain tracking of directories.
301 OPAMPREPRO set this to false to disable CUDF preprocessing. Less
303 efficient, but might help debugging solver issue.
304 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
306 available (e.g. for `opam install').
307 OPAMRETRIES sets the number of tries before failing downloads.
309 OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
311 OPAMROOT see option `--root'. This is automatically set by `opam env
313 --root=DIR --set-root'.
314 OPAMROOTISOK don't complain when running as root.
316 OPAMSAFE see option `--safe'.
318 OPAMSHOW see option `--show'.
320 OPAMSKIPUPDATE see option `--skip-updates'.
322 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
324 compatibility testing only.
325 OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
327 return a solution when they reach timeout; while the solution remains
328 assured to be consistent, there is no guarantee in this case that it
329 fits the expected optimisation criteria. If `true', opam willcontinue
330 with a warning, if `false' a timeout is an error. Currently only the
331 builtin-z3 backend handles this degraded case.
332 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
334 60.0, set to 0 for unlimited. Note that all solvers may not support
335 this option.
336 OPAMSTATS display stats at the end of command.
338 OPAMSTATUSLINE display a dynamic status line showing what's currently
340 going on on the terminal. (one of one of always, never or auto)
341 OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
343 OPAMSWITCH see option `--switch'. Automatically set by `opam env
345 --switch=SWITCH --set-switch'.
346 OPAMUNLOCKBASE see install option `--unlock-base'.
348 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
350 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
351 are set. See also option --criteria.
352 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
354 OPAMUSEOPENSSL force openssl use for hash computing.
356 OPAMUTF8 use UTF8 characters in output (one of one of always, never or
358 auto). By default `auto', which is determined from the locale).
359 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
361 Implies OPAMUTF8. This is set by default on OSX only.
362 OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
364 opam repository update.
365 OPAMVERBOSE see option `--verbose'.
367 OPAMVERSIONLAGPOWER do not use.
369 OPAMWITHDOC see install option `--with-doc'.
371 OPAMWITHTEST see install option `--with-test.
373 OPAMWORKINGDIR see option `--working-dir'.
375 OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
377 priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
378 OPAMVAR_var overrides the contents of the variable var when
380 substituting `%{var}%` strings in `opam` files.
381 OPAMVAR_package_var overrides the contents of the variable package:var
383 when substituting `%{package:var}%` strings in `opam` files.
384
386 All scripts and programmatic invocations of opam should use `--cli' in
387 order to ensure that they work seamlessly with future versions of the
388 opam client. Additionally, blog posts or other documentation can
389 benefit, as it prevents information from becoming stale.
390 Although opam only supports roots (~/.opam/) for the current version,
392 it does provide backwards compatibility for its command-line interface.
393 Since CLI version support was only added in opam 2.1, use OPAMCLI to
395 select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
396 for 2.1 (or later) versions, since an environment variable controlling
397 the parsing of syntax is brittle. To this end, opam displays a warning
398 if OPAMCLI specifies a valid version other than 2.0, and also if
399 `--cli=2.0' is specified.
400 The command-line version is selected by using the `--cli' option or the
402 OPAMCLI environment variable. `--cli' may be specified morethan once,
403 where the last instance takes precedence. OPAMCLI is only inspected if
404 `--cli' is not given.
405
407 As an exception to the following, the `exec' command returns 127 if the
408 command was not found or couldn't be executed, and the command's exit
409 value otherwise.
410 0 Success, or true for boolean queries.
412 1 False. Returned when a boolean return value is expected, e.g. when
414 running with --check, or for queries like opam lint.
415 2 Bad command-line arguments, or command-line arguments pointing to
417 an invalid context (e.g. file not following the expected format).
418 5 Not found. You requested something (package, version, repository,
420 etc.) that couldn't be found.
421 10 Aborted. The operation required confirmation, which wasn't given.
423 15 Could not acquire the locks required for the operation.
425 20 There is no solution to the user request. This can be caused by
427 asking to install two incompatible packages, for example.
428 30 Error in package definition, or other metadata files. Using
430 --strict raises this error more often.
431 31 Package script error. Some package operations were unsuccessful.
433 This may be an error in the packages or an incompatibility with
434 your system. This can be a partial error.
435 40 Sync error. Could not fetch some remotes from the network. This can
437 be a partial error.
438 50 Configuration error. Opam or system configuration doesn't allow
440 operation, and needs fixing.
441 60 Solver failure. The solver failed to return a sound answer. It can
443 be due to a broken external solver, or an error in solver
444 configuration.
445 99 Internal error. Something went wrong, likely due to a bug in opam
447 itself.
448 130 User interrupt. SIGINT was received, generally due to the user
450 pressing Ctrl-C.
451
453 See https://opam.ocaml.org/doc.
454
456 Vincent Bernardoff <vb@luminar.eu.org>
457 Raja Boujbel <raja.boujbel@ocamlpro.com>
458 Roberto Di Cosmo <roberto@dicosmo.org>
459 Thomas Gazagnaire <thomas@gazagnaire.org>
460 Louis Gesbert <louis.gesbert@ocamlpro.com>
461 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
462 Anil Madhavapeddy <anil@recoil.org>
463 Guillem Rieu <guillem.rieu@ocamlpro.com>
464 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
465 Frederic Tuong <tuong@users.gforge.inria.fr>
466
468 Check bug reports at https://github.com/ocaml/opam/issues.
469Opam 2.1.3 OPAM-VAR(1)