Documentation suggestion: scope of `env` stanzas

[jberdine]

This is just a report of behavior that was, to me, a surprise.

My, perhaps flawed, mental model is that the dune-workspace file has broadest effect, then the dune-project file(s), and then the individual dune files. I was surprised to discover that it was possible to define contexts in dune-workspace using profile names that were only defined in the dune file. Based on my understanding, this violates definition-before-use, so I was surprised. Maybe it is just me who is confused.

For context, the reason to move these definitions out of dune-workspace is that when copying the project directory (containing dune-workspace) into another project and building as a vendored dependency, the dune-workspace file seems to be ignored, while the dune file is not.

[ghost]

That seems like the right mental model to me. What do you mean by defining contexts in dune-workspace using profile names that were only defined in the dune file?

The idea is that all profiles exist, and we can match on the currently active profile in dune files.

[jberdine]

For example, dune-workspace has:

(context (opam (switch sledge) (name dbg) (profile dbg) (merlin)))
(context (opam (switch sledge) (name dbg-opt) (profile dbg-opt)))
(context (opam (switch sledge) (name opt) (profile opt)))

to indicate which profile each context should be build with. Then dune has:

(env
 (dbg
  (flags
   (-w +a-4-9-18-40-42-44-48@50-66 -strict-formats -strict-sequence
     -short-paths -bin-annot -keep-locs -keep-docs -opaque))
  (env-vars
   (PPX_TRACE_ENABLED 1))
  (inline_tests enabled))
 (dbg-opt
  (flags
   (-w -a -noassert -unboxed-types))
  (ocamlopt_flags (-O3))
  (env-vars
   (PPX_TRACE_ENABLED 1))
  (inline_tests disabled))
 (_
  (flags
   (-w -a -noassert -unboxed-types))
  (ocamlopt_flags (-O3))
  (env-vars
   (PPX_TRACE_ENABLED 0))
  (inline_tests disabled)))

to define what each profile means.

If I put that env stanza in dune-workspace, the normal build works fine. But when building as a vendored subdir, the context in effect will/could be something completely different like default, so the catchall case of the env stanza is needed, and so the build does not work if the env stanza is moved from dune to dune-workspace.

[ghost]

Hmm, I see. I'm not sure what can be done here. In general, the idea is that the scope of dune and dune-project files is wider than the one of dune-workspace files. More precisely, in the dune-workspace file you might write things that only work in your setup such as (switch sledge).

That's why dune-workspace files are not composable and we generally don't recommend committing them in repositories.

[ghost]

I thought a bit more about this, and maybe the issue boils down to the fact that we have both "build contexts" and "profiles". i.e., if they were the same, we could effectively define the various profiles in the dune-project and they would be immediately available. In the dune-workspace, we would then only list the profiles we want to build by default, and which opam switch we want to use as a backend.

We could conflate the two notions in version 3 of the language.