Track docs

[TheRealOwenRees]

First draft of track docs update

• updated links to contributing Readme.
• updated installation instrcutions to follow the Readme, but staying in the style of the original track installation docs
• Added a section for intsalling the OCaml LSP and a VS Code extension

[kahgoh]

Cloning the repo and building doesn't belong here. This INSTALLATION.md is presented to the students on the Installing OCaml locally page when they start the track. It is intended for the students, not the contributors. Students shouldn't need to do this. Contributors would most likely be looking at the README, so its to fine to leave it there.

[TheRealOwenRees]

Ah yes I got ahead of myself. The dependencies that they should install should be the ones in the Makefile still though I assume?

[kahgoh]

No, I don't think so. For example, they shouldn't need the yojson for parsing JSON - none of the exercises require JSON processing. I think the original list of base core_kernel ounit qcheck are the only ones that students need for the exercises.

[TheRealOwenRees]

You are correct. I will resubmit that

[kahgoh]

I've just managed to try out your instructions for setting up OCaml and got it working in a Debian Bookworm environment 😀. Admittedly, I used opam switch create exercism 5.3.0 instead of 5.1.1, but it still seems to work.

It's getting late here, but I'll come back to review the changes.

[TheRealOwenRees]

I've just managed to try out your instructions for setting up OCaml and got it working in a Debian Bookworm environment 😀. Admittedly, I used opam switch create exercism 5.3.0 instead of 5.1.1, but it still seems to work.

It's getting late here, but I'll come back to review the changes.

That's great. It should work for all versions >= 5.1.0. My default environment is 5.3.0 and I tested that with all versions In between.

[kahgoh]

I've just gone through and reviewed the changes. Comments and suggestions below 👇🏻

[kahgoh]

Is opam a script? I wasn't really sure ... alternatively, we could leave out the word script like this:

Suggested change

	Run the script to install the dependencies required by this track:
	Run the following to install the dependencies required by this track:

[kahgoh]

Since the items here mainly relate to VS Code, we could mention it in the heading. For example:

Suggested change

	5. Install IDE related tools (optional)
	The following relates to using VS Code as your code editor. Adjust accordingly.
	Install the OCaml language server from [here](https://github.com/ocaml/ocaml-lsp).
	Install the OCaml VS Code extension from [here](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform), or search for `OCaml Platform` by Ocaml Labs.
	5. Install tools in VS Code (optional)
	If you use VS Code:
	- Install the OCaml language server from [here](https://github.com/ocaml/ocaml-lsp).
	- Install the OCaml VS Code extension from the [marketplace](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform), or search for `OCaml Platform` by Ocaml Labs.

[TheRealOwenRees]

Thank you for the comments, I will adjust the text.

I know you said you installed a new envionemtn with the commands I mentioned. Did you try to install a new dev environment with make install_deps with OCaml 5.3.0? And if so, did you get error messages?

[kahgoh]

I know you said you installed a new envionemtn with the commands I mentioned. Did you try to install a new dev environment with make install_deps with OCaml 5.3.0? And if so, did you get error messages?

Thanks for reminding me! I forgot to try that out 😅.

I just tested it and got the same package conflicts as you did:

[ERROR] Package conflict!
  * No agreement on the version of ocaml-base-compiler:
    - (invariant) -> ocaml-base-compiler = 5.3.0
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-base-compiler < 4.14.3~
    You can temporarily relax the switch invariant with `--update-invariant'
  * Incompatible packages:
    - (invariant) -> ocaml-base-compiler = 5.3.0
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      dkml-base-compiler
  * Incompatible packages:
    - (invariant) -> ocaml-base-compiler = 5.3.0
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-variants
  * Missing dependency:
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-variants -> ocaml-beta
    unmet availability conditions: 'enable-ocaml-beta-repository'
  * Missing dependency:
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-variants -> system-msvc
    unmet availability conditions: 'os = "win32"'

[TheRealOwenRees]

I know you said you installed a new envionemtn with the commands I mentioned. Did you try to install a new dev environment with make install_deps with OCaml 5.3.0? And if so, did you get error messages?

Thanks for reminding me! I forgot to try that out 😅.

I just tested it and got the same package conflicts as you did:

[ERROR] Package conflict!
  * No agreement on the version of ocaml-base-compiler:
    - (invariant) -> ocaml-base-compiler = 5.3.0
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-base-compiler < 4.14.3~
    You can temporarily relax the switch invariant with `--update-invariant'
  * Incompatible packages:
    - (invariant) -> ocaml-base-compiler = 5.3.0
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      dkml-base-compiler
  * Incompatible packages:
    - (invariant) -> ocaml-base-compiler = 5.3.0
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-variants
  * Missing dependency:
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-variants -> ocaml-beta
    unmet availability conditions: 'enable-ocaml-beta-repository'
  * Missing dependency:
    - getopts -> lemonade < 0.4.0 -> mixture < 0.2.1 -> ocaml < 5.0.0 ->
      ocaml-variants -> system-msvc
    unmet availability conditions: 'os = "win32"'

Great (well not really that great). At least it means it isn't just me.

This can be fixed by replacing the make install_deps command with

opam install dune ounit qcheck fpath react ppx_deriving ppx_sexp_conv yojson ocp-indent calendar core mustache ezjsonm core_unix

Could you test that your enviroment works with that? This just removes getopts and installs the deps it contained needed to satisify the track environment.

With your approval, perhaps we can change this with a seperate PR? I submitted a fix to review just in case you want to test the branch first.

[kahgoh]

Could you test that your enviroment works with that? This just removes getopts and installs the deps it contained needed to satisify the track environment.

With your approval, perhaps we can change this with a seperate PR? I submitted a fix to review just in case you want to test the branch first.

Yup, I've tested this in the PR #553 and I was able to go right to generate the exercises. It looked ok to me, so I went ahead and merged that one.