Configurations/10-main.conf: fix solaris64-*-cc link problems.
[openssl.git] / Configurations / README
index fb94aa7..da64e8c 100644 (file)
@@ -1,5 +1,5 @@
 Configurations of OpenSSL target platforms
-------------------------------------------
+==========================================
 
 Target configurations are a collection of facts that we know about
 different platforms and their capabilities.  We organise them in a
@@ -23,18 +23,11 @@ In each table entry, the following keys are significant:
                            libraries into the final program.
         cflags          => Flags that are used at all times when
                            compiling.
-        debug_cflags    => Extra compilation flags used when making a
-                           debug build (when Configure receives the
-                           --debug option).  Typically something like
-                           "-g -O0".
-        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".
-        thread_cflags   => Extra compilation flags used when
-                           compiling with threading enabled.
-                           Explained further below.  [2]
+        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
+                           string such as "MACRO=value", or just
+                           "MACRO" for definitions without value.
         shared_cflag    => Extra compilation flags used when
                            compiling for shared libraries, typically
                            something like "-fPIC".
@@ -53,9 +46,6 @@ In each table entry, the following keys are significant:
         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
@@ -80,6 +70,14 @@ In each table entry, the following keys are significant:
                            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
@@ -101,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
@@ -146,6 +143,8 @@ In each table entry, the following keys are significant:
                                                 export vars as
                                                 accessor functions.
 
+        apps_extra_src  => Extra source to build apps/openssl, as
+                           needed by the target.
         cpuid_asm_src   => assembler implementation of cpuid code as
                            well as OPENSSL_cleanse().
                            Default to mem_clr.c
@@ -197,7 +196,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.
 
-    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.
@@ -246,7 +245,7 @@ In each table entry, the following keys are significant:
         }
 
 [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.
 
@@ -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.
 
@@ -411,7 +453,7 @@ example, the above would have "something" used, since 1 is true.
 Together with the use of Text::Template, this can be used as
 conditions based on something in the passed variables, for example:
 
-    IF[{- $config{no_shared} -}]
+    IF[{- $disabled{shared} -}]
       LIBS=libcrypto
       SOURCE[libcrypto]=...
     ELSE
@@ -427,3 +469,187 @@ or:
      RENAME[libcrypto]=ossl_libcrypto
      RENAME[libssl]=ossl_libssl
     ENDIF
+
+
+Build-file programming with the "unified" build system
+======================================================
+
+"Build files" are called "Makefile" on Unix-like operating systems,
+"descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
+
+To use the "unified" build system, the target configuration needs to
+set the three items 'build_scheme', 'build_file' and 'build_command'.
+In the rest of this section, we will assume that 'build_scheme' is set
+to "unified" (see the configurations documentation above for the
+details).
+
+For any name given by 'build_file', the "unified" system expects a
+template file in Configurations/ named like the build file, with
+".tmpl" appended, or in case of possible ambiguity, a combination of
+the second 'build_scheme' list item and the 'build_file' name.  For
+example, if 'build_file' is set to "Makefile", the template could be
+Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
+In case both Configurations/unix-Makefile.tmpl and
+Configurations/Makefile.tmpl are present, the former takes
+precedence.
+
+The build-file template is processed with the perl module
+Text::Template, using "{-" and "-}" as delimiters that enclose the
+perl code fragments that generate configuration-dependent content.
+Those perl fragments have access to all the hash variables from
+configdata.pem.
+
+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.
+
+                  It's called like this:
+
+                        src2obj(obj => "PATH/TO/objectfile",
+                                srcs => [ "PATH/TO/sourcefile", ... ],
+                                deps => [ "dep1", ... ],
+                                incs => [ "INCL/PATH", ... ]
+                                intent => one of "lib", "dso", "bin" );
+
+                  'obj' has the intended object file *without*
+                  extension, src2obj() is expected to add that.
+                  'srcs' has the list of source files to build the
+                  object file, with the first item being the source
+                  file that directly corresponds to the object file.
+                  'deps' is a list of explicit dependencies.  'incs'
+                  is a list of include file directories.  Finally,
+                  'intent' indicates what this object file is going
+                  to be used for.
+
+    obj2lib     - function that produces build file lines to build a
+                  static library file ("libfoo.a" in Unix terms) from
+                  object files.
+
+                  called like this:
+
+                        obj2lib(lib => "PATH/TO/libfile",
+                                objs => [ "PATH/TO/objectfile", ... ]);
+
+                  'lib' has the intended library file name *without*
+                  extension, obj2lib is expected to add that.  'objs'
+                  has the list of object files (also *without*
+                  extension) to build this library.
+
+    libobj2shlib - function that produces build file lines to build a
+                  shareable object library file ("libfoo.so" in Unix
+                  terms) from the corresponding static library file
+                  or object files.
+
+                  called like this:
+
+                        libobj2shlib(shlib => "PATH/TO/shlibfile",
+                                     lib => "PATH/TO/libfile",
+                                     objs => [ "PATH/TO/objectfile", ... ],
+                                     deps => [ "PATH/TO/otherlibfile", ... ],
+                                     ordinals => [ "word", "/PATH/TO/ordfile" ]);
+
+                  'lib' has the intended library file name *without*
+                  extension, libobj2shlib is expected to add that.
+                  '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
+                  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/libeay.num or util/ssleay.num in the
+                  source directory.
+
+                  This function has a choice; it can use the
+                  corresponding static library as input to make the
+                  shared library, or the list of object files.
+
+    obj2dso     - function that produces build file lines to build a
+                  dynamic shared object file from object files.
+
+                  called like this:
+
+                        obj2dso(lib => "PATH/TO/libfile",
+                                objs => [ "PATH/TO/objectfile", ... ],
+                                deps => [ "PATH/TO/otherlibfile",
+                                ... ]);
+
+                  This is almost the same as libobj2shlib, but the
+                  intent is to build a shareable library that can be
+                  loaded in runtime (a "plugin"...).  The differences
+                  are subtle, one of the most visible ones is that the
+                  resulting shareable library is produced from object
+                  files only.
+
+    obj2bin     - function that produces build file lines to build an
+                  executable file from object files.
+
+                  called like this:
+
+                        obj2bin(bin => "PATH/TO/binfile",
+                                objs => [ "PATH/TO/objectfile", ... ],
+                                deps => [ "PATH/TO/libfile", ... ]);
+
+                  'bin' has the intended executable file name
+                  *without* extension, obj2bin is expected to add
+                  that.  'objs' has the list of object files (also
+                  *without* extension) to build this library.  'deps'
+                  has the list of library files (also *without*
+                  extension) that the programs needs to be linked
+                  with.
+
+    in2script   - function that produces build file lines to build a
+                  script file from some input.
+
+                  called like this:
+
+                        in2script(script => "PATH/TO/scriptfile",
+                                  sources => [ "PATH/TO/infile", ... ]);
+
+                  'script' has the intended script file name.
+                  'sources' has the list of source files to build the
+                  resulting script from.
+
+In all cases, file file paths are relative to the build tree top, and
+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
+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
+    -}