Toggle interface generation with (executables_implicit_empty_intf)

Signed-off-by: Craig Ferguson <me@craigfe.io>

Author: craigfe

doc/dune-files.rst

@@ -91,6 +91,24 @@ Starting from dune 2.0, dune mangles compilation units of executables by
 default. However, this can still be turned off using ``(wrapped_executables
 false)``
 
+.. _executables_implicit_empty_intf:
+
+executables_implicit_empty_intf
+-------------------------------
+
+By default, executables defined via ``(executables(s) ...)`` or ``(test(s)
+...)`` stanzas are compiled with the interface file provided (e.g. ``.mli`` or
+``rei``). Since these modules cannot be used as library dependencies, it's
+common to give them empty interface files to strengthen the compiler's ability
+to detect unused values in these modules.
+
+Starting from dune 2.8, an option is available to automatically generate empty
+interface files for executables and tests that don't already have them:
+
+.. code:: scheme
+
+    (executables_implicit_empty_intf true)
+
 .. _explicit-js-mode:
 
 explicit_js_mode
@@ -633,9 +651,8 @@ binary at the same place as where ``ocamlc`` was found.
 Executables can also be linked as object or shared object files. See
 `linking modes`_ for more information.
 
-Starting from dune 2.8, executable modules without interface files (e.g. `.mli`,
-`.rei`) are compiled against empty interfaces in order to improve dead code
-detection.
+Starting from dune 2.8, it's possible to automatically generate empty interface
+files for executables. See `executables_implicit_empty_intf`_.
 
 ``<optional-fields>`` are:
 
@@ -1348,9 +1365,8 @@ running dune runtest you can use the following stanza:
     (libraries alcotest mylib)
     (action (run %{test} -e)))
 
-Starting from dune 2.8, test modules without interface files (e.g. `.mli`,
-`.rei`) are compiled against empty interfaces in order to improve dead code
-detection.
+Starting from dune 2.8, it's possible to automatically generate empty interface
+files for test executables. See `executables_implicit_empty_intf`_.
 
 test
 ----

src/dune_engine/dune_project.ml

@@ -159,6 +159,7 @@ type t =
   ; parsing_context : Univ_map.t
   ; implicit_transitive_deps : bool
   ; wrapped_executables : bool
+  ; executables_implicit_empty_intf : bool
   ; dune_version : Dune_lang.Syntax.Version.t
   ; generate_opam_files : bool
   ; use_standard_c_and_cxx_flags : bool option
@@ -210,6 +211,7 @@ let to_dyn
     ; packages
     ; implicit_transitive_deps
     ; wrapped_executables
+    ; executables_implicit_empty_intf
     ; dune_version
     ; generate_opam_files
     ; use_standard_c_and_cxx_flags
@@ -232,6 +234,7 @@ let to_dyn
           (Package.Name.Map.to_list packages) )
     ; ("implicit_transitive_deps", bool implicit_transitive_deps)
     ; ("wrapped_executables", bool wrapped_executables)
+    ; ("executables_implicit_empty_intf", bool executables_implicit_empty_intf)
     ; ("dune_version", Dune_lang.Syntax.Version.to_dyn dune_version)
     ; ("generate_opam_files", bool generate_opam_files)
     ; ("use_standard_c_and_cxx_flags", option bool use_standard_c_and_cxx_flags)
@@ -550,6 +553,9 @@ let implicit_transitive_deps_default ~lang:_ = true
 let wrapped_executables_default ~(lang : Lang.Instance.t) =
   lang.version >= (2, 0)
 
+let executables_implicit_empty_intf_default ~(lang : Lang.Instance.t) =
+  lang.version >= (3, 0)
+
 let strict_package_deps_default ~(lang : Lang.Instance.t) =
   lang.version >= (3, 0)
 
@@ -593,6 +599,9 @@ let infer ~dir packages =
   in
   let implicit_transitive_deps = implicit_transitive_deps_default ~lang in
   let wrapped_executables = wrapped_executables_default ~lang in
+  let executables_implicit_empty_intf =
+    executables_implicit_empty_intf_default ~lang
+  in
   let explicit_js_mode = explicit_js_mode_default ~lang in
   let strict_package_deps = strict_package_deps_default ~lang in
   let root = dir in
@@ -604,6 +613,7 @@ let infer ~dir packages =
   ; version = None
   ; implicit_transitive_deps
   ; wrapped_executables
+  ; executables_implicit_empty_intf
   ; stanza_parser
   ; project_file
   ; extension_args
@@ -695,6 +705,9 @@ let parse ~dir ~lang ~opam_packages ~file ~dir_status =
              "It is useless since the Merlin configurations are not ambiguous \
               anymore."
            loc lang.syntax (2, 8) ~what:"This field"
+     and+ executables_implicit_empty_intf =
+       field_o_b "executables_implicit_empty_intf"
+         ~check:(Dune_lang.Syntax.since Stanza.syntax (2, 8))
      and+ () = Dune_lang.Versioned_file.no_more_lang
      and+ generate_opam_files =
        field_o_b "generate_opam_files"
@@ -805,6 +818,10 @@ let parse ~dir ~lang ~opam_packages ~file ~dir_status =
        Option.value wrapped_executables
          ~default:(wrapped_executables_default ~lang)
      in
