Up and running with OCaml #1165

johnwhitington · 2020-09-17T17:46:14Z

This is a first crack at my proposal from ocaml/ocaml.org#1137

Please let me have any comments in the next couple of weeks or so, and I will polish it up (and test all the instructions from scratch on all platforms) so it is suitable for merging.

The aim is to have an uncontroversial, simple, set of instructions for getting up and running with OCaml which works on all platforms.

I am interested both in comments about scope, and about the actual contents.

cc @gasche @avsm

johnwhitington · 2020-09-17T18:26:46Z

Oh, I should say that this is intended to be good enough, before merging, to be the page loaded when someone clicks `Install OCaml' on the front page. So please read with that in mind.

gasche

Thanks! I left a couple minor comments.

site/learn/tutorials/up_and_running.md

gasche · 2020-09-17T19:16:18Z

site/learn/tutorials/up_and_running.md

+sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)
+```
+
+(If this method does not suit, please see [How to install


It's a minor point, but "does not suit" reads slightly strange to me (I would expect "suit you", but rather use another wording); maybe it's more common in regional versions of English I'm less familiar with.

I changed it to "suit you", which is probably better. What I was getting at, I think, with the choice of verb, is that some people don't like to curl and execute random scripts from the internet.

(The disadvantage of being a native English speaker, is that I have no way of explaining why the verb suit doesn't always need an object. The closest I can think of is that "fit" doesn't either e.g. "If the last piece fits you have finished.")

gasche · 2020-09-17T19:20:26Z

site/learn/tutorials/up_and_running.md

+
+##Editor support for OCaml
+
+**For Vim and Emacs**, install the merlin system using OPAM:


a link to the Merlin homepage would be nice (users can follow it if they want to know what kind of feature Merlin provides)

Done. (I also note that there are LSP implementations for vim and emacs on the web, but I assume plain merlin is still the easiest way for these editors...)

gasche · 2020-09-17T19:23:03Z

site/learn/tutorials/up_and_running.md

+the installation procedure will print instructions on how to link merlin with
+your editor. 
+
+For **Visual Studio Code**, the OCaml language server can by installed by OPAM.


Maybe something like "For Visual Studio Code and other LSP-supporting editors"? I have the impression that this description applies to most editors that recognize themselves as IDEs these days (of course the specific plugin will vary, and in some cases may not exist), and I would regret that people using another IDE would feel left out when the answer is most likely to be the same. (But then maybe those people don't really exist for OCaml anymore, and it's better to only talk about things we know for sure we support well.)

gasche · 2020-09-23T08:27:56Z

site/learn/tutorials/up_and_running.md

+
+*Table of contents*
+
+#Up and Running with OCaml


Minor comment. The rendering of your headings by Github is off (see https://github.com/johnwhitington/ocaml.org/blob/up-and-running/site/learn/tutorials/up_and_running.md), I think you should use a space before the title: ## Up rather than ##Up.

Fixed. Thanks.

johnwhitington · 2020-09-23T12:59:21Z

Ok, I'm finished for now. Let's get this merged, if everyone agrees, and we can see how beginners cope with it.

Octachron · 2020-09-23T13:20:47Z

site/learn/tutorials/up_and_running.md

+```
+
+(If this method does not suit you, please see [How to install
+OPAM](opam.ocaml.org/doc/install.html))


One issue that I have with that formulation is that the curl based installation would by my option of last resort on a linux distribution with outdated version of opam. Maybe it would make sense to inverse the two options: first start with the system-managed option, before moving to the user-managed script option.

For this section, I copied the instructions from the official guide: https://opam.ocaml.org/doc/Install.html

I can add a mention that any existing version should be removed first, if that would suffice?

I have the same issue with the opam page. In particular, the fact that the recommended installation path appears only in the third section is problematic. The recommended path should appear first to let readers skip the non-recommended options if they can. And removing any existing version is not the issue at hand?

Ah, I did not spot the phrase "This is generally the recommended way, when available and up-to-date" on the OPAM page. I will have a think about this.

Octachron · 2020-09-23T13:23:12Z

site/learn/tutorials/up_and_running.md

+```
+
+The installation procedure will print instructions on how to link Merlin with
+your editor.


I think it would be worth it to mention opam user-setup rather than refer the reader to some unspecified documentation.

The documentation is what opam install merlin prints out - I don't paste it into the tutorial, but I'm not sure how it's unspecified?

Is user-setup up to date? It looks not to have been updated in a while. Is it widely used? Do the merlin developers recommend it? I'm looking for consensus when writing this tutorial, above all.

Do you suggest just mentioning it, or making it the default instruction?

The reader cannot infer how involved is the remaining installation procedure with just a "Follow the printed instructions". And user-setup, it is still one of the option cited by merlin post-install and is mentioned in the merlin quick setup section. Moreover, it has the advantage to be editor independent which means that we can give the reader the information that the quick setup can be as quick as

opam user-setup install

Thanks. What's the Windows status?

I'm happy to deal with this in a followup PR, as I suspect noone is entirely sure what the opam user-setup status is. CCing @emillon who has been investigating the Windows support of Platform tools recently.

opam user-setup seems to start on windows, but displays some error messages and tries to detect ocamltop, emacs, vim, gedit and sublime3. I don't think it does something windows specific at the moment.

johnwhitington · 2020-09-24T13:05:31Z

I ran user-setup on my own computer (OS X, nothing special), and then tried to edit a file. I got:

"~/repos/cpdf-source/cpdfcommand.ml" 4665L, 166889C
Error detected while processing /Users/john/.opam/4.11.1/share/merlin/vim/autoload/merlin.vim:
line   86:
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/Users/john/.opam/4.11.1/share/merlin/vim/autoload/merlin.py", line 1, in <module>
    import subprocess
  File "/usr/local/Cellar/python@2/2.7.16_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/subprocess.py", line 72, in
 <module>
    import select
ImportError: dlopen(/usr/local/Cellar/python@2/2.7.16_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload/sel
ect.so, 0x0002): code signature in (/usr/local/Cellar/python@2/2.7.16_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7
/lib-dynload/select.so) not valid for use in process: mapped file has no cdhash, completely unsigned? Code has to be at least 
ad-hoc signed.
Error detected while processing function merlin#Register[136]..merlin#LoadProject:
line    2:
Traceback (most recent call last):
  File "<string>", line 1, in <module>
NameError: name 'merlin' is not defined
Press ENTER or type command to continue

I don't see how we can recommend it in this state...

(Edit: merlin works fine on my computer otherwise...)

johnwhitington · 2020-09-24T13:08:34Z

Ok, I've finished today's changes. Ready for further review whenever.

gasche · 2020-09-24T13:09:49Z

I don't see how we can recommend it in this state...

Fair point! (I hope you will report the issue on the appropriate development repository.)

johnwhitington · 2020-09-24T13:13:51Z

I don't see how we can recommend it in this state...

Fair point! (I hope you will report the issue on the appropriate development repository.)

Done: ocaml-opam/opam-user-setup#50

gasche · 2020-10-27T16:56:10Z

This looks like a nice proposal for a tutorial that would already improve the ocaml.org experience for beginners. (I may be useful to link to this tutorial from the Install page, but that could maybe be discussed independently?) I would be happy to see this discussed in its current, rather-final form, but it is not clear who would possibly make merge decisions or request changes.

(cc @agarwal, @avsm, @Chris00; are there other people with commit rights that I should consider pinging, or an alias to use in this situation?)

Note: (everyone cc-ed in this thread knows this, but to give more context) I'm part of the OCaml Foundation who funded this work from @johnwhitington. I'm not trying to influence people to merge it (I think it should be discussed on its own merits of course), only to influence people to give feedback and hopefully make decisions :-)

avsm · 2020-11-06T19:57:13Z

Many thanks, this very close to mergeable. I've pushed a snapshot of this to the staging branch and it can be viewed live at https://staging.ocaml.org/learn/tutorials/up_and_running.html

avsm · 2020-11-06T19:58:06Z

site/learn/tutorials/up_and_running.md

+
+### For Linux and MacOS
+
+We will install OCaml using OPAM, the OCaml package manager.  OPAM will also be


Suggested change

We will install OCaml using OPAM, the OCaml package manager. OPAM will also be

We will install OCaml using opam, the OCaml package manager. opam will also be

opam should be lower case

avsm · 2020-11-06T19:58:35Z

site/learn/tutorials/up_and_running.md

+
+```
+# Homebrew
+brew install gpatch


Why is this gpatch step necessary? Just brew install opam should be sufficient.

I took the MacOS instructions from here:

https://opam.ocaml.org/doc/Install.html

So if they are out of date, we need to fix them there too.

I have asked for an update here:

ocaml/opam#3433

Homebrew/homebrew-core#64301

Ok, I have removed the instruction on the assumption your patch will be approved.

PR for the opam install page:

ocaml/opam#4421

avsm · 2020-11-06T19:59:03Z

site/learn/tutorials/up_and_running.md

+The OCaml toplevel, version 4.11.1
+```
+
+**For either Linux or MacOS** as an alternative, a binary distribution of OPAM is


Suggested change

**For either Linux or MacOS** as an alternative, a binary distribution of OPAM is

**For either Linux or macOS** as an alternative, a binary distribution of opam is

avsm · 2020-11-06T19:59:57Z

site/learn/tutorials/up_and_running.md

+Protocol, the OCaml language server can by installed with OPAM:
+
+```
+$ opam pin add ocaml-lsp-server https://github.com/ocaml/ocaml-lsp.git


This pin is no longer necessary, as lsp has been released into opam

avsm · 2020-11-06T20:01:36Z

@johnwhitington with apologies for the delay, I've left some fairly minor comments. If you don't have time to address them, I can just fix them and merge in one go so this isn't further delayed.

johnwhitington · 2020-11-07T13:32:36Z

I have made the changes, with the exception of the gpatch one, upon which I have made further enquiries (see above).

This can be merged now, although I presume there will be a conflict between this and my other pull request (rearranging tutorials #1179 ), since this pull request adds an entry to the tutorial contents page. Perhaps it is best to merge #1179 first, then I can fix the conflicts in this one?

This PR reflects three lessons learned when writing the new ocaml.org "Up and Running" guide ocaml/ocaml.org#1165 : 1) Having the binary distribution at the top of this page, when it is not the recommended installation mechanism for most users, is confusing. 2) Brew will shortly be updated Homebrew/homebrew-core#64301 to make opam depend on gpatch, thus removing this instruction from the OS X instructions. 3) OSX is now spelled macOS

avsm · 2020-11-08T13:08:33Z

If you could merge this to master, that will also pick up a working CI.

johnwhitington · 2020-11-08T13:48:29Z

I executed:

git checkout master
git merge up-and-running
git push

It seemed to do something, but nothing has changed on this page. Should it have done?

avsm · 2020-11-08T17:07:25Z

You'll need to pull from the master branch of ocaml.org itself. Try:

git remote add upstream git://github.com/ocaml/ocaml.org
git checkout master
git pull upstream master
git checkout up-and-running
git merge master
git push

There are ways to make the above shorter, but not worth the git risk/reward :-)

johnwhitington · 2020-11-08T17:14:14Z

Thanks.

avsm · 2020-11-09T08:24:12Z

Thanks again!

gasche · 2020-11-09T08:29:15Z

... and thanks @avsm for the review work and decision-making. It looks like the implicit answer to my question above is "Anil is going to find extra hours in the day to look at these PRs", which is great in the short term, but please let us know if there is something more scalable we could do in the medium term. (I'm not volunteering to become a reviewer for ocaml.org, but I could think of volunteering other people if that sounded useful.)

avsm · 2020-11-09T09:00:04Z

I'll run it for the next six months at least to get the momentum going again: @patricoferris @kanishka-work and @ILeandersson have all offered to help with modernising the website so @agarwal and @GemmaG and I are mentoring them into it and working on making the site more contributor friendly. So please do keep the content updates coming :-)

This PR reflects three lessons learned when writing the new ocaml.org "Up and Running" guide ocaml/ocaml.org#1165 : 1) Pending: having the binary distribution at the top of this page, when it is not the recommended installation mechanism for most users, is confusing. 2) Brew will shortly be updated Homebrew/homebrew-core#64301 to make opam depend on gpatch, thus removing this instruction from the OS X instructions. 3) OSX is now spelled macOS Co-authored-by: Etienne Millon <etienne.millon@gmail.com>

johnwhitington added 6 commits September 3, 2020 16:05

Introduce new (blank) up-and-running tutorial

671d231

Template for content

32a1d31

First few sections ready, editor support to come

0f6030c

First draft

3f008b0

more

6e61dd6

Merge branch 'master' into up-and-running

dba99aa

gasche reviewed Sep 17, 2020

View reviewed changes

Small fixes

68dbdb9

gasche reviewed Sep 23, 2020

View reviewed changes

johnwhitington added 2 commits September 23, 2020 12:03

Fix headings

02597c2

Polish, add more Windows editor info, re-jig

61475c1

Octachron reviewed Sep 23, 2020

View reviewed changes

Fix OPAM instructions per review comments

adbe914

avsm reviewed Nov 6, 2020

View reviewed changes

opam case and remove opam pin

ff384c4

MacOS -> macOS

944d524

opam now depends on gpatch in brew, so don't mention.

27edb03

johnwhitington mentioned this pull request Nov 7, 2020

~Reorder options,~ fix brew instructions, spelling ocaml/opam#4421

Merged

Merge branch 'master' of https://github.com/ocaml/ocaml.org

23cd15d

avsm merged commit 134fb05 into ocaml:master Nov 9, 2020


		##Editor support for OCaml

		For Vim and Emacs, install the merlin system using OPAM:


		### For Linux and MacOS

		We will install OCaml using OPAM, the OCaml package manager. OPAM will also be

	For either Linux or MacOS as an alternative, a binary distribution of OPAM is
	For either Linux or macOS as an alternative, a binary distribution of opam is

Up and running with OCaml #1165

Up and running with OCaml #1165

Conversation

johnwhitington commented Sep 17, 2020

johnwhitington commented Sep 17, 2020

gasche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnwhitington Sep 18, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnwhitington commented Sep 23, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnwhitington commented Sep 24, 2020 • edited Loading

johnwhitington commented Sep 24, 2020

gasche commented Sep 24, 2020

johnwhitington commented Sep 24, 2020

gasche commented Oct 27, 2020

avsm commented Nov 6, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avsm commented Nov 6, 2020

johnwhitington commented Nov 7, 2020

avsm commented Nov 8, 2020

johnwhitington commented Nov 8, 2020

avsm commented Nov 8, 2020

johnwhitington commented Nov 8, 2020

avsm commented Nov 9, 2020

gasche commented Nov 9, 2020

avsm commented Nov 9, 2020

johnwhitington Sep 18, 2020 •

edited

Loading

johnwhitington commented Sep 24, 2020 •

edited

Loading