stdlib: Let filelib:find_source() search subdirs

The Design Principles states that an application can have Erlang
source files one level below the "src" directory, and now
filelib:find_source() by default searches one level below "src".

The same applies to "esrc". That directory is only mentioned in
filename(3).

5 files changed, 68 insertions, 23 deletions

diff --git a/lib/kernel/doc/src/kernel_app.xml b/lib/kernel/doc/src/kernel_app.xml
index e5ac031539..0762cebc94 100644
--- a/lib/kernel/doc/src/kernel_app.xml
+++ b/lib/kernel/doc/src/kernel_app.xml
@@ -4,7 +4,7 @@
 <appref>
   <header>
     <copyright>
-      <year>1996</year><year>2017</year>
+      <year>1996</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -469,8 +469,12 @@ MaxT = TickTime + TickTime / 4</code>
           <item><c>ObjSuffix = string()</c></item>
           <item><c>SrcSuffix = string()</c></item>
         </list>
-        <p>Specifies a list of rules for use by <c>filelib:find_file/2</c> and
-          <c>filelib:find_source/2</c>. If this is set to some other value
+        <p>Specifies a list of rules for use by
+	  <seealso marker="stdlib:filelib#find_file/2">
+	  <c>filelib:find_file/2</c></seealso>
+	  <seealso marker="stdlib:filelib#find_source/2">
+	  <c>filelib:find_source/2</c></seealso>
+          If this is set to some other value
           than the empty list, it replaces the default rules. Rules can be
           simple pairs of directory suffixes, such as <c>{"ebin",
           "src"}</c>, which are used by <c>filelib:find_file/2</c>, or
@@ -478,6 +482,16 @@ MaxT = TickTime + TickTime / 4</code>
           file name extensions, for example <c>[{".beam", ".erl", [{"ebin",
           "src"}]}</c>, which are used by <c>filelib:find_source/2</c>. Both
           kinds of rules can be mixed in the list.</p>
+	  <p>The interpretation of <c>ObjDirSuffix</c> and <c>SrcDirSuffix</c>
+	  is as follows: if the end of the directory name where an
+	  object is located matches <c>ObjDirSuffix</c>, then the
+	  name created by replacing <c>ObjDirSuffix</c> with
+	  <c>SrcDirSuffix</c> is expanded by calling
+	  <seealso marker="stdlib:filelib#wildcard/1">
+	  <c>filelib:wildcard/1</c></seealso>, and the first regular
+	  file found among the matches is the source file.
+	</p>
+
       </item>
     </taglist>
   </section>
diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml
index 80c4acffdb..11762a3c5a 100644
--- a/lib/stdlib/doc/src/filelib.xml
+++ b/lib/stdlib/doc/src/filelib.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2003</year><year>2017</year>
+      <year>2003</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -267,7 +267,7 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code>
         for a file with the extension <c>.beam</c>, the default rule is to
         look for a file with a corresponding extension <c>.erl</c> by
         replacing the suffix <c>"ebin"</c> of the object directory path with
-        <c>"src"</c>.
+        <c>"src"</c> or <c>"src/*"</c>.
         The file search is done through <seealso
         marker="#find_file/3"><c>find_file/3</c></seealso>. The directory of
         the object file is always tried before any other directory specified
diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml
index 14fd5ef787..1135a6dd80 100644
--- a/lib/stdlib/doc/src/filename.xml
+++ b/lib/stdlib/doc/src/filename.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1997</year><year>2017</year>
+      <year>1997</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -372,15 +372,18 @@ true
           tuples <c>{<anno>BinSuffix</anno>, <anno>SourceSuffix</anno>}</c> and
           is interpreted as follows: if the end of the directory name where the
           object is located matches <c><anno>BinSuffix</anno></c>, then the
-          source code directory has the same name, but with
-          <c><anno>BinSuffix</anno></c> replaced by
-          <c><anno>SourceSuffix</anno></c>. <c><anno>Rules</anno></c> defaults
+	  name created by replacing <c><anno>BinSuffix</anno></c> with
+          <c><anno>SourceSuffix</anno></c> is expanded by calling
+	  <seealso marker="filelib#wildcard/1">
+	  <c>filelib:wildcard/1</c></seealso>.
+	  If a regular file is found among the matches, the function
+	  returns that location together with <c><anno>Options</anno></c>.
+          Otherwise the next rule is tried, and so on.</p>
+        <p><c><anno>Rules</anno></c> defaults
           to:</p>
         <code type="none">
-[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]</code>
-        <p>If the source file is found in the resulting directory, the function
-          returns that location together with <c><anno>Options</anno></c>.
-          Otherwise the next rule is tried, and so on.</p>
+[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"},
+ {"ebin", "src/*"}, {"ebin", "esrc/*"}]</code>
         <p>The function returns <c>{<anno>SourceFile</anno>,
           <anno>Options</anno>}</c> if it succeeds.
           <c><anno>SourceFile</anno></c> is the absolute path to the source
diff --git a/lib/stdlib/src/filelib.erl b/lib/stdlib/src/filelib.erl
index d7c313f214..a9c055f72d 100644
--- a/lib/stdlib/src/filelib.erl
+++ b/lib/stdlib/src/filelib.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1997-2017. All Rights Reserved.
+%% Copyright Ericsson AB 1997-2018. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -544,17 +544,16 @@ default_search_rules() ->
      {"", ".c", c_source_search_rules()},
      {"", ".in", basic_source_search_rules()},
      %% plain old directory rules, backwards compatible
-     {"", ""},
-     {"ebin","src"},
-     {"ebin","esrc"}
-    ].
+     {"", ""}] ++ erl_source_search_rules().
 
 basic_source_search_rules() ->
     (erl_source_search_rules()
      ++ c_source_search_rules()).
 
 erl_source_search_rules() ->
