1OPAM-CONFIG(1)                    Opam Manual                   OPAM-CONFIG(1)
2
3
4

NAME

6       opam-config - Display configuration options for packages.
7

SYNOPSIS

9       opam config [OPTION]... [COMMAND] [ARG]...
10

DESCRIPTION

12       This command uses opam state to output information on how to use
13       installed libraries, update the PATH, and substitute variables used in
14       opam packages.
15
16       Apart from opam config env, most of these commands are used by opam
17       internally, and are of limited interest for the casual user.
18

COMMANDS

20       env Returns the bindings for the environment variables set in the
21           current switch, e.g. PATH, in a format intended to be evaluated by
22           a shell. With -v, add comments documenting the reason or package of
23           origin for each binding. This is most usefully used as eval $(opam
24           config env) to have further shell commands be evaluated in the
25           proper opam context. Can also be accessed through opam env.
26
27       revert-env
28           Reverts environment changes made by opam, e.g. eval $(opam config
29           revert-env) undoes what eval $(opam config env) did, as much as
30           possible.
31
32       exec [--] COMMAND [ARG]...
33           Execute COMMAND with the correct environment variables. This
34           command can be used to cross-compile between switches using opam
35           config exec --switch=SWITCH -- COMMAND ARG1 ... ARGn. Opam
36           expansion takes place in command and args. If no switch is present
37           on the command line or in the OPAMSWITCH environment variable,
38           OPAMSWITCH is not set in COMMAND's environment. Can also be
39           accessed through opam exec.
40
41       var VAR
42           Return the value associated with variable VAR. Package variables
43           can be accessed with the syntax pkg:var. Can also be accessed
44           through opam var
45
46       list [PACKAGE]...
47           Without argument, prints a documented list of all available
48           variables. With PACKAGE, lists all the variables available for
49           these packages. Use - to include global configuration variables for
50           this switch.
51
52       set VAR VALUE
53           Set the given opam variable for the current switch. Warning:
54           changing a configured path will not move any files! This command
55           does not perform any variable expansion.
56
57       unset VAR
58           Unset the given opam variable for the current switch. Warning:
59           unsetting built-in configuration variables can cause problems!
60
61       set-global VAR VALUE
62           Set the given variable globally in the opam root, to be visible in
63           all switches
64
65       unset-global VAR
66           Unset the given global variable
67
68       expand STRING
69           Expand variable interpolations in the given string
70
71       subst FILE...
72           Substitute variables in the given files. The strings %{var}% are
73           replaced by the value of variable var (see var).
74
75       report
76           Prints a summary of your setup, useful for bug-reports.
77
78       cudf-universe [FILE]
79           Outputs the current available package universe in CUDF format.
80
81       pef-universe [FILE]
82           Outputs the current package universe in PEF format.
83

OPTIONS

85       --inplace-path
86           When updating the PATH variable, replace any pre-existing opam path
87           in-place rather than putting the new path in front. This means
88           programs installed in opam that were shadowed will remain so after
89           opam env
90
91       --set-root
92           With the env and exec subcommands, also sets the OPAMROOT variable,
93           making sure further calls to opam will use the same root.
94
95       --set-switch
96           With the env and exec subcommands, also sets the OPAMSWITCH
97           variable, making sure further calls to opam will use the same
98           switch as this one.
99
100       --sexp
101           Print environment as an s-expression rather than in shell format
102
103       --shell=SHELL
104           Sets the configuration mode for opam environment appropriate for
105           SHELL. One of one of `bash', `sh', `csh', `zsh' or `fish'. Guessed
106           from the parent processes and the $SHELL variable by default.
107

COMMON OPTIONS

