setup-ocaml v2

[smorimoto]

This was actually all rewritten from scratch, and in the process many changes were made to make things better and better. (Mainly for Windows and Build Performance.)

Now the action does the following:

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. Save the opam cache
   • If the opam cache was not hit
10. Retrieve the opam download cache
11. Install depext
    • On Windows, not only opam-depext is installed, but depext-cygwinports is installed as well
12. Retrieve the dune cache
    • If the dune cache feature is enabled
    • If the cache already exists
13. Install the latest dune and enable the dune cache feature
    • If the dune cache feature is enabled
14. Pin the opam files, if they exist
    • If the pin feature is not disabled
    • If there is an opam file in the workspace that matches the glob pattern
15. Install the system dependencies required by the opam files via depext
    • If the 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

Inputs

• ocaml-compiler: The OCaml compiler packages to initialise. The packages must be separated by the comma.
  • required: Yes
• opam-repository: The URL of the repository to fetch the packages from.
  • required: No
  • default:
• opam-pin: Enable the automation feature for opam pin.
  • required: No
  • default: true
• opam-depext: Enable the automation feature for opam depext.
  • required: No
  • default: true
• opam-depext-flags: The flags for the opam depext command. The flags must be separated by the comma.
  • required: No
  • default:
• opam-local-packages: The local packages to be used by opam-pin or opam-depext. See @actions/glob for supported patterns.
  • required: No
  • default: *.opam
• opam-disable-sandboxing: Disable the opam sandboxing feature.
  • required: No
  • default: false
• dune-cache: Enable the dune cache feature.
  • required: No
  • default: false
• cache-prefix: The prefix of the cache keys.
  • required: No
  • default: v1
• github-token: DO NOT SET THIS. The API token to be used by the action to avoid rate-limiting when calling the GitHub API internally.
  • required: No
  • default: ${{ github.token }}

Follow-up to misunderstandable parts:

• opam-disable-sandboxing is always meaningless on Windows.

• opam-local-packages actually allows complex glob patterns that span multiple lines:

  See @actions/glob for supported patterns.

  - name: Use OCaml ${{ matrix.ocaml-compiler }}
    uses: avsm/setup-ocaml@v2
    with:
      ocaml-compiler: ${{ matrix.ocaml-compiler }}
      opam-local-packages: |
        *.opam
        !exclude.opam

• In what kind of cases should I use cache-prefix?

  • In a use case like add option to disable opam sandboxing #6, the cache is often not managed as expected because the action only generates the cache key based on the platform and architecture.

• Do I need to create an API token, set it as a repository secret, and pass it to the action via github-token?!

  • No. This is a hidden hack that allows the action to use the API token automatically generated each time in the action runner, which has minimal privileges. You don't have to set it up by yourself.

Comparison

Set-up

Here is a simple benchmark. However, this is not really a fair benchmark. In v2, if the cache wasn't hit, the time spent creating the cache and uploading it to the server is included, so they are a bit longer than the actual set-up time.
In addition, the set-up time on macOS is very unstable. The Actions team is currently working to fix it, but due to an issue such as actions/runner-images#2707, the set-up time for each run is completely unreliable.

	macos-latest	ubuntu-latest	windows-latest
v1	9m 0s	4m 30s	3m 20s
v2 (with cache)	0m 50s	0m 30s	1m 45s
v2 (without cache)	4m 55s	4m 40s	3m 5s

Others

Here is a result of benchmarking several times on a medium-sized repository using ubuntu-latest VM.

	opam install . --deps-only --with-test --with-doc	opam exec -- make build	opam exec -- make test
v1	8m 25s	0m 18s	0m 6s
v2 (with dune cache)	5m 10s	0m 4s	0m 1s

Relevant issues and pull requests

General

Issues

• support dependency caching #1
• pin the version of opam installed #2
• add option to disable opam sandboxing #6
• List of supported Ubuntu versions? #36
• Add support for ocaml-system #65
• Custom compiler options for ocaml >= 4.12 #67
• Install depexts before creating the switch #68
• [Windows] opam refers to paths that are not valid from any default shell #73

Pull requests

• Add findInPath method to locate all matching executables in the system path actions/toolkit#609: The PATH hacks on Windows are needed until this PR is merged.
• Prefer using GNU tar actions/toolkit#610: Same as above.

