Don't use CPP in Configurations/unix-Makefile.tmpl
[openssl.git] / Configurations / README.design
index d905937..cae08fc 100644 (file)
@@ -37,12 +37,13 @@ build-file templates, adapted for the platform they are meant for (see
 sections on %unified_info and build-file templates further down).
 
 The variables PROGRAMS, LIBS, ENGINES and SCRIPTS are used to declare
-end products.
+end products.  There are variants for them with '_NO_INST' as suffix
+(PROGRAM_NO_INST etc) to specify end products that shouldn't get
+installed.
 
-The variables SOURCE, DEPEND, INCLUDE and ORDINALS are indexed by a
-produced file, and their values are the source used to produce that
-particular produced file, extra dependencies, include directories
-needed, and ordinal files (explained further below.
+The variables SOURCE, DEPEND and INCLUDE are indexed by a produced
+file, and their values are the source used to produce that particular
+produced file, extra dependencies, and include directories needed.
 
 All their values in all the build.info throughout the source tree are
 collected together and form a set of programs, libraries, engines and
@@ -55,18 +56,15 @@ dependencies.
 
     # build.info
     LIBS=libcrypto libssl
-    ORDINALS[libcrypto]=crypto
-    ORDINALS[libssl]=ssl
     INCLUDE[libcrypto]=include
     INCLUDE[libssl]=include
     DEPEND[libssl]=libcrypto
 
 This is the top directory build.info file, and it tells us that two
-libraries are to be built, there are some ordinals to be used to
-declare what symbols in those libraries are seen as public, the
-include directory 'include/' shall be used throughout when building
-anything that will end up in each library, and that the library
-'libssl' depend on the library 'libcrypto' to function properly.
+libraries are to be built, the include directory 'include/' shall be
+used throughout when building anything that will end up in each
+library, and that the library 'libssl' depend on the library
+'libcrypto' to function properly.
 
     # apps/build.info
     PROGRAMS=openssl
@@ -91,6 +89,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 +103,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:
 
@@ -122,27 +122,33 @@ This is the build.info file in 'ssl/', and it tells us that the
 library 'libssl' is built from the source file 'ssl/tls.c'.
 
     # engines/build.info
-    ENGINES=libossltest
-    SOURCE[libossltest]=e_ossltest.c
-    DEPEND[libossltest]=../libcrypto
-    INCLUDE[libossltest]=../include
-
-This is the build.info file in 'engines/', telling us that an engine
-called 'engines/libossltest' shall be built, that it's source is
+    ENGINES=dasync
+    SOURCE[dasync]=e_dasync.c
+    DEPEND[dasync]=../libcrypto
+    INCLUDE[dasync]=../include
+
+    ENGINES_NO_INST=ossltest
+    SOURCE[ossltest]=e_ossltest.c
+    DEPEND[ossltest]=../libcrypto.a
+    INCLUDE[ossltest]=../include
+
+This is the build.info file in 'engines/', telling us that two engines
+called 'engines/dasync' and 'engines/ossltest' shall be built, that
+dasync's source is 'engines/e_dasync.c' and ossltest's source is
 'engines/e_ossltest.c' and that the include directory 'include/' may
-be used when building anything that will be part of this engine.
-Finally, the engine 'engines/libossltest' depends on the library
-'libcrypto' to function properly.
+be used when building anything that will be part of these engines.
+Also, both engines depend on the library 'libcrypto' to function
+properly.  ossltest is explicitly linked with the static variant of
+the library 'libcrypto'.  Finally, only dasync is being installed, as
+ossltest is only for internal testing.
 
 When Configure digests these build.info files, the accumulated
 information comes down to this:
 
     LIBS=libcrypto libssl
-    ORDINALS[libcrypto]=crypto
     SOURCE[libcrypto]=crypto/aes.c crypto/evp.c crypto/cversion.c
     DEPEND[crypto/cversion.o]=crypto/buildinf.h
     INCLUDE[libcrypto]=include
-    ORDINALS[libssl]=ssl
     SOURCE[libssl]=ssl/tls.c
     INCLUDE[libssl]=include
     DEPEND[libssl]=libcrypto
@@ -152,13 +158,19 @@ information comes down to this:
     INCLUDE[apps/openssl]=. include
     DEPEND[apps/openssl]=libssl
 
-    ENGINES=engines/ossltest
+    ENGINES=engines/dasync
+    SOURCE[engines/dasync]=engines/e_dasync.c
+    DEPEND[engines/dasync]=libcrypto
+    INCLUDE[engines/dasync]=include
+
+    ENGINES_NO_INST=engines/ossltest
     SOURCE[engines/ossltest]=engines/e_ossltest.c
-    DEPEND[engines/ossltest]=libcrypto
+    DEPEND[engines/ossltest]=libcrypto.a
     INCLUDE[engines/ossltest]=include
     
     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 +181,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
-variables must only be source files (possibly generated)
+The indexes for SOURCE 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.
@@ -209,15 +222,14 @@ indexes:
                pairs.  These are directly inferred from the INCLUDE
                variables in build.info files.
 
+  install   => a hash table containing 'type' => [ 'file' ... ] pairs.
+               The types are 'programs', 'libraries', 'engines' and
+               'scripts', and the array of files list the files of
+               that type that should be installed.
+
   libraries => a list of libraries.  These are directly inferred from
                the LIBS variable in build.info files.
 
-  ordinals  => a hash table containing 'file' => [ 'word', 'ordfile' ]
-               pairs.  'file' and 'word' are directly inferred from
-               the ORDINALS variables in build.info files, while the
-               file 'ofile' comes from internal knowledge in
-               Configure.
-
   programs  => a list of programs.  These are directly inferred from
                the PROGRAMS variable in build.info files.
 
@@ -258,17 +270,26 @@ section above would be digested into a %unified_info table:
                     [
                         "crypto/buildinf.h",
                     ],
-                "engines/ossltest" =>
+                "engines/dasync" =>
                     [
                         "libcrypto",
                     ],
+                "engines/ossltest" =>
+                    [
+                        "libcrypto.a",
+                    ],
                 "libssl" =>
                     [
                         "libcrypto",
                     ],
+                "util/mkbuildinf.pl" =>
+                    [
+                        "util/Foo.pm",
+                    ],
             },
         "engines" =>
             [
+                "engines/dasync",
                 "engines/ossltest",
             ],
         "generate" =>
