Rename %{root} to %{workspace_root} (#993)

Signed-off-by: Jeremie Dimino <jeremie@dimino.org>

CHANGES.md

@@ -141,6 +141,8 @@ next
   `^` to `deps`
   (#957, @rgrinberg)
 
+- Rename `ROOT` to `workspace_root` in dune files (#993, @diml)
+
 - Lowercase all built-in %{variables} in dune files (#956, @rgrinberg)
 
 - New syntax for naming dependencies: `(deps (:x a b) (:y (glob_files *.c*)))`.

doc/dune-files.rst

@@ -495,7 +495,8 @@ ocamllex
     (rule
       (targets <name>.ml)
       (deps    <name>.mll)
-      (action  (chdir %{root} (run %{bin:ocamllex} -q -o %{targets} %{deps}))))
+      (action  (chdir %{workspace_root}
+                (run %{bin:ocamllex} -q -o %{targets} %{deps}))))
 
 To use a different rule mode, use the long form:
 
@@ -515,7 +516,8 @@ ocamlyacc
     (rule
       (targets <name>.ml <name>.mli)
       (deps    <name>.mly)
-      (action  (chdir %{root} (run %{bin:ocamlyacc} %{deps}))))
+      (action  (chdir %{workspace_root}
+                (run %{bin:ocamlyacc} %{deps}))))
 
 To use a different rule mode, use the long form:
 
@@ -825,19 +827,18 @@ Variables are expanded after the set language is interpreted.
 Variables expansion
 -------------------
 
-Some fields can contains variables of the form ``$(var)`` or ``%{var}`` that are
+Some fields can contains variables of the form ``%{var}`` that are
 expanded by dune.
 
 Dune supports the following variables:
 
--  ``root`` is the relative path to the root of the build
-   context. Note that ``root`` depends on the workspace
-   configuration. As such you shouldn't use ``root`` to denote the
-   root of your project. Use ``project_root`` instead for this purpose
--  ``project_root`` is the root of the current scope. It is typically
-   the toplevel directory of your project and as long as you have at
-   least one ``<package>.opam`` file there, ``project_root`` is
-   independent of the workspace configuration
+- ``project_root`` is the root of the current project. It is typically
+   the toplevel directory of your project and as long as you have a
+   ``dune-project`` file there, ``project_root`` is independent of the
+   workspace configuration
+- ``workspace_root`` is the root of the current workspace. Note that
+  the value of ``workspace_root`` is not constant and depends on
+  whether your project is vendored or not
 -  ``CC`` is the C compiler command line (list made of the compiler
    name followed by its flags) that was used to compile OCaml in the
    current build context
@@ -1051,7 +1052,8 @@ you had setup a rule for every file of the form:
        (rule
         (targets file.pp.ml)
         (deps    file.ml)
-        (action  (with-stdout-to %{targets} (chdir %{root} <action>))))
+        (action  (with-stdout-to %{targets}
+                  (chdir %{workspace_root} <action>))))
 
 The equivalent of a ``-pp <command>`` option passed to the OCaml compiler is
 ``(system "<command> %{input-file}")``.
@@ -1151,8 +1153,8 @@ dune allows a user to organize dependency lists by naming them. The user is
 allowed to assign a group of dependencies a name that can later be referred to
 in actions (like the ``%{deps}`` and ``%{targets}`` built in variables).
 
-One instance where is useful is for naming globs. Here's an example of an
-imaginary bundle command:
+One instance where this is useful is for naming globs. Here's an
+example of an imaginary bundle command:
 
 .. code:: scheme
 
@@ -1166,9 +1168,10 @@ imaginary bundle command:
     (action
      (run %{bin:bundle} index.html -css %{css} -js %{js} -img %{img} -o %{targets})))
 
-Note that such named dependency list can also include unnamed dependencies (like
-``index.html`` in the example above). Also, such user defined names wil shadow
-built in variables. So ``(:root x)`` will shadow the built in ``%{root}``
+Note that such named dependency list can also include unnamed
+dependencies (like ``index.html`` in the example above). Also, such
+user defined names wil shadow built in variables. So
+``(:workspace_root x)`` will shadow the built in ``%{workspace_root}``
 variable.
 
 .. _glob:
@@ -1362,7 +1365,7 @@ of your project. What you should write instead is:
     (rule
      (targets blah.ml)
      (deps    blah.mll)
-     (action  (chdir %{root} (run ocamllex -o %{targets} %{deps}))))
+     (action  (chdir %{workspace_root} (run ocamllex -o %{targets} %{deps}))))
 
 Locks
 -----

doc/migration.rst

@@ -171,6 +171,7 @@ Jbuild                    Dune
 ``${^}``                  ``%{deps}``
 ``${path:file}``          ``%{dep:file}``
 ``${SCOPE_ROOT}``         ``%{project_root}``
+``${ROOT}``               ``%{workspace_root}``
 ``${findlib:..}``         ``%{lib:..}``
 ``${CPP}``                ``%{cpp}``
 ``${CC}``                 ``%{cc}``

src/jbuild.ml

