Note: we may want to update the opam-switch command to build learn-ocaml dependencies

[erikmd]

Related user(s):

@erikmd

⋅⋅⋅

Related project scope(s):

documentation

Bug description:

The pages

• https://ocaml-sf.org/learn-ocaml/howto-setup-exercise-development-environment.html
• https://ocaml-sf.org/learn-ocaml/howto-deploy-a-learn-ocaml-instance.html

resp. suggest doing

opam switch create . --deps-only --locked

and

opam switch create . --deps-only && opam install opam-installer

Issue 1. as I recently tested on my machine, the switch deps resolution can take a long time, given the ocaml version is not specified (albeit it is kind-of fixed for a given learn-ocaml version, namely 4.12.x)

Issue 2. the fact that these build instructions are in two different places is suboptimal.

Issue 3. is opam-installer really needed ?

Issue 4. some standard developers instructions are missing, e.g. installing merlin, and useful dev config.

⋅⋅⋅

What OS do you use?

GNU/Linux

What OS version/distribution do you use?

Debian

⋅⋅⋅

Additional context:

Issue 1. I suggest the command opam switch create . --package=ocaml-base-compiler.4.12.1 --deps-only --locked, which worked for me™

Issue 2. Maybe put the opam-switch command in only one page (+ back-links)?

Issue 3. I don't know for opam-installer; maybe @AltGr could recall the use cases of this package?

Issue 4. opam install merlin seems natural, but it might cause a whole rebuild after opam install --deps-only --locked.

I tried opam install --solver=aspcud --criteria="-sum(solution,avoid-version),-count(removed),-count(down),-count(changed)" merlin to minimize version changes, and it looked fine. I don't know if there's something simpler to do.

Finally we might recommend (but this is a minor suggestion) in the learn-ocaml dev howto, to define a bash alias such as:

compile() {
  ( cd ~/git/learn-ocaml/ && eval $(opam env) && set -x && opam install --deps-only --locked . \
  && make test && make && make opaminstall \
  && learn-ocaml build serve --repo=demo-repository )
}

See also https://discuss.ocaml.org/t/learn-ocaml-1-0-approaching-call-for-testers/13621 :

opam update
opam source learn-ocaml --dev --dir=learn-ocaml-beta && \
  cd learn-ocaml-beta && \
  opam switch create . --locked && \
  export OPAMSWITCH=$PWD && \
  eval $(opam env)
learn-ocaml build serve --repo=REPOSITORY

[AltGr]

• Issue 1 --locked in fact specifies the exact OCaml version, so that should solve the issue (although it's not explicit about the variant, i.e. ocaml-system, ocaml-base-compiler or variants ; but we may not want to be specific about these). More recent opam version should also be better at this.

• Issue 3 seems to be a leftover, since now dune install is used instead (which is pretty bad practice in general but well, there is no good alternative and here is not the place to rant). grep returns nothing, in any case.

• Issue 4 hm I am not sure everyone has their tools of choice and this may not be the best place to provide "yet another ocaml/opam startup guide".
  however, opam>=2.2.0~alpha provides a way for packages to specify "preferred development tools" that can be added to depends with the filter {with-dev-setup}; then adding --with-dev-setup to the opam install command will pick them directly (not sure merlin really fits in there, specially since it needs additional editor setup to be useful, but this makes full sense when e.g. you require contributions to follow some ocamlformat formatting: that becomes a dependency for developers although it's not strictly speaking one of the project).

  opam install merlin seems natural, but it might cause a whole rebuild after opam install --deps-only --locked.

  A (maybe simpler ?) solution could be to use opam pin on the packages that shouldn't be upgraded. A fundamental issue is that you break the whole locked thing if you upgrade anything afterwards 😬. Another workaround would be to respecify the initial target to enforce it: opam install --locked . merlin (but that should be tested on earlier opam versions)