4.2 KiB
Migrating from Jbuilder to Dune
Dune was initially called Jbuilder. Up to mid-2018, the package was
still called jbuilder
which only installed a jbuilder
binary. This
document explain how the migration to Dune will happen.
Timeline
The general idea is that the migration is gradual and existing Jbuilder projects don't need to be updated all at once. We encourage users to switch their development repositories and continue their usual release cycle. There is no need to re-release existing packages just to switch to Dune immediately.
The plan is as follow:
July 2018: release of Dune 1.0.0
First release of the opam package dune
. The jbuilder
package
becomes a transitional package that depends on dune
.
The dune
package installs two binaries: dune
and jbuilder
. These
two binaries are exactly the same and they work on both Jbuilder and
Dune projects. Additionally they recognize both Jbuilder and Dune
configuration files. The new Dune configuration files are described
later in this document.
January 2019: deprecation of Jbuilder
At this point, the jbuilder
binary emits a warning on every startup
inviting users to switch to dune
. When encountering jbuild
or
other Jbuilder configuration files, both binaries emit a warning. The
rest is unchanged.
During this period, it makes sense for projects to do new releases just to switch to Dune if none of their existing releases is using Dune.
July 2019: support for Jbuilder is dropped
jbuilder
is now a dummy executable that always exit with an error
message on startup. dune
no longer reads jbuild
or other Jbuidler
configuration files but still prints a warning when encountering
them.
At this point, a conflict with newer versions of dune
will be added
to all opam packages that rely on the jbuilder
binary or Jbuilder
configuration files.
January 2020: the jbuilder binary goes away
The dune
package no longer installs a jbuilder
binary. The rest is
unchanged.
Distant future
Once we are sure there are no more jbuild
files out there, Dune will
completely ignore jbuild
and other Jbuilder configuration files.
New configuration files
Until July 2019, dune
will still read jbuild
and other Jbuilder
configuration files. There is no change in these files.
However, based on the experience acquired since the first release of Jbuilder, we made a few changes in the configuration files read by Dune. The most notable ones are the following:
jbuild
files are renamed simplydune
- projects now have a
dune-project
file at their root jbuild-ignore
files are replaced byignored_subdirs
stanzas indune
filesjbuild-workspace
are replaced bydune-workspace
filesjbuild-workspace<suffix>
files no longer mean anything
Following are detailed explanation of the differences between the Jbuilder configuration files and the Dune ones.
dune-project files
These are a new kind of file. With Jbuilder, projects used to be
identified by the presence of at least one <package>.opam
file in a
directory. This will still be supported until July 2019, however as
Jbuilder evolved it became clear that we needed project files, so Dune
introduces dune-project
files to mark the root of projects.
Eventually, we are hoping that Dune will generate opam files. So users
will only have to write a dune-project
file.
The purpose of this file is to:
- delimit projects in larger workspaces
- set a few project-wide parameters, such as the name, the version of the Dune language in use or specification of extra features (plugins) used in the project
Eventually, for users who wish to do so it should be possible to centralize all the configuration of a project in this file.
dune files
These are the same as jbuild
files.
dune-workspace
These are the same as jbuild-workspace
files.
When looking for the root of the workspace, Jbuilder also looks for
files whose name start with jbuild-workspace
, such as
jbuild-workspace.in
. This rule will be kept until July 2019, however
it is not preserved for dune-workspace
files. I.e. a
dune-workspace.in
file means nothing.
This rule was only useful when we didn't have project files.