Dune 3.20.0 Regression Error With Jsoo And Module Without Implementation

Aug 25, 2025 by ADMIN 73 views

Regression: New Error with Jsoo and Module Without Implementation

Introduction

Hey guys! Today, we're diving into a tricky regression issue that popped up with the latest Dune release (3.20.0). It involves js_of_ocaml and modules without implementation, and it's something you might run into if you're working on similar projects. So, let's break down the problem, how to reproduce it, and what's going on under the hood. Understanding these kinds of issues is crucial for maintaining smooth builds and keeping our projects running flawlessly.

When dealing with OCaml and js_of_ocaml, especially in projects that leverage Dune for build management, encountering unexpected compilation errors can be a real headache. The error we're focusing on today specifically arises when using modules without implementation in conjunction with js_of_ocaml after upgrading to Dune 3.20.0. This situation highlights the importance of understanding how Dune handles module dependencies and how js_of_ocaml interacts with the build system. To effectively troubleshoot and resolve this issue, it's essential to grasp the roles of .mli files (interface files) and how they are treated differently from .ml files (implementation files). Moreover, having a clear understanding of Dune's build rules and how they orchestrate the compilation process is key. We'll walk through a minimal reproducible example to illustrate the problem, step by step, making it easier for you to identify and address similar challenges in your own projects. Remember, staying on top of these intricacies not only helps in fixing immediate errors but also in building a robust and maintainable codebase in the long run.

Expected Behavior

Before the update, I had a straightforward js_of_ocaml executable that utilized a (module_without_implementation interface). This setup compiled perfectly fine with Dune version 3.19.1, both on OCaml 4.14.1 and 5.2.0. The expected behavior was a clean compilation process, resulting in a working JavaScript output. The key here is that the interface-only module should have been correctly handled by the build system without needing a corresponding implementation file. This is a common pattern in OCaml for defining APIs and types that are implemented elsewhere, or potentially provided by external libraries. The smooth compilation in Dune 3.19.1 indicated that the build system correctly interpreted the module dependency and generated the necessary JavaScript code without errors. This expectation is grounded in the way Dune's build rules were designed to handle such cases, ensuring that interface-only modules are correctly linked and processed by js_of_ocaml. Therefore, the regression in Dune 3.20.0 highlights a significant change in how these modules are treated, making it crucial to understand the underlying cause for a seamless upgrade experience.

Actual Behavior

After updating to Dune 3.20.0, a compilation error emerged, halting the build process. The error message was quite specific:

File "bin/.main.eobjs/jsoo/_unknown_", line 1, characters 0-0:
Error: No rule found for bin/.main.eobjs/jsoo/dune__exe__Interface.cmo.js

This error indicates that Dune couldn't find a build rule for the JavaScript output (.cmo.js) of the interface module. This is unexpected because the interface module should be handled differently than a module with implementation. Essentially, the build system was looking for a JavaScript-compiled version of the interface, which doesn't make sense since interfaces don't contain executable code. The critical aspect of this error is that it represents a regression—a previously working configuration that now fails after an update. This immediately suggests a change in Dune's build rules or dependency handling that affects js_of_ocaml and modules without implementation. Identifying regressions is crucial in software development as they can disrupt existing workflows and require immediate attention. In this case, the error points to a potential issue in how Dune 3.20.0 processes interface-only modules within the js_of_ocaml context, necessitating a deeper investigation into the changes introduced in the new version and their impact on the build process.

Reproduction

To reproduce this bug, I've created a minimal example. This makes it easier for others to confirm the issue and for the Dune team to debug it. The setup is as follows:

.
├── bin
│   ├── dune
│   ├── interface.mli
│   └── main.ml
└── dune-project

Here's a breakdown of the files:

dune file (in bin directory):
```
(executable
 (modes js)
 (modules_without_implementation interface)
 (name main))
```
This Dune file defines an executable named main that compiles to JavaScript ((modes js)). It also specifies that the interface module is a module without implementation ((modules_without_implementation interface)).
interface.mli:
```
type t = Foo
```
This is the interface file defining a simple type t with a single constructor Foo. Notice there's no corresponding .ml file, making it a module without implementation.
main.ml:
```
let _ = Interface.Foo
```
This is the main program that simply references the Foo constructor from the Interface module.
dune-project:
```
(lang dune 3.19)
(name minjs)
(package
 (name minjs)
 (depends ocaml dune js_of_ocaml)
 (allow_empty))
```
This file defines the project settings, including the Dune language version, project name, and dependencies.

To reproduce the bug, follow these steps:

Create a new Opam switch with OCaml 4.14.1 (or 5.2.0):

opam switch create test ocaml-base-compiler.4.14.1
eval $(opam env --switch=test)

