diff --git a/data/news/platform/platform-2023-12.md b/data/news/platform/platform-2023-12.md new file mode 100644 index 0000000000..ed1eb6a46e --- /dev/null +++ b/data/news/platform/platform-2023-12.md @@ -0,0 +1,155 @@ +--- +title: "Platform Newsletter: November and December 2023" +description: Monthly update from the OCaml Platform team. +date: "2024-01-24" +tags: [platform] +--- + +Welcome to the eighth edition of the OCaml Platform newsletter! + +In this November and December 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:** +- The `odoc` team is starting work on improving `odoc` performances. After shipping important features, including a link to source code, syntax for tables, and recent support for search, they are turning their focus on consolidating the full documentation generation stack (including Dune rules and integration with OCaml.org package docs) and improving performances. +- [opam 2.2~alpha3 is out](https://ocaml.org/changelog/2023-11-15-opam-2-2-0-alpha3)! It is the last alpha release, and the opam team plans to start the beta release next cycle. +- Anticipating on the January update, the compiler PR necessary for Merlin project-wide references has been merged! This will be part of OCaml 5.2, meaning that starting with the next compiler version, OCaml developers will be able to query for project-wide references (and limited support for project-wide rename!) in their projects. Read more [here](https://discuss.ocaml.org/t/ann-preview-play-with-project-wide-occurrences-for-ocaml/13814) to know how you can test the feature. + +**Releases:** +- [Odoc 2.4.0](https://ocaml.org/changelog/2023-12-14-odoc-2.4.0) +- [OCaml LSP 1.17.0](https://ocaml.org/changelog/2023-12-18-ocaml-lsp-1.17.0) +- [Merlin 4.13](https://ocaml.org/changelog/2023-12-06-merlin-4.13) +- [Dune 3.12.1](https://ocaml.org/changelog/2023-11-29-dune-3.12.1) +- [opam 2.2.0~alpha3 +](https://ocaml.org/changelog/2023-11-15-opam-2-2-0-alpha3) + +## **[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), @kit-ty-kate (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). + +**Activities:** +- Introduced a locking mechanism to prevent conflicts in multiple repositories and fixed a bug in Dune's locking code. -- [ocaml/dune#9140](https://github.com/ocaml/dune/pull/9140) +- Enabled project locking without a network connection using locally cached `opam-repository`. -- [ocaml/dune#9202](https://github.com/ocaml/dune/pull/9202) +- Enhanced handling of `opam-repositories` with non-standard contents (non-file objects). -- [ocaml/dune#9352](https://github.com/ocaml/dune/pull/9352) +- Added a feature where users can set arbitrary variables which can be referred to by opam packages while solving a project's dependencies. This gives users more control over decisions made by the solver and which dependencies their project ends up having in its `lockdir`. -- [ocaml/dune#9325](https://github.com/ocaml/dune/pull/9325) +- Ensured `lockdir` contains all dependencies of local packages for consistency. This prevents Dune from presenting inconsistent information to users who have changed their project's dependencies after creating a `lockdir`. Instead, they'll be prompted to recompute their `lockdir`. -- [ocaml/dune#9156](https://github.com/ocaml/dune/pull/9156) +- Ability to detect which dependencies in the `lockdir` are only needed when building tests. This will be necessary to allow users to skip downloading and building packages that are only needed for testing unless they are running tests. -- [ocaml/dune#9095](https://github.com/ocaml/dune/pull/9095) +- Improved support for Windows, focusing on better Curl integration and opam library adjustments for Windows architectures. -- [ocaml/dune#9252](https://github.com/ocaml/dune/pull/9252), [ocaml/dune#9048](https://github.com/ocaml/dune/pull/9048) +- Refined context/lock file handling in Dune package management. -- [ocaml/dune#9343](https://github.com/ocaml/dune/pull/9343) +- Refined context/lock file handling. Before each context had an associated lock file so lock files were selected via context arguments. Now the context middlemen have been removed and the users selects lock files by specifying the lockfile itself. This applies to most pkg related commands. -- [ocaml/dune#9343](https://github.com/ocaml/dune/pull/9343) +- Added support for the `conflicts` field in opam files -- [ocaml/dune#9340](https://github.com/ocaml/dune/pull/9340) +- Looked into solutions to add support for deptops -- [ocaml/dune#9430](https://github.com/ocaml/dune/pull/9430) +- Writing the PID of process that created the lock file [ocaml/dune#9295](https://github.com/ocaml/dune/pull/9295) to be able to easily determine which process is holding the revision store lock +- Avoid Git translating its CLI [ocaml/dune#9390](https://github.com/ocaml/dune/pull/9390). Since we use the Git binary under the hood, users with different locales might get translated Git output. Since our Git output is not shown to the user, we disable translation. +- Remove `opam-repository-url` option [ocaml/dune#9373](https://github.com/ocaml/dune/pull/9373) Removes all CLI options that deal with repositories. All `opam-repositories` are now controlled in the `dune-workspace` file. +- Support for specifying particular branches/commits for repos [ocaml/dune#9241](https://github.com/ocaml/dune/pull/9241) adds support for specifying branches and commits as `opam-repository` sources, so the user can fix one particular state of `opam-repository` +- Enable checking out tags [ocaml/dune#9471](https://github.com/ocaml/dune/pull/9471) adds the same support as above but for tags. It does so by saving the tags in per-remote namespaces, thus it works very much like branches. +- Implement downloading sources via Git [ocaml/dune#9506](https://github.com/ocaml/dune/pull/9506) enables cloning source directories via the rev store, thus caching most commits when working with multiple projects from the same repo, etc. +- Read the main branch correctly even if tags exist [ocaml/dune#9549](https://github.com/ocaml/dune/pull/9549) fixes an issue where the code that determines the tracking branch got confused in the presence of namespaced tags. +- Dune will compute checksums for lock files of packages which don't already have checksums in their opam metadata. -- [ocaml/dune#9384](https://github.com/ocaml/dune/pull/9384) +- Package metadata for a Dune project can be read from `.opam` files rather than `dune-project` -- [ocaml/dune#9418](https://github.com/ocaml/dune/pull/9418) +- Support for conflict classes in opam files for the solver -- [ocaml/dune#9442](https://github.com/ocaml/dune/pull/9442) +- The ability to add additional constraints to feed the solver -- [ocaml/dune#9337](https://github.com/ocaml/dune/pull/9337) + +## **[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 (Tarides), @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. + + +**Activities:** + +- We’ve released [opam 2.2.0~alpha3](https://github.com/ocaml/opam/releases/tag/2.2.0-alpha3), a culmination of the last 4 months of work. This release, amongst other fixes and improvements, adds in the opam file a way to specify path environment variable rewriting rules for `setenv:`and `envbuild:` field on Windows. -- [#5636](https://github.com/ocaml/opam/pull/5636) +- Generate a static binary for producing a Windows binary -- [#5680](https://github.com/ocaml/opam/pull/5680) +- Fix carriage return on `opam env`on cygwin -- [#5715](https://github.com/ocaml/opam/pull/5715) +- Handle which Git to use at opam init on Windows -- [#5718](https://github.com/ocaml/opam/pull/5718) +- We’ve also fixed a number of issues on Windows: + - Fix issues in the C stubs for Windows - [#5714](https://github.com/ocaml/opam/pull/5714) + - Fix incorrect error message in configure on Windows - [#5667](https://github.com/ocaml/opam/pull/5667) + - Always resolve the fullpath to the `cygpath` executable - [#5716](https://github.com/ocaml/opam/pull/5716) + +## **[`odoc`]** Add Search Capabilities to `odoc` ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @panglesd (Tarides), @EmileTrotignon (Tarides), @julow (Tarides), @jonludlam (Tarides) + +**Why:** Improve usability and navigability in OCaml packages documentation, both locally and on OCaml.org, by offering advanced search options like type-based queries. + +**What:** Implementing a search engine interface in `odoc`, complete with a UI and a search index. Additionally, we're developing a default client-side search engine based on Sherlodoc. + +**Activities:** + +- After merging [the PR that added support for search to `odoc`](https://github.com/ocaml/odoc/pull/972) in October, we continued work on building an `odoc`-compatible search engine based on [Sherlodoc](https://doc.sherlocode.com/). This will give a search engine with type-based search for every package that uses `odoc`. The plan is to make Sherlodoc the search engine in Dune's documentation generation. You can try an early demo on [Varray's doc](https://art-w.github.io/varray/varray/Varray) -- [art-w/sherlodoc#4](https://github.com/art-w/sherlodoc/pull/4) +- Buiding on `odoc`'s support for search, we merged a PR that adds occurrences information to the search index. This will allows `odoc` search engines to improve the order of search results by using the number of occurences. -- [ocaml/odoc#976](https://github.com/ocaml/odoc/pull/976) + +## **[`odoc`]** Syntax for Images and Assets in `odoc` ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @panglesd (Tarides), @jonludlam (Tarides), @dbuenzli, @gpetiot (Tarides) + +**Why:** Empower package authors to create rich, engaging documentation by enabling the integration of multimedia elements directly into OCaml package documentation. + +**What:** We're introducing new syntax and support for embedding media (images, audio, videos) and handling assets within the `odoc` environment. + +**Activities:** +- Added assets in the environment to treat them similarly as other resolvable elements. This addressed the remaining feedback from reviews, and if no other blocker is found, the PR should be ready to merge. -- [ocaml/odoc#1002](https://github.com/ocaml/odoc/pull/1002) + +## **[`odoc`]** Improving `odoc` Performance ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @jonludlam (Tarides), @julow (Tarides), @gpetiot (Tarides) + +**Why:** Address performance issues in `odoc`, particularly for large-scale documentation, to enhance efficiency and user experience, and unlock local documentation generation in large code bases. + +**What:** Profiling `odoc` to identify the main performance bottlenecks, and optimising `odoc` with the findings. + +**Activities:** +- Experimented with different data structures and algorithms for more efficient documentation generation on large files. --[ocaml/odoc#1033](https://github.com/ocaml/odoc/pull/1033), [ocaml/odoc#1036](https://github.com/ocaml/odoc/pull/1036), [ocaml/odoc#1049](https://github.com/ocaml/odoc/pull/1049) +- Implemented item lookup improvements in signatures for faster processing. -- [ocaml/odoc#1049](https://github.com/ocaml/odoc/pull/1049) +- Developed a fix for memory issues caused by `module type of` expressions, with promising results from testing at Jane Street. -- [ocaml/odoc#1042](https://github.com/ocaml/odoc/pull/1042) + +## **[Dune]** Generate Dependencies Documentation with Dune ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @jonludlam (Tarides) + +**Why:** Enhance the usability of locally-generated documentation by providing direct access to dependencies' documentation. + +**What:** Implementing new Dune rules for `odoc` to enable efficient documentation generation and access to documentation for all opam packages in your switch. + +**Activities:** +- The new Dune rules have been merged and are available in the newest release of Dune 3.12.1. Try running `dune build @doc-new` to generate your documentation and tell us what you think! -- [ocaml/dune#8803](https://github.com/ocaml/dune/pull/8803) +- Shortly after the release, we noticed an issues with dependency handling. We're working on a fix that should be released -- [ocaml/dune#9461](https://github.com/ocaml/dune/pull/9461) + +## **[Merlin]** Support for Project-Wide References in Merlin ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code)) + +**Contributed by:** @voodoos (Tarides), @trefis (Tarides), @Ekdohibs (OCamlPro), @gasche (INRIA) + +**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 `merlin single occurrences` and LSP `textDocument/references` support, extending compiler's Shapes for global occurrences, and integrating these features in Dune, Merlin, and OCaml LSP. + +**Activities:** +- The first iteration on project-wide occurrences is closing-in, and we made a custom [`opam-repository`](https://github.com/voodoos/opam-repository-index) to test the feature while the changes make their way into the upstream compiler. This gave us the opportunity to test the feature on more real projects, and after another round of bug-fixing and UI improvement we [opened it](https://discuss.ocaml.org/t/ann-preview-play-with-project-wide-occurrences-for-ocaml/13814) to the community for wider testing. +- Anticipating the January update, the [compiler PR](https://github.com/ocaml/ocaml/pull/12508) has been merged! :tada: The next steps are to revisit the patches on the other projects and to open PRs upstream. Dune is the next in line. -- [ocaml/ocaml#12508](https://github.com/ocaml/ocaml/pull/12508) + +## **[Merlin]** Improving Merlin's Performance ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code)) + +**Contributed by:** @pitag (Tarides), @Engil (Tarides), @3Rafal (Tarides) + +**Why:** Some Merlin queries have been shown to scale poorly in large codebases, making the editor experience subpar, and users report that they sometimes must wait a few seconds to get the answer. This is obviously a major issue that hurts developer experience, so we're working on improving Merlin performance when it falls short. + +**What:** Developing benchmarking tools and optimising Merlin's performance through targeted improvements based on profiling and analysis of benchmark results. + +**Activities:** +- We've made the file cache lifetime configurable. Varying the lifetime will allow experimenting with Merlin's time/space trade-off. Before, it was constantly set to 5 min. -[#1698](https://github.com/ocaml/merlin/pull/1698) + - Introduced a config that lets users set a file cache lifespan. When modified to a larger value it should improve performance for large repositories -- [ocaml/merlin#1698](https://github.com/ocaml/merlin/pull/1698) + - Introduced the file cache lifespan flag to `ocaml-lsp`, so it can be used for all LSP clients -- [ocaml/ocaml-lsp#1210](https://github.com/ocaml/ocaml-lsp/pull/1210) +- We've enriched the telemetry that comes embedded in the `ocamlmerlin` responses: + - We've added information about cache hits and misses of the various Merlin caches: `cmi-files` cache, `cmt-files` cache, typer phase cache, PPX phase cache, and reader phase cache. - [#1711](https://github.com/ocaml/merlin/pull/1711) + - We've added information about the size of the major heap at the end of an `ocamlmerlin` query - [#1717](https://github.com/ocaml/merlin/pull/1717) +- We've finished up Merlin's new Fuzzy CI, a by-product of the performance work. + - We've opened the PRs - [#1716](https://github.com/ocaml/merlin/pull/1716) (and [#1719](https://github.com/ocaml/merlin/pull/1719)) + - We've written a GitHub wiki entry with a high-level description about it. - [Merlin Fuzzy CI](https://github.com/ocaml/merlin/wiki/Merlin-Fuzzy-CI) \ No newline at end of file diff --git a/data/news/platform/platform-2024-01.md b/data/news/platform/platform-2024-01.md new file mode 100644 index 0000000000..4fbc53132c --- /dev/null +++ b/data/news/platform/platform-2024-01.md @@ -0,0 +1,122 @@ +--- +title: "Platform Newsletter: January 2024" +description: Monthly update from the OCaml Platform team. +date: "2024-02-27" +tags: [platform] +--- + +Welcome to the ninth edition of the OCaml Platform newsletter! + +In this January 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:** +- A preview version of the long-awaited Merlin project-wide references is available. Read more on [the announcement](https://discuss.ocaml.org/t/ann-preview-play-with-project-wide-occurrences-for-ocaml/13814). +- A first beta of opam 2.2 is [available](https://ocaml.org/changelog/2024-01-18-opam-2-2-0-beta1)! Try it, and let the opam team know if you encounter any issues using opam on Windows. +- The `odoc` team started an effort to unify the OCaml.org package documentation with the local workflow provided by Dune. This is very exciting, as the result should be a much improved local documentation with Dune and faster releases of `odoc` features on OCaml.org. They are at the very beginning of the project, but stay tuned for exciting news in the coming months! + +**Releases:** +- [Dune 3.13.0](https://ocaml.org/changelog/2024-01-16-dune-3.13.0) +- [Dune 3.12.2](https://ocaml.org/changelog/2024-01-05-dune-3.12.2) +- [opam 2.2.0~beta1](https://ocaml.org/changelog/2024-01-18-opam-2-2-0-beta1) +- [`odoc` 2.4.1](https://ocaml.org/changelog/2024-01-24-odoc-2.4.1) + +## **[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), @kit-ty-kate (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). + +**Activities:** +- Support opam’s pin-depends field -- https://github.com/ocaml/dune/pull/9685 +- Set %{pkg:dev} correctly for packages that use dev sources -- https://github.com/ocaml/dune/pull/9605 +- Remove Repository_id refactor, which instead now uses Git URLs to specify revisions -- https://github.com/ocaml/dune/pull/9614 +- Remove `--skip-update` and automatically infer offline mode when possible -- https://github.com/ocaml/dune/pull/9683 +- Support submodules in repos -- https://github.com/ocaml/dune/pull/9798 +- Don't download the same package source archive multiple times during a build. Many OCaml packages are in Git repos (and source archives) with several other related packages, and it's common for a project to depend on several packages from the same repo. Without this change, the source archive for a repo would be downloaded once for each package from that repo appearing in a project's dependencies -- https://github.com/ocaml/dune/pull/9771 +- Add a cond statement for choosing lockdirs. This allows the lockdir to be chosen based on properties of the current system (e.g., OS, architecture) which will simplify working on projects with system-specific dependencies. -- https://github.com/ocaml/dune/pull/9750 + +## **[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 (Tarides), @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. + +**Activities:** +- Add `rsync` package to internal Cygwin packages list (enables local pinning and is used by the VCS backends -- [ocaml/opam#5808](https://github.com/ocaml/opam/pull/5808) +- Check and advertise to use Git for Windows -- [ocaml/opam#5718](https://github.com/ocaml/opam/pull/5718) +- Released [opam 2.2~beta1](https://ocaml.org/changelog/2024-01-18-opam-2-2-0-beta1) + +## **[`odoc`]** 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) + +**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 write 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. + +**Activities:** +- We started by comparing the various drivers, their needs and constraints, and to flesh out what the conventions could look like. We will publish an RFC before starting the implementation work to ensure that we indeed understood the needs of everyone. + +## **[`odoc`]** Add Search Capabilities to `odoc` ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @panglesd (Tarides), @EmileTrotignon (Tarides), @julow (Tarides), @jonludlam (Tarides) + +**Why:** Improve usability and navigability in OCaml packages documentation, both locally and on OCaml.org, by offering advanced search options like type-based queries. + +**What:** Implementing a search engine interface in `odoc`, complete with a UI and a search index. Additionally, we're developing a default client-side search engine based on Sherlodoc. + +**Activities:** +- We kept working on Sherlodoc in Januray, and a [new version was released](https://discuss.ocaml.org/t/ann-sherlodoc-a-search-engine-for-ocaml-documentation/14011) a few weeks ago, which can now be embedded on `odoc`-built doc sites. +- We also finished updating the Dune rules which drive `odoc`, to enable the new search feature on locally built docs. These changes were released as part of Dune 3.14.0. -- [ocaml/dune#9772](https://github.com/ocaml/dune/pull/9772) + +## **[`odoc`]** Syntax for Images and Assets in `odoc` ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @panglesd (Tarides), @jonludlam (Tarides), @dbuenzli, @gpetiot (Tarides) + +**Why:** Empower package authors to create rich, engaging documentation by enabling the integration of multimedia elements directly into OCaml package documentation. + +**What:** We're introducing new syntax and support for embedding media (images, audio, videos) and handling assets within the `odoc` environment. + +**Activities:** +- The PR is still under active review and we're addressing the last minor concerns. -- [ocaml/odoc#1002](https://github.com/ocaml/odoc/pull/1002) + +## **[`odoc`]** Improving `odoc` Performance ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @jonludlam (Tarides), @julow (Tarides), @gpetiot (Tarides) + +**Why:** Address performance issues in `odoc`, particularly for large-scale documentation, to enhance efficiency and user experience and unlock local documentation generation in large code bases. + +**What:** Profiling `odoc` to identify the main performance bottlenecks and optimising `odoc` with the findings. + +**Activities:** +- We investigated a couple of issues brought forth by the `module type of` fix that was mentioned last month. This eventually resulted in a series of PRs: [ocaml/odoc#1078](https://github.com/ocaml/odoc/pull/1078), [ocaml/odoc#1079](https://github.com/ocaml/odoc/pull/1079) and [ocaml/odoc#1081](https://github.com/ocaml/odoc/pull/1081) +- We also noticed that `odoc`'s handling of the load path was quadratic, so we changed that in [ocaml/odoc#1075](https://github.com/ocaml/odoc/pull/1075). + +## **[Merlin]** Support for Project-Wide References in Merlin ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code)) + +**Contributed by:** @voodoos (Tarides), @trefis (Tarides), @Ekdohibs (OCamlPro), @gasche (INRIA), @Octachron (INRIA) + +**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 `merlin single occurrences` and LSP `textDocument/references` support, extending compiler's Shapes for global occurrences and integrating these features in Dune, Merlin, and OCaml LSP. + +**Activities:** +- Released a preview version of project-wide references and announced it on Discuss, asking for feedback - [[ANN][PREVIEW] Play with project-wide occurrences for OCaml!](https://discuss.ocaml.org/t/ann-preview-play-with-project-wide-occurrences-for-ocaml/13814) +- Merged the compiler PR - [ocaml/ocaml#12506](https://github.com/ocaml/ocaml/pull/12508) +- As a teaser for future work that will build on project-wide references, we started prototyping the project-wide `rename` feature - [voodoos/ocaml-lsp#index-preview](https://github.com/voodoos/ocaml-lsp/tree/index-preview) + +## **[Merlin]** Improving Merlin's Performance ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code)) + +**Contributed by:** @pitag (Tarides), @Engil (Tarides) + +**Why:** Some Merlin queries have been shown to scale poorly in large codebases, making the editor experience subpar. Users report that they sometimes must wait a few seconds to get the answer. This is obviously a major issue that hurts developer experience, so we're working on improving Merlin performance when it falls short. + +**What:** Developing benchmarking tools and optimising Merlin's performance through targeted improvements based on profiling and analysis of benchmark results. + +**Activities:** +- We merged the Fuzzy testing CI. As a reminder, this CI tests Merlin PRs for behaviour regressions. This will help us make sure that we don't inadvertently break Merlin queries by testing them on a broad range of use cases - [ocaml/merlin#1716](https://github.com/ocaml/merlin/pull/1716) +- In `merlin-lib`, we started writing a prototype to process the buffer in parallel with the query computation. Parallelism refers to OCaml 5 parallelism (domains). \ No newline at end of file diff --git a/data/news/platform/platform-2024-02.md b/data/news/platform/platform-2024-02.md new file mode 100644 index 0000000000..7190a20d50 --- /dev/null +++ b/data/news/platform/platform-2024-02.md @@ -0,0 +1,123 @@ +--- +title: "Platform Newsletter: February 2024" +description: Monthly update from the OCaml Platform team. +date: "2024-03-26" +tags: [platform] +--- + +Welcome to the tenth edition of the OCaml Platform newsletter! + +In this February 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:** +- The OCaml Platform tools have added support for OCaml 5.2. It's available in the temporary releases + - [`Merlin 4.14-502~preview`](https://ocaml.org/p/merlin/4.14-502~preview) (@voodoos (Tarides)) + - [`Ocaml-lsp-server 1.18.0~5.2preview`](https://ocaml.org/p/ocaml-lsp-server/1.18.0~5.2preview) (@voodoos (Tarides)) + - [`Ppxlib 0.32.1~5.2preview`](https://ocaml.org/p/ppxlib/0.32.1~5.2preview) (@NathanReb (partly funded by the OCaml Software Foundation)). + +**Releases:** +- [UTop 2.14.0](https://ocaml.org/changelog/2024-02-27-utop-2.14.0) +- [Merlin 4.14](https://ocaml.org/changelog/2024-02-26-merlin-4.14) +- [Dune 3.14.0](https://ocaml.org/changelog/2024-02-12-dune.3.14.0) +- [Ppxlib 0.31.2](https://ocaml.org/changelog/2024-02-07-ppxlib-0.32.0) +- [Dune 3.13.1](https://ocaml.org/changelog/2024-02-05-dune-3.13.1) + +## **[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), @kit-ty-kate (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). + +**Activities:** +- One of the main remaining blockers to make Dune package management usable in real world project is to make some of the low level dependencies, notably OCamlFind and the OCaml compiler, relocatable. -- [ocaml/ocamlfind#72](https://github.com/ocaml/ocamlfind/pull/72) +- We experimented with a Coq-platform patch to make OCamlFind relocatable, but we faced issues with packages using `topkg` due to `ocamlbuild` build failures. This led to identifying an error with directory symlink handling in Dune [ocaml/dune#9873](https://github.com/ocaml/dune/issues/9873), [ocaml/dune#9937](https://github.com/ocaml/dune/pull/9937) +- To track the buildability of opam packages with Dune package management, we worked on a GitHub action that effectively provides us with a dashboard of opam packages coverage on a select set of packages. The repository is available at [gridbugs/dune-pkg-dashboard](https://github.com/gridbugs/dune-pkg-dashboard). +- Based on the findings from the above, several issues were opened on the Dune issue tracker. All the known issues are now tracked in the [Package Management MVP](https://github.com/ocaml/dune/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Package+Management+MVP%22) milestone on Dune's issue tracker. +- We also focused on improving features that were previously implemented. Noteworthy changes include the addition of [workspace package pins](https://github.com/ocaml/dune/pull/10072) and enhancements for correct path handling in packages -- [ocaml/dune#9940](https://github.com/ocaml/dune/pull/9940) +- Work included updates and refactorings to improve source fetching, particularly the removal of a rudimentary Git config parser in favor of using `git config` directly ([ocaml/dune#9905](https://github.com/ocaml/dune/pull/9905)), and enhancements to how Dune handles Git repositories, such as the checking out of Git repos via `rev_store` ([ocaml/dune#10060](https://github.com/ocaml/dune/pull/10060)). +- Contributions also focused on refining and testing Dune's package handling, including a fix to ensure that opam's untar code is not used ([ocaml/dune#10085](https://github.com/ocaml/dune/pull/10085)), and improvements to Dune's handling of recursive submodules in Git repos ([ocaml/dune#10130](https://github.com/ocaml/dune/pull/10130)). + +## **[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 (Tarides), @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. + +**Activities:** +- Addressed the issue where the Windows loader would display blocking dialogue boxes upon failing to find DLLs, adhering to best practices by suppressing these dialogs, and opting for exit codes instead. This enhancement eliminates disruptive interruptions, ensuring a more seamless operation for automated tasks and CI environments. -- [#5828](https://github.com/ocaml/opam/pull/5828) +- Fixed shell detection issues when opam is invoked via Cygwin's `/usr/bin/env`, enhancing compatibility and user experience for those utilising Cygwin alongside `cmd` or PowerShell. -- [#5797](https://github.com/ocaml/opam/pull/5797) +- Recommend Developer Mode on Windows. To optimise storage and align with best practices, Developer Mode is recommended for enabling symlink support. -- [#5831](https://github.com/ocaml/opam/pull/5831) +- Resolved issues related to environment variable handling, specifically fixing bugs where updates or additions to environment variables would incorrectly remove or alter them. -- [#5837](https://github.com/ocaml/opam/pull/5837) +- Addressed early loading of git location information, particularly benefiting Windows users by ensuring correct retrieval and application of git-related configurations. -- [#5842](https://github.com/ocaml/opam/pull/5842) +- Disabled ACL in Cygwin. By setting `noacl` in `/etc/fstab` for `/cygdrive` mount, this change avoids permission mismatch errors, enhancing reliability and usability for Cygwin users. -- [#5796](https://github.com/ocaml/opam/pull/5796) +- Introduced the ability to define the package manager path at initialisation, improving customisation and integration capabilities for Windows users. -- [#5847](https://github.com/ocaml/opam/pull/5847) +- Added `winsymlinks:native` to the Cygwin environment variable, improving compatibility within the Cygwin ecosystem. -- [#5793](https://github.com/ocaml/opam/pull/5793) +- Fixed script generation issues related to path quoting, ensuring smoother initialisation and setup processes, especially in mixed-environment scenarios like Cygwin. -- [#5841](https://github.com/ocaml/opam/pull/5841) +- Corrected the precedence and handling of `git-location` configurations during initialisation, streamlining Git integration and providing clearer control over Git settings. -- [#5848](https://github.com/ocaml/opam/pull/5848) +- Extended the use of eval-variables to internal Cygwin installations and adjusted the setup to better accommodate Windows-specific requirements, enhancing flexibility and system compiler integration. -- [#5829](https://github.com/ocaml/opam/pull/5829) + +## **[`odoc`]** 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), 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 write 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. + +**Activities:** +- Work continued on the design for the new `odoc` drivers conventions shared by Dune and OCaml.org, and we plan to publish the RFC in March. +- We also started comparing and prototyping various approaches to add sidebar support to `odoc`. Several prototypes have been developed and discussed with the team, and we will resume work on the sidebar implementation once the driver conventions have been adopted. + +## **[`odoc`]** Add Search Capabilities to `odoc` ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @panglesd (Tarides), @EmileTrotignon (Tarides), @julow (Tarides), @jonludlam (Tarides) + +**Why:** Improve usability and navigability in OCaml packages documentation, both locally and on OCaml.org, by offering advanced search options like type-based queries. + +**What:** Implementing a search engine interface in `odoc`, complete with a UI and a search index. Additionally, we're developing a default client-side search engine based on Sherlodoc. + +**Activities:** +- The implementation and refinement of sherlodoc's integration with odoc were our major focuses, this included making sherlodoc pass opam CI on different architectures and adjusting the dune rules for better usability -- [ocaml/dune#9956](https://github.com/ocaml/dune/pull/9956) +- After the big sherlodoc PR was merged and sherlodoc released last month, work continued on refining the dune rules for sherlodoc and on adjusting the search bar's scope based on discussions with the team. +- We implemented keyboard navigation in the search bar to improve its usability -- [ocaml/odoc#1088](https://github.com/ocaml/odoc/pull/1088) + +## **[`odoc`]** Improving `odoc` Performance ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation)) + +**Contributed by:** @jonludlam (Tarides), @julow (Tarides), @gpetiot (Tarides) + +**Why:** Address performance issues in `odoc`, particularly for large-scale documentation, to enhance efficiency and user experience and unlock local documentation generation in large code bases. + +**What:** Profiling `odoc` to identify the main performance bottlenecks and optimising `odoc` with the findings. + +**Activities:** +- Performance improvements were achieved by addressing issues with source location lookups for non-existent identifiers, significantly improving link time for large codebases. +- Several PRs from the module-type-of work were opened, including fixes and tests aimed at enhancing `odoc`'s handling of transitive library dependencies, shape lookup, and module-type-of expansions -- [ocaml/odoc#1078](https://github.com/ocaml/odoc/pull/1078), [ocaml/odoc#1081](https://github.com/ocaml/odoc/pull/1081) +- Improve the efficiency of finding `odoc` files in accessible paths, cutting the time to generate documentation by two in some of our tests -- [ocaml/odoc#1075](https://github.com/ocaml/odoc/pull/1075) + +## **[Merlin]** Support for Project-Wide References in Merlin ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code)) + +**Contributed by:** @voodoos (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, extending compiler's Shapes for global occurrences and integrating these features in Dune, Merlin, and OCaml LSP. + +**Activities:** +- Continued investigations and improvements on Dune rules to address configuration issues +- After adding support for OCaml 5.2 to `merlin-lib`, we've rebased the project-wide occurrences work over it. +- We also started work with the Jane Stree team to test project wide references at scale in their monorepo. Following our initial integration, we focused on refining Merlin's indexing and occurrence query capabilities, including addressing bottlenecks and regressions in shape reductions -- [ocaml/ocaml#13001](https://github.com/ocaml/ocaml/pull/13001) + +## **[Merlin]** Improving Merlin's Performance ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code)) + +**Contributed by:** @pitag (Tarides), @Engil (Tarides) + +**Why:** Some Merlin queries have been shown to scale poorly in large codebases, making the editor experience subpar. Users report that they sometimes must wait a few seconds to get the answer. This is obviously a major issue that hurts developer experience, so we're working on improving Merlin performance when it falls short. + +**What:** Developing benchmarking tools and optimising Merlin's performance through targeted improvements based on profiling and analysis of benchmark results. + +**Activities:** +- In `merlin-lib`, we've continued the work on a prototype to process the buffer in parallel with the query computation. Parallelism refers to OCaml 5 parallelism (domains). \ No newline at end of file diff --git a/data/news/platform/platform-2024-05.md b/data/news/platform/platform-2024-05.md new file mode 100644 index 0000000000..659917a370 --- /dev/null +++ b/data/news/platform/platform-2024-05.md @@ -0,0 +1,164 @@ +--- +title: "Platform Newsletter: March-May 2024" +description: Monthly update from the OCaml Platform team. +date: "2024-06-10" +tags: [platform] +--- + +Welcome to the eleventh edition of the OCaml Platform newsletter! + +In this March-May 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:** + +- Explorations on Dune package management have reached a Minimal-Viable-Product (MVP) stage: a version of Dune that can build non-trivial projects like [OCaml.org](https://github.com/ocaml/ocaml.org) and [Bonsai](https://github.com/janestreet/bonsai). With a working MVP, the team is shifting their focus to putting Dune package management in the hands of the community. To that end, we have started the Dune Developer Preview Program, where we will test Dune package management with users and refine the user experience in preparation for a final release. +- The opam team released a second beta of [opam 2.2](https://discuss.ocaml.org/t/ann-opam-2-2-0-beta2/14461), and with it, opened the [final PR](https://github.com/ocaml/opam-repository/pull/25861) to add support for Windows OCaml to the opam-repository. Once the PR is merged, opam 2.2 will be usable with the upstream opam-repository on Windows, paving the way for a third beta very soon, and a Release Candidate next. +- The odoc team has finalized the initial design for Odoc 3.0 and opened several [RFCs](https://github.com/ocaml/odoc/discussions) to gather community input. We've implemented a new [Odoc driver](https://github.com/ocaml/odoc/pull/1121) that follows the Odoc 3.0 design and have already started prototyping key parts of the design. +- Merlin's project-wide references query is getting very close to release. The necessary [compiler PR](https://github.com/ocaml/ocaml/pull/13001) has been merged and included in OCaml 5.2, and the [Dune rules PR](https://github.com/ocaml/dune/pull/10422) has been merged and included in Dune 3.16. The next steps are to merge the [PR in Merlin](https://github.com/ocaml/merlin/pull/1766) itself and the small patch in OCaml LSP. +- The set of standard derivers shipped with `ppx_deriving.std` (i.e. `[@@deriving show, make, ord, eq, ...]`) as well as `ppx_deriving_yojson` are now directly written against Ppxlib's API. That impacts developers in two ways. First, it allows you to enjoy reliable editor features in projects with those derivers (Ppxlib preserves Merlin's location invariants). Second, you can avoid a hard dependency on those derivers by using Ppxlib's `deriving_inline` feature on them. Thanks a lot to @sim642 for all your work and very kind patience, @NathanReb for reviewing and release managing, and everyone else involved! + +**Releases:** +- [Ppxlib 0.32.1](https://github.com/ocaml/opam-repository/pull/25713) +- [Merlin 5.0](https://ocaml.org/changelog/2024-05-22-merlin-5.0) +- [Dune 3.14.2](https://ocaml.org/changelog/2024-03-13-dune.3.14.2) +- [Dune 3.15.0](https://ocaml.org/changelog/2024-04-03-dune.3.15.0) +- [Dune 3.15.2](https://ocaml.org/changelog/2024-04-23-dune.3.15.2) +- [Dune 3.15.3](https://ocaml.org/changelog/2024-05-26-dune.3.15.3) +- [Odoc 2.4.2](https://ocaml.org/changelog/2024-04-30-odoc-2.4.2) +- [opam 2.1.6](https://ocaml.org/changelog/2024-05-22-opam-2-1-6) +- [opam 2.2.0~beta2](https://ocaml.org/changelog/2024-04-09-opam-2.2.0-beta2) +- [ocamlformat 0.26.2](https://ocaml.org/changelog/2024-04-23-ocamlformat-0.26.2) + +## **[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:** + +Over the past three months, significant progress has been made in adding Dune's support for package management. We are thrilled to report that our prototypes have reached a Minimal Viable Product (MVP) stage: an experimental version of Dune package management that can be used to build non-trivial projects, including OCaml.org and Bonsai, which we are using in our tests. + +There is still a long way to go, but with this milestone reached, we are now shifting our focus from prototyping to putting the feature in the hands of the community. We are moving to testing the new Dune feature with users, and in particular, now that we have a good understanding of the technical blockers and their workarounds, we will be focusing on validating and refining the developer experience (DX) of Dune package management in preparation for a first release. + +To that end, the Dune team has started a Dune Developer Preview Program. We're currently testing the Developer Preview of package management with selected beta testers, and once the biggest issues have been addressed, we'll be opening it to the broader community. + +**Activities:** +- Continued addressing remaining issues with ocamlfind and zarith. + - Added repro PRs for ocamlfind and zarith issues – [ocaml/dune#10233](https://github.com/ocaml/dune/pull/10233), [ocaml/dune#10235](https://github.com/ocaml/dune/pull/10235). + - Iterated on a solution for relocatable ocamlfind – [ocaml/ocamlfind#72](https://github.com/ocaml/ocamlfind/pull/72). + - Removed `.mml` references in ocamlfind – [ocaml/ocamlfind#75](https://github.com/ocaml/ocamlfind/pull/75). + - Set OCAMLFIND_DESTDIR for install actions to fix ocamlfind installation issues – [ocaml/dune#10267](https://github.com/ocaml/dune/pull/10267). +- Added a test reproducing error when locking when a pin stanza contains a relative path outside the workspace – [ocaml/dune#10255](https://github.com/ocaml/dune/pull/10255). +- Fixed package creation issues with directories on different filesystems – [ocaml/dune#10214](https://github.com/ocaml/dune/pull/10214). +- Opened PRs to address user errors, improve error messages, and enhance environment handling for pkg rules – [ocaml/dune#10385](https://github.com/ocaml/dune/pull/10385), [ocaml/ocamlbuild#327](https://github.com/ocaml/ocamlbuild/pull/327), [ocaml/dune#10403](https://github.com/ocaml/dune/pull/10403), [ocaml/dune#10407](https://github.com/ocaml/dune/pull/10407), [ocaml/dune#10455](https://github.com/ocaml/dune/pull/10455). +- Addressed several issues related to `withenv` actions, `dune pkg lock`, and unexpected behavior with variable updates – [ocaml/dune#10404](https://github.com/ocaml/dune/issues/10404), [ocaml/dune#10408](https://github.com/ocaml/dune/issues/10408), [ocaml/dune#10417](https://github.com/ocaml/dune/issues/10417), [ocaml/dune#10440](https://github.com/ocaml/dune/issues/10440), [ocaml/opam#5925](https://github.com/ocaml/opam/issues/5925), [ocaml/opam#5926](https://github.com/ocaml/opam/issues/5926). +- Approved relocatable releases of ocamlfind and ocamlbuild – [ocaml-dune/opam-overlays#1](https://github.com/ocaml-dune/opam-overlays/pull/1), [ocaml-dune/opam-overlays#2](https://github.com/ocaml-dune/opam-overlays/pull/2). +- Cleaned up and sought feedback on the relocatable ocamlfind PR – [ocaml/ocamlfind#72](https://github.com/ocaml/ocamlfind/pull/72). +- To work around the fact that the compiler is not relocatable (yet!), we worked on adding support to Dune to manage compiler and developer tools, an experimental feature we call Dune Toolchain. – [ocaml/dune#10470](https://github.com/ocaml/dune/pull/10470), [ocaml/dune#10474](https://github.com/ocaml/dune/pull/10474), [ocaml/dune#10475](https://github.com/ocaml/dune/pull/10475), [ocaml/dune#10476](https://github.com/ocaml/dune/pull/10476), [ocaml/dune#10477](https://github.com/ocaml/dune/pull/10477), [ocaml/dune#10478](https://github.com/ocaml/dune/pull/10478). +- Addressed various issues related to pkg lock, environment updates, and package management – [ocaml/dune#10512](https://github.com/ocaml/dune/pull/10512), [ocaml/dune#10499](https://github.com/ocaml/dune/pull/10499), [ocaml/dune#10498](https://github.com/ocaml/dune/pull/10498), [ocaml/dune#10531](https://github.com/ocaml/dune/pull/10531), [ocaml/dune#10521](https://github.com/ocaml/dune/pull/10521), [ocaml/dune#10539](https://github.com/ocaml/dune/pull/10539), [ocaml/dune#10540](https://github.com/ocaml/dune/pull/10540), [ocaml/dune#10543](https://github.com/ocaml/dune/pull/10543), [ocaml/dune#10544](https://github.com/ocaml/dune/pull/10544), [ocaml/dune#10545](https://github.com/ocaml/dune/pull/10545), [ocaml/dune#10538](https://github.com/ocaml/dune/issues/10538), [ocaml/dune#10542](https://github.com/ocaml/dune/issues/10542), [ocaml/dune#10595](https://github.com/ocaml/dune/pull/10595), [ocaml/dune#10596](https://github.com/ocaml/dune/pull/10596), [ocaml/dune#10592](https://github.com/ocaml/dune/issues/10592), [ocaml/dune#10593](https://github.com/ocaml/dune/issues/10593). +- Merged PRs to use unpack code for rsync URLs and disable hg/darcs fetch code – [ocaml/dune#10556](https://github.com/ocaml/dune/pull/10556), [ocaml/dune#10561](https://github.com/ocaml/dune/pull/10561). + +## **[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:** + +The opam team is getting closer to a final release of opam 2.2 with support for Windows. In the past months, we have released a second beta of opam 2.2, addressing a number of issues reported by users on previous releases, including Windows issues. + +Excitingly, we also opened the [final PR](https://github.com/ocaml/opam-repository/pull/25861) adding support for Windows OCaml to opam-repository. With the PR merged, the opam team is expecting to be able to move to a Release Candidate in June. + +Stay tuned for more exciting news and releases in the coming weeks and months! + +**Activities:** + +- Packaging the compiler in opam-repository + - We cleared WIP items in the [windows-initial](https://github.com/dra27/opam-repository/commits/windows-initial) branch, creating the [mingw-w64-shims](https://github.com/dra27/mingw-w64-shims) repository for the C stub program and generation script needed for the mingw-w64-shims opam package. + - Various fixes for msvs-detect were upstreamed and the opam packaging PR finalized – [metastack/msvs-tools#17](https://github.com/metastack/msvs-tools/pull/17), [metastack/msvs-tools#18](https://github.com/metastack/msvs-tools/pull/18). + - Initial upstreaming PRs were opened for Visual Studio configuration – [ocaml/opam-repository#25440](https://github.com/ocaml/opam-repository/pull/25440), reorganization of conf-zstd – [ocaml/opam-repository#25441](https://github.com/ocaml/opam-repository/pull/25441), and native Windows depexts – [ocaml/opam-repository#25442](https://github.com/ocaml/opam-repository/pull/25442). + - Fixed mccs package dependencies upstream – [ocaml-opam/ocaml-mccs#52](https://github.com/ocaml-opam/ocaml-mccs/pull/52), [ocaml/opam-repository#25482](https://github.com/ocaml/opam-repository/pull/25482). + - Upstreamed support for source-packaging of flexdll – [ocaml/flexdll#135](https://github.com/ocaml/flexdll/pull/135). + - Worked on packaging scripts for winpthreads for OCaml 5.3.0 – [ocaml/winpthreads#1](https://github.com/ocaml/winpthreads/pull/1). + - Further upstreaming PRs were opened for mingw-w64-shims – [ocaml/opam-repository#25454](https://github.com/ocaml/opam-repository/pull/25454), and flexdll and winpthreads sources packages – [ocaml/opam-repository#25512](https://github.com/ocaml/opam-repository/pull/25512). + - Reviewed and tested changes related to the 4.14.2 release for the sunset branch of opam-repository-mingw – [ocaml-opam/opam-repository-mingw#20](https://github.com/ocaml-opam/opam-repository-mingw/pull/20), [ocaml-opam/opam-repository-mingw#21](https://github.com/ocaml-opam/opam-repository-mingw/pull/21). + - Updated the [windows-initial](https://github.com/dra27/opam-repository/commits/windows-initial) branch to support MSYS2, including creating [msys2-opam](https://github.com/dra27/msys2-opam) to complement [mingw-w64-shims](https://github.com/dra27/mingw-w64-shims). + - Upstreamed issues with the ocaml-variants.5.1.1+effect-syntax package – [ocaml/opam-repository#25645](https://github.com/ocaml/opam-repository/pull/25645). + - Investigated BER MetaOCaml, determining that 4.14.1+BER does not work on Windows and disabled it in opam-repository – [ocaml/opam-repository#25648](https://github.com/ocaml/opam-repository/pull/25648). + - Worked further on the draft PR, addressing the issue of invalid maintainer email addresses for packages – [ocaml/opam-repository#25826](https://github.com/ocaml/opam-repository/pull/25826). + - Opened the main PR for Windows compiler support – [ocaml/opam-repository#25861](https://github.com/ocaml/opam-repository/pull/25861), with a parallel draft PR for updating the compiler's opam file – [ocaml/ocaml#13160](https://github.com/ocaml/ocaml/pull/13160). + - Backported [ocaml/ocaml#13100](https://github.com/ocaml/ocaml/pull/13100) to 5.1.x ocaml-variants – [ocaml/opam-repository#25828](https://github.com/ocaml/opam-repository/pull/25828), awaiting opam 2.2.0~beta3 release. +- Release opam 2.2 + - Completed work on various patches and PRs, including fixes for accented characters in Dune – [ocaml/opam#5861](https://github.com/ocaml/opam/issues/5861), [ocaml/opam#5871](https://github.com/ocaml/opam/pull/5871), [janestreet/spawn#58](https://github.com/janestreet/spawn/pull/58), [ocaml/opam#5862](https://github.com/ocaml/opam/pull/5862). + - Worked on performance improvements for Windows, including adding job statuses and a proof-of-concept for a spinner on slow-running build jobs – [ocaml/opam#5883](https://github.com/ocaml/opam/pull/5883). + - Finalizing fix on Cygwin PATH handling for opam 2.2.0 beta2 – [ocaml/opam#5832](https://github.com/ocaml/opam/pull/5832). + - Mark the internal cygwin installation as recommended - [ocaml/opam#5903](https://github.com/ocaml/opam/pull/5903) + - Hijack the `%{?val_if_true:val_if_false}%` syntax to support extending the variables of packages with + in their name - [ocaml/opam#5840](https://github.com/ocaml/opam/pull/5840) + - Fixed issues with downloading URLs with invalid characters and opam's internal state – [ocaml/opam#5921](https://github.com/ocaml/opam/pull/5921), [ocaml/opam#5922](https://github.com/ocaml/opam/pull/5922). + - Assembled test harnesses for `opam init` and addressed issues with `opam lint` warnings – [dra27/opam-testing](https://github.com/dra27/opam-testing), [ocaml/opam#5927](https://github.com/ocaml/opam/pull/5927), [ocaml/opam#5928](https://github.com/ocaml/opam/pull/5928). + - Fixed reversal of environment updates and minor issues in GitHub Actions – [ocaml/opam#5935](https://github.com/ocaml/opam/pull/5935), [ocaml/opam#5938](https://github.com/ocaml/opam/pull/5938). + - [Released opam 2.2~beta2](https://discuss.ocaml.org/t/ann-opam-2-2-0-beta2/14461). + - Fixed issues related to environment variable handling – [ocaml/opam#5935](https://github.com/ocaml/opam/pull/5935). + - Finalized fixes for Git for Windows menu – [ocaml/opam#5963](https://github.com/ocaml/opam/pull/5963). + - Minor fixes to `--cygwin-extra-packages` – [ocaml/opam#5964](https://github.com/ocaml/opam/pull/5964). + - Refactored `opam init` for a more logical experience – [ocaml/opam#5963](https://github.com/ocaml/opam/pull/5963). + - Updated lint warning 41 PR – [ocaml/opam#5927](https://github.com/ocaml/opam/pull/5927). + - Responded to issues found by testers of Windows compiler packages – [ocaml/flexdll#138](https://github.com/ocaml/flexdll/issues/138), [ocaml/flexdll#139](https://github.com/ocaml/flexdll/issues/139). + - Completely reworked `opam init` to detect Cygwin and MSYS2 installations. + - Fixed issues with the `?` operator and MSYS2's native curl implementation – [ocaml/opam#5983](https://github.com/ocaml/opam/pull/5983), [ocaml/opam#5984](https://github.com/ocaml/opam/pull/5984). + +## **[`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), 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:** + +The Odoc team has made significant progress on the upcoming Odoc 3.0. We held productive in-person meetings in Paris to discuss crucial design aspects such as the CLI, source code rendering, and references. These discussions led to the publications of RFCs for the various components of the design specification. + +We also started implementing a new Odoc driver that adheres to the new design for testing purposes, and began prototyping several of the new features. + +While discussions on the RFCs and specific features are still ongoing, we are very excited to have a solid set of design specifications under community review and to have begun implementing key parts of the new design. + +**Activities:** + +- Investigated package name/library name mismatches and module name clashes – [jonludlam/2997e905a468bfa0e625bf98b24868e5](https://gist.github.com/jonludlam/2997e905a468bfa0e625bf98b24868e5), [jonludlam/0a5f1391ccbb2d3040318b154da8593a](https://gist.github.com/jonludlam/0a5f1391ccbb2d3040318b154da8593a). +- Continued work on odoc 3.0 design, including meetings and discussions, culminating in the publication of the RFC – [ocaml/odoc/discussions/1097](https://github.com/ocaml/odoc/discussions/1097). +- Worked on the navigation PR, added functionalities, fixed bugs, and completed the rebase – [ocaml/odoc#1088](https://github.com/ocaml/odoc/pull/1088). +- Met in Paris to discuss the odoc 3.0 design, covering topics such as CLI, rendering source code, and references. +- Opened a PR with basic support for markdown in standalone pages – [ocaml/odoc#1110](https://github.com/ocaml/odoc/pull/1110). +- Published the current proposal for assets as a discussion – [ocaml/odoc#1113](https://github.com/ocaml/odoc/discussions/1113). +- Continued discussions on Markdown rendering and asset references - [ocaml/odoc#1110](https://github.com/ocaml/odoc/pull/1110). +- Implemented a new driver for testing the odoc 3.0 implementation – [ocaml/odoc#1121](https://github.com/ocaml/odoc/pull/1121), [ocaml/odoc#1128](https://github.com/ocaml/odoc/pull/1128). +- Worked on implementing the --parent-id flag part of the Odoc 3.0 spec – [ocaml/odoc#1126](https://github.com/ocaml/odoc/pull/1126). +- Worked on implementing the `-L` and `-P` flags [ocaml/odoc#1132](https://github.com/ocaml/odoc/pull/1132) + +## **[Merlin]** Support for Project-Wide References in Merlin ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code)) + +**Contributed by:** @vds (Tarides), @Ekdohibs (OCamlPro), @Octachron (INRIA), @gasche (INRIA), @emillon (Tarides), @rgrinberg (Jane Street), @Julow (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, extending compiler's Shapes for global occurrences and integrating these features in Dune, Merlin, and OCaml LSP. + +**Summary:** + +The past few months have seen fantastic progress on releasing Merlin's project-wide reference query: The compiler PR got merged and included in the now released OCaml 5.2; The Dune rules PR got merged, and with it significant performance improvements have been made on the indexing tool. The [final PR](https://github.com/ocaml/merlin/pull/1766) in Merlin is open and under review. That PR as well as the small LSP patch to support the feature are about to be merged. + +The PR on Merlin also adds support for the feature in the Merlin server plug-in for Emacs. Support for the Merlin server plug-in for Vim has been added separately. All editor plug-ins based on LSP will support the new feature automatically. + +**Activities:** + +- We followed up on our compiler PR to improve performance for shape aliases weak reduction. It got merged, and made it into OCaml 5.2.0. – [ocaml/ocaml#13001](https://github.com/ocaml/ocaml/pull/13001) +- We improved the Dune rules that drive the indexer: Simplified the rules, added benchmarks, discussed and improved performance. The PR got merged, and made it into Dune 3.16. - [ocaml/dune#10422](https://github.com/ocaml/dune/pull/10422) +- We polished the indexer `ocaml-index`: Profiled it and improved its speed by a factor ~2, and improved its CLI. +- We added a `:MerlinOccurrencesProjectWide` command to the Vim plug-in based on the Merlin server - [ocaml/merlin#1767](https://github.com/ocaml/merlin/pull/1767) \ No newline at end of file diff --git a/data/news/platform/platform-2024-08.md b/data/news/platform/platform-2024-08.md new file mode 100644 index 0000000000..ef5112297c --- /dev/null +++ b/data/news/platform/platform-2024-08.md @@ -0,0 +1,237 @@ +--- +title: "Platform Newsletter: June-August 2024" +description: Monthly update from the OCaml Platform team. +date: "2024-09-20" +tags: [platform] +--- + +Welcome to the twelfth edition of the OCaml Platform newsletter! + +In this June-August 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:** + + + +* **Dune package management soon in public beta:** [Developer Preview Program](https://discuss.ocaml.org/t/ann-dune-developer-preview-updates/15160) expands with 60+ interview sign-ups (16 conducted so far), NPS soaring from +9 to +28! Public beta coming soon with exciting features like automatic dependency locking and dev tool management. [See it in action](https://mas.to/deck/@leostera/112988841207690720)! +* **Opam 2.2 is out:** [Native Windows support is here](https://discuss.ocaml.org/t/ann-opam-2-2-0-is-out/14893)! Seamless setup with `opam init`, `opam-repository` compatible with Windows. OCaml on Windows is now a reality. +* **Odoc 3.0 gets close to a release:** New features like global sidebars and media support are ready in odoc. Integration with Dune and OCaml.org pipeline in progress - get ready to test the new documentation experience soon! [Check out the RFCs](https://github.com/ocaml/odoc/discussions/1097). +* **Project-wide references is live:** Merlin 5.1 and OCaml LSP 1.18.0 bring powerful code navigation to your editor. Built on years of compiler work, it's a game-changer for large codebases. +* **Starting to bridge the gap between Merlin and OCaml LSP:** New LSP queries for type enclosing, documentation, and more. We’re working towards consistent, feature-rich experience across all editors powered by OCaml LSP. + +**Releases:** + + + +* [opam 2.2.0~beta3](https://ocaml.org/changelog/2024-06-10-opam-2-2-0-beta3) +* [opam 2.2.0~rc1](https://ocaml.org/changelog/2024-06-21-opam-2-2-0-rc1) +* [opam 2.2.0](https://ocaml.org/changelog/2024-07-01-opam-2-2-0) +* [opam 2.2.1](https://ocaml.org/changelog/2024-08-22-opam-2-2-1) +* [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) +* [OCaml LSP 1.19.0](https://ocaml.org/changelog/2024-07-31-ocaml-lsp-1.19.0) +* [OCaml LSP 1.18.0](https://ocaml.org/changelog/2024-07-11-ocaml-lsp-1.18.0) +* [Ppxlib 0.33.0](https://ocaml.org/changelog/2024-07-25-ppxlib-0.33.0) + + +## **Dune Package Management ([W4](https://ocaml.org/docs/platform-roadmap#w4-build-a-project))** + +**Contributed by:** @rgrinberg (Jane Street), @Leonidas (Tarides), @gridbugs (Tarides), @maiste (Tarides), @ElectreAAS (Tarides), @moyodiallo (Tarides), @Alizter + +**Synopsis:** Integrating package management into Dune, making it the sole tool needed for OCaml development. This unification eliminates installation time (just download Dune's pre-built binary), automates external tool management (e.g., for `dune fmt` or `dune ocamllsp`), and significantly reduces build times through caching (packages and compiler are built only once across projects). + +**Summary:** + +Following our announcement of reaching the Minimal Viable Product (MVP) stage for Dune's package management in the [last newsletter](https://discuss.ocaml.org/t/ocaml-platform-newsletter-march-may-2024/14765), we've made substantial progress on our stated goals. As promised, we've shifted our focus from prototyping to user testing and refining the developer experience (DX). + +The Developer Preview Program (see [latest update](https://discuss.ocaml.org/t/ann-dune-developer-preview-updates/15160)) has expanded significantly from its early stages. We've conducted approximately 16 developer interviews out of the 60 sign ups, representing a diverse cross-section of the OCaml community. The interviewees include both newcomers and experienced OCaml users. Notably, about 40% of participants have over 3 years of OCaml experience, while 35% are relative newcomers with less than a year of experience. The majority come from Linux and macOS environments, with participants representing various sectors including tech companies, research institutions, and independent developers. + +These sessions have provided crucial feedback and driven improvements. This extensive user testing has paid off, with the Net Promoter Score jumping from +9 to an estimated +28 - a clear sign that the community is excited about the improvements we've made. + +Key developments since the last update include: + + + +* A nightly binary distribution of Dune with package management enabled, which will be made available publicly in the coming weeks. +* We started work on automated handling of developer tools (ocamlformat, ocamllsp, odoc) -- users will be able run `dune fmt`, or `dune ocamllsp`, and Dune will take care of installing OCamlFormat and OCaml LSP automatically if they are not available. +* Implementation of automatic dependency locking when project’s dependency changes -- you can now run Dune in watch mode and let it install your dependencies without any intervention after updating your dune-project +* We’ve enabled Dune cache by default, which works with your package dependencies. With this change, Dune will not recompile dependencies more than once when building new projects, including the compiler! + +The team has moved beyond just testing with OCaml.org and Bonsai, now conducting broader compatibility tests across the opam repository. Initial results show about 50% of packages can be authored using Dune with package management, with ongoing efforts to increase the coverage (we expect resolution of a few issues on a select few foundational packages to significantly increase that percentage). + +In line with the commitment to prepare for a first release, the team plans to launch a public beta in the coming weeks. This marks a significant step from our current private Developer Preview testing with selected beta testers, to a broader community release. + +Stay tuned for the upcoming announcement, and in the meantime, have a look a the demos and some enthusiastic messages from beta testers: + + + +* Demo on [Mastodon](https://mas.to/deck/@leostera/112988841207690720) or [X](https://x.com/leostera/status/1825519465527673238) +* “Just did the dune package management preview, it’s looking very sharp” -- [https://x.com/ckarmstrong/status/1830937156434747566](https://x.com/ckarmstrong/status/1830937156434747566) +* “Really looking forward to this! No more switches, no more opam, just dune behaving like a modern package manager. Having played around with it, it's just so so nice. The focus on DX really makes me hopeful about OCaml's future.” -- [https://x.com/synecdokey/status/1825533523283079474](https://x.com/synecdokey/status/1825533523283079474) + +**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), [ocaml/dune#10791](https://github.com/ocaml/dune/pull/10791)) +* Began upstreaming the Dune toolchain feature ([ocaml/dune#10639](https://github.com/ocaml/dune/pull/10639), [ocaml/dune#10719](https://github.com/ocaml/dune/pull/10719)) +* Added implicit relock when dependencies change -- [ocaml/dune#10641](https://github.com/ocaml/dune/pull/10641) +* Improved dependency solving and constraint handling ([ocaml/dune#10726](https://github.com/ocaml/dune/pull/10726)) +* Added developer preview features and configuration options ([ocaml/dune#10627](https://github.com/ocaml/dune/pull/10627)) +* Implemented progress indicators for package builds and lockfile generation ([ocaml/dune#10802](https://github.com/ocaml/dune/pull/10802), [ocaml/dune#10803](https://github.com/ocaml/dune/pull/10803)) +* Improved error messages and logging ([ocaml/dune#10662](https://github.com/ocaml/dune/pull/10662)) +* Created extensive test suite for new package management features ([ocaml/dune#10798](https://github.com/ocaml/dune/pull/10798)) +* Resolved issues with building specific packages (e.g., seq, lwt) ([ocaml/dune#10788](https://github.com/ocaml/dune/issues/10788), [ocaml/dune#10839](https://github.com/ocaml/dune/issues/10839)) +* Enable cache on fetch actions for faster builds ([ocaml/dune#10850](https://github.com/ocaml/dune/pull/10850)) +* Improved handling of dev tools like ocamlformat ([ocaml/dune#10647](https://github.com/ocaml/dune/pull/10647)) +* Developed tools for testing package compatibility coverage on opam-repository + + +## **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) + +**Synopsis:** Releasing opam 2.2 with native Windows support to enhance OCaml's viability on Windows, making the official `opam-repository` usable on Windows and encouraging more Windows-friendly packages. + +**Summary:** + +The release of opam 2.2.0, [announced on Discuss](https://discuss.ocaml.org/t/ann-opam-2-2-0-is-out/14893) early July, marks a significant milestone for the OCaml ecosystem. This version brings native support for both the opam client and compiler packages in `opam-repository` on Windows, opening new possibilities for OCaml development on this platform. + +opam 2.2.0 officially supports Cygwin and is compatible with MSYS2. Windows users can now run `opam init` in their preferred console for a guided setup, resulting in a fully functional OCaml environment. This release represents the culmination of a [multi-year effort](https://github.com/ocaml/opam/issues/246#issuecomment-2166133625) involving extensive contributions from the community. + +The OCaml ecosystem is already adapting to this new capability. A [CI check for Windows compilation](https://github.com/ocaml/opam-repository/pull/26069) has been added to opam-repository, and the [GitHub Action ocaml/setup-ocaml](https://github.com/ocaml/setup-ocaml/releases/tag/v3.0.0) now uses opam 2.2.0, facilitating OCaml development on Windows in GitHub projects. + +Community members are actively working to improve Windows compatibility across the ecosystem. Notable efforts include [Hugo Heuzard's](https://github.com/hhugo) work on [OCamlBuild](https://github.com/ocaml/opam-repository/pull/26164) and several other [Windows-related PRs](https://github.com/ocaml/opam-repository/pulls?q=is%3Apr+windows+created%3A%3E2023-06-01). + +We encourage package authors to set up Windows CI for their projects and address Windows-related issues. This collective effort will be crucial in expanding OCaml's reach and usability on the Windows platform. + +**Activities:** + + + +* Opam binary: + * 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) +* Update opam-repository to be compatible with Windows: + * 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) + * Updated opam-repository with Windows-specific package information: + * Added Windows compiler packages ([ocaml/opam-repository#25861](https://github.com/ocaml/opam-repository/pull/25861)) + * Fixed issues with OCaml variants on Windows ([ocaml/opam-repository#26033](https://github.com/ocaml/opam-repository/pull/26033)) + * Updated and released mingw-w64-shims.0.2.0 to fix setup-ocaml issues ([ocaml/opam-repository#26123](https://github.com/ocaml/opam-repository/pull/26123)) +* Released stable version of opam 2.2.0 with full Windows support 🎉 ([announcement](https://ocaml.org/changelog/2024-01-18-opam-2-2-0-beta1)) + + +## **Upgrading OCaml Package Documentation with Odoc 3.0 ([W25](https://ocaml.org/docs/platform-roadmap#w25-generate-documentation))** + +**Contributed by:** @jonludlam (Tarides), @julow (Tarides), @panglesd (Tarides), @EmileTrotignon (Tarides), Luke Maurer (Jane Street) + +**Synopsis:** Upgrading OCaml package documentation experience with odoc 3, featuring improved navigation, cross-package referencing, media support, and more. This upgrade aims to improve the documentation experience both locally and on OCaml.org, encouraging higher-quality package documentation. + +**Summary:** + +Following the completion and community review of the RFCs for odoc 3.0, we've made significant strides in implementing the new design and features. Our progress over the past few months has brought us close to a complete implementation of the odoc 3.0 feature set. As we finalize development and approach the first release, our focus is shifting towards integration with the rest of the ecosystem. + +Key Developments in the past months include: + + + +* 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 + +As we near completion of the core odoc 3.0 feature set, our focus is shifting towards finalizing integration with Dune and the OCaml.org documentation pipeline. We're excited to get all of these improvements in your hands and get your feedback on the new documentation experience. Stay tuned for announcements regarding testing opportunities and the upcoming release of odoc 3.0! + +**Activities:** + + + +* 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) +* Fixed hierarchical pages being given wrong parent ID -- [ocaml/odoc#1148](https://github.com/ocaml/odoc/pull/1148) +* Parsing of `path-references` to pages and modules ([ocaml/odoc#1142](https://github.com/ocaml/odoc/pull/1142)) +* Support for assets and media in documentation ([ocaml/odoc#1184](https://github.com/ocaml/odoc/pull/1184)) +* Implemented "Global" sidebar feature ([ocaml/odoc#1145](https://github.com/ocaml/odoc/pull/1145)) +* Added support for external pages and non-package documentation ([ocaml/odoc#1183](https://github.com/ocaml/odoc/pull/1183)) +* Improved CSS for better visual presentation ([ocaml/odoc#1159](https://github.com/ocaml/odoc/pull/1159)) +* Add a marshalled output for index generation ([ocaml/odoc#1084](https://github.com/ocaml/odoc/pull/1084)) +* Implemented Voodoo/Dune driver for improved integration ([ocaml/odoc#1168](https://github.com/ocaml/odoc/pull/1168)) +* Added frontmatter support to mld pages ([ocaml/odoc#1187](https://github.com/ocaml/odoc/pull/1187)) +* Improved breadcrumbs to show packages and libraries ([ocaml/odoc#1190](https://github.com/ocaml/odoc/pull/1190)) + + +## **Project-Wide References in OCaml Editors ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code))** + +**Contributed by:** @vds (Tarides) + +**Synopsis:** Introducing project-wide reference features in Merlin and OCaml LSP to enhance code navigation and refactoring capabilities, bringing OCaml's editor experience in line with other modern programming languages. + +**Summary:** + +As [announced](https://discuss.ocaml.org/t/ann-project-wide-occurrences-in-merlin-and-lsp/14847) in June, 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 thrilled 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) +* Wrote a [wiki page](https://github.com/ocaml/merlin/wiki/Get-project%E2%80%90wide-occurrences) for project-wide occurrences +* Updated [the Merlin website](https://ocaml.github.io/merlin/editor/emacs/#search-for-an-identifiers-occurrences) +* Updated the [platform changelog](https://github.com/ocaml/ocaml.org/pull/2580) +* Improved handling of label and constructor declarations ([ocaml/merlin#1785](https://github.com/ocaml/merlin/pull/1785)) +* Contributed compiler improvements: +* Implemented distinct unique identifiers for implementations and interfaces ([ocaml/ocaml#13286](https://github.com/ocaml/ocaml/pull/13286)) +* Developed a system for linking unique identifiers of declarations ([ocaml/ocaml#13308](https://github.com/ocaml/ocaml/pull/13308)) +* Contributed to improvements in longident locations ([ocaml/ocaml#13302](https://github.com/ocaml/ocaml/pull/13302)) + + +## **Bridging the Gap Between Merlin and OCaml LSP ([W19](https://ocaml.org/docs/platform-roadmap#w19-navigate-code))** + +**Contributed by:** @xvw (Tarides), @vds (Tarides) + +**Synopsis:** Working towards feature parity between Merlin and OCaml LSP to provide a consistent, feature-rich development experience across all editors, making OCaml LSP the comprehensive backend for OCaml editor support. + +**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` and we will work on editor integration next. + +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. + +Since June, we’ve worked on a number of new LSP queries and code actions, including: + + + +* A custom `ocamllsp/getDocumentation` query to request the `odoc` documentation +* A custom `ocamllsp/construct` query to browse and fill typed holes (`_`) +* A code-action for syntactic and semantic movement shortcuts based on Merlin's Jump command + +**Activities** + + + +* Added custom queries for type enclosing and documentation retrieval: + * Type enclosing query ([ocaml/ocaml-lsp#1304](https://github.com/ocaml/ocaml-lsp/pull/1304)) + * Documentation query ([ocaml/ocaml-lsp#1336](https://github.com/ocaml/ocaml-lsp/pull/1336)) +* Created a custom construct query ([ocaml/ocaml-lsp#1348](https://github.com/ocaml/ocaml-lsp/pull/1348)) +* Implemented semantic and syntactic movement shortcuts ([ocaml/ocaml-lsp#1364](https://github.com/ocaml/ocaml-lsp/pull/1364)) +* Backported and released Merlin 4.16 with necessary commands ([opam-repository PR](https://github.com/ocaml/opam-repository/pull/26052)) +* Refactored usage of `Typedtree` from `ocaml-lsp` to `merlin-lib` ([ocaml/merlin#1811](https://github.com/ocaml/merlin/pull/1811), [ocaml/merlin#1812](https://github.com/ocaml/merlin/pull/1812)) \ No newline at end of file