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

NAME

6       opam-init - Initialize opam state, or set init options.
7

SYNOPSIS

9       opam init [OPTION]... [NAME] [ADDRESS]
10

DESCRIPTION

12       Initialise the opam state, or update opam init options
13
14       The init command initialises a local "opam root" (by default, ~/.opam/)
15       that holds opam's data and packages. This is a necessary step for
16       normal operation of opam. The initial software repositories are
17       fetched, and an initial 'switch' can also be installed, according to
18       the configuration and options. These can be afterwards configured using
19       opam switch and opam repository.
20
21       The initial repository and defaults can be set through a configuration
22       file found at ~/.opamrc or /etc/opamrc.
23
24       Additionally, this command allows one to customise some aspects of
25       opam's shell integration, when run initially (avoiding the interactive
26       dialog), but also at any later time.
27

ARGUMENTS

29       ADDRESS
30           Address of the initial package repository, when creating a new opam
31           root.
32
33       NAME (absent=default)
34           Name of the initial repository, when creating a new opam root.
35

OPTIONS

37       -a, --auto-setup
38           Automatically do a full setup, including adding a line to your
39           shell init files.
40
41       --bare
42           Initialise the opam state, but don't setup any compiler switch yet.
43
44       --bypass-checks
45           Skip checks on required or recommended tools, and assume everything
46           is fine
47
48       -c PACKAGE, --compiler=PACKAGE
49           Set the compiler to install (when creating an initial switch)
50
51       --config=FILE
52           Use the given init config file. If repeated, latest has the highest
53           priority (i.e. each field gets its value from where it was defined
54           last). Specifying a URL pointing to a config file instead is
55           allowed.
56
57       --disable-completion
58           Disable shell completion in opam init scripts.
59
60       --disable-sandboxing
61           Use a default configuration with sandboxing disabled (note that
62           this may be overridden by `opamrc' if --no-opamrc is not specified
63           or --config is used). Use this at your own risk, without sandboxing
64           it is possible for a broken package script to delete all your
65           files.
66
67       --disable-shell-hook
68           Disable registration of a shell hook in opam init scripts.
69
70       --dot-profile=FILENAME
71           Name of the configuration file to update instead of ~/.profile or
72           ~/.zshrc based on shell detection.
73
74       --enable-completion
75           Setup shell completion in opam init scripts, for supported shells.
76
77       --enable-shell-hook
78           Setup opam init scripts to register a shell hook that will
79           automatically keep the shell environment up-to-date at every
80           prompt.
81
82       -i, --interactive
83           Run the setup interactively (this is the default for an initial
84           run, or when no more specific options are specified)
85
86       -j JOBS, --jobs=JOBS
87           Set the maximal number of concurrent jobs to use. The default value
88           is calculated from the number of cores. You can also set it using
89           the $OPAMJOBS environment variable.
90
91       -k KIND, --kind=KIND
92           Specify the kind of the repository to be used (one of `http',
93           `local', `git', `darcs' or `hg').
94
95       -n, --no-setup
96           Do not update the user shell configuration to setup opam. Also
97           implies --disable-shell-hook, unless --interactive or specified
98           otherwise
99
100       --no-opamrc
101           Don't read `/etc/opamrc' or `~/.opamrc': use the default settings
102           and the files specified through --config only
103
104       --reinit
105           Re-run the initial checks and setup, according to opamrc, even if
106           this is not a new opam root
107
108       --shell=SHELL
109           Sets the configuration mode for opam environment appropriate for
110           SHELL. One of one of `bash', `sh', `csh', `zsh' or `fish'. Guessed
111           from the parent processes and the $SHELL variable by default.
112
113       --shell-setup
114           Automatically setup the user shell configuration for opam, e.g.
115           adding a line to the `~/.profile' file.
116
117       --show-default-opamrc
118           Print the built-in default configuration to stdout and exit
119

CONFIGURATION FILE

121       Any field from the built-in initial configuration can be overridden
122       through ~/.opamrc, /etc/opamrc, or a file supplied with --config. The
123       default configuration for this version of opam can be obtained using
124       --show-default-opamrc.
125

PACKAGE BUILD OPTIONS

127       -b, --keep-build-dir
128           Keep the build directories after compiling packages. This is
129           equivalent to setting $OPAMKEEPBUILDDIR to "true".
130
131       -d, --with-doc, --build-doc
132           Build the package documentation. This only affects packages listed
133           on the command-line. The --build-doc form is deprecated as this
134           does also installation. This is equivalent to setting $OPAMWITHDOC
135           (or the deprecated $OPAMBUILDDOC) to "true".
136
137       --dry-run
138           Simulate the command, but don't actually perform any changes. This
139           also can be set with environment variable $OPAMDEBUG.
140
141       --fake
142           This option registers the actions into the opam database, without
143           actually performing them. WARNING: This option is dangerous and
144           likely to break your opam environment. You probably want
145           `--dry-run'. You've been warned.
146
147       --ignore-constraints-on[=PACKAGES] (default=)
148           Forces opam to ignore version constraints on all dependencies to
149           the listed packages. This can be used to test compatibility, but
150           expect builds to break when using this. Note that version
151           constraints on optional dependencies and conflicts are unaffected.
152           This is equivalent to setting $OPAMIGNORECONSTRAINTS.
153
154       --inplace-build
155           When compiling a package which has its source bound to a local
156           directory, process the build and install actions directly in that
157           directory, rather than in a clean copy handled by opam. This only
158           affects packages that are explicitly listed on the command-line.
159           This is equivalent to setting $OPAMINPLACEBUILD to "true".
160
161       --locked[=SUFFIX] (default=locked)
162           In commands that use opam files found from pinned sources, if a
163           variant of the file with an added .SUFFIX extension is found (e.g.
164           foo.opam.locked besides foo.opam), that will be used instead. This
165           is typically useful to offer a more specific set of dependencies
166           and reproduce similar build contexts, hence the name. The opam lock
167           plugin can be used to generate such files, based on the versions of
168           the dependencies currently installed on the host. This is
169           equivalent to setting the $OPAMLOCKED environment variable. Note
170           that this option doesn't generally affect already pinned packages.
171
172       -m MAKE, --make=MAKE
173           Use MAKE as the default 'make' command. Deprecated: use opam config
174           set[-global] make MAKE instead. Has no effect if the make variable
175           is defined.
176
177       --no-checksums
178           Do not verify the checksum of downloaded archives.This is
179           equivalent to setting $OPAMNOCHECKSUMS to "true".
180
181       --require-checksums
182           Reject the installation of packages that don't provide a checksum
183           for the upstream archives. This is equivalent to setting
184           $OPAMREQUIRECHECKSUMS to "true".
185
186       --reuse-build-dir
187           Reuse existing build directories (kept by using --keep-build-dir),
188           instead of compiling from a fresh clone of the source. This can be
189           faster, but also lead to failures if the build systems of the
190           packages don't handle upgrades of dependencies well. This is
191           equivalent to setting $OPAMREUSEBUILDDIR to "true".
192
193       --show-actions
194           Call the solver and display the actions. Don't perform any changes.
195           This is equivalent to setting $OPAMSHOW.
196
197       --skip-updates
198           When running an install, upgrade or reinstall on source-pinned
199           packages, they are normally updated from their origin first. This
200           flag disables that behaviour and will keep them to their version in
201           cache. This is equivalent to setting $OPAMSKIPUPDATE.
202
203       -t, --with-test, --build-test
204           Build and run the package unit-tests. This only affects packages
205           listed on the command-line. The --build-test form is deprecated as
206           this also affects installation. This is equivalent to setting
207           $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
208
209       --unlock-base
210           Allow changes to the packages set as switch base (typically, the
211           main compiler). Use with caution. This is equivalent to setting the
212           $OPAMUNLOCKBASE environment variable
213

COMMON OPTIONS

215       These options are common to all commands.
216
217       --best-effort
218           Don't fail if all requested packages can't be installed: try to
219           install as many as possible. Note that not all external solvers may
220           support this option (recent versions of aspcud or mccs should).
221           This is equivalent to setting $OPAMBESTEFFORT environment variable.
222
223       --color=WHEN
224           Colorize the output. WHEN must be one of `always', `never' or
225           `auto'.
226
227       --criteria=CRITERIA
228           Specify user preferences for dependency solving for this run.
229           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
230           on the supported language, and the external solvers available, see
231           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
232           using solver preferences can be found at
233           http://www.dicosmo.org/Articles/usercriteria.pdf.
234
235       --cudf=FILENAME
236           Debug option: Save the CUDF requests sent to the solver to
237           FILENAME-<n>.cudf.
238
239       --debug
240           Print debug message to stderr. This is equivalent to setting
241           $OPAMDEBUG to "true".
242
243       --debug-level=LEVEL
244           Like --debug, but allows specifying the debug level (--debug sets
245           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
246
247       --git-version
248           Print the git version of opam, if set (i.e. you are using a
249           development version), and exit.
250
251       --help[=FMT] (default=auto)
252           Show this help in format FMT. The value FMT must be one of `auto',
253           `pager', `groff' or `plain'. With `auto', the format is `pager` or
254           `plain' whenever the TERM env var is `dumb' or undefined.
255
256       --ignore-pin-depends
257           Ignore extra pins required by packages that get pinned, either
258           manually through opam pin or through opam install DIR. This is
259           equivalent to setting IGNOREPINDEPENDS=true.
260
261       --json=FILENAME
262           Save the results of the opam run in a computer-readable file. If
263           the filename contains the character `%', it will be replaced by an
264           index that doesn't overwrite an existing file. Similar to setting
265           the $OPAMJSON variable.
266
267       --no-aspcud
268           Deprecated.
269
270       --no-auto-upgrade
271           When configuring or updating a repository that is written for an
272           earlier opam version (1.2), opam internally converts it to the
273           current format. This disables this behaviour. Note that
274           repositories should define their format version in a 'repo' file at
275           their root, or they will be assumed to be in the older format. It
276           is, in any case, preferable to upgrade the repositories manually
277           using opam admin upgrade [--mirror URL] when possible.
278
279       --no-self-upgrade
280           Opam will replace itself with a newer binary found at OPAMROOT/opam
281           if present. This disables this behaviour.
282
283       -q, --quiet
284           Disables --verbose.
285
286       --root=ROOT
287           Use ROOT as the current root path. This is equivalent to setting
288           $OPAMROOT to ROOT.
289
290       --safe, --readonly
291           Make sure nothing will be automatically updated or rewritten.
292           Useful for calling from completion scripts, for example. Will fail
293           whenever such an operation is needed ; also avoids waiting for
294           locks, skips interactive questions and overrides the $OPAMDEBUG
295           variable. This is equivalent to set environment variable $OPAMSAFE.
296
297       --solver=CMD
298           Specify the CUDF solver to use for resolving package installation
299           problems. This is either a predefined solver (this version of opam
300           supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
301           aspcud-old, packup), or a custom command that should contain the
302           variables %{input}%, %{output}%, %{criteria}%, and optionally
303           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
304
305       --strict
306           Fail whenever an error is found in a package definition or a
307           configuration file. The default is to continue silently if
308           possible.
309
310       --switch=SWITCH
311           Use SWITCH as the current compiler switch. This is equivalent to
312           setting $OPAMSWITCH to SWITCH.
313
314       --use-internal-solver
315           Disable any external solver, and use the built-in one (this
316           requires that opam has been compiled with a built-in solver). This
317           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
318
319       -v, --verbose
320           Be more verbose. One -v shows all package commands, repeat to also
321           display commands called internally (e.g. tar, curl, patch etc.)
322           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
323
324       --version
325           Show version information.
326
327       -w, --working-dir
328           Whenever updating packages that are bound to a local,
329           version-controlled directory, update to the current working state
330           of their source instead of the last committed state, or the ref
331           they are pointing to. This only affects packages explicitly listed
332           on the command-line.It can also be set with $OPAMWORKINGDIR.
333
334       -y, --yes
335           Answer yes to all yes/no questions without prompting. This is
336           equivalent to setting $OPAMYES to "true".
337

ENVIRONMENT VARIABLES

339       Opam makes use of the environment variables listed here. Boolean
340       variables should be set to "0", "no", "false" or the empty string to
341       disable, "1", "yes" or "true" to enable.
342
343       OPAMALLPARENS surround all filters with parenthesis
344
345       OPAMAUTOREMOVE see remove option `--auto-remove`
346
347       OPAMBESTEFFORT see option `--best-effort`
348
349       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
350       the criteria when the `--best-effort` option is set, and is expected to
351       maximise the `opam-query` property in the solution
352
353       OPAMCOLOR, when set to always or never, sets a default value for the
354       --color option.
355
356       OPAMCRITERIA specifies user preferences for dependency solving. The
357       default value depends on the solver version, use `config report` to
358       know the current setting. See also option --criteria
359
360       OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
361
362       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
363       for more options.
364
365       OPAMDEBUG see options `--debug' and `--debug-level'.
366
367       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
368
369       OPAMDRYRUN see option `--dry-run`
370
371       OPAMEDITOR sets the editor to use for opam file editing, overrides
372       $EDITOR and $VISUAL
373
374       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
375       fails. 0 to print all.
376
377       OPAMEXTERNALSOLVER see option `--solver'.
378
379       OPAMFAKE see option `--fake`
380
381       OPAMFETCH specifies how to download files: either `wget', `curl' or a
382       custom command where variables %{url}%, %{out}%, %{retry}%,
383       %{compress}% and %{checksum}% will be replaced. Overrides the
384       'download-command' value from the main config file.
385
386       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
387
388       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
389
390       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
391
392       OPAMJOBS sets the maximum number of parallel workers to run.
393
394       OPAMJSON log json output to the given file (use character `%' to index
395       the files)
396
397       OPAMLOCKED see install option `--locked`
398
399       OPAMLOGS logdir sets log directory, default is a temporary directory in
400       /tmp
401
402       OPAMMAKECMD set the system make command to use
403
404       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
405       in an earlier format to the current one, on 'update' or 'init'.
406
407       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
408       some backups. This skips some finalisers and may also help to get more
409       reliable backtraces
410
411       OPAMLOCKRETRIES sets the number of tries after which opam gives up
412       acquiring its lock and fails. <= 0 means infinite wait.
413
414       OPAMMERGEOUT merge process outputs, stderr on stdout
415
416       OPAMNO answer no to any question asked.
417
418       OPAMNOASPCUD Deprecated.
419
420       OPAMNOCHECKSUMS enables option --no-checksums when available.
421
422       OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
423
424       OPAMPINKINDAUTO sets whether version control systems should be detected
425       when pinning to a local path. Enabled by default since 1.3.0.
426
427       OPAMPRECISETRACKING fine grain tracking of directories
428
429       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
430       available (e.g. for `opam install`).
431
432       OPAMRETRES sets the number of tries before failing downloads.
433
434       OPAMROOT see option `--root'. This is automatically set by `opam env
435       --root=DIR --set-root'.
436
437       OPAMROOTISOK don't complain when running as root.
438
439       OPAMSAFE see option `--safe'
440
441       OPAMSHOW see option `--show`
442
443       OPAMSKIPUPDATE see option `--skip-updates`
444
445       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
446       compatibility testing only.
447
448       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
449       60.0, set to 0 for unlimited. Note that all solvers may not support
450       this option.
451
452       OPAMSTATUSLINE display a dynamic status line showing what's currently
453       going on on the terminal. (one of one of `always', `never' or `auto')
454
455       OPAMSTATS display stats at the end of command
456
457       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
458
459       OPAMSWITCH see option `--switch'. Automatically set by `opam env
460       --switch=SWITCH --set-switch'.
461
462       OPAMUNLOCKBASE see install option `--unlock-base`
463
464       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
465       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
466       are set. See also option --criteria
467
468       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
469
470       OPAMUSEOPENSSL force openssl use for hash computing
471
472       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
473       or `auto'). By default `auto', which is determined from the locale).
474
475       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
476       Implies OPAMUTF8. This is set by default on OSX only.
477
478       OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
479       an opam repository update
480
481       OPAMVAR_var overrides the contents of the variable var when
482       substituting `%{var}%` strings in `opam` files.
483
484       OPAMVAR_package_var overrides the contents of the variable package:var
485       when substituting `%{package:var}%` strings in `opam` files.
486
487       OPAMVERBOSE see option `--verbose'.
488
489       OPAMWORKINGDIR see option `--working-dir`
490
491       OPAMYES see option `--yes'.
492

EXIT STATUS

494       As an exception to the following, the `exec' command returns 127 if the
495       command was not found or couldn't be executed, and the command's exit
496       value otherwise.
497
498       0   Success, or true for boolean queries.
499
500       1   False. Returned when a boolean return value is expected, e.g. when
501           running with --check, or for queries like opam lint.
502
503       2   Bad command-line arguments, or command-line arguments pointing to
504           an invalid context (e.g. file not following the expected format).
505
506       5   Not found. You requested something (package, version, repository,
507           etc.) that couldn't be found.
508
509       10  Aborted. The operation required confirmation, which wasn't given.
510
511       15  Could not acquire the locks required for the operation.
512
513       20  There is no solution to the user request. This can be caused by
514           asking to install two incompatible packages, for example.
515
516       30  Error in package definition, or other metadata files. Using
517           --strict raises this error more often.
518
519       31  Package script error. Some package operations were unsuccessful.
520           This may be an error in the packages or an incompatibility with
521           your system. This can be a partial error.
522
523       40  Sync error. Could not fetch some remotes from the network. This can
524           be a partial error.
525
526       50  Configuration error. Opam or system configuration doesn't allow
527           operation, and needs fixing.
528
529       60  Solver failure. The solver failed to return a sound answer. It can
530           be due to a broken external solver, or an error in solver
531           configuration.
532
533       99  Internal error. Something went wrong, likely due to a bug in opam
534           itself.
535
536       130 User interrupt. SIGINT was received, generally due to the user
537           pressing Ctrl-C.
538

FURTHER DOCUMENTATION

540       See https://opam.ocaml.org/doc.
541

AUTHORS

543       Vincent Bernardoff <vb@luminar.eu.org>
544       Raja Boujbel <raja.boujbel@ocamlpro.com>
545       Roberto Di Cosmo <roberto@dicosmo.org>
546       Thomas Gazagnaire <thomas@gazagnaire.org>
547       Louis Gesbert <louis.gesbert@ocamlpro.com>
548       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
549       Anil Madhavapeddy <anil@recoil.org>
550       Guillem Rieu <guillem.rieu@ocamlpro.com>
551       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
552       Frederic Tuong <tuong@users.gforge.inria.fr>
553

BUGS

555       Check bug reports at https://github.com/ocaml/opam/issues.
556
557
558
559Opam 2.0.4                                                        OPAM-INIT(1)
Impressum