Skip to content

Document how opam chooses the default compiler during opam init and opam switch create #6778

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kit-ty-kate wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document how opam chooses the default compiler during opam init and opam switch create #6778

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions doc/pages/FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,3 +437,31 @@ We don't recommend using it in day-to-day use of opam in the shell, because
you'll be typing more and you won't get to notice exciting new features! If the
behaviour of a command or option is altered, and you write something which in no
longer valid, opam will try to tell you what the new command should look like.

---

#### 🐫 How does `opam init` and `opam switch create <version>` know which compiler package to choose?

Since opam 2.4, `opam init` will choose `ocaml-base-compiler` as default
compiler for the `default` switch, and let the solver choose the latest
version. Of course this default can always be changed using `--compiler`
or by skipping the creation of the `default` switch all-together with
`--bare`.
Comment on lines +445 to +449
Copy link
Member

@dra27 dra27 Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Since opam 2.4, `opam init` will choose `ocaml-base-compiler` as default
compiler for the `default` switch, and let the solver choose the latest
version. Of course this default can always be changed using `--compiler`
or by skipping the creation of the `default` switch all-together with
`--bare`.
Since opam 2.4, `opam init` will select `ocaml-base-compiler` as the default
compiler package for the `default` switch, and let the solver choose the latest
version. This can always be changed using `--compiler` or by skipping the
creation of the `default` switch altogether with `--bare`.


For example if you would rather use the OCaml compiler that you have
installed by other means, you can use the `ocaml-system` package as follows:
Copy link
Member

@dra27 dra27 Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
installed by other means, you can use the `ocaml-system` package as follows:
installed outside opam, you can use the `ocaml-system` package as follows:

?

`opam init --compiler=ocaml-system`. Be careful though, system-wide compilers
can be setup in a way that the default opam-repository doesn't expect,
so failures may occur. Thus this option should only be used if you know
Copy link
Member

@dra27 dra27 Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
so failures may occur. Thus this option should only be used if you know
so failures may occur. We recommend this option should only be used if you know

?

what you're doing.
Comment on lines +451 to +456
Copy link
Member

@dra27 dra27 Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example if you would rather use the OCaml compiler that you have
installed by other means, you can use the `ocaml-system` package as follows:
`opam init --compiler=ocaml-system`. Be careful though, system-wide compilers
can be setup in a way that the default opam-repository doesn't expect,
so failures may occur. Thus this option should only be used if you know
what you're doing.
For example, if you would rather use the OCaml compiler that you have
installed by other means, you can use the `ocaml-system` package as follows:
`opam init --compiler=ocaml-system`. Be careful, though; system-wide compilers
can be set-up in a way that the default opam-repository doesn't expect,
so failures may occur. Thus this option should only be used if you know
what you're doing.


`opam switch create <version>` on the other hand, works slightly differently.
Since the only unknown is: which package is going to be used.
Comment on lines +458 to +459
Copy link
Member

@dra27 dra27 Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`opam switch create <version>` on the other hand, works slightly differently.
Since the only unknown is: which package is going to be used.
`opam switch create <version>` on the other hand, works slightly differently,
since the only unknown is exactly which package is going to be used.

Opam decides this by looking at all the packages that have been tagged as
`compiler`, filter which ones have the right version, and then let the solver
decide. For example calling `opam switch create 5.4 5.4.0` will create a
switch named `5.4` and look for compiler packages with versions `5.4.0` which
by default, with [opam-repository](https://github.com/ocaml/opam-repository/),
will get back with `ocaml-base-compiler.5.4.0` and `ocaml-system.5.4.0`.
Since 2025, `ocaml-system` is tagged as `avoid-version` so the solver will
choose `ocaml-base-compiler.5.4.0`.
Comment on lines +460 to +467
Copy link
Member

@dra27 dra27 Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Opam decides this by looking at all the packages that have been tagged as
`compiler`, filter which ones have the right version, and then let the solver
decide. For example calling `opam switch create 5.4 5.4.0` will create a
switch named `5.4` and look for compiler packages with versions `5.4.0` which
by default, with [opam-repository](https://github.com/ocaml/opam-repository/),
will get back with `ocaml-base-compiler.5.4.0` and `ocaml-system.5.4.0`.
Since 2025, `ocaml-system` is tagged as `avoid-version` so the solver will
choose `ocaml-base-compiler.5.4.0`.
Opam decides this by finding all packages which have the given and which
that have been flagged as `compiler` and then presents just these packages
to the solver. For example calling `opam switch create 5.4 5.4.0` will create a
switch named `5.4` and look for compiler packages with versions `5.4.0` which
by default, with [opam-repository](https://github.com/ocaml/opam-repository/),
will be with `ocaml-base-compiler.5.4.0`, `ocaml-system.5.4.0` and
`ocaml-variants.5.4.0+options`. `ocaml-system.5.4.0` is flagged as `avoid-version`,
so the solver will choose `ocaml-base-compiler.5.4.0`.

(although I can't remember for certain why ocaml-base-compiler.5.4.0 is guaranteed to be selected, given that it actually has more dependencies than ocaml-variants.5.4.0+options)

1 change: 1 addition & 0 deletions master_changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,7 @@ users)
## Github Actions

## Doc
* Document how opam chooses the default compiler during `opam init` and `opam switch create` [#6778 @kit-ty-kate - fix #6407]

## Security fixes

Expand Down