-    [{"ebin","src"}, {"ebin","esrc"}].
+    [{"ebin","src"}, {"ebin","esrc"},
+     {"ebin",filename:join("src", "*")},
+     {"ebin",filename:join("esrc", "*")}].
 
 c_source_search_rules() ->
     [{"priv","c_src"}, {"priv","src"}, {"bin","c_src"}, {"bin","src"}, {"", "src"}].
@@ -634,8 +633,16 @@ try_dir_rule(Dir, Filename, From, To) ->
 	    Src = filename:join(NewDir, Filename),
 	    case is_regular(Src) of
 		true -> {ok, Src};
-		false -> error
+		false -> find_regular_file(wildcard(Src))
 	    end;
 	false ->
 	    error
     end.
+
+find_regular_file([]) ->
+    error;
+find_regular_file([File|Files]) ->
+    case is_regular(File) of
+        true -> {ok, File};
+        false -> find_regular_file(Files)
+    end.
diff --git a/lib/stdlib/test/filelib_SUITE.erl b/lib/stdlib/test/filelib_SUITE.erl
index c94821bc75..261acb70ad 100644
--- a/lib/stdlib/test/filelib_SUITE.erl
+++ b/lib/stdlib/test/filelib_SUITE.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 2005-2017. All Rights Reserved.
+%% Copyright Ericsson AB 2005-2018. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@
 	 wildcard_one/1,wildcard_two/1,wildcard_errors/1,
 	 fold_files/1,otp_5960/1,ensure_dir_eexist/1,ensure_dir_symlink/1,
 	 wildcard_symlink/1, is_file_symlink/1, file_props_symlink/1,
-         find_source/1]).
+         find_source/1, find_source_subdir/1]).
 
 -import(lists, [foreach/2]).
 
@@ -47,7 +47,7 @@ all() ->
     [wildcard_one, wildcard_two, wildcard_errors,
      fold_files, otp_5960, ensure_dir_eexist, ensure_dir_symlink,
      wildcard_symlink, is_file_symlink, file_props_symlink,
-     find_source].
+     find_source, find_source_subdir].
 
 groups() -> 
     [].
@@ -559,3 +559,24 @@ find_source(Config) when is_list(Config) ->
     {ok, ParserYrl} = filelib:find_file(ParserYrlName, ParserYrlDir),
     {ok, ParserYrl} = filelib:find_file(ParserYrlName, ParserYrlDir, []),
     ok.
+
+find_source_subdir(Config) when is_list(Config) ->
+    BeamFile = code:which(inets), % Located in lib/inets/src/inets_app/
+    BeamName = filename:basename(BeamFile),
+    BeamDir = filename:dirname(BeamFile),
+    SrcName = filename:basename(BeamFile, ".beam") ++ ".erl",
+
+    {ok, SrcFile} = filelib:find_source(BeamName, BeamDir),
+    SrcName = filename:basename(SrcFile),
+
+    {error, not_found} =
+        filelib:find_source(BeamName, BeamDir,
+                            [{".beam",".erl",[{"ebin","src"}]}]),
+    {ok, SrcFile} =
+        filelib:find_source(BeamName, BeamDir,
+                            [{".beam",".erl",
+                              [{"ebin",filename:join("src", "*")}]}]),
+
+    {ok, SrcFile} = filelib:find_file(SrcName, BeamDir),
+
+    ok.