diff options
author | Richard Levitte <levitte@openssl.org> | 2018-12-02 20:37:30 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2018-12-03 10:00:14 +0100 |
commit | 547a3320fcaa971ab2e827a4cd6512199607c9e9 (patch) | |
tree | 1d2ad3185a37e2af5604ea5840da42f0c5b311db | |
parent | 9b1c0e006b9e7fde14b6719b40853e5c3557ec98 (diff) |
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)
-rw-r--r-- | build.info | 4 | ||||
-rw-r--r-- | doc/man7/openssl_user_macros.pod.in | 60 |
2 files changed, 63 insertions, 1 deletions
diff --git a/build.info b/build.info index 53629c40eb..c2ed667afb 100644 --- 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 \ - 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[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 diff --git a/doc/man7/openssl_user_macros.pod.in b/doc/man7/openssl_user_macros.pod.in new file mode 100644 index 0000000000..8af5aea7fb --- /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 |