Install Dune 3.20.0 and js_of_ocaml:
```
opam install dune.3.20.0 js_of_ocaml
```
Attempt to build the project:
```
dune build # error
```
This will result in the error described earlier.
To confirm it's a regression, install Dune 3.19.1:
```
opam install dune.3.19.1
eval $(opam env)
```
Clean the build and build again:
```
dune clean
dune build # no error
```
This should build without errors, confirming the regression in Dune 3.20.0.

This step-by-step reproduction guide is essential for anyone looking to verify the issue. The use of a minimal example, including the dune-project and dune files, is crucial because it isolates the problem and reduces the potential for confounding factors. By clearly outlining the environment setup, such as using a specific OCaml version and Opam switch, we ensure that the reproduction is consistent across different systems. Furthermore, the commands provided are explicit and easy to follow, even for those who may be less familiar with Dune or OCaml development. The contrast between the failing build in Dune 3.20.0 and the successful build in 3.19.1 serves as a clear indicator of the regression, highlighting the importance of version control and thorough testing in software development. This methodical approach not only aids in confirming the bug but also provides a solid foundation for debugging and ultimately resolving the issue.

Specifications

Version of dune: 3.20.0
Version of ocaml: 4.14.1 (also tested on 5.2.0)
Operating system: Kubuntu 25.04 x86_64
js_of_ocaml version: 6.2.0

These specifications are crucial for understanding the context in which the bug occurs. The Dune version (3.20.0) is the primary suspect, as the issue arose immediately after the upgrade. The OCaml versions (4.14.1 and 5.2.0) indicate that the bug isn't specific to a single OCaml compiler version, suggesting a broader issue within Dune's build process. The operating system (Kubuntu 25.04 x86_64) provides information about the environment, although it's less likely to be a direct cause of the bug. The js_of_ocaml version (6.2.0) is also relevant, as the interaction between Dune and js_of_ocaml is where the problem manifests. Together, these specifications form a comprehensive picture of the environment where the regression occurs, which is essential for debugging and resolving the issue effectively. Knowing the exact versions and configurations helps developers narrow down the potential causes and reproduce the bug consistently.

Additional Information

I also ran dune build --verbose to get more detailed output. Here's what it showed:

Shared cache: enabled-except-user-rules
Shared cache location: /home/dorian/.cache/dune/db
Workspace root: /home/dorian/Documents/Github/minjs
Auto-detected concurrency: 20
Dune context:
 { name = "default"
 ; kind = "default"
 ; profile = Dev
 ; merlin = true
 ; fdo_target_exe = None
 ; build_dir = In_build_dir "default"
 ; instrument_with = []
 }
Actual targets:
- alias @@default
File "bin/.main.eobjs/jsoo/_unknown_", line 1, characters 0-0:
Error: No rule found for bin/.main.eobjs/jsoo/dune__exe__Interface.cmo.js

This verbose output provides valuable insights into Dune's build process. The key takeaway is the error message, which reiterates that no rule was found for compiling the interface module to JavaScript. The surrounding context, such as the shared cache settings and detected concurrency, is less directly relevant to the core issue but can be useful for understanding the overall build environment. The Dune context section confirms the build profile and other settings, which are mostly default values in this case. The Actual targets line indicates that Dune is trying to build the default alias, which includes the executable. The fact that the error occurs during the build of this alias suggests that the issue is fundamental to the build process. Ultimately, the verbose output reinforces the initial error message and provides additional context for debugging. The consistent error message across different build modes (regular build and verbose build) strengthens the hypothesis that the problem lies in how Dune 3.20.0 handles interface-only modules within the js_of_ocaml context, rather than being a transient or environment-specific issue.

Conclusion

So, there you have it! A new regression in Dune 3.20.0 that affects js_of_ocaml projects using modules without implementation. We've seen the expected behavior, the actual error, how to reproduce it, and the specifications of the environment where it occurs. Hopefully, this detailed breakdown helps you if you encounter this issue, and it provides the Dune team with the information they need to fix it. Keep an eye out for updates, and happy coding!

This regression highlights the importance of thorough testing and clear communication when reporting bugs. By providing a minimal reproducible example and detailed specifications, we make it easier for the maintainers to understand and address the issue. In the OCaml ecosystem, where Dune plays a crucial role in build automation, regressions like this can have a significant impact on developers. Therefore, promptly identifying and reporting these issues is vital for maintaining a smooth development experience. Furthermore, this case underscores the value of understanding the underlying build processes and how different components, such as js_of_ocaml and Dune, interact. A deeper understanding of these interactions not only helps in troubleshooting but also in designing more robust and maintainable projects. As the OCaml ecosystem continues to evolve, staying informed about the latest changes and potential regressions is key to efficient and effective development.