From f36fd54017cdbf8f549ec9ad19e8bf4e76c8a8aa Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Sun, 24 Jun 2018 15:04:46 +0630 Subject: [PATCH 1/2] Add migration page to manual This includes the old migration page + a simple migration check list Signed-off-by: Rudi Grinberg --- doc/index.rst | 1 + doc/jbuild.rst | 4 ++ MIGRATION.md => doc/migration.rst | 92 +++++++++++++++++++++++++------ 3 files changed, 79 insertions(+), 18 deletions(-) rename MIGRATION.md => doc/migration.rst (65%) diff --git a/doc/index.rst b/doc/index.rst index 2e42d9d7..ebf6add4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -22,3 +22,4 @@ Welcome to jbuilder's documentation! menhir faq known-issues + migration diff --git a/doc/jbuild.rst b/doc/jbuild.rst index 166b54d4..5744341d 100644 --- a/doc/jbuild.rst +++ b/doc/jbuild.rst @@ -1070,8 +1070,12 @@ syntax: ``(alias src/runtest)``, ``(alias src/foo/bar/runtest)``, ... - ``(glob_files )``: depend on all files matched by ````, see the :ref:`glob ` for details + +.. _source_tree: + - ``(source_tree )``: depend on all source files in the subtree with root ```` + - ``(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 diff --git a/MIGRATION.md b/doc/migration.rst similarity index 65% rename from MIGRATION.md rename to doc/migration.rst index dfc58c3b..18a93860 100644 --- a/MIGRATION.md +++ b/doc/migration.rst @@ -1,12 +1,13 @@ -Migrating from Jbuilder to Dune -=============================== +********* +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. +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 @@ -14,9 +15,10 @@ 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: +The plan is as follows: -### July 2018: release of Dune 1.0.0 +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`. @@ -27,7 +29,8 @@ 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 +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 @@ -38,7 +41,8 @@ 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 +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 @@ -49,16 +53,24 @@ 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 +January 2020: the jbuilder binary goes away +------------------------------------------- The `dune` package no longer installs a `jbuilder` binary. The rest is unchanged. -### Distant future +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 ----------------------- @@ -79,7 +91,8 @@ Dune. The most notable ones are the following: Following are detailed explanation of the differences between the Jbuilder configuration files and the Dune ones. -### dune-project files +dune-project files +------------------ These are a new kind of file. With Jbuilder, projects used to be identified by the presence of at least one `.opam` file in a @@ -91,19 +104,23 @@ 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 + +- 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 +dune files +---------- These are the same as `jbuild` files. -### dune-workspace +dune-workspace +-------------- These are the same as `jbuild-workspace` files. @@ -114,3 +131,42 @@ 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 ` 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]}`` +======== =========== From c07e0655fb8450a1a74707ae8c556c5c394517fc Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Mon, 25 Jun 2018 15:54:32 +0630 Subject: [PATCH 2/2] Refer to migration page from manual and readme Signed-off-by: Rudi Grinberg --- MIGRATION.md | 4 ++++ README.md | 7 +++++++ 2 files changed, 11 insertions(+) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 00000000..47bd8140 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,4 @@ +jbuilder has been renamed to dune. Refer to the manual for details of the +migration: + +[manual](http://dune.readthedocs.io/en/latest/migration.html). diff --git a/README.md b/README.md index dca8a720..72801acc 100644 --- a/README.md +++ b/README.md @@ -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 ------