109       These options are common to all commands.
110
111       --best-effort
112           Don't fail if all requested packages can't be installed: try to
113           install as many as possible. Note that not all external solvers may
114           support this option (recent versions of aspcud or mccs should).
115           This is equivalent to setting $OPAMBESTEFFORT environment variable.
116
117       --color=WHEN
118           Colorize the output. WHEN must be one of `always', `never' or
119           `auto'.
120
121       --criteria=CRITERIA
122           Specify user preferences for dependency solving for this run.
123           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
124           on the supported language, and the external solvers available, see
125           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
126           using solver preferences can be found at
127           http://www.dicosmo.org/Articles/usercriteria.pdf.
128
129       --cudf=FILENAME
130           Debug option: Save the CUDF requests sent to the solver to
131           FILENAME-<n>.cudf.
132
133       --debug
134           Print debug message to stderr. This is equivalent to setting
135           $OPAMDEBUG to "true".
136
137       --debug-level=LEVEL
138           Like --debug, but allows specifying the debug level (--debug sets
139           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
140
141       --git-version
142           Print the git version of opam, if set (i.e. you are using a
143           development version), and exit.
144
145       --help[=FMT] (default=auto)
146           Show this help in format FMT. The value FMT must be one of `auto',
147           `pager', `groff' or `plain'. With `auto', the format is `pager` or
148           `plain' whenever the TERM env var is `dumb' or undefined.
149
150       --ignore-pin-depends
151           Ignore extra pins required by packages that get pinned, either
152           manually through opam pin or through opam install DIR. This is
153           equivalent to setting IGNOREPINDEPENDS=true.
154
155       --json=FILENAME
156           Save the results of the opam run in a computer-readable file. If
157           the filename contains the character `%', it will be replaced by an
158           index that doesn't overwrite an existing file. Similar to setting
159           the $OPAMJSON variable.
160
161       --no-aspcud
162           Deprecated.
163
164       --no-auto-upgrade
165           When configuring or updating a repository that is written for an
166           earlier opam version (1.2), opam internally converts it to the
167           current format. This disables this behaviour. Note that
168           repositories should define their format version in a 'repo' file at
169           their root, or they will be assumed to be in the older format. It
170           is, in any case, preferable to upgrade the repositories manually
171           using opam admin upgrade [--mirror URL] when possible.
172
173       --no-self-upgrade
174           Opam will replace itself with a newer binary found at OPAMROOT/opam
175           if present. This disables this behaviour.
176
177       -q, --quiet
178           Disables --verbose.
179
180       --root=ROOT
181           Use ROOT as the current root path. This is equivalent to setting
182           $OPAMROOT to ROOT.
183
184       --safe, --readonly
185           Make sure nothing will be automatically updated or rewritten.
186           Useful for calling from completion scripts, for example. Will fail
187           whenever such an operation is needed ; also avoids waiting for
188           locks, skips interactive questions and overrides the $OPAMDEBUG
189           variable. This is equivalent to set environment variable $OPAMSAFE.
190
191       --solver=CMD
192           Specify the CUDF solver to use for resolving package installation
193           problems. This is either a predefined solver (this version of opam
194           supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
195           aspcud-old, packup), or a custom command that should contain the
196           variables %{input}%, %{output}%, %{criteria}%, and optionally
197           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
198
199       --strict
200           Fail whenever an error is found in a package definition or a
201           configuration file. The default is to continue silently if
202           possible.
203
204       --switch=SWITCH
205           Use SWITCH as the current compiler switch. This is equivalent to
206           setting $OPAMSWITCH to SWITCH.
207
208       --use-internal-solver
209           Disable any external solver, and use the built-in one (this
210           requires that opam has been compiled with a built-in solver). This
211           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
212
213       -v, --verbose
214           Be more verbose. One -v shows all package commands, repeat to also
215           display commands called internally (e.g. tar, curl, patch etc.)
216           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
217
218       --version
219           Show version information.
220
221       -w, --working-dir
222           Whenever updating packages that are bound to a local,
223           version-controlled directory, update to the current working state
224           of their source instead of the last committed state, or the ref
225           they are pointing to. This only affects packages explicitly listed
226           on the command-line.It can also be set with $OPAMWORKINGDIR.
227
228       -y, --yes
229           Answer yes to all yes/no questions without prompting. This is
230           equivalent to setting $OPAMYES to "true".
231

ENVIRONMENT VARIABLES

233       Opam makes use of the environment variables listed here. Boolean
234       variables should be set to "0", "no", "false" or the empty string to
235       disable, "1", "yes" or "true" to enable.
236
237       OPAMALLPARENS surround all filters with parenthesis
238
239       OPAMAUTOREMOVE see remove option `--auto-remove`
240
241       OPAMBESTEFFORT see option `--best-effort`
242
243       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
244       the criteria when the `--best-effort` option is set, and is expected to
245       maximise the `opam-query` property in the solution
246
247       OPAMCOLOR, when set to always or never, sets a default value for the
248       --color option.
249
250       OPAMCRITERIA specifies user preferences for dependency solving. The
251       default value depends on the solver version, use `config report` to
252       know the current setting. See also option --criteria
253
254       OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
255
256       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
257       for more options.
258
259       OPAMDEBUG see options `--debug' and `--debug-level'.
260
261       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
262
263       OPAMDRYRUN see option `--dry-run`
264
265       OPAMEDITOR sets the editor to use for opam file editing, overrides
266       $EDITOR and $VISUAL
267
268       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
269       fails. 0 to print all.
270
271       OPAMEXTERNALSOLVER see option `--solver'.
272
273       OPAMFAKE see option `--fake`
274
275       OPAMFETCH specifies how to download files: either `wget', `curl' or a
276       custom command where variables %{url}%, %{out}%, %{retry}%,
277       %{compress}% and %{checksum}% will be replaced. Overrides the
278       'download-command' value from the main config file.
279
280       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
281
282       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
283
284       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
285
286       OPAMJOBS sets the maximum number of parallel workers to run.
287
288       OPAMJSON log json output to the given file (use character `%' to index
289       the files)
290
291       OPAMLOCKED see install option `--locked`
292
293       OPAMLOGS logdir sets log directory, default is a temporary directory in
294       /tmp
295
296       OPAMMAKECMD set the system make command to use
297
298       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
299       in an earlier format to the current one, on 'update' or 'init'.
300
301       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
302       some backups. This skips some finalisers and may also help to get more
303       reliable backtraces
304
305       OPAMLOCKRETRIES sets the number of tries after which opam gives up
306       acquiring its lock and fails. <= 0 means infinite wait.
307
308       OPAMMERGEOUT merge process outputs, stderr on stdout
309
310       OPAMNO answer no to any question asked.
311
312       OPAMNOASPCUD Deprecated.
313
314       OPAMNOCHECKSUMS enables option --no-checksums when available.
315
316       OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
317
318       OPAMPINKINDAUTO sets whether version control systems should be detected
319       when pinning to a local path. Enabled by default since 1.3.0.
320
321       OPAMPRECISETRACKING fine grain tracking of directories
322
323       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
324       available (e.g. for `opam install`).
325
326       OPAMRETRES sets the number of tries before failing downloads.
327
328       OPAMROOT see option `--root'. This is automatically set by `opam env
329       --root=DIR --set-root'.
330
331       OPAMROOTISOK don't complain when running as root.
332
333       OPAMSAFE see option `--safe'
334
335       OPAMSHOW see option `--show`
336
337       OPAMSKIPUPDATE see option `--skip-updates`
338
339       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
340       compatibility testing only.
341
342       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
343       60.0, set to 0 for unlimited. Note that all solvers may not support
344       this option.
345
346       OPAMSTATUSLINE display a dynamic status line showing what's currently
347       going on on the terminal. (one of one of `always', `never' or `auto')
348
349       OPAMSTATS display stats at the end of command
350
351       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
352
353       OPAMSWITCH see option `--switch'. Automatically set by `opam env
354       --switch=SWITCH --set-switch'.
355
356       OPAMUNLOCKBASE see install option `--unlock-base`
357
358       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
359       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
360       are set. See also option --criteria
361
362       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
363
364       OPAMUSEOPENSSL force openssl use for hash computing
365
366       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
367       or `auto'). By default `auto', which is determined from the locale).
368
369       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
370       Implies OPAMUTF8. This is set by default on OSX only.
371
372       OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
373       an opam repository update
374
375       OPAMVAR_var overrides the contents of the variable var when
376       substituting `%{var}%` strings in `opam` files.
377
378       OPAMVAR_package_var overrides the contents of the variable package:var
379       when substituting `%{package:var}%` strings in `opam` files.
380
381       OPAMVERBOSE see option `--verbose'.
382
383       OPAMWORKINGDIR see option `--working-dir`
384
385       OPAMYES see option `--yes'.
386

EXIT STATUS

388       As an exception to the following, the `exec' command returns 127 if the
389       command was not found or couldn't be executed, and the command's exit
390       value otherwise.
391
392       0   Success, or true for boolean queries.
393
394       1   False. Returned when a boolean return value is expected, e.g. when
395           running with --check, or for queries like opam lint.
396
397       2   Bad command-line arguments, or command-line arguments pointing to
398           an invalid context (e.g. file not following the expected format).
399
400       5   Not found. You requested something (package, version, repository,
401           etc.) that couldn't be found.
402
403       10  Aborted. The operation required confirmation, which wasn't given.
404
405       15  Could not acquire the locks required for the operation.
406
407       20  There is no solution to the user request. This can be caused by
408           asking to install two incompatible packages, for example.
409
410       30  Error in package definition, or other metadata files. Using
411           --strict raises this error more often.
412
413       31  Package script error. Some package operations were unsuccessful.
414           This may be an error in the packages or an incompatibility with
415           your system. This can be a partial error.
416
417       40  Sync error. Could not fetch some remotes from the network. This can
418           be a partial error.
419
420       50  Configuration error. Opam or system configuration doesn't allow
421           operation, and needs fixing.
422
423       60  Solver failure. The solver failed to return a sound answer. It can
424           be due to a broken external solver, or an error in solver
425           configuration.
426
427       99  Internal error. Something went wrong, likely due to a bug in opam
428           itself.
429
430       130 User interrupt. SIGINT was received, generally due to the user
431           pressing Ctrl-C.
432

FURTHER DOCUMENTATION

434       See https://opam.ocaml.org/doc.
435

AUTHORS

437       Vincent Bernardoff <vb@luminar.eu.org>
438       Raja Boujbel <raja.boujbel@ocamlpro.com>
439       Roberto Di Cosmo <roberto@dicosmo.org>
440       Thomas Gazagnaire <thomas@gazagnaire.org>
441       Louis Gesbert <louis.gesbert@ocamlpro.com>
442       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
443       Anil Madhavapeddy <anil@recoil.org>
444       Guillem Rieu <guillem.rieu@ocamlpro.com>
445       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
446       Frederic Tuong <tuong@users.gforge.inria.fr>
447

BUGS

449       Check bug reports at https://github.com/ocaml/opam/issues.
450
451
452
453Opam 2.0.6                                                      OPAM-CONFIG(1)
Impressum