Cache

Issues

• Update zstd actions/runner-images#2858

Dune cache

Issues

• Use of caching in Dune's Github Actions dune#3987
• [Cache] Somehow it doesn't seem to hit the cache dune#4166
• [Cache] Cache daemon is not Windows compatible dune#4167

Pull requests

• Fix the conflict with the environment variable name used by dune opam#4535: The dune cache feature is not supported on macOS until opam 2.0.9 is released. (See: 2.0.9 backported commits opam#4547)
• Fix temp path creation in Dune cache dune#4406: The dune cache feature is not supported on Windows until dune 2.8.5 is released. (See: [new release] dune-build-info, dune, dune-configurator, dune-site, dune-action-plugin, dune-private-libs and dune-glob (2.8.5) opam-repository#18405)

Acknowledgement: This work was done under great supervision of @dra27.

[psafont]

Wouldn't the previous version numbers work as well?

[smorimoto]

For now, no, but we can support it. (I didn't have much incentive to support it, so I did not implement that out to keep the code simple.)

[psafont]

I think keeping the current format is beneficial for users: it's short, which helps users to tests the packages on multiple versions; and it's the same as in v1, which helps currents users to migrate.

[smorimoto]

It's understandable that it makes the migration easier. However, I want to be as close as possible to the new package naming style introduced in 4.12: https://ocaml.org/releases/4.12.0.html (like: --package=ocaml-variants.4.12.0+options,ocaml-option-flambda,ocaml-option-nnpchecker)

[smorimoto]

@psafont I just re-added semver style version matching support! (For base compilers, not variants, you can just use 4.12.x. This greatly reduces maintenance costs.)

[smorimoto]

@Gbury Perhaps you are also interested in this change.

[Gbury]

good to know, ^^

[psafont]

I'd like to see a testing workflow by default, this is the oportunity to "recommend" a workflow to ocaml newcomers:

Suggested change

	- run: opam install . --deps-only
	- run: opam exec -- dune build
	- run: opam exec -- dune runtest
	- run: opam install . --deps-only --with-test
	- run: opam exec -- dune build
	- run: opam exec -- dune runtest

[smorimoto]

I was thinking about the same thing, but from v2, opam pin and depext run automatically (You can optionally disable it), so I intentionally removed it to keep the example very minimal. (If partial revert the changes, we have to add --with-test to the opam-depext-flanges input.)

[smorimoto]

Otherwise, we can disable these functionalities by default. Because it's mainly for large projects.

[psafont]

If it can be enabled I'd like to see how to use these advanced option.

Usually for testing there are no depexts needed, so having the tests would still work. Starting with opam 2.1.0 would the depexts be automatically installed with opam install?

[smorimoto]

Definitely. Users should see what they are. Yes, in general it's not required, but it's often needed, so I'd like to put it to avoid confusion.

Starting with opam 2.1.0 would the depexts be automatically installed with opam install?

IIRC, opam-depext as a package will be deprecated and will just be bundled with opam. CC: @rjbou

[rjbou]

yes, depext is integrated in opam 2.1 (not yet release, soon a release candidate), but opam 2.0 still uses opam-depext plugin. Ftm it is frozen, and once 2.1 released it will be slowly deprecated.

[smorimoto]

By the way, if setup-ocaml try to install the opam-depext package with opam 2.1, how opam behave? Returns an error? Or install the old, unbundled depext?

[smorimoto]

@psafont I just applied the suggestion!

[rjbou]

The package is still available, so it will installs it, and can uses it, but its content won't be update (except major issue/security bug). With the new integrated system, there is no more the need to call opam depext ..., it's completely transparent. So calling opam depext with opam 2.1 will behave as opam 2.0 : install plugin depext and calls it.
The main inconvenience is that you will do an external dependency check twice.

[smorimoto]

With the new integrated system, there is no more the need to call opam depext ..., it's completely transparent.

Whoa! This is much cooler than I thought!
I'm happy to know that it won't break. I just wanted to make sure that OCaml workflows around the world would not break unless I made changes for opam 2.1 immediately after the release.
Thank you, as always, for all your fantastic work on opam!