From 9d8d4f823926c4ae508aabee9284f4cd26c0f308 Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 28 Jul 2025 15:31:06 +0200 Subject: [PATCH 1/6] track docs first draft --- docs/INSTALLATION.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index bcfa830ecc..3117cc31fc 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -15,25 +15,40 @@ To work on the exercises, you will need these pieces of software: opam switch ``` - Switch to that version. If, for example, the latest version is 4.08.0, you will run: + If you already have a switch for OCaml 5.1, either load that by running `opam switch `, or create a new switch by running: ```bash - opam switch 4.08.0 + opam switch create exercism 5.1.1 ``` -3. Install extended standard libraries and test libraries + The name `exercism` here is optional, but naming your switches is a good practice. - Some exercises use only the OCaml standard library, and some use the - extended libraries by Jane Street called Base and Core\_kernel. +3. Install extended standard libraries and test libraries - The test library is called OUnit, and some exercises additionally use the - QCheck library for property-based tests. + Run the script to install the dependencies required by this track, and test the local installation: ```bash - opam install base core_kernel ounit qcheck + git clone https://github.com/exercism/ocaml.git + cd ocaml + git submodule update --init --recursive + + # see https://github.com/exercism/ocaml/blob/master/.travis/Dockerfile#L12 + # might take a while + make install_deps + + # Run generator tests + make test_generator + + # Execute generator + make generate_exercises + + # Run exercise tests + make test ``` -4. Install and use interactive shell + Some exercises use only the OCaml standard library, and some use the extended libraries by Jane Street called Base and Core_kernel. + +4. Install and use interactive shell (optional) A summary of [Setting up and using `utop`](https://dev.realworldocaml.org/install.html): @@ -48,3 +63,11 @@ To work on the exercises, you will need these pieces of software: #require "base";; open Base ``` + +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. From d943a0eaea4cb1ad2e70609ea431c2aa1f701459 Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 28 Jul 2025 15:32:24 +0200 Subject: [PATCH 2/6] spelling error fix --- README.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index fac10eed57..b8b6580c4d 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,11 @@ notes contain a few details specific to Ocaml. ### Local setup -**Prerequesites** +**Prerequisites** -* OCaml `5.1` -* opam -* make +- OCaml `5.1` +- opam +- make ```sh git clone https://github.com/exercism/ocaml.git @@ -41,12 +41,11 @@ make test
Container setup +**Prerequisites** -**Prerequesites** - -* VSCode -* VSCode Remote Containers extension -* Docker +- VSCode +- VSCode Remote Containers extension +- Docker ```sh git clone https://github.com/exercism/ocaml.git @@ -120,6 +119,6 @@ You should base your tests off this data, in order to provide consistency across If you find this documentation is inaccurate or incomplete, or can be improved in any way, please don't hesitate to raise an [issue](https://github.com/exercism/ocaml/issues) or submit a pull request. - ### OCaml icon + The [OCaml](https://ocaml.org) logo is released under the [Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/) license. From ad65c62d03de7c7a9c90dafd8f8f0457aca8992b Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 28 Jul 2025 15:35:40 +0200 Subject: [PATCH 3/6] update contributing readme link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b8b6580c4d..45c096b44a 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ make test ## Adding an Exercise -The [contributing guide](https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md) provides guidance on +The [contributing guide](https://github.com/exercism/docs/blob/main/building/tracks/README.md) provides guidance on how to add a new exercise, or port an existing exercise from another language track. This is a brief guide, with specifics for the OCaml track. From 177b75b311b938722b787bc258574df12484f7f6 Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 29 Jul 2025 15:22:22 +0200 Subject: [PATCH 4/6] update installation to include makefile deps --- docs/INSTALLATION.md | 22 +++------------------- 1 file changed, 3 insertions(+), 19 deletions(-) diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 3117cc31fc..a92fe9cabe 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -25,28 +25,14 @@ To work on the exercises, you will need these pieces of software: 3. Install extended standard libraries and test libraries - Run the script to install the dependencies required by this track, and test the local installation: + Run the script to install the dependencies required by this track: ```bash - git clone https://github.com/exercism/ocaml.git - cd ocaml - git submodule update --init --recursive - - # see https://github.com/exercism/ocaml/blob/master/.travis/Dockerfile#L12 - # might take a while - make install_deps - - # Run generator tests - make test_generator - - # Execute generator - make generate_exercises - - # Run exercise tests - make test + opam install dune fpath ocamlfind ounit qcheck react ppx_deriving ppx_let ppx_sexp_conv yojson ocp-indent calendar getopts ``` Some exercises use only the OCaml standard library, and some use the extended libraries by Jane Street called Base and Core_kernel. + The test library is called OUnit, and some exercises additionally use the QCheck library for property-based tests. 4. Install and use interactive shell (optional) @@ -67,7 +53,5 @@ To work on the exercises, you will need these pieces of software: 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. From bd5fc79a7e37daa801f30f6351b0df6a071c7d29 Mon Sep 17 00:00:00 2001 From: Owen Date: Wed, 30 Jul 2025 14:29:04 +0200 Subject: [PATCH 5/6] change dependencies to minimum required for students --- docs/INSTALLATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index a92fe9cabe..a3f4f60f73 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -28,7 +28,7 @@ To work on the exercises, you will need these pieces of software: Run the script to install the dependencies required by this track: ```bash - opam install dune fpath ocamlfind ounit qcheck react ppx_deriving ppx_let ppx_sexp_conv yojson ocp-indent calendar getopts + opam install base core_kernel ounit qcheck ``` Some exercises use only the OCaml standard library, and some use the extended libraries by Jane Street called Base and Core_kernel. From 55b634d1567d906ff7af338e4052e7c3688b797d Mon Sep 17 00:00:00 2001 From: Owen Date: Thu, 31 Jul 2025 16:49:05 +0200 Subject: [PATCH 6/6] wording changes for installation and VS Code tools --- docs/INSTALLATION.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index a3f4f60f73..93c8df4ad9 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -25,7 +25,7 @@ To work on the exercises, you will need these pieces of software: 3. Install extended standard libraries and test libraries - Run the script to install the dependencies required by this track: + Run the following to install the dependencies required by this track: ```bash opam install base core_kernel ounit qcheck @@ -33,6 +33,7 @@ To work on the exercises, you will need these pieces of software: Some exercises use only the OCaml standard library, and some use the extended libraries by Jane Street called Base and Core_kernel. The test library is called OUnit, and some exercises additionally use the QCheck library for property-based tests. + Running the above command will install these libraries. 4. Install and use interactive shell (optional) @@ -50,8 +51,9 @@ To work on the exercises, you will need these pieces of software: open Base ``` -5. Install IDE related tools (optional) +5. Install tools in VS Code (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. + 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 [here](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform), or search for `OCaml Platform` by Ocaml Labs.