Document "secret" behaviors

[Khady]

Pardon the title, I'm not sure how to word the idea in only a few words.

Dune has some default flags and some behaviors that change depending on some things like the profile. But those things aren't documented anywhere. For example the -g flag is added (all the time AFAIK?) and can't be erased even when overwriting the list of flags. There is also -opaque, which might be inserted sometimes, but it's not clear when and if it can be controlled. I'm guessing there are other things like this.

At first glance it seems that a profile is just a name, so all the changes happening behind the curtain get very surprising. At ahrefs we have the default profile (I think it's dev) almost all the time, even when we build production binaries. It's just easier this way, we don't have to make sure that --profile=release is not forgotten anywhere. And a profile for the CI that is more strict. Every once in a while I have to jump to dune source code to make sure that a flag we want to use isn't going to be added or erased by accident.

(env
 (ci_build
  (flags ((:include dune_flags.sexp) -warn-error +A-d)))
 (_
  (flags (:include dune_flags.sexp))))

[rr0gi]

bumping the issue

[Alizter]

I've actually been thinking about this today. We are currently in the middle of a big documentation rewrite by @emillon so it would be a good opportunity to address this issue.

The issue of the -g flag is also something of interest, but we don't have any plans to make it configurable at the moment. @rgrinberg do you think making -g user configurable is a good idea?

[Khady]

It would also be interesting to mention how it affects ppx. I remember some discussions about passing an argument like profile=xxx when a ppx is launched, which some ppx use to generate (or not) different code when the mode is release.

[Khady]

Real world example of why we need this doc, I'm trying to see what happens when switching between different profiles that have the same flags (or almost the same flags) and I end up with very different compilation times. The profile dev is almost twice faster.

time-compilation.sh

#!/usr/bin/env bash

export DUNE_CACHE=disabled
dune build --profile=$1 ahrefs.exe

benchmarks

monorepo/backend/megaindex$ hyperfine -p "dune clean" -L profile dev,release,ci_build "./time-compilation.sh {profile}" 
Benchmark #1: ./time-compilation.sh dev
  Time (mean ± σ):     113.208 s ±  1.025 s    [User: 1460.016 s, System: 374.723 s]
  Range (min … max):   111.671 s … 114.871 s    10 runs

Benchmark #2: ./time-compilation.sh release
  Time (mean ± σ):     223.045 s ±  1.559 s    [User: 1461.203 s, System: 379.472 s]
  Range (min … max):   220.786 s … 225.762 s    10 runs

Benchmark #3: ./time-compilation.sh ci_build
  Time (mean ± σ):     222.388 s ±  1.169 s    [User: 1457.645 s, System: 384.203 s]
  Range (min … max):   220.366 s … 223.824 s    10 runs

Summary
  './time-compilation.sh dev' ran
    1.96 ± 0.02 times faster than './time-compilation.sh ci_build'
    1.97 ± 0.02 times faster than './time-compilation.sh release'

dune

(env
 (ci_build
  (flags
   ((:include dune_flags.sexp)
    -warn-error
    +A-d)))
 (_
  (flags
   (:include dune_flags.sexp))))

dune_flags.sexp

; run `ocamlc -warn-help` for the list of all warnings
(-strict-formats -strict-sequence -short-paths -w +a-4@8-40..42-44-45-48-58-66-68-70-102)

[rgrinberg]

@Alizter one can remove -g already

@Khady Yes, --profile dev enables --opaque which gives faster compilation.