VMS: honor --openssldir setting

[openssl.git] / Configurations / README

diff --git a/Configurations/README b/Configurations/README
index afc60049d18478643a40d770a9ccf3264283a903..da64e8c79bf8aa45ed242e907a48af719062e68a 100644 (file)
--- a/Configurations/README
+++ b/Configurations/README
@@ -99,8 +99,7 @@ In each table entry, the following keys are significant:
                            some options.  In this case, the first
                            string in the list is the name of the build
                            scheme.
-                           Currently recognised build schemes are
-                           "mk1mf" and "unixmake" and "unified".
+                           Currently recognised build scheme is "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
@@ -358,20 +357,51 @@ 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.
 
+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
 
-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.
+
+Sometimes, the generator file itself depends on other files, for
+example if it is a perl script that depends on other perl modules.
+This can be expressed using DEPEND like this:
+
+    DEPEND[asm/something.pl]=../perlasm/Foo.pm
+
+There may also be cases where the exact file isn't easily specified,
+but an inclusion directory still needs to be specified.  INCLUDE can
+be used in that case:
+
+    INCLUDE[asm/something.pl]=../perlasm
+
+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
         echo "/* haha */" > haha.h
     ENDRAW[Makefile(unix)]
 
-The word withing square brackets is the build_file configuration item
+The word within square brackets is the build_file configuration item
 or the build_file configuration item followed by the second word in the
 build_scheme configuration item for the configured target within
 parenthesis as shown above.  For example, with the following relevant
@@ -390,6 +420,18 @@ configuration items:
    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.
 
@@ -461,6 +503,35 @@ 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.
 
+    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", ... ]
+                                    generator_incs => [ "INCL/PATH", ... ]
+                                    generator_deps => [ "dep1", ... ]
+                                    generator => [ "generatingfile", ... ]
+                                    incs => [ "INCL/PATH", ... ],
+                                    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.  '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.