Merge pull request ocaml#1810 from rgrinberg/tweak-errors

Improve error message & add docs

.gitignore

@@ -11,4 +11,4 @@ bootstrap.cmo
 bootstrap.exe
 Makefile.dev
 src/setup.ml
-/_build_bootstrap
+/_boot

.travis-ci.sh

@@ -92,9 +92,9 @@ case "$TARGET" in
     ./boot.exe
     echo -en "travis_fold:end:dune.boot\r"
     if [ $WITH_OPAM -eq 1 ] ; then
-      _build_bootstrap/install/default/bin/dune runtest && \
-      _build_bootstrap/install/default/bin/dune build @test/blackbox-tests/runtest-js && \
-      ! _build_bootstrap/install/default/bin/dune build @test/fail-with-background-jobs-running
+      _boot/install/default/bin/dune runtest && \
+      _boot/install/default/bin/dune build @test/blackbox-tests/runtest-js && \
+      ! _boot/install/default/bin/dune build @test/fail-with-background-jobs-running
       RESULT=$?
       if [ $UPDATE_OPAM -eq 0 ] ; then
         rm -rf ~/.opam

src/c_sources.ml

@@ -80,16 +80,17 @@ let make (d : _ Dir_with_dune.t)
             | Some source -> (loc, source)
             | None ->
               Errors.fail loc "%s does not exist as a C source. \
-                               One of %s must be present"
-                s (String.enumerate_or (C.Kind.possible_fns kind s))
+                               %s must be present"
+                s (String.enumerate_one_of (C.Kind.possible_fns kind s))
           )
         in
         let names =
           Option.value ~default:Ordered_set_lang.standard in
         let c = eval C.Kind.C c_sources.c c_name (names lib.c_names) in
         let cxx = eval C.Kind.Cxx c_sources.cxx cxx_name (names lib.cxx_names) in
         let all = String.Map.union c cxx ~f:(fun _ (_loc1, c) (loc2, cxx) ->
-          Errors.fail loc2 "%a source file is invalid because %a exists"
+          Errors.fail loc2 "%a and %a have conflicting names. \
+                            You must rename one of them."
             Path.pp_in_source (C.Source.path cxx)
             Path.pp_in_source (C.Source.path c)
         ) in

src/c_sources.mli

@@ -1,3 +1,5 @@
+(** This module loads and validates C/C++ sources from directories. *)
+
 open Stdune
 
 type t
@@ -6,11 +8,16 @@ val empty : t
 
 val for_lib : t -> dir:Path.t -> name:Lib_name.t -> C.Sources.t
 
+(** [load_sources dir ~files] will load the C sources in [dir] into a two double
+    map. The first level will is keyed by C vs. C++ sources. The second level is
+    keyed by the object name of the source. *)
 val load_sources
   :  dir:Path.t
   -> files:String.Set.t
   -> C.Source.t String.Map.t C.Kind.Dict.t
 
+(** [make stanzas ~c_sources] will load and validate C/C++ sources. [c_sources]
+    should be a two level map such as the one returned by [load_sources] *)
 val make
   :  Stanza.t list Dir_with_dune.t
   -> c_sources:C.Source.t String.Map.t C.Kind.Dict.t

src/dir_contents.ml

@@ -437,7 +437,8 @@ let rec get sctx ~dir =
                                   | Some d -> File_tree.Dune_file.path d))
                     "%a file %s appears in several directories:\
                     @\n- %a\
-                    @\n- %a"
+                    @\n- %a\
+                    @\nThis is not allowed, please rename one of them."
                     (C.Kind.pp) (C.Source.kind x)
                     name
                     Path.pp_in_source (C.Source.src_dir x)

src/stdune/string.ml

@@ -236,6 +236,9 @@ let enumerate_gen s =
 
 let enumerate_and = enumerate_gen "and"
 let enumerate_or  = enumerate_gen "or"
+let enumerate_one_of = function
+  | [x] -> x
+  | s -> "One of " ^ enumerate_or s
 
 let concat ~sep = function
   | [] -> ""

src/stdune/string.mli

@@ -62,6 +62,9 @@ val enumerate_and : string list -> string
 (** Produces: "x, y or z" *)
 val enumerate_or  : string list -> string
 
+(** Produces: "One of x, y or z" *)
+val enumerate_one_of : t list -> t
+
 module Set : sig
   include Set.S with type elt = t
 

test/blackbox-tests/test-cases/duplicate-c-cxx-obj/run.t

@@ -16,4 +16,5 @@ user intended.
   Error: c file foo appears in several directories:
   - .
   - sub
+  This is not allowed, please rename one of them.
   [1]

test/blackbox-tests/test-cases/duplicate-c-cxx/run.t

@@ -4,7 +4,7 @@ c_names and cxx_names with overlapping names in the same stanza
   File "dune", line 4, characters 12-15:
   4 |  (cxx_names foo))
                   ^^^
-  Error: foo.cpp source file is invalid because foo.c exists
+  Error: foo.cpp and foo.c have conflicting names. You must rename one of them.
   [1]
 
 c_names with overlapping names in different stanzas

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

@@ -6,5 +6,5 @@
   File "src/dune", line 4, characters 10-17:
   4 |  (c_names stubs/x))
                 ^^^^^^^
-  Error: x does not exist as a C source. One of x.c must be present
+  Error: x does not exist as a C source. x.c must be present
   [1]