Add support for C++ in Configurations/unix-Makefile.tmpl

[openssl.git] / Configurations / README

diff --git a/Configurations/README b/Configurations/README
index 40875a3ba2bba11f52957924239bb652279a8da6..0b82dedca903723a9fa5e9ded5c4a6e8d64be24e 100644 (file)
--- a/Configurations/README
+++ b/Configurations/README
@@ -17,12 +17,20 @@ In each table entry, the following keys are significant:
         sys_id          => System identity for systems where that
                            is difficult to determine automatically.
 
-        cc              => The compiler command, usually one of "cc",
+        cc              => The C compiler command, usually one of "cc",
                            "gcc" or "clang".  This command is normally
                            also used to link object files and
                            libraries into the final program.
+        cxx             => The C++ compiler command, usually one of
+                           "c++", "g++" or "clang++".  This command is
+                           also used when linking a program where at
+                           least one of the object file is made from
+                           C++ source.
         cflags          => Flags that are used at all times when
-                           compiling.
+                           compiling C object files.
+        cxxflags        => Flags that are used at all times when
+                           compiling C++ object files.  If unset, it
+                           gets the same value as cflags.
         defines         => As an alternative, macro definitions may be
                            present here instead of in `cflags'.  If
                            given here, they MUST be as an array of the
@@ -99,8 +107,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,6 +365,11 @@ 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:
 
@@ -375,6 +387,18 @@ 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
@@ -385,7 +409,7 @@ BEGINRAW and ENDRAW lines as follows:
         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
@@ -404,6 +428,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.
 
@@ -482,6 +518,10 @@ They are all expected to return a string with the lines they produce.
 
                         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" );
 
@@ -491,9 +531,14 @@ They are all expected to return a string with the lines they produce.
                   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.
+                  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.