Enhance and clear the support of linker flags

[openssl.git] / Configurations / README

diff --git a/Configurations/README b/Configurations/README
index ecf2b7908b9b58ca2113d9f4969b70aa46c75306..fb94aa723ed388e5ccd008147fefa84f6e72ff68 100644 (file)
--- a/Configurations/README
+++ b/Configurations/README
@@ -39,25 +39,22 @@ In each table entry, the following keys are significant:
                            compiling for shared libraries, typically
                            something like "-fPIC".
 
-        ld              => the linker command, usually not defined
+        (linking is a complex thing, see [3] below)
+        ld              => Linker command, usually not defined
                            (meaning the compiler command is used
                            instead).
                            (NOTE: this is here for future use, it's
                            not implemented yet)
-        lflags          => the flags that are used at all times when
-                           linking.  These can have a % sign in them
-                           showing where the OpenSSL libraries should
-                           appear, otherwise these flags will come
-                           last.  So in a typical links situation,
-                           this is a quick table of results:
-
-                           "-foo%-bar"  > -foo -lssl -lcrypto -bar
-                           "-foo%"      > -foo -lssl -lcrypto
-                           "-foo"       > -lssl -lcrypto -foo
+        lflags          => Flags that are used when linking apps.
+        shared_ldflag   => Flags that are used when linking shared
+                           or dynamic libraries.
+        plib_lflags     => Extra linking flags to appear just before
+                           the libraries on the command line.
+        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.
-        shared_lflags   => Like shared_cflags, but used when linking.
 
         ar              => The library archive command, the default is
                            "ar".
@@ -253,6 +250,31 @@ In each table entry, the following keys are significant:
     be "(unknown)", in which case the user MUST give some compilation
     flags to Configure.
 
+[3] OpenSSL has three types of things to link from object files or
+    static libraries:
+
+    - shared libraries; that would be libcrypto and libssl.
+    - shared objects (sometimes called dynamic libraries);  that would
+      be the engines.
+    - applications; those are apps/openssl and all the test apps.
+
+    Very roughly speaking, linking is done like this (words in braces
+    represent the configuration settings documented at the beginning
+    of this file):
+
+    shared libraries:
+        {ld} $(CFLAGS) {shared_ldflag} -shared -o libfoo.so \
+            -Wl,--whole-archive libfoo.a -Wl,--no-whole-archive \
+            {plib_lflags} -lcrypto {ex_libs}
+
+    shared objects:
+        {ld} $(CFLAGS) {shared_ldflag} -shared -o libeng.so \
+            blah1.o blah2.o {plib_lflags} -lcrypto {ex_libs}
+
+    applications:
+        {ld} $(CFLAGS) {lflags} -o app \
+            app1.o utils.o {plib_lflags} -lssl -lcrypto {ex_libs}
+
 
 Historically, the target configurations came in form of a string with
 values separated by colons.  This use is deprecated.  The string form