@@ -1299,7 +1299,7 @@ module Rule = struct
       ; action  =
           (loc,
            Chdir
-             (S.virt_var __POS__ "root",
+             (S.virt_var __POS__ "workspace_root",
               Run (S.virt_text __POS__ "ocamllex",
                    [ S.virt_text __POS__ "-q"
                    ; S.virt_text __POS__ "-o"
@@ -1320,7 +1320,7 @@ module Rule = struct
       ; action  =
           (loc,
            Chdir
-             (S.virt_var __POS__ "root",
+             (S.virt_var __POS__ "workspace_root",
               Run (S.virt_text __POS__ "ocamlyacc",
                    [S.virt_var __POS__ "deps"])))
       ; mode

src/menhir.ml

@@ -61,7 +61,8 @@ module Run (P : PARAMS) = struct
   let sources ms =
     List.map ~f:source ms
 
-  (* Expand special variables, such as %{root}, in the stanza's flags. *)
+  (* Expand special variables, such as %{workspace_root}, in the stanza's
+     flags. *)
 
   let flags =
     SC.expand_and_eval_set

src/pform.ml

@@ -113,7 +113,6 @@ module Map = struct
       ; "ocamlopt"       , path ocamlopt
       ; "arch_sixtyfour" , string (string_of_bool context.arch_sixtyfour)
       ; "make"           , make
-      ; "root"           , values [Value.Dir context.build_dir]
       ]
     in
     let uppercased =
@@ -135,6 +134,8 @@ module Map = struct
       ; "ext_dll"        , string context.ext_dll
       ; "ext_exe"        , string context.ext_exe
       ; "profile"        , string context.profile
+      ; "workspace_root" , values [Value.Dir context.build_dir]
+      ; "ROOT"           , renamed_in ~version:(1, 0) ~new_name:"workspace_root"
       ]
     in
     { vars =

src/preprocessing.ml

@@ -397,8 +397,8 @@ let get_ppx_driver sctx ~loc ~scope ~dir_kind pps =
     >>= fun libs ->
     Ok (ppx_driver_exe sctx libs ~dir_kind, driver)
 
-let target_var = String_with_vars.virt_var __POS__ "targets"
-let root_var   = String_with_vars.virt_var __POS__ "root"
+let target_var         = String_with_vars.virt_var __POS__ "targets"
+let workspace_root_var = String_with_vars.virt_var __POS__ "workspace_root"
 
 let cookie_library_name lib_name =
   match lib_name with
@@ -451,7 +451,7 @@ let lint_module sctx ~dir ~dep_kind ~lint ~lib_name ~scope ~dir_kind =
           (fun ~source:_ ~ast:_ -> ())
         | Action (loc, action) ->
           (fun ~source ~ast:_ ->
-             let action = Action.Unexpanded.Chdir (root_var, action) in
+             let action = Action.Unexpanded.Chdir (workspace_root_var, action) in
              Module.iter source ~f:(fun _ (src : Module.File.t) ->
                let src_path = Path.relative dir src.name in
                let bindings = Pform.Map.input_file src_path in
@@ -541,7 +541,7 @@ let make sctx ~dir ~dep_kind ~lint ~preprocess
                   (Redirect
                      (Stdout,
                       target_var,
-                      Chdir (root_var,
+                      Chdir (workspace_root_var,
                              action)))
                   ~loc
                   ~dir

test/blackbox-tests/test-cases/aliases/src/dune

@@ -1,3 +1,3 @@
 (alias
  (name x)
- (action (chdir %{root} (echo "running in .\n"))))
+ (action (chdir %{workspace_root} (echo "running in .\n"))))

test/blackbox-tests/test-cases/aliases/src/foo/bar/dune

@@ -1,3 +1,3 @@
 (alias
  (name x)
- (action (chdir %{root} (echo "running in bar\n"))))
+ (action (chdir %{workspace_root} (echo "running in bar\n"))))

test/blackbox-tests/test-cases/aliases/src/foo/baz/dune

@@ -1,3 +1,3 @@
 (alias
  (name x)
- (action (chdir %{root} (echo "running in baz\n"))))
+ (action (chdir %{workspace_root} (echo "running in baz\n"))))

test/blackbox-tests/test-cases/inline_tests/dune-file/dune

@@ -12,7 +12,7 @@
     (echo "\n")
     (echo "let () = print_int 43;;")))
   (flags inline-test-runner %{library-name}
-          -source-tree-root %{root} -diff-cmd -)))
+          -source-tree-root %{workspace_root} -diff-cmd -)))
 
 (library
  (name foo_tests)

test/blackbox-tests/test-cases/inline_tests/run.t

@@ -30,7 +30,7 @@
        (inline-test-runner
         %{library-name}
         -source-tree-root
-        %{root}
+        %{workspace_root}
         -diff-cmd
         -))
       (generate_runner

test/blackbox-tests/test-cases/shadow-bindings/dune

@@ -1,8 +1,8 @@
 
 (alias
  (name runtest)
- (deps (:root foo))
- (action (echo %{root})))
+ (deps (:workspace_root foo))
+ (action (echo %{workspace_root})))
 
 (alias
  (name   runtest)