doc/internal/man7/VERSION.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 VERSION - OpenSSL version information
   6
   7 =head1 SYNOPSIS
   8
   9  MAJOR=3
  10  MINOR=0
  11  PATCH=0
  12  PRE_RELEASE_TAG=dev
  13  BUILD_METADATA=
  14  RELEASE_DATE=
  15  SHLIB_VERSION=3
  16
  17 =head1 DESCRIPTION
  18
  19 This file is a set of keyed information looking like simple variable
  20 assignments.  When given an empty value, they are seen as unassigned.
  21 The keys that are recognised are:
  22
  23 =over 4
  24
  25 =item B<MAJOR>, B<MINOR>, B<PATCH>
  26
  27 The three parts of OpenSSL's 3 numbered version number, MAJOR.MINOR.PATCH.
  28 These are used to compose the values for the C macros B<OPENSSL_VERSION_MAJOR>,
  29 B<OPENSSL_VERSION_MINOR>, B<OPENSSL_VERSION_PACTH>.
  30
  31 =item B<PRE_RELEASE_TAG>
  32
  33 This is the added pre-release tag, which is added to the version separated by
  34 a dash.  For a value C<foo>, the C macro B<OPENSSL_VERSION_PRE_RELEASE> gets
  35 the string C<-foo> (dash added).
  36
  37 =item B<BUILD_METADATA>
  38
  39 Extra metadata to be used by anyone for their own purposes.  This is added to
  40 the version and possible pre-release tag, separated by a plus sign.  For a
  41 value C<bar>, the C macro B<OPENSSL_VERSION_BUILD_METADATA> gets the string
  42 C<+bar>.
  43
  44 =item B<RELEASE_DATE>
  45
  46 Defined in releases.  When not set, it gets the value C<xx XXX xxxx>.
  47
  48 =item B<SHLIB_VERSION>
  49
  50 The shared library version, which is something other than the project version.
  51
  52 =back
  53
  54 It is a configuration error if B<MAJOR>, B<MINOR>, B<PATCH> and B<SHLIB_VERSION>
  55 don't have values.  Configuration will stop in that case.
  56
  57 =head2 Affected configuration data
  58
  59 The following items in %config from F<configdata.pm> are affected:
  60
  61 =over 4
  62
  63 =item $config{major}, $config{minor}, $config{patch}, $config{shlib_version}
  64
  65 These items get their values from B<MAJOR>, B<MINOR>, B<PATCH>, and
  66 B<SHLIB_VERSION>, respectively.
  67
  68 =item $config{prerelease}
  69
  70 If B<PRERELEASE> is assigned a value, $config{prerelease} gets that same value,
  71 prefixed by a dash, otherwise the empty string.
  72
  73 =item $config{build_metadata}
  74
  75 If B<BUILD_METADATA> is assigned a value, $config{build_metadata} gets that same
  76 value, prefixed by a plus sign, otherwise the empty string.
  77
  78 =item $config{release_date}
  79
  80 If B<RELEASE_DATE> is assigned a value, $config{release_date} gets that same
  81 value, otherwise the string C<xx XXX yyyy>.
  82
  83 =item $config{version}
  84
  85 The minimal version number, a string composed from B<MAJOR>, B<MINOR> and
  86 B<PATCH>, separated by periods.  For C<MAJOR=3>, C<MINOR=0> and C<PATCH=0>,
  87 the string will be C<3.0.0>.
  88
  89 =item $config{full_version}
  90
  91 The fully loaded version number, a string composed from $config{version},
  92 $config{prerelease} and $config{build_metadata}.  See   See L</EXAMPLES> for
  93 a few examples.
  94
  95 =back
  96
  97 =head1 EXAMPLES
  98
  99 =over 4
 100
 101 =item 1.
 102
 103  MAJOR=3
 104  MINOR=0
 105  PATCH=0
 106  PRE_RELEASE_TAG=dev
 107  BUILD_METADATA=
 108
 109 The fully loaded version number ($config{full_version}) will be
 110 C<3.0.0-dev>.
 111
 112 =item 2.
 113
 114  MAJOR=3
 115  MINOR=0
 116  PATCH=0
 117  PRE_RELEASE_TAG=
 118  BUILD_METADATA=something
 119
 120 The fully loaded version number ($config{full_version}) will be
 121 C<3.0.0+something>.
 122
 123 =item 3.
 124
 125  MAJOR=3
 126  MINOR=0
 127  PATCH=0
 128  PRE_RELEASE_TAG=alpha3
 129  BUILD_METADATA=something
 130
 131 The fully loaded version number ($config{full_version}) will be
 132 C<3.0.0-alpha3+something>.
 133
 134 =back
 135
 136 =head1 SEE ALSO
 137
 138 L<OpenSSL_version(3)>
 139
 140 =head1 COPYRIGHT
 141
 142 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 143
 144 Licensed under the Apache License 2.0 (the "License").  You may not use
 145 this file except in compliance with the License.  You can obtain a copy
 146 in the file LICENSE in the source distribution or at
 147 L<https://www.openssl.org/source/license.html>.
 148
 149 =cut