Merge pull request #912 from rgrinberg/migration-manual
Add migration page to manual
This commit is contained in:
Rudi Grinberg
GitHub
commit
f7a4e517fe
118
MIGRATION.md
118
MIGRATION.md
|
|
@ -1,116 +1,4 @@
|
|||
Migrating from Jbuilder to Dune
|
||||
===============================
|
||||
jbuilder has been renamed to dune. Refer to the manual for details of the
|
||||
migration:
|
||||
|
||||
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 simply `dune`
|
||||
- projects now have a `dune-project` file at their root
|
||||
- `jbuild-ignore` files are replaced by `ignored_subdirs` stanzas in
|
||||
`dune` files
|
||||
- `jbuild-workspace` are replaced by `dune-workspace` files
|
||||
- `jbuild-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.
|
||||
[manual](http://dune.readthedocs.io/en/latest/migration.html).
|
||||
|
|
|
|||
|
|
@ -142,6 +142,13 @@ Support
|
|||
If you have questions about jbuilder, you can send an email to
|
||||
ocaml-core@googlegroups.com or [open a ticket on github][issues].
|
||||
|
||||
|
||||
Migration from jbuilder
|
||||
-----------------------
|
||||
|
||||
Migration from jbuilder to dune is described in the
|
||||
[manual](http://dune.readthedocs.io/en/latest/migration.html).
|
||||
|
||||
Status
|
||||
------
|
||||
|
||||
|
|
|
|||
|
|
@ -22,3 +22,4 @@ Welcome to jbuilder's documentation!
|
|||
menhir
|
||||
faq
|
||||
known-issues
|
||||
migration
|
||||
|
|
|
|||
|
|
@ -1071,8 +1071,12 @@ syntax:
|
|||
``(alias src/runtest)``, ``(alias src/foo/bar/runtest)``, ...
|
||||
- ``(glob_files <glob>)``: depend on all files matched by ``<glob>``, see the
|
||||
:ref:`glob <glob>` for details
|
||||
|
||||
.. _source_tree:
|
||||
|
||||
- ``(source_tree <dir>)``: depend on all source files in the subtree with root
|
||||
``<dir>``
|
||||
|
||||
- ``(universe)``: depend on everything in the universe. This is for
|
||||
cases where dependencies are too hard to specify. Note that Jbuilder
|
||||
will not be able to cache the result of actions that depend on the
|
||||
|
|
|
|||
|
|
@ -0,0 +1,172 @@
|
|||
*********
|
||||
Migration
|
||||
*********
|
||||
|
||||
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 follows:
|
||||
|
||||
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.
|
||||
|
||||
Check List
|
||||
==========
|
||||
|
||||
This section is a concise list of migration tasks that will be required to
|
||||
transition from jbuilder to dune.
|
||||
|
||||
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 simply `dune`
|
||||
- projects now have a `dune-project` file at their root
|
||||
- `jbuild-ignore` files are replaced by `ignored_subdirs` stanzas in
|
||||
`dune` files
|
||||
- `jbuild-workspace` are replaced by `dune-workspace` files
|
||||
- `jbuild-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.
|
||||
|
||||
Variable Syntax
|
||||
---------------
|
||||
|
||||
``${foo} and $(foo)`` are no longer valid variable syntax in dune files.
|
||||
Variables are defined as ``%{foo}``. This change is done to simplify
|
||||
interoperability with bash commands which also use teh ``${foo}`` syntax.
|
||||
|
||||
``(files_recursively_in ..)`` is removed
|
||||
----------------------------------------
|
||||
|
||||
The ``files_recursively_in`` dependency specification is invalid in dune files.
|
||||
A :ref:`source_tree <source_tree>` stanza has been introduced to reflect the
|
||||
actual function of this stanza.
|
||||
|
||||
Escape Sequences
|
||||
----------------
|
||||
|
||||
Invalid escape sequences of the form ``\x`` where ``x`` is a character other
|
||||
than ``[0-9]``, ``x``, ``n``, ``r``, ``t``, ``b`` are not allowed in dune files.
|
||||
|
||||
Comments Syntax
|
||||
---------------
|
||||
|
||||
Block comments of the form ``#| ... |#`` and comments of the form ``#;`` are not
|
||||
supported in dune files.
|
||||
|
||||
Renamed Variables
|
||||
-----------------
|
||||
|
||||
The following table consists of variables than have been renamed in dune:
|
||||
|
||||
======== ===========
|
||||
Jbuild Dune
|
||||
======== ===========
|
||||
``${@}`` ``%{targets}``
|
||||
``${^}`` ``%{deps}``
|
||||
``${<}`` ``%{deps[0]}``
|
||||
======== ===========
|
||||
Loading…
Reference in New Issue