WIP INTERNAL TO OCAML PLATFORM TEAM - DO NOT SHARE
Welcome to the eighth edition of the OCaml Platform newsletter!
In this November+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. To understand the direction we're headed, especially regarding development workflows and user experience improvements, check out our roadmap.
Highlights:
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.Releases:
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.
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.
Activities:
opam-repository
. โ ocaml/dune#9202opam-repositories
with non-standard contents (non-file objects). โ ocaml/dune#9352lockdir
. โ ocaml/dune#9325lockdir
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#9156lockdir
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#9095conflicts
field in opam files โ ocaml/dune#9340opam-repository-url
option ocaml/dune#9373 Removes all CLI options that deal with repositories. All opam-repositories
are now controlled in the dune-workspace
file.opam-repository
sources, so the user can fix one particular state of opam-repository
.opam
files rather than dune-project
โ ocaml/dune#9418Contributed 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:
x-env-path-rewrite
field necessary for Windows support. - #5636odoc
] Add Search Capabilities to odoc
(W25)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:
odoc
in October, we continued work on building an odoc
-compatible search engine based on Sherlodoc. 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 โ art-w/sherlodoc#4odoc
'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#976odoc
] Syntax for Images and Assets in odoc
(W25)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:
odoc
] Improving odoc
Performance (W25)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:
module type of
expressions, with promising results from testing at Jane Street. โ ocaml/odoc#1042Contributed 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:
dune build @doc-new
to generate your documentation and tell us what you think! โ ocaml/dune#8803Contributed 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:
opam-repository
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 to the community for wider testing.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:
ocaml-lsp
, so it can be used for all LSP clients โ ocaml/ocaml-lsp#1210ocamlmerlin
responses: