Make it possible to specify source files that will only be used for shared libs

[openssl.git] / Configurations / README

diff --git a/Configurations/README b/Configurations/README
index c031884896065fe25bdccfa2f9b53ee1b5fb534b..a5a006e46a348b28132c47b21ce17a6773bd358d 100644 (file)
--- a/Configurations/README
+++ b/Configurations/README
@@ -28,30 +28,6 @@ In each table entry, the following keys are significant:
                            given here, they MUST be as an array of the
                            string such as "MACRO=value", or just
                            "MACRO" for definitions without value.
                            given here, they MUST be as an array of the
                            string such as "MACRO=value", or just
                            "MACRO" for definitions without value.

-        debug_cflags    => Extra compilation flags used when making a
-                           debug build (when Configure receives the
-                           --debug option).  Typically something like
-                           "-g -O0".
-        debug_defines   => Similarly to `debug_cflags', this gets
-                           combined with `defines' during a debug
-                           build.  The value here MUST also be an
-                           array of the same form as for `defines'.
-        release_cflags  => Extra compilation flags used when making a
-                           release build (when Configure receives the
-                           --release option, or doesn't receive the
-                           --debug option).  Typically something like
-                           "-O" or "-O3".
-        release_defines => Similarly to `release_cflags', this gets
-                           combined with `defines' during a release
-                           build.  The value here MUST also be an
-                           array of the same form as for `defines'.
-        thread_cflags   => Extra compilation flags used when
-                           compiling with threading enabled.
-                           Explained further below.  [2]
-        thread_defines  => Similarly to `thread_cflags', this gets
-                           combined with `defines' when threading is
-                           enabled.  The value here MUST also be an
-                           array of the same form as for `defines'.

         shared_cflag    => Extra compilation flags used when
                            compiling for shared libraries, typically
                            something like "-fPIC".
         shared_cflag    => Extra compilation flags used when
                            compiling for shared libraries, typically
                            something like "-fPIC".


@@ -70,9 +46,6 @@ In each table entry, the following keys are significant:
         ex_libs         => Extra libraries that are needed when
                            linking.
 
         ex_libs         => Extra libraries that are needed when
                            linking.
 

-        debug_lflags    => Like debug_cflags, but used when linking.
-        release_lflags  => Like release_cflags, but used when linking.
-

         ar              => The library archive command, the default is
                            "ar".
                            (NOTE: this is here for future use, it's
         ar              => The library archive command, the default is
                            "ar".
                            (NOTE: this is here for future use, it's


@@ -97,6 +70,14 @@ In each table entry, the following keys are significant:
                            this is here for future use, it's not
                            implemented yet)
 
                            this is here for future use, it's not
                            implemented yet)
 

+        thread_scheme   => The type of threads is used on the
+                           configured platform.  Currently known
+                           values are "(unknown)", "pthreads",
+                           "uithreads" (a.k.a solaris threads) and
+                           "winthreads".  Except for "(unknown)", the
+                           actual value is currently ignored but may
+                           be used in the future.  See further notes
+                           below [2].

         dso_scheme      => The type of dynamic shared objects to build
                            for.  This mostly comes into play with
                            engines, but can be used for other purposes
         dso_scheme      => The type of dynamic shared objects to build
                            for.  This mostly comes into play with
                            engines, but can be used for other purposes


@@ -119,7 +100,7 @@ In each table entry, the following keys are significant:
                            string in the list is the name of the build
                            scheme.
                            Currently recognised build schemes are
                            string in the list is the name of the build
                            scheme.
                            Currently recognised build schemes are

-                           "mk1mf" and "unixmake" and "unified".
+                           "unixmake" and "unified".

                            For the "unified" build scheme, this item
                            *must* be an array with the first being the
                            word "unified" and the second being a word
                            For the "unified" build scheme, this item
                            *must* be an array with the first being the
                            word "unified" and the second being a word


@@ -216,7 +197,7 @@ In each table entry, the following keys are significant:
     'inherit_from' that indicate what other configurations to inherit
     data from.  These are resolved recursively.
 
     'inherit_from' that indicate what other configurations to inherit
     data from.  These are resolved recursively.
 

-    Inheritance works as a set of default values that can be overriden
+    Inheritance works as a set of default values that can be overridden

     by corresponding key values in the inheriting configuration.
 
     Note 1: any configuration table can be used as a template.
     by corresponding key values in the inheriting configuration.
 
     Note 1: any configuration table can be used as a template.


@@ -265,7 +246,7 @@ In each table entry, the following keys are significant:
         }
 
 [2] OpenSSL is built with threading capabilities unless the user
         }
 
 [2] OpenSSL is built with threading capabilities unless the user

-    specifies 'no-threads'.  The value of the key 'thread_cflags' may
+    specifies 'no-threads'.  The value of the key 'thread_scheme' may

     be "(unknown)", in which case the user MUST give some compilation
     flags to Configure.
 
     be "(unknown)", in which case the user MUST give some compilation
     flags to Configure.
 


@@ -377,13 +358,32 @@ sense at all to just have a rename like that (why not just use
 "libbar" everywhere?), it does make sense when it can be used
 conditionally.  See a little further below for an example.
 
 "libbar" everywhere?), it does make sense when it can be used
 conditionally.  See a little further below for an example.
 

+In some cases, it's desirable to include some source files in the
+shared form of a library only:
+
+    SHARED_SOURCE[libfoo]=dllmain.c
+

 For any file to be built, it's also possible to tell what extra
 include paths the build of their source files should use:
 
     INCLUDE[foo]=include
 
 For any file to be built, it's also possible to tell what extra
 include paths the build of their source files should use:
 
     INCLUDE[foo]=include
 

-It's possible to have raw build file lines, between BEGINRAW and
-ENDRAW lines as follows:
+In some cases, one might want to generate some source files from
+others, that's done as follows:
+
+    GENERATE[foo.s]=asm/something.pl $(CFLAGS)
+    GENERATE[bar.s]=asm/bar.S
+
+The value of each GENERATE line is a command line or part of it.
+Configure places no rules on the command line, except the the first
+item muct be the generator file.  It is, however, entirely up to the
+build file template to define exactly how those command lines should
+be handled, how the output is captured and so on.
+
+NOTE: GENERATE lines are limited to one command only per GENERATE.
+
+As a last resort, it's possible to have raw build file lines, between
+BEGINRAW and ENDRAW lines as follows:

 
     BEGINRAW[Makefile(unix)]
     haha.h: {- $builddir -}/Makefile
 
     BEGINRAW[Makefile(unix)]
     haha.h: {- $builddir -}/Makefile


@@ -409,6 +409,18 @@ configuration items:
    build hoho.h: echo "/* hoho */" > hoho.h
    ENDRAW[build.ninja(unix)]
 
    build hoho.h: echo "/* hoho */" > hoho.h
    ENDRAW[build.ninja(unix)]
 

+Should it be needed because the recipes within a RAW section might
+clash with those generated by Configure, it's possible to tell it
+not to generate them with the use of OVERRIDES, for example:
+
+    SOURCE[libfoo]=foo.c bar.c
+    
+    OVERRIDES=bar.o
+    BEGINRAW[Makefile(unix)]
+    bar.o: bar.c
+       $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $<
+    ENDRAW[Makefile(unix)]
+

 See the documentation further up for more information on configuration
 items.
 
 See the documentation further up for more information on configuration
 items.
 


@@ -480,6 +492,26 @@ The build-file template is expected to define at least the following
 perl functions in a perl code fragment enclosed with "{-" and "-}".
 They are all expected to return a string with the lines they produce.
 
 perl functions in a perl code fragment enclosed with "{-" and "-}".
 They are all expected to return a string with the lines they produce.
 

+    generatesrc - function that produces build file lines to generate
+                  a source file from some input.
+
+                  It's called like this:
+
+                        generatesrc(src => "PATH/TO/tobegenerated",
+                                    generator => [ "generatingfile", ... ]
+                                    deps => [ "dep1", ... ],
+                                    intent => one of "libs", "dso", "bin" );
+
+                  'src' has the name of the file to be generated.
+                  'generator' is the command or part of command to
+                  generate the file, of which the first item is
+                  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.  'deps' is a list of explicit
+                  dependencies.  '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.
 
     src2obj     - function that produces build file lines to build an
                   object file from source files and associated data.
 


@@ -530,7 +562,7 @@ They are all expected to return a string with the lines they produce.
 
                   'lib' has the intended library file name *without*
                   extension, libobj2shlib is expected to add that.
 
                   'lib' has the intended library file name *without*
                   extension, libobj2shlib is expected to add that.

-                  'shlib' has the correcponding shared library name
+                  'shlib' has the corresponding shared library name

                   *without* extension.  'deps' has the list of other
                   libraries (also *without* extension) this library
                   needs to be linked with.  'objs' has the list of
                   *without* extension.  'deps' has the list of other
                   libraries (also *without* extension) this library
                   needs to be linked with.  'objs' has the list of


@@ -596,7 +628,7 @@ the build file actions run with the build tree top as current working
 directory.
 
 Make sure to end the section with these functions with a string that
 directory.
 
 Make sure to end the section with these functions with a string that

-you thing is apropriate for the resulting build file.  If nothing
+you thing is appropriate for the resulting build file.  If nothing

 else, end it like this:
 
       "";       # Make sure no lingering values end up in the Makefile
 else, end it like this:
 
       "";       # Make sure no lingering values end up in the Makefile