Skip to content

Latest commit

 

History

History
177 lines (140 loc) · 7.89 KB

README.md

File metadata and controls

177 lines (140 loc) · 7.89 KB

Set up OCaml

Main workflow CodeQL

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.12.x

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

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

      - 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

Advanced Configurations

See Examples for more complex patterns.

Inputs

Name Required Description Type Default
ocaml-compiler Yes The OCaml compiler packages to initialise. The packages must be separated by the comma. (e.g. 4.12.x, ocaml-base-compiler.4.12.0, ocaml-variants.4.12.0+options,ocaml-option-flambda,ocaml-option-musl,ocaml-option-static) string
opam-repositories No The name and URL pair of the repository to fetch the packages from. string
opam-pin No Enable the automation feature for opam pin. bool true
opam-depext No Enable the automation feature for opam depext. bool true
opam-depext-flags No The flags for the opam depext command. The flags must be separated by the comma. string
opam-local-packages No The local packages to be used by opam-pin or opam-depext. See @actions/glob for supported patterns. string *.opam
opam-disable-sandboxing No Disable the opam sandboxing feature. bool false
dune-cache No Enable the dune cache feature. This feature requires dune 2.8.5 or later on the Windows runners. bool false
cache-prefix No The prefix of the cache keys. string v1

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: