document the existence of external solvers better

[gasche]

Today I tried to point an OPAM user on the caml-list to a documentation of what external solvers are and how to install them. I failed to find such a page. The best I could find is the Specifying Solver Preferences page that seems to have evolved to have a bit of this information (but is too advanced for beginners), and the online solver farm page that takes a different approach.

This issue is related to #1267 , but I don't think it is a duplicate. #1267 is about making external solvers easy to install, but right now there is not even an easy-to-find description of what they are and are useful for, which is orthogonal.

[AltGr]

Well spotted, thanks. This should probably be close to the install / setup guide pages.

[samoht]

Could opam itself warn about missing external solvers?

[dbuenzli]

Could opam itself warn about missing external solvers?

When ?

[samoht]

When the internal solver goes crazy? For instance, after the user press [n] when opam asks him to downgrade all his packages? Or it would be possible to add a hook in the internal solver to print a message when the returned solution is not optimal.

[AltGr]

It does already, but at init.
The idea of adding an heuristics on top of the heuristics to detect if they went wrong is a bit spooky to me, but if it's done e.g. when hitting the timeout, that sounds like a good idea.

[AltGr]

Added http://opam.ocaml.org/doc/Usage.html#Beforeyougetstartedquotexternalsolversquot

[gasche]

Thanks! I would like to send a pull-request for minor clarifications, but I cannot find the git repository for the OPAM documentation (why is it not linked in a clear way on the documentation website? the links I can find point to opam2web which is not really helpful).

[AltGr]

it's simply in the main repo, in doc/pages
(used to be in a github wiki, but that was too constrained)
Indeed, there should be a link to the source on the website.

[AltGr]

Links to the source should now appear in the footer (once the patches propagage) :)

[gasche]

Over at ocsigen/lwt#177 @hcarty had a recommendation for the external solver documentation:

It would be nice to have links to the upstream solver sites and either instructions on how to tell opam to use a particular external solver (command line --solver vs $OPAMEXTERNALSOLVER in the environment). A brief note on why aspcud is recommended over the other would be helpful too as the other two options look much simpler to build from source.

I'm also thinking that maybe we should move it to the "Install" rather than "Usage" page (with maybe a reference in a visible-enough place in Usage).

[hcarty]

Thank you for bringing this over @gasche. The install page seems like a good place if it's effectively a requirement.