Document the enhancements for DEPEND and INCLUDE and use a better example

Reviewed-by: Emilia Käsper <emilia@openssl.org>

1 files changed, 59 insertions, 21 deletions

diff --git a/Configurations/README.design b/Configurations/README.design
index d9059375fc..5777e72441 100644
--- a/Configurations/README.design
+++ b/Configurations/README.design
@@ -91,6 +91,7 @@ depends on the library 'libssl' to function properly.
     
     GENERATE[buildinf.h]=../util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)"
     DEPEND[buildinf.h]=../Makefile
+    DEPEND[../util/mkbuildinf.pl]=../util/Foo.pm
 
 This is the build.info file in 'crypto', and it tells us a little more
 about what's needed to produce 'libcrypto'.  LIBS is used again to
@@ -104,7 +105,8 @@ source files, 'crypto/aes.c', 'crypto/evp.c' and 'crypto/cversion.c'.
 It also shows us that building the object file inferred from
 'crypto/cversion.c' depends on 'crypto/buildinf.h'.  Finally, it 
 also shows the possibility to declare how some files are generated
-using some script, in this case a perl script.
+using some script, in this case a perl script, and how such scripts
+can be declared to depend on other files, in this case a perl module.
 
 Two things are worth an extra note:
 
@@ -159,6 +161,7 @@ information comes down to this:
     
     GENERATE[crypto/buildinf.h]=util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)"
     DEPEND[crypto/buildinf.h]=Makefile
+    DEPEND[util/mkbuildinf.pl]=util/Foo.pm
 
 
 A few notes worth mentioning:
@@ -169,13 +172,14 @@ PROGRAMS may be used to declare programs only.
 
 ENGINES may be used to declare engines only.
 
-The indexes for SOURCE, INCLUDE and ORDINALS must only be end product
-files, such as libraries, programs or engines.  The values of SOURCE
+The indexes for SOURCE and ORDINALS must only be end product files,
+such as libraries, programs or engines.  The values of SOURCE
 variables must only be source files (possibly generated)
 
-DEPEND shows a relationship between different produced files, such
-as a program depending on a library, or between an object file and
-some extra source file.
+INCLUDE and DEPEND shows a relationship between different files
+(usually produced files) or between files and directories, such as a
+program depending on a library, or between an object file and some
+extra source file.
 
 When Configure processes the build.info files, it will take it as
 truth without question, and will therefore perform very few checks.
@@ -266,6 +270,10 @@ section above would be digested into a %unified_info table:
                     [
                         "libcrypto",
                     ],
+                "util/mkbuildinf.pl" =>
+                    [
+                        "util/Foo.pm",
+                    ],
             },
         "engines" =>
             [
@@ -300,6 +308,10 @@ section above would be digested into a %unified_info table:
                     [
                         "include",
                     ],
+                "util/mkbuildinf.pl" =>
+                    [
+                        "util",
+                    ],
             }
         "libraries" =>
             [
@@ -403,6 +415,8 @@ etc.
 
                         generatesrc(src => "PATH/TO/tobegenerated",
                                     generator => [ "generatingfile", ... ]
+                                    generator_incs => [ "INCL/PATH", ... ]
+                                    generator_deps => [ "dep1", ... ]
                                     incs => [ "INCL/PATH", ... ],
                                     deps => [ "dep1", ... ],
                                     intent => one of "libs", "dso", "bin" );
@@ -413,11 +427,14 @@ etc.
                   expected to be the file to generate from.
                   generatesrc() is expected to analyse and figure out
                   exactly how to apply that file and how to capture
-                  the result.  'incs' and 'deps' are include
-                  directories and files that are used if $(CC) used as
-                  an intermediary step when generating the end product
-                  (the file indicated by 'src').  'intent' indicates
-                  what the generated file is going to be used for.
+                  the result.  'generator_incs' and 'generator_deps'
+                  are include directories and files that the generator
+                  file itself depends on.  'incs' and 'deps' are
+                  include directories and files that are used if $(CC)
+                  is used as an intermediary step when generating the
+                  end product (the file indicated by 'src').  'intent'
+                  indicates what the generated file is going to be
+                  used for.
 
     src2obj     - function that produces build file lines to build an
                   object file from source files and associated data.
@@ -538,7 +555,7 @@ programs and all intermediate files, using the rule generating
 functions defined in the build-file template.
 
 As an example with the smaller build.info set we've seen as an
-example, producing the rules to build 'libssl' would result in the
+example, producing the rules to build 'libcrypto' would result in the
 following calls:
 
     # Note: libobj2shlib will only be called if shared libraries are
@@ -548,20 +565,41 @@ following calls:
     # to the implementation to decide which to use as input.
     # Note 3: common.tmpl peals off the ".o" extension from all object
     # files, as the platform at hand may have a different one.
-    libobj2shlib(shlib => "libssl",
-                 lib => "libssl",
-                 objs => [ "ssl/tls" ],
-                 deps => [ "libcrypto" ]
-                 ordinals => [ "ssl", "util/libssl.num" ]);
+    libobj2shlib(shlib => "libcrypto",
+                 lib => "libcrypto",
+                 objs => [ "crypto/aes", "crypto/evp", "crypto/cversion" ],
+                 deps => [  ]
+                 ordinals => [ "crypto", "util/libcrypto.num" ]);
+
+    obj2lib(lib => "libcrypto"
+            objs => [ "crypto/aes", "crypto/evp", "crypto/cversion" ]);
 
-    obj2lib(lib => "libssl"
-            objs => [ "ssl/tls" ]);
+    src2obj(obj => "crypto/aes"
+            srcs => [ "crypto/aes.c" ],
+            deps => [ ],
+            incs => [ "include" ],
+            intent => "lib");
 
-    src2obj(obj => "ssl/tls"
-            srcs => [ "ssl/tls.c" ],
+    src2obj(obj => "crypto/evp"
+            srcs => [ "crypto/evp.c" ],
             deps => [ ],
             incs => [ "include" ],
             intent => "lib");
 
+    src2obj(obj => "crypto/cversion"
+            srcs => [ "crypto/cversion.c" ],
+            deps => [ "crypto/buildinf.h" ],
+            incs => [ "include" ],
+            intent => "lib");
+
+    generatesrc(src => "crypto/buildinf.h",
+                generator => [ "util/mkbuildinf.pl", "\"$(CC)",
+                               "$(CFLAGS)\"", "\"$(PLATFORM)\"" ],
+                generator_incs => [ "util" ],
+                generator_deps => [ "util/Foo.pm" ],
+                incs => [ ],
+                deps => [ ],
+                intent => "lib");
+
 The returned strings from all those calls are then concatenated
 together and written to the resulting build-file.