+     let executables_implicit_empty_intf =
+       Option.value executables_implicit_empty_intf
+         ~default:(executables_implicit_empty_intf_default ~lang)
+     in
      let strict_package_deps =
        Option.value strict_package_deps
          ~default:(strict_package_deps_default ~lang)
@@ -864,6 +881,7 @@ let parse ~dir ~lang ~opam_packages ~file ~dir_status =
      ; parsing_context
      ; implicit_transitive_deps
      ; wrapped_executables
+     ; executables_implicit_empty_intf
      ; dune_version
      ; generate_opam_files
      ; use_standard_c_and_cxx_flags
@@ -913,6 +931,8 @@ let set_parsing_context t parser =
 
 let wrapped_executables t = t.wrapped_executables
 
+let executables_implicit_empty_intf t = t.executables_implicit_empty_intf
+
 let () =
   let open Dune_lang.Decoder in
   Extension.register_simple Action_plugin.syntax (return []);

src/dune_engine/dune_project.mli

@@ -173,6 +173,8 @@ val dune_version : t -> Dune_lang.Syntax.Version.t
 
 val wrapped_executables : t -> bool
 
+val executables_implicit_empty_intf : t -> bool
+
 val strict_package_deps : t -> bool
 
 val cram : t -> bool

src/dune_rules/exe_rules.ml

@@ -102,8 +102,8 @@ let with_empty_intf ~sctx ~dir module_ =
   Super_context.add_rule sctx ~dir rule;
   Module.add_file module_ Ml_kind.Intf (Module.File.make Dialect.ocaml name)
 
-let executables_rules ~sctx ~dune_version ~dir ~expander ~dir_contents ~scope
-    ~compile_info ~embed_in_plugin_libraries (exes : Dune_file.Executables.t) =
+let executables_rules ~sctx ~dir ~expander ~dir_contents ~scope ~compile_info
+    ~embed_in_plugin_libraries (exes : Dune_file.Executables.t) =
   (* Use "eobjs" rather than "objs" to avoid a potential conflict with a library
      of the same name *)
   let modules, obj_dir =
@@ -131,7 +131,8 @@ let executables_rules ~sctx ~dune_version ~dir ~expander ~dir_contents ~scope
         let name = Module.name m in
         let m = Pp_spec.pp_module_as pp name m in
         let add_empty_intf =
-          dune_version >= (2, 8)
+          let project = Scope.project scope in
+          Dune_project.executables_implicit_empty_intf project
           && List.mem name ~set:executable_names
           && not (Module.has m ~ml_kind:Intf)
         in
@@ -218,9 +219,8 @@ let rules ~sctx ~dir ~dir_contents ~scope ~expander
     (exes : Dune_file.Executables.t) =
   let compile_info = compile_info ~scope exes in
   let f () =
-    executables_rules exes ~sctx ~dune_version ~dir ~dir_contents ~scope
-      ~expander ~compile_info
-      ~embed_in_plugin_libraries:exes.embed_in_plugin_libraries
+    executables_rules exes ~sctx ~dir ~dir_contents ~scope ~expander
+      ~compile_info ~embed_in_plugin_libraries:exes.embed_in_plugin_libraries
   in
   Buildable_rules.gen_select_rules sctx compile_info ~dir;
   Bootstrap_info.gen_rules sctx exes ~dir compile_info;

test/blackbox-tests/test-cases/implicit-empty-executables.t/bin/dependency.ml test/blackbox-tests/test-cases/executables-implicit-empty-intf.t/bin/dependency.ml

@@ -1,7 +1,11 @@
 Executables with no corresponding `.mli` file will have one generated for them
 by Dune:
 
-  $ echo "(lang dune 2.8)" > dune-project
+  $ cat >dune-project <<EOF
+  > (lang dune 2.8)
+  > (executables_implicit_empty_intf true)
+  > EOF
+
   $ dune build ./bin/executable.exe
   File "bin/executable.ml", line 1, characters 4-10:
   1 | let unused = Dependency.a
@@ -25,20 +29,19 @@ as will test binaries:
   $ cat _build/default/test/test.mli
   (* Auto-generated by Dune *)
 
-Empty `.mli` files are only generated when lang version >= 2.8:
-
-  $ dune clean
-  $ echo "(lang dune 2.7)" > dune-project
-  $ dune build ./bin/executable.exe
-  $ dune runtest
-  $ test ! -f _build/default/bin/executable.mli
-  $ test ! -f _build/default/test/test.mli
-
 If an executable already has an interface, it is preserved:
 
   $ dune clean
-  $ echo "(lang dune 2.8)" > dune-project
   $ dune build ./bin_with_intf/executable.exe
   $ cat _build/default/bin_with_intf/executable.mli
   val a : int
 
+Generation of empty `.mli` files is disabled by default prior to lang 3.0:
+
+  $ dune clean
+  $ echo >dune-project "(lang dune 2.8)"
+  $ dune build ./bin/executable.exe
+  $ dune runtest
+  $ test ! -f _build/default/bin/executable.mli
+  $ test ! -f _build/default/test/test.mli
+