Commit 547a3320 authored by Richard Levitte's avatar Richard Levitte
Browse files

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: default avatarMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/7742)
parent 9b1c0e00

build.info

+3 −1
Original line number Diff line number Diff line
@@ -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

doc/man7/openssl_user_macros.pod.in

0 → 100644
+60 −0
Original line number Diff line number Diff line 
=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