@@ -300,25 +321,32 @@ section above would be digested into a %unified_info table:
                     [
                         "include",
                     ],
+                "util/mkbuildinf.pl" =>
+                    [
+                        "util",
+                    ],
             }
-        "libraries" =>
-            [
-                "libcrypto",
-                "libssl",
-            ],
-        "ordinals" =>
+        "install" =>
             {
-                "libcrypto" =>
+                "engines" =>
                     [
-                        "crypto",
-                        "util/libcrypto.num",
+                        "engines/dasync",
                     ],
-                "libssl" =>
+                "libraries" =>
                     [
-                        "ssl",
-                        "util/libssl.num",
+                        "libcrypto",
+                        "libssl",
                     ],
-            },
+                "programs" =>
+                    [
+                        "apps/openssl",
+                    ],
+           },
+        "libraries" =>
+            [
+                "libcrypto",
+                "libssl",
+            ],
         "programs" =>
             [
                 "apps/openssl",
@@ -348,6 +376,14 @@ section above would be digested into a %unified_info table:
                     [
                         "crypto/evp.c",
                     ],
+                "engines/e_dasync.o" =>
+                    [
+                        "engines/e_dasync.c",
+                    ],
+                "engines/dasync" =>
+                    [
+                        "engines/e_dasync.o",
+                    ],
                 "engines/e_ossltest.o" =>
                     [
                         "engines/e_ossltest.c",
@@ -403,6 +439,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 +451,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.
@@ -464,8 +505,7 @@ etc.
                         libobj2shlib(shlib => "PATH/TO/shlibfile",
                                      lib => "PATH/TO/libfile",
                                      objs => [ "PATH/TO/objectfile", ... ],
-                                     deps => [ "PATH/TO/otherlibfile", ... ],
-                                     ordinals => [ "word", "/PATH/TO/ordfile" ]);
+                                     deps => [ "PATH/TO/otherlibfile", ... ]);
 
                   'lib' has the intended library file name *without*
                   extension, libobj2shlib is expected to add that.
@@ -474,11 +514,7 @@ etc.
                   libraries (also *without* extension) this library
                   needs to be linked with.  'objs' has the list of
                   object files (also *without* extension) to build
-                  this library.  'ordinals' MAY be present, and when
-                  it is, its value is an array where the word is
-                  "crypto" or "ssl" and the file is one of the ordinal
-                  files util/libcrypto.num or util/libssl.num in the
-                  source directory.
+                  this library.
 
                   This function has a choice; it can use the
                   corresponding static library as input to make the
@@ -538,7 +574,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 +584,40 @@ 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 => [  ]);
+
+    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.