Skip to content

Track docs #547

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 1, 2025
Merged

Track docs #547

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9d8d4f8
track docs first draft
TheRealOwenRees Jul 28, 2025
d943a0e
spelling error fix
TheRealOwenRees Jul 28, 2025
ad65c62
update contributing readme link
TheRealOwenRees Jul 28, 2025
177b75b
update installation to include makefile deps
TheRealOwenRees Jul 29, 2025
bd5fc79
change dependencies to minimum required for students
TheRealOwenRees Jul 30, 2025
cad9f33
Merge branch 'main' into track-docs
TheRealOwenRees Jul 31, 2025
55b634d
wording changes for installation and VS Code tools
TheRealOwenRees Jul 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -41,12 +41,11 @@ make test
<details>
<summary>Container setup</summary>

**Prerequisites**

**Prerequesites**

* VSCode
* VSCode Remote Containers extension
* Docker
- VSCode
- VSCode Remote Containers extension
- Docker

```sh
git clone https://github.com/exercism/ocaml.git
Expand All @@ -71,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.
Expand Down Expand Up @@ -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.
41 changes: 32 additions & 9 deletions docs/INSTALLATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <switch-name>`, 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@TheRealOwenRees TheRealOwenRees Jul 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct. I will resubmit that

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):

Expand All @@ -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.