Doc: add doc/man7/openssl_user_macros.pod.in

This manual is a start to describe macros that users can use to affect
what symbols are exported by the public header files.

Because the macro OPENSSL_API_COMPAT has a default that's affected by
configuration choices, we must make it a generated manual.

Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/7742)

diff --git a/build.info b/build.info
index 53629c40ebab0586636e0857aa15aa778fa480e6..c2ed667afb04af36f24f82922085b41f5de24cbd 100644 (file)
--- a/build.info
+++ b/build.info
@@ -22,13 +22,15 @@ DEPEND[libssl]=libcrypto
 # Empty DEPEND "indices" means the dependencies are expected to be built
 # unconditionally before anything else.
 DEPEND[]=include/openssl/opensslconf.h crypto/include/internal/bn_conf.h \
 # Empty DEPEND "indices" means the dependencies are expected to be built
 # unconditionally before anything else.
 DEPEND[]=include/openssl/opensslconf.h crypto/include/internal/bn_conf.h \

-         crypto/include/internal/dso_conf.h
+         crypto/include/internal/dso_conf.h doc/man7/openssl_user_macros.pod

 DEPEND[include/openssl/opensslconf.h]=configdata.pm
 GENERATE[include/openssl/opensslconf.h]=include/openssl/opensslconf.h.in
 DEPEND[crypto/include/internal/bn_conf.h]=configdata.pm
 GENERATE[crypto/include/internal/bn_conf.h]=crypto/include/internal/bn_conf.h.in
 DEPEND[crypto/include/internal/dso_conf.h]=configdata.pm
 GENERATE[crypto/include/internal/dso_conf.h]=crypto/include/internal/dso_conf.h.in
 DEPEND[include/openssl/opensslconf.h]=configdata.pm
 GENERATE[include/openssl/opensslconf.h]=include/openssl/opensslconf.h.in
 DEPEND[crypto/include/internal/bn_conf.h]=configdata.pm
 GENERATE[crypto/include/internal/bn_conf.h]=crypto/include/internal/bn_conf.h.in
 DEPEND[crypto/include/internal/dso_conf.h]=configdata.pm
 GENERATE[crypto/include/internal/dso_conf.h]=crypto/include/internal/dso_conf.h.in

+DEPEND[doc/man7/openssl_user_macros.pod]=configdata.pm
+GENERATE[doc/man7/openssl_user_macros.pod]=doc/man7/openssl_user_macros.pod.in

 
 IF[{- defined $target{shared_defflag} -}]
   SHARED_SOURCE[libcrypto]=libcrypto.ld
 
 IF[{- defined $target{shared_defflag} -}]
   SHARED_SOURCE[libcrypto]=libcrypto.ld

diff --git a/doc/man7/openssl_user_macros.pod.in b/doc/man7/openssl_user_macros.pod.in
new file mode 100644 (file)
index 0000000..8af5aea
--- /dev/null
+++ b/doc/man7/openssl_user_macros.pod.in
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+openssl_user_macros, OPENSSL_API_COMPAT - User defined macros
+
+=head1 DESCRIPTION
+
+User defined macros allow the programmer to control certain aspects of
+what is exposed by the OpenSSL headers.
+
+B<NOTE:> to be effective, a user defined macro I<must be defined
+before including any header file that depends on it>, either in the
+compilation command (C<cc -DMACRO=value>) or by defining the macro in
+source before including any headers.
+
+Other manual pages may refer to this page when declarations depend on
+user defined macros.
+
+=head2 The macros
+
+=over
+
+=item B<OPENSSL_API_COMPAT>
+
+The value is a version number similar to the
+L<OPENSSL_VERSION_NUMBER(3)> macro.  Any symbol that is deprecated in
+versions up to and including the version given in this macro will not
+be declared.  Any version number may be given, but these numbers are
+the current known major deprecation points, making them the most
+meaningful:
+
+=over
+
+=item C<0x00908000L> (version 0.9.8)
+
+=item C<0x10000000L> (version 1.0.0)
+
+=item C<0x10100000L> (version 1.1.0)
+
+=back
+
+If not set, this macro will default to
+C<{- join('', map { my @x = split /=/,$_; $x[1] }
+              grep /^OPENSSL_MIN_API=/, @{$config{openssl_api_defines} // []})
+     || '0x00000000L'
+  -}>.
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut