**WIP INTERNAL TO OCAML PLATFORM TEAM - DO NOT SHARE**

Welcome to the twelfth edition of the OCaml Platform newsletter!

In this June 2024 edition, we are excited to bring you the latest on the OCaml Platform, continuing our tradition of highlighting recent developments as seen in [previous editions](https://discuss.ocaml.org/tag/platform-newsletter). To understand the direction we're headed, especially regarding development workflows and user experience improvements, check out our [roadmap](https://ocaml.org/docs/platform-roadmap).

**Highlights:**

- First release of project-wide occurrences queries for editor tooling. The design of the feature will be presented at the [OCaml Workshop](https://icfp24.sigplan.org/details/ocaml-2024-papers/3/Project-wide-occurrences-for-OCaml-a-progress-report) in September.
- TODO: opam 2.2 and workshop talk

**Releases:**
- [opam 2.2.0~beta3](https://ocaml.org/changelog/2024-06-10-opam-2-2-0-beta3)
- opam 2.2.0~rc1
- opam 2.2.0
- [Dune 3.16.0](https://ocaml.org/changelog/2024-06-17-dune.3.16.0)
- opam-publish 2.3.1
- [Merlin 5.1](https://ocaml.org/changelog/2024-06-24-merlin-5.1)
- [Merlin 4.16](https://ocaml.org/changelog/2024-06-12-merlin-4.16)
- [Merlin 4.15](https://ocaml.org/changelog/2024-06-03-merlin-54.15)

## **[Dune]** Exploring Package Management in Dune ([W4](https://ocaml.org/docs/platform-roadmap#w4-build-a-project))

**Contributed by:** @rgrinberg (Tarides), @Leonidas-from-XIV (Tarides), @gridbugs (Tarides), @Alizter

**Why:** Unify OCaml tooling under a single command line for all development workflows. This addresses one of the most important pain points [reported by the community](https://www.dropbox.com/s/omba1d8vhljnrcn/OCaml-user-survey-2020.pdf?dl=0).

**What:** Prototyping the integration of package management into Dune using opam as a library. We're introducing a `dune pkg lock` command to generate a lock file and enhancing `dune build` to handle dependencies in the lock file. More details in the [Dune RFC](https://github.com/ocaml/dune/issues/7680).

**Summary:**

In last month's newsletter, we announced the Dune Developer Preview program, which marked our transitioning from prototyping Dune package management to user testing in preparation to a public release. We are now focusing on iterating based on feedback, aiming to develop a robust version of Dune package management that's suitable for widespread use in OCaml projects.

Based on our initial user interviews, this month included the following improvements:
- Implementing auto-locking when dependencies change in `dune-project` (particularly useful with Dune watch mode)
- Enabling automatic installation of OCamlFormat when running `dune fmt`. We're particularly excited about this feature and plan to extend this workflow to other Platform tools used by Dune.
- Improving logs
- Making package locking cancellable
- And more

We've also begun upstreaming some of the features developed during the Developer Preview to Dune's main branch.

**Activities:**

- Implemented workaround to avoid unstable compilers -- [ocaml/dune#10668](https://github.com/ocaml/dune/pull/10668)
- Added support for multiple checksums -- [ocaml/dune#10624](https://github.com/ocaml/dune/pull/10624)
- Began upstreaming the Dune toolchain feature -- [ocaml/dune#10639](https://github.com/ocaml/dune/pull/10639)
- Added implicit relock when dependencies change -- [ocaml/dune#10641](https://github.com/ocaml/dune/pull/10641)
- Implemented build and availability of OCamlFormat as a dev-tool -- [ocaml/dune#10613](https://github.com/ocaml/dune/pull/10613), [ocaml/dune#10647](https://github.com/ocaml/dune/pull/10647)

## **[opam]** Native Support for Windows in opam 2.2 ([W5](https://ocaml.org/docs/platform-roadmap#w5-manage-dependencies))

**Contributed by:** @rjbou (OCamlPro), @kit-ty-kate (Ahrefs), @dra27 (Tarides), @AltGr (OCamlPro)

**Why:** Enhance OCaml's viability on Windows by integrating native opam and `opam-repository` support, fostering a larger community, and more Windows-friendly packages.

**What:** Releasing opam 2.2 with native Windows support, making the official `opam-repository` usable on Windows platforms.

**Summary:**

Opam 2.2 was released and announced on [Discuss](https://discuss.ocaml.org/t/ann-opam-2-2-0-is-out/14893). The release comes with native support both for the opam client itself, and also for the compiler's packages in `opam-repository`!

The community has already started rallying to make the `opam-repository` more usable on Windows, including adding a CI check for Windows compilation on package submission (by @kit-y-kate at [opam-repository#26069](https://github.com/ocaml/opam-repository/pull/26069). They also started upstreaming `opam-repository-mingw` patches for core packages, like OCamlBuild (by @hhugo at [opam-repository#26164](https://github.com/ocaml/opam-repository/pull/26164).

The GitHub Action `ocaml/setup-ocaml` version 3.0.0 now uses opam 2.2.0 to bring OCaml support, and is ready to use in your GitHub projects (by @smorimoto). It's already in use in core projects, like [Dune](https://github.com/ocaml/dune/pull/10655).

This release marks the end of the project, but the effort to create a delightful user experience for Windows users is far from being over! Now that the foundational building blocks support Windows, we as a community need to rally to make as much of the opam-repository packages Windows-compatible as possible. If you're a package author, we strongly encourage you to setup a Windows CI for your project and start addressing Windows-related issues on your packages.

**Activities:**

- Fixed issues with `opam init` on Windows -- [ocaml/opam#5991](https://github.com/ocaml/opam/pull/5991), [ocaml/opam#5992](https://github.com/ocaml/opam/pull/5992), [ocaml/opam#5993](https://github.com/ocaml/opam/pull/5993), [ocaml/opam#5994](https://github.com/ocaml/opam/pull/5994), [ocaml/opam#5995](https://github.com/ocaml/opam/pull/5995), [ocaml/opam#5996](https://github.com/ocaml/opam/pull/5996), [ocaml/opam#5997](https://github.com/ocaml/opam/pull/5997), [ocaml/opam#5998](https://github.com/ocaml/opam/pull/5998), [ocaml/opam#6000](https://github.com/ocaml/opam/pull/6000)
- Improved status display during slow operations on Windows -- [ocaml/opam#5977](https://github.com/ocaml/opam/pull/5977)
- Enabled opam to work with Windows usernames containing spaces -- [ocaml/opam#5457](https://github.com/ocaml/opam/pull/5457)
- Fixed `opam init -yn` to handle menus in the release candidate -- [ocaml/opam#6033](https://github.com/ocaml/opam/pull/6033)
- Updated PowerShell script for installing opam from GitHub releases: [ocaml/opam#5906](https://github.com/ocaml/opam/pull/5906)
- Fixed hang issue with `setup-ocaml` and depexts -- [ocaml/opam#6046](https://github.com/ocaml/opam/pull/6046)
- Updated `opam-repository` Windows CI -- [ocaml/opam-repository#26081](https://github.com/ocaml/opam-repository/pull/26081), [ocaml/opam-repository#26073](https://github.com/ocaml/opam-repository/pull/26073), [ocaml/opam-repository#26080](https://github.com/ocaml/opam-repository/pull/26080)
- Added backport of MSVC in OCaml-variants.5.2.0+msvc -- [ocaml/opam-repository#26082](https://github.com/ocaml/opam-repository/pull/26082)
- Updated native Cygwin depexts -- [ocaml/opam-repository#26130](https://github.com/ocaml/opam-repository/pull/26130)

## **[`odoc`]** `odoc` 3.0: Unify OCaml.org and Local Package Documentation ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation))

**Contributed by:** @jonludlam (Tarides), @julow (Tarides), @panglesd (Tarides), @EmileTrotignon (Tarides), Luke Maurer (Jane Street)

**Why:** Improving local documentation generation workflow will help package authors write better documentation for their packages, and consolidating the different `odoc` documentation generators will help make continuous improvements to `odoc` available to a larger audience.

**What:** We will create conventions that drivers must follow to ensure that their output will be functional. Once established, we will update the Dune rules to follow these rules, access new `odoc` features (e.g., source rendering), and provide similar functionalities to docs.ocaml.org (a navigational sidebar, for instance). This will effectively make Dune usable to generate OCaml.org package documentation.

**Summary:**

With the RFCs for `odoc` 3.0 completed and shared with contributors and the community for feedback, the `odoc` team is transitioning from planning to implementation of the designs and features outlined in the RFCs.

This month's progress includes:
- Adding new options to the `odoc` CLI to begin the implementation of the `odoc` 3 CLI
- Implementing new syntax such as path-references
- Developing the global sidebar with a TOC featuring standalone pages and package module hierarchy

In the coming weeks, the team will continue this work, but it will also start looking into integration points with `odoc` 3.0, including Dune rules and integration with the OCaml.org documentation pipeline.

**Activities:**

- Implemented parsing of `path-references` to pages and modules: [ocaml/odoc#1142](https://github.com/ocaml/odoc/pull/1142)
- Added `path-references` lookup functionality -- [ocaml/odoc#1150](https://github.com/ocaml/odoc/pull/1150)
- Added the `--current-package` option -- [ocaml/odoc#1151](https://github.com/ocaml/odoc/pull/1151)
- Implemented a "Global" Sidebar -- [ocaml/odoc#1145](https://github.com/ocaml/odoc/pull/1145)
- Fixed hierarchical pages being given wrong parent ID -- [ocaml/odoc#1148](https://github.com/ocaml/odoc/pull/1148)

## **[Merlin]** Support for Project-Wide References in Merlin ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code))

**Contributed by:** @vds (Tarides)

**Why:** Enhance code navigation and refactoring for developers by providing project-wide reference editor features, aligning OCaml with the editor experience found in other languages.

**What:** Introducing `ocamlmerlin server occurrences` and LSP `textDocument/references` support for project-wide queries. This required indexing projects with local indexation using Shapes done in the compiler, a Dune-orchestrated global indexation, and the integration of these features in Dune, Merlin, and OCaml LSP.

**Summary:**

As [announced](https://discuss.ocaml.org/t/ann-project-wide-occurrences-in-merlin-and-lsp/14847) a few weeks ago, Merlin project-wide references is now available in Merlin 5.1 and the preview of OCaml LSP 1.18.0. Users of LSP-powered editors (like VSCode with the OCaml Platform extension) and classic Emacs and Vim plugins can now query project-wide references of OCaml terms. This requires building the index with the new Dune alias `@ocaml-index`.

This release represents the culmination of a multiyear effort by the Merlin team, including extensive work on the compiler to provide the necessary information for implementing this feature in Merlin.

We're beyond excited to share this feature with the community and look forward to your feedback.

While the feature should work well in most cases, we're aware of some limitations. Our next steps include adding support for interface files and module paths. Stay tuned!

**Activities:**

- Completed work on incremental occurrences indexation and related Dune rules -- [ocaml/dune#10422](https://github.com/ocaml/dune/pull/10422)
- Fixed issues with querying from interface files -- [ocaml/merlin#1779](https://github.com/ocaml/merlin/pull/1779), [ocaml/merlin#1781](https://github.com/ocaml/merlin/pull/1781)
- Improved behavior when cursor is on label/constructor declarations -- [ocaml/merlin#1785](https://github.com/ocaml/merlin/pull/1785)
- Released `Merlin.5.1-502`, `ocaml-index.1.0`, and a new preview of `ocaml-lsp-server` with project-wide occurrences support -- [ocaml/opam-repository#26114](https://github.com/ocaml/opam-repository/pull/26114)
- Announced the release on Discuss -- [Project-wide occurrences in Merlin and LSP](https://discuss.ocaml.org/t/ann-project-wide-occurrences-in-merlin-and-lsp/14847)

## **[OCaml LSP]** Bridging the Gap Between Merlin and OCaml LSP ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code))

**Contributed by:** @xvw (Tarides), @vds (Tarides)

**Why:** Merlin and OCaml LSP currently offer different feature sets, creating inconsistencies in editor support. By achieving feature parity between the two, we aim to make OCaml LSP the comprehensive backend for OCaml editor support. This will provide users with a more consistent, feature-rich development experience across all editors, including Emacs and Vim.

**What:** We are upstreaming features from OCaml LSP, such as the `signatureHelp` request, and ensuring we expose every Merlin feature from OCaml LSP, either through requests or custom code actions, such as `type-enclosing` request.

**Summary:**

In June, we started work on bridging the gap between OCaml LSP and Merlin. We've started with exposing Merlin's type-enclosing request in OCaml LSP. The feature is now available as `ocamllsp/typeEnclosing`.

As a reminder, Merlin's `type-enclosing` feature allows users to get the type of the identifier under the cursor. It highlights the identifier and displays its type. Users can climb the typed tree to display the type of larger expressions surrounding the cursor.

**Activities**

- OCaml LSP's type-enclosing request -- [ocaml-lsp#1304](https://github.com/ocaml/ocaml-lsp/pull/1304)