Set up OCaml

Set up an OCaml and opam environment in GitHub Actions and add to PATH.

Action

The action does the following:

Main

1. Change the file system behavioral parameters
   • Windows only
2. Retrieve the Cygwin cache
   • Windows only
   • If the cache already exists
3. Retrieve the opam cache
   • If the cache already exists
4. Prepare the Cygwin environment
   • Windows only
5. Save the Cygwin cache
   • Windows only
6. Install opam
7. Initialise the opam state
8. Install the OCaml compiler
   • If the opam cache was not hit
9. Remove the opam repositories
10. Save the opam cache
    • If the opam cache was not hit
11. Initialise the opam repositories
12. Retrieve the opam download cache
13. Install depext
    • On Windows, not only opam-depext is installed, but depext-cygwinports is installed as well
14. Retrieve the dune cache
    • If the dune cache feature is enabled
    • If the cache already exists
15. Install the latest dune and enable the dune cache feature
    • If the dune cache feature is enabled
16. Pin the opam files, if they exist
    • If the opam pin feature is not disabled
    • If there is an opam file in the workspace that matches the glob pattern
17. Install the system dependencies required by the opam files via depext
    • If the opam depext feature is enabled
    • If there is an opam file in the workspace that matches the glob pattern

Post

The reason for not caching opam stuff in the post stage (more precisely, why you can't) is due to the size of the cache and repeatability. They should be cached immediately after initialisation to minimize the size of the cache.

1. Remove oldest dune cache files to free space
   • If the dune cache feature is enabled
2. Save the dune cache
   • If the dune cache feature is enabled
3. Save the opam download cache

What is the difference between opam dependencies and depext dependencies?

• opam dependencies: opam packages installed by opam install.
• depext dependencies: System packages installed by apt-get install, yum install, brew install, etc.

Usage

We adhere to semantic versioning, it's safe to use the major version (v2) in your workflow. If you use the master branch, this could break your workflow when we publish a breaking update and increase the major version.

- name: Use OCaml ${{ matrix.ocaml-compiler }}
  uses: ocaml/setup-ocaml@v2
  #                      ^^^
  with:
    ocaml-compiler: ${{ matrix.ocaml-compiler }}

steps:
  # Reference the major version of a release (most recommended)
  - uses: ocaml/setup-ocaml@v2
  # Reference a specific commit (most strict)
  - uses: ocaml/setup-ocaml@<SHA>
  # Reference a semver version of a release (not recommended)
  - uses: ocaml/[email protected]
  # Reference a branch (most dangerous)
  - uses: ocaml/setup-ocaml@master

Example workflow

See the Hello World OCaml Action that uses Dune and opam to build a simple library.

It's possible to feed different values to the input depending on the platform of the runner. The syntax of GitHub's workflows is flexible enough to offer several methods to do this.

name: Main workflow

on:
  pull_request:
  push:
  schedule:
    # Prime the caches every Monday
    - cron: 0 1 * * MON

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        os:
          - macos-latest
          - ubuntu-latest
          - windows-latest
        ocaml-compiler:
          - 4.13.x

    runs-on: ${{ matrix.os }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Use OCaml ${{ matrix.ocaml-compiler }}
        uses: ocaml/setup-ocaml@v2
        with:
          ocaml-compiler: ${{ matrix.ocaml-compiler }}

      - run: opam install . --deps-only --with-test

      - run: opam exec -- dune build

      - run: opam exec -- dune runtest

Extends

STATUS: EXPERIMENTAL

Note: All extends are recommended to use in separate jobs run on ubuntu-latest.

• deploy-doc
• lint-doc
• lint-fmt
• lint-opam

deploy-doc

name: Deploy odoc

on:
  push:
    branches:
      - master

jobs:
  deploy-doc:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Use OCaml 4.13.x
        uses: ocaml/setup-ocaml@v2
        with:
          ocaml-compiler: 4.13.x
          dune-cache: true

      - name: Deploy odoc to GitHub Pages
        uses: ocaml/setup-ocaml/deploy-doc@v2

See action.yml for inputs.

lint-doc

jobs:
  lint-doc:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Use OCaml 4.13.x
        uses: ocaml/setup-ocaml@v2
        with:
          ocaml-compiler: 4.13.x
          dune-cache: true

      - name: Lint doc
        uses: ocaml/setup-ocaml/lint-doc@v2

See action.yml for inputs.

lint-fmt

Note: The ocamlformat configuration file must have the version of the ocamlformat used in the project.

jobs:
  lint-fmt:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Use OCaml 4.13.x
        uses: ocaml/setup-ocaml@v2
        with:
          ocaml-compiler: 4.13.x
          dune-cache: true

      - name: Lint fmt
        uses: ocaml/setup-ocaml/lint-fmt@v2

See action.yml for inputs.

lint-opam

jobs:
  lint-opam:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Use OCaml 4.13.x
        uses: ocaml/setup-ocaml@v2
        with:
          ocaml-compiler: 4.13.x
          dune-cache: true

      - name: Lint opam
        uses: ocaml/setup-ocaml/lint-opam@v2

See action.yml for inputs.

Advanced Configurations

See Examples for more complex patterns.

Inputs

Roadmap

This action aims to provide an OS-neutral interface to opam, and so will not add features that only work on one operating system. It will also track the latest stable release of opam.

Support

Please feel free to post to the discuss.ocaml.org forum with any questions you have about this action.

Previous discussions include:

• https://discuss.ocaml.org/t/github-actions-for-ocaml-now-stable-and-on-the-ocaml-org/7889
• https://discuss.ocaml.org/t/github-actions-for-ocaml-opam-now-available/4745