See full changelog
Fixes
-
Catch merlin desturct exceptions (#626)
-
Fix broken debouncing (#627)
Read the latest releases and updates from the OCaml ecosystem.
Catch merlin desturct exceptions (#626)
Fix broken debouncing (#627)
Fix compilation on MacOS SDK < 10.13. The native watch mode is disabled in such instances (#5431 fix #5430, @rgrinberg)
Do no add workspace_root to BUILD_PATH_PREFIX_MAP
for projects before 3.0
(5448, @rgrinberg)
Fix performance regression in incremental builds (#5439, @snowleopard)
Fix digest computation bug introduced in 3.0.1 (#5451, @rgrinberg)
On behalf of the ocamllsp team, I’m pleased to announce version 1.10.0. The only new feature this release offers is better code folding, but there are some important bug fixes and performance improvements. If you encounter any sluggishness with our server, do not hesitate to report it.
Unless there are serious bugs with this release, this will be the last release for OCaml 4.13.
Happy Hacking.
Fix infer interface code action crash when implementation source does not exist (#597)
Improve error message when the reason plugin for merlin is absent (#608)
Fix chdir
races when running ppx (#550)
More accurate completion kinds. New completion kinds for variants and fields. Removed inaccurate completion kinds for constructors and types. (#510)
Fix handling request cancellation (#616)
On behalf of the dune team, I’m delighted to announce the availability of dune 3.0.
The team has been working on this release for over 6 months, and there’s a bunch of new work to report. I’ll only highlight the some of the interesting new developments:
The watch mode has been rewritten from scratch to be faster and more scalable. We also no longer rely on any 3rd party tools such as fswatch. If any of you still have a dune workspace dune is still struggling with, we cannot wait to hear from you.
The watch mode now also starts an RPC server in the background. This RPC protocol is going to be the basis for other tools to interact with dune. Watch out for announcement on the LSP side to see how we’ll be making use of it to improve the editing experience.
The dune cache has been rewritten as well. It is now simpler and more reliable. There are still some components missing, such as distribution of the artifacts over the network. Nevertheless, we welcome you all to experiment with this feature and give us feedback.
We’ve addressed one of our oldest feature requests: high level rules for ctypes projects. This feature is still experimental, so we need feedback from real world projects before declaring it as mature.
Of course, there are many other fixes, enhancements, and only a few breaking changes in this release. We hope you have an easy time upgrading.
Happy Hacking.
Remove uchar
and seq
dummy ocamlfind libraries from dune's builtin
library database (#5260, @kit-ty-kate)
Add a DUNE_DIFF_COMMAND
environment variable to match --diff-command
command-line parameter (@raphael-proust, fix #5369, #5375)
Add support for odoc-link rules (#5045, @jonludlam, @lubegasimon)
Dune will no longer generate documentation for hidden modules (#5045, @jonludlam, @lubegasimon)
Parse the native_pack_linker
field of ocamlc -config
(#5281, @TheLortex)
Fix plugins with dot in the name (#5182, @bobot, review @rgrinberg)
Don't generate the dune-site build part when not needed (#4861, @bobot, review @kit-ty-kate)
Fix installation of implementations of virtual libraries (#5150, fix #3636, @rgrinberg)
Run tests in all modes defined. Previously, jsoo was excluded. (@hhugo, #5049, fix #4951)
Allow to configure the alias to run the jsoo tests (@hhugo, #5049, #4999)
Set jsoo compilation flags in the env
stanza (@hhugo, #5049, #1613)
Allow to configure jsoo separate compilation in the env
stanza. Previously,
it was hard coded to always be enabled in the dev
profile. (@hhugo, #5049,
fix #970)
Fix build-info version in jsoo executables (@hhugo, #5049, fix #4444)
Pass -no-check-prims
when building bytecode for jsoo (@hhugo, #5049, #4027)
Fix jsoo builds when dynamically linked foreign archives are disabled (@hhugo, #5049)
Disallow empty packages starting from 3.0. Empty packages may be
re-enabled by adding the (allow_empty)
to the package stanza in
the dune-project file. (#4867, fix #2882, @kit-ty-kate, @rgrinberg)
Add link_flags
field to the executable
field of inline_tests
(#5088,
fix #1530, @jvillard)
In watch mode, use fsevents instead of fswatch on OSX (#4937, #4990, fixes #4896 @rgrinberg)
Remove inotifywait
watch mode backend on Linux. We now use the inotify API
exclusively (#4941, @rgrinberg)
Report cycles between virtual libraries and their implementation (#5050, fixes #2896, @rgrinberg)
Warn when lang versions have an ignored suffix. (lang dune 2.3.4)
or (lang dune 2.3suffix)
were silently parsed as 2.3
and we know suggest to remove
the prefix. (#5040, @emillon)
Allow users to specify dynamic dependencies in rules. For example (deps %{read:foo.gen})
(#4662, fixes #4089, @jeremiedimino)
Sandbox infer rules for menhir. Fixes possible "inconsistent assumptions" errors (#5015, @rgrinberg)
Experimental support for ctypes stubs (#3905, fixes #135, @mbacarella)
Fix interpretation of binaries
defined in the env stanza
. Binaries
defined in x/dune
wouldn't be visible in `x/*/**/dune. (#4975, fixes #4976,
@Leonidas-from-XIV, @rgrinberg)
Do not list private libraries in package listings (#4945, fixes #4799, @rgrinberg)
Allow spaces in cram test paths (#4980, fixes #4162, @rgrinberg)
Improve error handling of misbehaving cram scripts. (#4981, fix #4230, @rgrinberg)
Fix foreign_stubs
inside a tests
stanza. Previously, dune would crash
when this field was present (#4942, fix #4946, @rgrinberg)
Add the enabled_if
field to inline_tests
within the library
stanza.
This allows us to disable executing the inline tests while still allowing for
compilation (#4939, @rgrinberg)
Generate a dune-project
when initializing projects with dune init proj ...
(#4881, closes #4367, @shonfeder)
Allow spaces in the directory argument of the subdir
stanza (#4943, fixes
#4907, @rgrinberg)
Add a %{toolchain}
expansion variable (#4899, fixes #3949, @rgrinberg)
Include dependencies of executables when creating toplevels (either dune top
or dune utop
) (#4882, fixes #4872, @Gopiancode)
Fixes opam
META file requires entry for private libs (#4841, fixes #4839, @toots)
Fixes dune exec
not adding .exe on Windows (#4371, fixes #3322, @MisterDA)
Allow multiple cinaps stanzas in the same directory (#4460, @rgrinberg)
Fix $ dune subst
in empty git repositories (#4441, fixes #3619, @rgrinberg)
Improve interpretation of ansi escape sequence when spawning processes (#4408, fixes #2665, @rgrinberg)
Allow (package pkg)
in dependencies even if pkg
is an installed package
(#4170, @bobot)
Allow %{version:pkg}
to work for external packages (#4104, @kit-ty-kate)
Add (glob_files_rec <dir>/<glob>)
for globbing files recursively (#4176,
@jeremiedimino)
Automatically generate empty .mli
files for executables and tests (#3768,
fixes #3745, @CraigFe)
Add ocaml
command subgroup for OCaml related commands such as utop
, top
,
and merlin
(#3936, @rgrinberg).
Detect unknown variables more eagerly (#4184, @jeremiedimino)
Improve location of variables and macros in error messages (#4205, @jeremiedimino)
Auto-detect dune-project
files as dune
files in Emacs (#4222, @shonfeder)
Dune no longer automatically create or edit dune-project
files
(#4239, fixes #4108, @jeremiedimino)
Warn if dune-project
is not found (fatal in release mode) (#5343, @emillon)
Cleanup temporary files after running $ dune exec
. (#4260, fixes #4243,
@rgrinberg)
Add a new subcommand dune ocaml dump-dot-merlin
that prints a mix of all the
merlin configuration of a directory (defaulting to the current directory) in
the Merlin configuration syntax. (#4250, @voodoos)
Enable cram tests by default (#4262, @rgrinberg)
Drop support for opam 1.x (#4280, @jeremiedimino)
Stop calling ocamlfind
to determine the library search path or
library installation directory. This makes the behavior of Dune
simpler and more reproducible (#4281, @jeremiedimino)
Remove the external-lib-deps
command. This command was only
approximative and the cost of maintainance was getting too high. We
removed it to make room for new more important features (#4298,
@jeremiedimino)
It is now possible to define action dependencies through a chain of aliases. (#4303, @aalekseyev)
If an .ml file is not used by an executable, Dune no longer report parsing error in this file (#4330, @jeremiedimino)
Add support for sandboxing using hard links (#4360, Andrey Mokhov)
Fix dune crash when subdir
is an absolute path (#4366, @anmonteiro)
Changed the implementation of actions attached to aliases, as in
(rule (alias runtest) (action (run ./test)))
. A visible result for
users is that such actions are now memoized for longer. For
instance:
$ echo '(rule (alias runtest) (action (echo "X=%{env:X=0}\n")))` > dune
$ X=1 dune runtest
X=1
$ X=2 dune runtest
X=2
$ X=1 dune runtest
Previously, Dune would have re-executed the action again at the last line. Now it remembers the result of the first execution.
Fix a bug where dune would always re-run all actions that produce symlinks, even if their dependencies did not change. (#4405, @aalekseyev)
Fix a bug that was causing Dune to re-hash generated files more often than necessary (#4419, @jeremiedimino)
Fields allowed in the config file are now also allowed in the workspace file (#4426, @jeremiedimino)
Add options to control how Dune should handle stdout and stderr of actions when then succeed. It is now possible to ask Dune to ignore the stdout of actions when they succeed or to request that the stderr of actions must be empty. This allows to reduce the noise of large builds (#4422, #4515, @jeremiedimino)
The @all
alias no longer depends directly on copies of files from the source
directory (#4461, @nojb)
Allow dune-file as an alternative file name for dune files (needs to be enabled in the dune-project file) (#4428, @nojb)
Drop support for upgrading jbuilder projects (#4473, @jeremiedimino)
Extend the environment variable BUILD_PATH_PREFIX_MAP
to rewrite
the root of the build dir (or sandbox) to /workspace_root
(#4466,
@jeremiedimino)
Simplify the implementation of build cache. We stop using the cache daemon to access the cache and instead write to and read from it directly. The new cache implementation is based on Jenga's cache library, which was thoroughly tested on large-scale builds. Using Jenga's cache library will also make it easier for us to port Jenga's cloud cache to Dune. (#4443, #4465, Andrey Mokhov)
More informative error message when Dune can't read a target that's supposed to be produced by the action. Old message is still produced on ENOENT, but other errors deserve a more detailed report. (#4501, @aalekseyev)
Fixed a bug where a sandboxed action would fail if it declares no dependencies in
its initial working directory or any directory it chdir
s into. (#4509, @aalekseyev)
Fix a crash when clearing temporary directories (#4489, #4529, Andrey Mokhov)
Dune now memoizes all errors when running in the file-watching mode. This speeds up incremental rebuilds but may be inconvenient in rare cases, e.g. if a build action fails due to a spurious error, such as running out of memory. Right now, the only way to force such actions to be rebuilt is to restart Dune, which clears all memoized errors. In future, we would like to provide a way to rerun all actions failed due to errors without restarting the build, e.g. via a Dune RPC call. (#4522, Andrey Mokhov)
Remove dune compute
. It was broken and unused (#4540,
@jeremiedimino)
No longer generate an approximate merlin files when computing the ocaml flags fails, for instance because they include the contents of a file that failed to build. This was a niche feature and it was getting in the way of making Dune's core better. (#4607, @jeremiedimino)
Make Dune display the progress indicator in all output modes except quiet (#4618, @aalekseyev)
Report accurate process timing information in trace mode (enabled with
--trace-file
) (#4517, @rgrinberg)
Do not log live_words
and free_words
in trace file. This allows using
Gc.quick_stat
which does not scan the heap. (#4643, @emillon)
Don't let command run by Dune observe the environment variable
INSIDE_EMACS
in order to improve reproducibility (#4680,
@jeremiedimino)
Fix root_module
when used in public libraries (#4685, fixes #4684,
@rgrinberg, @CraigFe)
Fix root_module
when used with preprocessing (#4683, fixes #4682,
@rgrinberg, @CraigFe)
Display Coq profile flags in dune printenv
(#4767, @ejgallego)
Introduce mdx stanza 0.2, requiring mdx >= 1.9.0, with a new generic deps
field and the possibility to statically link libraries
in the test
executable. (#3956, #5391, fixes #3955)
Improve lookup of optional or disabled binaries. Previously, we'd treat every executable with missing libraries as optional. Now, we treat make sure to look at the library's optional or enabled_if status (#4786).
Always use 7 char hash prefix in build info version (#4857, @jberdine, fixes #4855)
Allow to explicitly disable/enable the use of dune subst
by adding a
new (subst <disable|enable>)
stanza to the dune-project
file.
(#4864, @kit-ty-kate)
Simplify the way dune
discovers the root of the workspace. It now
stops at the first dune-workspace
file it encounters, and fails if
it finds neither a dune-workspace
nor a dune-project
file
(#4921, fixes #4459, @jeremiedimino)
Dune no longer reads installed META files for libraries distributed with the compiler, instead using its own internal database. (#4946, @nojb)
Add support for (empty_module_interface_if_absent)
in executable and library
stanzas. (#4955, @nojb)
Add support for %{bin-available:...}
(#4995, @jeremiedimino)
Make sure running git
or hg
in a sandboxed action, such as a
cram test cannot escape the sandbox and pick up some random git or
mercurial repository on the file system (#4996, @jeremiedimino)
Allow %{read:...}
in more places such as (enabled_if ...)
(#4994, @jeremiedimino)
Run each action in its own process group so that we don't leave stray processes behind when killing actions (#4998, @jeremiedimino)
Add an option expand_aliases_in_sandbox
(#5003, @jeremiedimino)
Allow to cancel the initial scan via Control+C (#4460, fixes #4364 @jeremiedimino)
Add experimental support for directory targets (#3316, #5025, Andrey Mokhov),
enabled via (using directory-targets 0.1)
in dune-project
.
Delete old promote-into
, promote-until-clean
and promote-until-clean-into
syntax (#5091, Andrey Mokhov).
Add link_flags in the env stanza (#5215)
Bootstrap: ignore errors when trying to remove generated files. (#5407, @damiendoligez)
--skip-lint
, --skip-build
, --skip-test
and
--keep-build-dir
to the main command (#419, @NathanReb)Additions
Bugs fixed
val x : #c
) (@jonludlam, #809)mli
files.
(#339, #357, @julow, @Leonidas-from-XIV)dune
MDX 0.2 stanza by
setting the MDX_RUN_NON_DETERMINISTIC
environment variable. (#365,
#366, @Leonidas-from-XIV)Fix missing -linkall flag when linking library dune-sites.plugin ( #4348, @kakadu, @bobot, reported by @kakadu)
No longer reference deprecated Toploop functions when using dune files in OCaml syntax. (#4834, fixes #4830, @nojb)
Use the stag format API to be compatible with OCaml 5.0 (#5351, @emillon).
Fix post-processing of dune-package (fix #4389, @strub)
;;
to the output of toplevel phrases that were missing it.
(#346, @Leonidas-from-XIV)mdx
binary anymore (#274, @gpetiot)rule
command (#312, @gpetiot)require-package
label, use the mdx
stanza in dune
instead. This label was only used for the rule
command and can now be
safely removed. (#363, @Leonidas-from-XIV){@ocaml kind=toplevel env=e1[ code ]}
input_name
to the Expansion_context.Extension
and Expansion_context.Deriver
modules (#284, @tatchi)gen_symbol
to strip previous unique suffix before adding a new one (#285, @ceastlund)name_type_params_in_td
to use prefixes a
, b
, ... instead of v_x
. (#285, @ceastlund)type_is_recursive
and really_recursive
where they would
consider a type declaration recursive if the type appeared inside an attribute
payload (#299, @NathanReb);;
(#342, @Leonidas-from-XIV)We are pleased to announce the minor release of opam 2.1.2.
This opam release consists of backported fixes, including:
dnf
if yum
does not exist on RHEL-based systems (#4825)--no-depexts
in CLI 2.0 mode. This further improves the use of opam 2.1 as a drop-in replacement for opam 2.0 in CI, for example with setup-ocaml in GitHub Actions. (#4908)Opam installation instructions (unchanged):
From binaries: run
bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh) --version 2.1.2"
or download manually from the GitHub "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni
to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.
From source, using opam:
opam update; opam install opam-devel
(then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni
to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)
From source, manually: see the instructions in the README.
We hope you enjoy this new minor version, and remain open to bug reports and suggestions.
compact
and sparse
are now deprecated and will be removed by version 1.0 (#1803, @gpetiot)align-cases
, align-constructors-decl
and align-variants-decl
(#1793, @gpetiot)disambiguate-non-breaking-match
(#1805, @gpetiot)break-before-in
(#1888, @gpetiot)break-cases={toplevel,all}
(#1890, @gpetiot)break-collection-expressions
(#1891, @gpetiot)break-fun-decl=smart
(#1892, @gpetiot)break-fun-sig=smart
(#1893, @gpetiot)break-string-literals
(#1894, @gpetiot)break-struct
(#1895, @gpetiot)extension-indent
(#1896, @gpetiot)function-indent
(#1897, @gpetiot)function-indent-nested
(#1898, @gpetiot)if-then-else={fit-or-vertical,k-r}
(#1899, @gpetiot)indicate-multiline-delimiters=closing-on-separate-line
(#1900, @gpetiot)indent-after-in
(#1901, @gpetiot)let-binding-indent
(#1902, @gpetiot)let-binding-spacing=sparse
(#1903, @gpetiot)match-indent
(#1904, @gpetiot)match-indent-nested
(#1905, @gpetiot)module-item-spacing=preserve
(#1906, @gpetiot)nested-match
(#1907, @gpetiot)parens-tuple-patterns
(#1908, @gpetiot)sequence-style=before
(#1909, @gpetiot)stritem-extension-indent
(#1910, @gpetiot)type-decl-indent
(#1911, @gpetiot){|...|}
(#1754, @nojb, @hhugo)*
, %
, #
-ops) (#1776, @gpetiot)indicate-multiline-delimiters=closing-on-separate-line
(#1786, @gpetiot)foo ~(x:int)
instead of the explicit foo ~x:(x:int)
. (ocaml#10434) (#1756, #1759, @gpetiot).
This syntax is only produced when the output syntax is at least OCaml 4.14.ocaml-version
option to select the version of OCaml syntax of the output (#1759, @gpetiot)Additions
Bugs fixed
Additions
Disable functionality reliant on ocamlformat-rpc for now (#555)
4.13 compatiblity
occurences
to work when looking for locally abstract types
(#1382)-alert
compiler flag (#1401)-error-style
compiler flag (#1402, @nojb)Oops, we went looking but didn't find the changelog for this release 🙈
.merlin
files, and as a consequence no longer
depends on dot-merlin-reader. (#523)Feedback on this post is welcomed on Discuss!
We are pleased to announce the release of opam 2.1.1.
With opam 2.1.1, if you export OPAMCLI=2.0
into your environment then workflows expecting opam 2.0 should now behave even more equivalently.
opam 2.1.1 includes both the fixes in opam 2.0.10.
General fixes:
--packages
option for CLI version 2.0, e.g. OPAMCLI=2.0 opam switch create . 4.12.0+options --packages=ocaml-option-flambda
. In opam 2.1 and later, this syntax remains an error (#4843)opam switch set-invariant
: default repositories were loaded instead of the switch's repositories selection (#4869)Integrated depext support has a few updates:
And finally two regressions have been dealt with:
Unix.environment
on load (as a toplevel expression). This regression affected opam's libraries, rather than the binary itself (#4789)A few issues with the compilation of opam from sources have been fixed as well (e.g. mingw-w64 with g++ 11.2 now works)
Opam installation instructions (unchanged):
From binaries: run
bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh) --version 2.1.1"
or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni
to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.
From source, using opam:
opam update; opam install opam-devel
(then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni
to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)
From source, manually: see the instructions in the README.
We hope you enjoy this new minor version, and remain open to bug reports and suggestions.
--packages
option with cli 2.0, and a specific error message for cli 2.1
[#4853 @rjbou - fix #4843]Feedback on this post is welcomed on Discuss!
We are pleased to announce the release of opam 2.0.10.
Two subtle fixes are included in opam 2.0.10. These actually affect the ocaml
package. Both of these are Heisenbugs - investigating what's going wrong on your system may well have fixed them, they were both found on Windows!
$(opam env --revert)
is the reverse of the more familiar $(opam env)
but it's effectively called by opam whenever you change switch. It has been wrong since 2.0.0 for the case where several values are added to an environment variable in one setenv
update. For example, if a package included a setenv
field of the form [PATH += "dir1:dir2"]
, then this would not be reverted, but [[PATH += "dir1"] [PATH += "dir2"]]
would be reverted. As it happens, this bug affects the ocaml
package, but it was masked by another setenv
update in the same package.
The other fix is also to do with setenv
. It can be seen immediately after creating a switch but before any additional packages are installed, as this Dockerfile
shows:
FROM ocaml/opam@sha256:244b948376767fe91e2cd5caca3b422b2f8d332f105ef2c8e14fcc9a20b66e25
RUN sudo apt-get install -y ocaml-nox
RUN opam --version
RUN opam switch create show-issue ocaml-system
RUN eval $(opam env) ; echo $CAML_LD_LIBRARY_PATH
RUN opam install conf-which
RUN eval $(opam env) ; echo $CAML_LD_LIBRARY_PATH
Immediately after switch creation, $CAML_LD_LIBRARY_PATH
was set to /home/opam/.opam/show-issue/lib/stublibs:
, rather than /home/opam/.opam/show-issue/lib/stublibs:/usr/local/lib/ocaml/4.08.1/stublibs:/usr/lib/ocaml/stublibs
Opam installation instructions (unchanged):
From binaries: run
bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh) --version 2.0.10"
or download manually from the Github "Releases" page to your PATH. In this case, don't forget to run opam init --reinit -ni
to enable sandboxing if you had version 2.0.0~rc manually installed or to update you sandbox script.
From source, using opam:
opam update; opam install opam-devel
(then copy the opam binary to your PATH as explained, and don't forget to run opam init --reinit -ni
to enable sandboxing if you had version 2.0.0~rc manually installed or to update your sandbox script)
From source, manually: see the instructions in the README.
We hope you enjoy this new minor version, and remain open to bug reports and suggestions.
v
as prefix for tags but the project version omits it. Now
they share the same URL. (#402, #404, @Leonidas-from-XIV)dune-release
supported unannotated tags in a few places already, now it supports using
them for creating a release. (#383, @Leonidas-from-XIV)---V
command option to be -V
(#388, @Leonidas-from-XIV)dune-release
on projects that do not use the changelog or have it in a
different format. (#381, #383 @Leonidas-from-XIV)dune-release
couldn't retrieve a release on GitHub if the
tag and project version don't match (e.g. v1.0
vs 1.0
). dune-release
would in such case believe the release doesn't exist, attempt to create it
and subsequently fail. (#387, #395, @Leonidas-from-XIV)Hot on the heels of the OCaml 4.13 announcement(s!), the odoc
team is pleased to announce the release of odoc 2.0.0
!
tl;dr: The new version produces much better output than the old version, it's the engine at the core of the package docs in v3.ocaml.org, and it also has a new website.
This release has been a long time coming -- years! -- and contains several notable improvements over the odoc 1.5
series: a new language model, a new rendering layer allowing output in several formats, and improved control over the output structure.
The internal library used by odoc
that models the OCaml module system has been completely rewritten over a multi-year effort by @jonludlam and @Julow, according to a design by @lpw25. The rewrite gives odoc
a much better understanding of the module system compared to the original implementation. This library is used for two main processes:
odoc
takes complex module type expressions like this one from tyxml:module Make
(Xml : Xml_sigs.T with type ('a, 'b) W.ft = 'a -> 'b)
(Svg : Svg_sigs.T with module Xml := Xml)
: Html_sigs.Make(Xml)(Svg).T
with type +'a elt = Xml.elt
and type +'a attrib = Xml.attrib
Then turns it into an output page containing the correct types, values, modules, includes, and documentation.
odoc
handles complex paths found in OCaml source in order to calculate the correct definition link. For example, in the following snippet:module type A = sig
module M : sig module type S end
module N : M.S
end
module B : sig module type S = sig type t end end
module C : A with module M = B with type N.t = int
type t = C.N.t
resolution is the process by which odoc
determines which documentation page to take you when you click on C.N.t
.
The new model has logic to handle many features of the OCaml language, as can be explored here.
A particularly important improvement is in handling canonical modules (explained in the link above). The upshot of this is that there should never be any more odd double underscores leaking into your docs!
For some more info on this, as well as the new output renderers, see our talk at the OCaml workshop last year
@Drup put a considerable amount of work into replacing the odoc 1.5
custom HTML generator with a new rendering layer. This features a new intermediate format allowing new output formats to be added far more easily than before.
Included in odoc 2.0
are renderers for HTML and man pages (both contributed by @Drup) and LaTeX (contributed by @Octachron). The LaTeX renderer has already been integrated into the OCaml build process to generate docs (see https://github.com/ocaml/ocaml/pull/9997 and related PRs). @jonludlam also made an alternative HTML renderer designed specifically for v3.ocaml.org. Finally, a new markdown renderer is being prepared by @lubegasimon and should land in the next release.
We look forward to many new renderers being created for the varied use cases present in the community!
odoc 2.0
introduces a new mechanism to specify the structure of the files produced. Although it's a relatively simple new feature, it nevertheless has enabled odoc
to be used in new ways. In particular, it has allowed odoc
to construct the
package documentation for the new OCaml website, v3.ocaml.org. There is also an example driver, showing how odoc
can be used to construct a stand-alone website for an OCaml package that contains fully-linked documentation for a package and all of its dependencies. This has been used to create odoc
's new website.
Like the OCaml compiler itself, running odoc
on your code requires careful sequencing of the invocations to produce the correct result. Fortunately both dune
and odig
understand how to do this, so most users don't need to know the details. If you want more than these tools provide though, we've written a simple reference driver, documenting exactly what's necessary to use odoc
to produce rich documentation. A more complete (and more complex) example is the tool voodoo, which is being used to create the docs for v3.ocaml.org.
As previously posted, the new version of the OCaml website has been under development for some time now, and an important new feature is the integration of package listings, including documentation for every version of every package. More has been written about this elsewhere, but it's important to note that the new OCaml.org website required a preview version of odoc 2.0
to work. We've made a few bug fixes since then, so we will update the pipeline to use the released version very soon. For more info on the pipeline to build the docs, see our recent talk at this year's OCaml Workshop.
The website for odoc
has been improved with guides for documentation authors, integrators, and contributors. This site is intended to grow over time with more content to help people write docs for their packages.
This release, particularly because of the new output renderers, puts odoc
in a place where it supercedes OCamldoc in most respects. There are a few features we're missing (see the comparison in the docs), including
most notably that we don't render the source (OCamldoc's --keep-code
argument), and that there is no support for custom tags. If odoc
is lacking features that you're currently relying on in OCamldoc, we'd love to hear from you!
Finally, I'd like to use this opportunity to launch an invitation. With v3.ocaml.org now showing all the package docs in their current state, I'd like to invite all our package authors, maintainers, contributors, and users to take a look over their favourite packages and see what the documentation looks like. Good documentation is one of the most important requests from the previous OCaml developer surveys, and with v3.ocaml.org as a new documentation hub, now is a great time to be making improvements where they're required. With this new release of odoc
, previewing your docs should be as simple as dune build @doc
.
Some packages already have great docs - a few examples are:
many others have more patchy docs. Let's fix that!
We're also looking for more contributors to odoc
. It's much improved now, but there's still plenty more to do. Come and join the fun!
Breaking changes
Additions
{!modules:...}
(@Julow, #597)Bugs fixed
uwt
now can be documented (@jonludlam, #708)Fix debouncing of document updates. It was essentially completely broken in all but the most trivial cases. (#509 fixes #504)
Fix completion when passing named and functional arguments (#512)