Real World OCaml recommendation

[jonahbeckford]

Followups from https://github.com/realworldocaml/book/issues/3657:

• [x] the seamless base and utop experience is complete
• [ ] documentation updated saying that RWO (only the chapters using base) are good reference material for Windows users.
• [ ] general callout in documentation a) for advanced users only to submit patches to RWO for updates to Windows; there is no chance Diskuv is capable of reviewing everything in that book and b) for beginners that Windows support in RWO is "early" adoption

The net effect will be another great source of learning material for Windows OCaml users.

[avsm]

I've got a DKML installation running on my Windows box now, so I'm happy to modify the RWO text whenever you're ready, @jonahbeckford. /cc @yminsky.

[jonahbeckford]

Sigh. I lost my window of time to do the action items in the first quarter. Realistically this won't start until May. It is top of the list though.

[jonahbeckford]

Status Update

Jul 23

• [ ] Problem 1: Backport of https://github.com/ocaml/ocaml/pull/12364 (XDG_CONFIG_HOME/ocaml/init.ml) was made available in DkML 2.0.0. However, that ocaml/ocaml PR does not close the issue for RWO readers because:

  • I do not expect RWO readers to use ocaml when they can use utop
  • As of DkML 2.0.1 base is only accessible to utop, not ocaml

  Recent versions of utop look in a similar place: XDG_CONFIG_HOME/utop/init.ml. However, utop has a bug on Windows and is blocked by https://github.com/ocaml-community/utop/issues/451

• [X] Problem 2: The standard in https://github.com/ocaml/ocaml/pull/12364 and the xdg package is LOCALAPPDATA.

• [ ] Problem 3: I am proposing language in RWO to set the "Encoding" correctly. The commit Install DkML. Set up utop of https://github.com/realworldocaml/book/pull/3669/commits has that proposal.

Jul 7

• @avsm @nojb Almost finished with the implementation of this. Right now, I am doing testing, and am blocked by small but related important issues.

Set up utop

RWO Page: http://dev.realworldocaml.org/install.html

Proposal: Tweak this section to have a ~/.ocamlinit that works for native Windows users.

Problem 1: The OCaml toplevel does not recognize a user-global .ocamlinit file

I uncovered the following (cross-posted to windows channel in Slack):

Looks like the toplevel has a big omission on native Windows. I'm surprised I didn't encounter this before, but in hindsight I rarely use the toplevel (until now). According to https://v2.ocaml.org/manual/toplevel.html :

On start-up (before the first phrase is read), if the file .ocamlinit exists in the current directory, its contents are read as a sequence of OCaml phrases and executed as per the #use directive described in section 14.2. The evaluation outcode for each phrase are not displayed. If the current directory does not contain an .ocamlinit file, the file XDG_CONFIG_HOME/ocaml/init.ml is looked up according to the XDG base directory specification and used instead (on Windows this is skipped). If that file doesn’t exist then an [.ocamlinit] file in the users’ home directory (determined via environment variable HOME) is used if existing.

Because HOME is not defined in native Windows (or worse, it is defined if you use MSYS2 tooling but that definition is almost always the wrong location to use) ... there is no directory to put .ocamlinit except the current directory.

Mitigation (this won't work):

For now in DkML I'll set XDG_CONFIG_HOME to %APPDATA%, but that is not portable to other (future?) native Windows OCaml systems.

Real Mitigation: Needs a ocaml/ocaml compiler patch.

Problem 2: Ambiguous whether APPDATA or LOCALAPPDATA should be home for .ocamlinit

XDG_CONFIG_HOME has been interpreted inconsistently in the OCaml ecosystem:

• Dune uses LOCALAPPDATA in the xdg package. Confer: https://github.com/ocaml/dune/blob/8f7bcffb1f797bf2d240430d1be09be462654857/otherlibs/xdg/xdg.ml#L38-L40

• OCamlPro uses APPDATA in the directories package. Confer: https://github.com/OCamlPro/directories/blob/1cf7211f918fa909e5f77c0dfbb059c74071e99b/src/windows/directories.ml#L36-L37

The difference is that APPDATA is Roaming, which means if you are in a managed corporate (or educational) environment your .ocamlinit will travel with you.

Mitigation: We just need to pick one ... preferably the one that the OCaml compiler team is comfortable with. I've also opened https://github.com/OCamlPro/directories/issues/15 to get some background on why they chose APPDATA.

Problem 3: .ocamlinit can't be created/edited with Notepad

Without some complicated-for-beginner steps, Notepad will create files that are CRLF line terminated in UTF-16 LE encoding.

That gives:

─────────────────────────┬───────────────────────────────────────────────────────────────────┬──────────────────────────                         │ Welcome to utop version %%VERSION%% (using OCaml version 4.14.0)! │                                                   └───────────────────────────────────────────────────────────────────┘
[1mFile ".ocamlinit", line 1, characters 0-2[0m:
1 | ��
    [1;35m^^[0m
[1;35mAlert[0m deprecated: ISO-Latin1 characters in identifiers
[1mFile ".ocamlinit", line 1, characters 2-3[0m:
1 | ��
      [1;31m^[0m
[1;31mError[0m: Illegal character (\r)

Type #utop_help for help about using utop.