1opam-init(1) Opam Manual opam-init(1)
2
6 opam-init - Initialize opam state, or set init options.
7
9 opam init [OPTION]... [NAME] [ADDRESS]
10
12 Initialise the opam state, or update opam init options
13 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 The initial repository and defaults can be set through a configuration
22 file found at ~/.opamrc or /etc/opamrc.
23 Additionally, this command allows to customise some aspects of opam's
25 shell integration, when run initially (avoiding the interactive
26 dialog), but also at any later time.
27
29 ADDRESS
30 Address of the initial package repository, when creating a new opam
31 root.
32 NAME (absent=default)
34 Name of the initial repository, when creating a new opam root.
35
37 -a, --auto-setup
38 Automatically do a full setup, including adding a line to your
39 shell init files.
40 --bare
42 Initialise the opam state, but don't setup any compiler switch yet.
43 --bypass-checks
45 Skip checks on required or recommended tools, and assume everything
46 is fine
47 -c PACKAGE, --compiler=PACKAGE
49 Set the compiler to install (when creating an initial switch)
50 --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 --disable-completion
58 Disable shell completion in opam init scripts.
59 --disable-sandboxing
61 Use a default configuration with sandboxing disabled (note that
62 this may be overriden 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 --disable-shell-hook
68 Disable registration of a shell hook in opam init scripts.
69 --dot-profile=FILENAME
71 Name of the configuration file to update instead of ~/.profile or
72 ~/.zshrc based on shell detection.
73 --enable-completion
75 Setup shell completion in opam init scripts, for supported shells.
76 --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 -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 -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 -k KIND, --kind=KIND
92 Specify the kind of the repository to be used (one of `http',
93 `local', `git', `darcs' or `hg').
94 -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 --no-opamrc
101 Don't read `/etc/opamrc' or `~/.opamrc': use the default settings
102 and the files specified through --config only
103 --reinit
105 Re-run the initial checks and setup, according to opamrc, even if
106 this is not a new opam root
107 --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 --shell-setup
114 Automatically setup the user shell configuration for opam, e.g.
115 adding a line to the `~/.profile' file.
116 --show-default-opamrc
118 Print the built-in default configuration to stdout and exit
119
121 Any field from the built-in initial configuration can be overriden
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
127 -b, --keep-build-dir
128 Keep the build directories after compiling packages. This is
129 equivalent to setting $OPAMKEEPBUILDDIR to "true".
130 -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 --dry-run
138 Simulate the command, but don't actually perform any changes.
139 --fake
141 This option registers the actions into the opam database, without
142 actually performing them. WARNING: This option is dangerous and
143 likely to break your opam environment. You probably want
144 `--dry-run'. You've been warned.
145 --ignore-constraints-on[=PACKAGES] (default=)
147 Forces opam to ignore version constraints on all dependencies to
148 the listed packages. This can be used to test compatibility, but
149 expect builds to break when using this. Note that version
150 constraints on optional dependencies and conflicts are unaffected.
151 --inplace-build
153 When compiling a package which has its source bound to a local
154 directory, process the build and install actions directly in that
155 directory, rather than in a clean copy handled by opam. This only
156 affects packages that are explicitly listed on the command-line.
157 This is equivalent to setting $OPAMINPLACEBUILD to "true".
158 --locked[=SUFFIX] (default=locked)
160 In commands that use opam files found from pinned sources, if a
161 variant of the file with an added .SUFFIX extension is found (e.g.
162 foo.opam.locked besides foo.opam), that will be used instead. This
163 is typically useful to offer a more specific set of dependencies
164 and reproduce similar build contexts, hence the name. The opam lock
165 plugin can be used to generate such files, based on the versions of
166 the dependencies currently installed on the host. This is
167 equivalent to setting the $OPAMLOCK environment variable. Note that
168 this option doesn't generally affect already pinned packages.
169 -m MAKE, --make=MAKE
171 Use MAKE as the default 'make' command. Deprecated: use opam config
172 set[-global] make MAKE instead. Has no effect if the make variable
173 is defined.
174 --no-checksums
176 Do not verify the checksum of downloaded archives.This is
177 equivalent to setting $OPAMNOCHECKSUMS to "true".
178 --require-checksums
180 Reject the installation of packages that don't provide a checksum
181 for the upstream archives. This is equivalent to setting
182 $OPAMREQUIRECHECKSUMS to "true".
183 --reuse-build-dir
185 Reuse existing build directories (kept by using --keep-build-dir),
186 instead of compiling from a fresh clone of the source. This can be
187 faster, but also lead to failures if the build systems of the
188 packages don't handle upgrades of dependencies well. This is
189 equivalent to setting $OPAMREUSEBUILDDIR to "true".
190 --show-actions
192 Call the solver and display the actions. Don't perform any changes.
193 --skip-updates
195 When running an install, upgrade or reinstall on source-pinned
196 packages, they are normally updated from their origin first. This
197 flag disables that behaviour and will keep them to their version in
198 cache.
199 -t, --with-test, --build-test
201 Build and run the package unit-tests. This only affects packages
202 listed on the command-line. The --build-test form is deprecated as
203 this also affects installation. This is equivalent to setting
204 $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
205 --unlock-base
207 Allow changes to the packages set as switch base (typically, the
208 main compiler). Use with caution.
209
211 These options are common to all commands.
212 --best-effort
214 Don't fail if all requested packages can't be installed: try to
215 install as many as possible. Note that not all external solvers may
216 support this option (recent versions of aspcud or mccs should).
217 --color=WHEN
219 Colorize the output. WHEN must be one of `always', `never' or
220 `auto'.
221 --criteria=CRITERIA
223 Specify user preferences for dependency solving for this run.
224 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
225 on the supported language, and the external solvers available, see
226 http://opam.ocaml.org/doc/Specifying_Solver_Preferences.html. A
227 general guide to using solver preferences can be found at
228 http://www.dicosmo.org/Articles/usercriteria.pdf.
229 --cudf=FILENAME
231 Debug option: Save the CUDF requests sent to the solver to
232 FILENAME-<n>.cudf.
233 --debug
235 Print debug message to stderr. This is equivalent to setting
236 $OPAMDEBUG to "true".
237 --debug-level=LEVEL
239 Like --debug, but allows specifying the debug level (--debug sets
240 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
241 --git-version
243 Print the git version of opam, if set (i.e. you are using a
244 development version), and exit.
245 --help[=FMT] (default=auto)
247 Show this help in format FMT. The value FMT must be one of `auto',
248 `pager', `groff' or `plain'. With `auto', the format is `pager` or
249 `plain' whenever the TERM env var is `dumb' or undefined.
250 --ignore-pin-depends
252 Ignore extra pins required by packages that get pinned, either
253 manually through opam pin or through opam install DIR. This is
254 equivalent to setting IGNOREPINDEPENDS=true.
255 --json=FILENAME
257 Save the results of the opam run in a computer-readable file. If
258 the filename contains the character `%', it will be replaced by an
259 index that doesn't overwrite an existing file. Similar to setting
260 the $OPAMJSON variable.
261 --no-auto-upgrade
263 When configuring or updating a repository that is written for an
264 earlier opam version (1.2), opam internally converts it to the
265 current format. This disables this behaviour. Note that
266 repositories should define their format version in a 'repo' file at
267 their root, or they will be assumed to be in the older format. It
268 is, in any case, preferable to upgrade the repositories manually
269 using opam admin upgrade [--mirror URL] when possible.
270 --no-self-upgrade
272 Opam will replace itself with a newer binary found at OPAMROOT/opam
273 if present. This disables this behaviour.
274 -q, --quiet
276 Disables --verbose.
277 --root=ROOT
279 Use ROOT as the current root path. This is equivalent to setting
280 $OPAMROOT to ROOT.
281 --safe, --readonly
283 Make sure nothing will be automatically updated or rewritten.
284 Useful for calling from completion scripts, for example. Will fail
285 whenever such an operation is needed ; also avoids waiting for
286 locks, skips interactive questions and overrides the $OPAMDEBUG
287 variable.
288 --solver=CMD
290 Specify the CUDF solver to use for resolving package installation
291 problems. This is either a predefined solver (this version of opam
292 supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
293 aspcud-old, packup), or a custom command that should contain the
294 variables %{input}%, %{output}%, %{criteria}%, and optionally
295 %{timeout}%.
296 --strict
298 Fail whenever an error is found in a package definition or a
299 configuration file. The default is to continue silently if
300 possible.
301 --switch=SWITCH
303 Use SWITCH as the current compiler switch. This is equivalent to
304 setting $OPAMSWITCH to SWITCH.
305 --use-internal-solver, --no-aspcud
307 Disable any external solver, and use the built-in one (this
308 requires that opam has been compiled with a built-in solver).
309 -v, --verbose
311 Be more verbose. One -v shows all package commands, repeat to also
312 display commands called internally (e.g. tar, curl, patch etc.)
313 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
314 --version
316 Show version information.
317 -w, --working-dir
319 Whenever updating packages that are bound to a local,
320 version-controlled directory, update to the current working state
321 of their source instead of the last committed state, or the ref
322 they are pointing to. This only affects packages explicitly listed
323 on the command-line.
324 -y, --yes
326 Answer yes to all yes/no questions without prompting. This is
327 equivalent to setting $OPAMYES to "true".
328
330 Opam makes use of the environment variables listed here. Boolean
331 variables should be set to "0", "no", "false" or the empty string to
332 disable, "1", "yes" or "true" to enable.
333 OPAMCOLOR, when set to always or never, sets a default value for the
335 --color option.
336 OPAMCRITERIA specifies user preferences for dependency solving. The
338 default value depends on the solver version, use `config report` to
339 know the current setting. See also option --criteria
340 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
342 for more options.
343 OPAMDEBUG see options `--debug' and `--debug-level'.
345 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
347 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
349 fails. 0 to print all.
350 OPAMEXTERNALSOLVER see option `--solver'.
352 OPAMFETCH specifies how to download files: either `wget', `curl' or a
354 custom command where variables %{url}%, %{out}%, %{retry}%,
355 %{compress}% and %{checksum}% will be replaced. Overrides the
356 'download-command' value from the main config file.
357 OPAMJOBS sets the maximum number of parallel workers to run.
359 OPAMJSON log json output to the given file (use character `%' to index
361 the files)
362 OPAMLOCK see option `--lock'.
364 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
366 in an earlier format to the current one, on 'update' or 'init'.
367 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
369 some backups. This skips some finalisers and may also help to get more
370 reliable backtraces
371 OPAMLOCKRETRIES sets the number of tries after which OPAM gives up
373 acquiring its lock and fails. <= 0 means infinite wait.
374 OPAMNO answer no to any question asked.
376 OPAMNOASPCUD see option `--no-aspcud'.
378 OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
380 OPAMPINKINDAUTO sets whether version control systems should be detected
382 when pinning to a local path. Enabled by default since 1.3.0.
383 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
385 available (e.g. for `opam install`).
386 OPAMRETRY sets the number of tries before failing downloads.
388 OPAMROOT see option `--root'. This is automatically set by `opam env
390 --root=DIR --set-root'.
391 OPAMROOTISOK don't complain when running as root.
393 OPAMSAFE see option `--safe'
395 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
397 compatibility testing only.
398 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
400 60.0, set to 0 for unlimited. Note that all solvers may not support
401 this option.
402 OPAMSTATUSLINE display a dynamic status line showing what's currently
404 going on on the terminal. (one of one of `always', `never' or `auto')
405 OPAMSWITCH see option `--switch'. Automatically set by `opam env
407 --switch=SWITCH --set-switch'.
408 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
410 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
411 are set. See also option --criteria
412 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
414 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
416 or `auto'). By default `auto', which is determined from the locale).
417 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
419 Implies OPAMUTF8. This is set by default on OSX only.
420 OPAMVAR_var overrides the contents of the variable var when
422 substituting `%{var}%` strings in `opam` files.
423 OPAMVAR_package_var overrides the contents of the variable package:var
425 when substituting `%{package:var}%` strings in `opam` files.
426 OPAMVERBOSE see option `--verbose'.
428 OPAMYES see option `--yes'.
430
432 As an exception to the following, the `exec' command returns 127 if the
433 command was not found or couldn't be executed, and the command's exit
434 value otherwise.
435 0 Success, or true for boolean queries.
437 1 False. Returned when a boolean return value is expected, e.g. when
439 running with --check, or for queries like opam lint.
440 2 Bad command-line arguments, or command-line arguments pointing to
442 an invalid context (e.g. file not following the expected format).
443 5 Not found. You requested something (package, version, repository,
445 etc.) that couldn't be found.
446 10 Aborted. The operation required confirmation, which wasn't given.
448 15 Could not acquire the locks required for the operation.
450 20 There is no solution to the user request. This can be caused by
452 asking to install two incompatible packages, for example.
453 30 Error in package definition, or other metadata files. Using
455 --strict raises this error more often.
456 31 Package script error. Some package operations were unsuccessful.
458 This may be an error in the packages or an incompatibility with
459 your system. This can be a partial error.
460 40 Sync error. Could not fetch some remotes from the network. This can
462 be a partial error.
463 50 Configuration error. Opam or system configuration doesn't allow
465 operation, and needs fixing.
466 60 Solver failure. The solver failed to return a sound answer. It can
468 be due to a broken external solver, or an error in solver
469 configuration.
470 99 Internal error. Something went wrong, likely due to a bug in opam
472 itself.
473 130 User interrupt. SIGINT was received, generally due to the user
475 pressing Ctrl-C.
476
478 See https://opam.ocaml.org/doc.
479
481 Vincent Bernardoff <vb@luminar.eu.org>
482 Raja Boujbel <raja.boujbel@ocamlpro.com>
483 Roberto Di Cosmo <roberto@dicosmo.org>
484 Thomas Gazagnaire <thomas@gazagnaire.org>
485 Louis Gesbert <louis.gesbert@ocamlpro.com>
486 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
487 Anil Madhavapeddy <anil@recoil.org>
489 Guillem Rieu <guillem.rieu@ocamlpro.com>
490 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
491 Frederic Tuong <tuong@users.gforge.inria.fr>
492
494 Check bug reports at https://github.com/ocaml/opam/issues.
495Opam 2.0.1 opam-init(1)