1opam-repository(1) Opam Manual opam-repository(1)
2
6 opam-repository - Manage opam repositories.
7
9 opam repository [OPTION]... [COMMAND] [ARG]...
10
12 This command is used to manage package repositories. Repositories can
13 be registered through subcommands add, remove and set-url, and are
14 updated from their URLs using opam update. Their names are global for
15 all switches, and each switch has its own selection of repositories
16 where it gets package definitions from.
17 Main commands add, remove and set-repos act only on the current switch,
19 unless differently specified using options explained in SCOPE
20 SPECIFICATION OPTIONS.
21 Without a subcommand, or with the subcommand list, lists selected
23 repositories, or all configured repositories with --all.
24
26 Without argument, defaults to list.
27 add NAME [ADDRESS] [QUORUM] [FINGERPRINTS]
29 Adds under NAME the repository at address ADDRESS to the list of
30 configured repositories, if not already registered, and sets this
31 repository for use in the current switch (or the specified scope).
32 ADDRESS is required if the repository name is not already
33 registered, and is otherwise an error if different from the
34 registered address. The quorum is a positive integer that
35 determines the validation threshold for signed repositories, with
36 fingerprints the trust anchors for said validation.
37 Note: By default, the repository is only added to the current
39 switch. To add a switch to other repositories, you need to use the
40 --all or --set-default options (see below). If you want to enable a
41 repository only to install of of its switches, you may be looking
42 for opam switch create --repositories=REPOS.
43 remove NAME...
45 Unselects the given repositories so that they will not be used to
46 get package definitions anymore. With --all, makes opam forget
47 about these repositories completely.
48 set-repos NAME...
50 Explicitely selects the list of repositories to look up package
51 definitions from, in the specified priority order (overriding
52 previous selection and ranks), according to the specified scope.
53 set-url NAME ADDRESS [QUORUM] [FINGERPRINTS]
55 Updates the URL and trust anchors associated with a given
56 repository name. Note that if you don't specify [QUORUM] and
57 [FINGERPRINTS], any previous settings will be erased.
58 list
60 Lists the currently selected repositories in priority order from
61 rank 1. With --all, lists all configured repositories and the
62 switches where they are active.
63 priority NAME RANK
65 Synonym to add NAME --rank RANK
66
68 These flags allow to choose what selections are changed by add, remove,
69 set-repos. If no flag in this section is specified the updated
70 selections default to the current switch. Multiple scopes can be
71 selected, e.g. --this-switch --set-default.
72 -a, --all-switches
74 Act on the selections of all configured switches
75 --dont-select
77 Don't update any selections
78 --on-switches=SWITCHES
80 Act on the selections of the given list of switches
81 --set-default
83 Act on the default repository selection that is used for newly
84 created switches
85 --this-switch
87 Act on the selections for the current switch (this is the default)
88
90 -k KIND, --kind=KIND
91 Specify the kind of the repository to be used (one of `http',
92 `local', `git', `darcs' or `hg').
93 --rank=RANK (absent=1)
95 Set the rank of the repository in the list of configured
96 repositories. Package definitions are looked in the repositories in
97 increasing rank order, therefore 1 is the highest priority.
98 Negative ints can be used to select from the lowest priority, -1
99 being last. set-repos can otherwise be used to explicitly set the
100 repository list at once.
101 -s, --short
103 Output raw lists of names, one per line, skipping any details.
104
106 These options are common to all commands.
107 --best-effort
109 Don't fail if all requested packages can't be installed: try to
110 install as many as possible. Note that not all external solvers may
111 support this option (recent versions of aspcud or mccs should).
112 --color=WHEN
114 Colorize the output. WHEN must be one of `always', `never' or
115 `auto'.
116 --criteria=CRITERIA
118 Specify user preferences for dependency solving for this run.
119 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
120 on the supported language, and the external solvers available, see
121 http://opam.ocaml.org/doc/Specifying_Solver_Preferences.html. A
122 general guide to using solver preferences can be found at
123 http://www.dicosmo.org/Articles/usercriteria.pdf.
124 --cudf=FILENAME
126 Debug option: Save the CUDF requests sent to the solver to
127 FILENAME-<n>.cudf.
128 --debug
130 Print debug message to stderr. This is equivalent to setting
131 $OPAMDEBUG to "true".
132 --debug-level=LEVEL
134 Like --debug, but allows specifying the debug level (--debug sets
135 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
136 --git-version
138 Print the git version of opam, if set (i.e. you are using a
139 development version), and exit.
140 --help[=FMT] (default=auto)
142 Show this help in format FMT. The value FMT must be one of `auto',
143 `pager', `groff' or `plain'. With `auto', the format is `pager` or
144 `plain' whenever the TERM env var is `dumb' or undefined.
145 --ignore-pin-depends
147 Ignore extra pins required by packages that get pinned, either
148 manually through opam pin or through opam install DIR. This is
149 equivalent to setting IGNOREPINDEPENDS=true.
150 --json=FILENAME
152 Save the results of the opam run in a computer-readable file. If
153 the filename contains the character `%', it will be replaced by an
154 index that doesn't overwrite an existing file. Similar to setting
155 the $OPAMJSON variable.
156 --no-auto-upgrade
158 When configuring or updating a repository that is written for an
159 earlier opam version (1.2), opam internally converts it to the
160 current format. This disables this behaviour. Note that
161 repositories should define their format version in a 'repo' file at
162 their root, or they will be assumed to be in the older format. It
163 is, in any case, preferable to upgrade the repositories manually
164 using opam admin upgrade [--mirror URL] when possible.
165 --no-self-upgrade
167 Opam will replace itself with a newer binary found at OPAMROOT/opam
168 if present. This disables this behaviour.
169 -q, --quiet
171 Disables --verbose.
172 --root=ROOT
174 Use ROOT as the current root path. This is equivalent to setting
175 $OPAMROOT to ROOT.
176 --safe, --readonly
178 Make sure nothing will be automatically updated or rewritten.
179 Useful for calling from completion scripts, for example. Will fail
180 whenever such an operation is needed ; also avoids waiting for
181 locks, skips interactive questions and overrides the $OPAMDEBUG
182 variable.
183 --solver=CMD
185 Specify the CUDF solver to use for resolving package installation
186 problems. This is either a predefined solver (this version of opam
187 supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
188 aspcud-old, packup), or a custom command that should contain the
189 variables %{input}%, %{output}%, %{criteria}%, and optionally
190 %{timeout}%.
191 --strict
193 Fail whenever an error is found in a package definition or a
194 configuration file. The default is to continue silently if
195 possible.
196 --switch=SWITCH
198 Use SWITCH as the current compiler switch. This is equivalent to
199 setting $OPAMSWITCH to SWITCH.
200 --use-internal-solver, --no-aspcud
202 Disable any external solver, and use the built-in one (this
203 requires that opam has been compiled with a built-in solver).
204 -v, --verbose
206 Be more verbose. One -v shows all package commands, repeat to also
207 display commands called internally (e.g. tar, curl, patch etc.)
208 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
209 --version
211 Show version information.
212 -w, --working-dir
214 Whenever updating packages that are bound to a local,
215 version-controlled directory, update to the current working state
216 of their source instead of the last committed state, or the ref
217 they are pointing to. This only affects packages explicitly listed
218 on the command-line.
219 -y, --yes
221 Answer yes to all yes/no questions without prompting. This is
222 equivalent to setting $OPAMYES to "true".
223
225 Opam makes use of the environment variables listed here. Boolean
226 variables should be set to "0", "no", "false" or the empty string to
227 disable, "1", "yes" or "true" to enable.
228 OPAMCOLOR, when set to always or never, sets a default value for the
230 --color option.
231 OPAMCRITERIA specifies user preferences for dependency solving. The
233 default value depends on the solver version, use `config report` to
234 know the current setting. See also option --criteria
235 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
237 for more options.
238 OPAMDEBUG see options `--debug' and `--debug-level'.
240 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
242 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
244 fails. 0 to print all.
245 OPAMEXTERNALSOLVER see option `--solver'.
247 OPAMFETCH specifies how to download files: either `wget', `curl' or a
249 custom command where variables %{url}%, %{out}%, %{retry}%,
250 %{compress}% and %{checksum}% will be replaced. Overrides the
251 'download-command' value from the main config file.
252 OPAMJOBS sets the maximum number of parallel workers to run.
254 OPAMJSON log json output to the given file (use character `%' to index
256 the files)
257 OPAMLOCK see option `--lock'.
259 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
261 in an earlier format to the current one, on 'update' or 'init'.
262 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
264 some backups. This skips some finalisers and may also help to get more
265 reliable backtraces
266 OPAMLOCKRETRIES sets the number of tries after which OPAM gives up
268 acquiring its lock and fails. <= 0 means infinite wait.
269 OPAMNO answer no to any question asked.
271 OPAMNOASPCUD see option `--no-aspcud'.
273 OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
275 OPAMPINKINDAUTO sets whether version control systems should be detected
277 when pinning to a local path. Enabled by default since 1.3.0.
278 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
280 available (e.g. for `opam install`).
281 OPAMRETRY sets the number of tries before failing downloads.
283 OPAMROOT see option `--root'. This is automatically set by `opam env
285 --root=DIR --set-root'.
286 OPAMROOTISOK don't complain when running as root.
288 OPAMSAFE see option `--safe'
290 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
292 compatibility testing only.
293 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
295 60.0, set to 0 for unlimited. Note that all solvers may not support
296 this option.
297 OPAMSTATUSLINE display a dynamic status line showing what's currently
299 going on on the terminal. (one of one of `always', `never' or `auto')
300 OPAMSWITCH see option `--switch'. Automatically set by `opam env
302 --switch=SWITCH --set-switch'.
303 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
305 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
306 are set. See also option --criteria
307 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
309 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
311 or `auto'). By default `auto', which is determined from the locale).
312 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
314 Implies OPAMUTF8. This is set by default on OSX only.
315 OPAMVAR_var overrides the contents of the variable var when
317 substituting `%{var}%` strings in `opam` files.
318 OPAMVAR_package_var overrides the contents of the variable package:var
320 when substituting `%{package:var}%` strings in `opam` files.
321 OPAMVERBOSE see option `--verbose'.
323 OPAMYES see option `--yes'.
325
327 As an exception to the following, the `exec' command returns 127 if the
328 command was not found or couldn't be executed, and the command's exit
329 value otherwise.
330 0 Success, or true for boolean queries.
332 1 False. Returned when a boolean return value is expected, e.g. when
334 running with --check, or for queries like opam lint.
335 2 Bad command-line arguments, or command-line arguments pointing to
337 an invalid context (e.g. file not following the expected format).
338 5 Not found. You requested something (package, version, repository,
340 etc.) that couldn't be found.
341 10 Aborted. The operation required confirmation, which wasn't given.
343 15 Could not acquire the locks required for the operation.
345 20 There is no solution to the user request. This can be caused by
347 asking to install two incompatible packages, for example.
348 30 Error in package definition, or other metadata files. Using
350 --strict raises this error more often.
351 31 Package script error. Some package operations were unsuccessful.
353 This may be an error in the packages or an incompatibility with
354 your system. This can be a partial error.
355 40 Sync error. Could not fetch some remotes from the network. This can
357 be a partial error.
358 50 Configuration error. Opam or system configuration doesn't allow
360 operation, and needs fixing.
361 60 Solver failure. The solver failed to return a sound answer. It can
363 be due to a broken external solver, or an error in solver
364 configuration.
365 99 Internal error. Something went wrong, likely due to a bug in opam
367 itself.
368 130 User interrupt. SIGINT was received, generally due to the user
370 pressing Ctrl-C.
371
373 See https://opam.ocaml.org/doc.
374
376 Vincent Bernardoff <vb@luminar.eu.org>
377 Raja Boujbel <raja.boujbel@ocamlpro.com>
378 Roberto Di Cosmo <roberto@dicosmo.org>
379 Thomas Gazagnaire <thomas@gazagnaire.org>
380 Louis Gesbert <louis.gesbert@ocamlpro.com>
381 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
382 Anil Madhavapeddy <anil@recoil.org>
383 Guillem Rieu <guillem.rieu@ocamlpro.com>
384 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
385 Frederic Tuong <tuong@users.gforge.inria.fr>
386
388 Check bug reports at https://github.com/ocaml/opam/issues.
389Opam 2.0.1 opam-repository(1)