| 1 |
#!/usr/bin/env perl |
| 2 |
|
| 3 |
use 5.008001; |
| 4 |
use strict; |
| 5 |
use warnings; |
| 6 |
|
| 7 |
use Cwd qw(abs_path); |
| 8 |
use English qw( |
| 9 |
$EVAL_ERROR $EXCEPTIONS_BEING_CAUGHT $OS_ERROR $RS -no_match_vars |
| 10 |
); |
| 11 |
use Fcntl qw(SEEK_SET); |
| 12 |
use File::Basename qw(dirname); |
| 13 |
use File::Spec::Functions qw(catfile); |
| 14 |
use Getopt::Long qw(GetOptionsFromArray); |
| 15 |
use POSIX qw(ceil); |
| 16 |
|
| 17 |
our $VERSION = '1.96'; |
| 18 |
|
| 19 |
local $SIG{__DIE__} = sub { |
| 20 |
my ($cause) = @_; |
| 21 |
|
| 22 |
if ($EXCEPTIONS_BEING_CAUGHT) { |
| 23 |
return; |
| 24 |
} |
| 25 |
|
| 26 |
print STDERR $cause, "\n"; |
| 27 |
|
| 28 |
exit 1; |
| 29 |
}; |
| 30 |
|
| 31 |
my ($args) = eval { parse_options(\@ARGV) } |
| 32 |
or fatal( 'Failed to parse command line options', $EVAL_ERROR ); |
| 33 |
|
| 34 |
my @constants = eval { load_config( $args->{config} ) } |
| 35 |
or fatal( 'Failed to load configuration file', $EVAL_ERROR ); |
| 36 |
|
| 37 |
my @perl_constants = sort map { $_->{exported_name} } @constants; |
| 38 |
|
| 39 |
eval { generate_constants_c( $args->{'constants-file'}, @constants ) } |
| 40 |
or fatal( 'Failed to generate constants file', $EVAL_ERROR ); |
| 41 |
|
| 42 |
eval { generate_constants_test( $args->{'test-file'}, @perl_constants ) } |
| 43 |
or fatal( 'Failed to generate constants test script', $EVAL_ERROR ); |
| 44 |
|
| 45 |
eval { update_module( $args->{'module-file'}, @perl_constants ) } |
| 46 |
or fatal( 'Failed to update Net::SSLeay module file', $EVAL_ERROR ); |
| 47 |
|
| 48 |
eval { update_pod( $args->{'pod-file'}, @perl_constants ) } |
| 49 |
or fatal( 'Failed to update Pod file', $EVAL_ERROR ); |
| 50 |
|
| 51 |
|
| 52 |
sub dist_file { |
| 53 |
my @path = @_; |
| 54 |
|
| 55 |
return abs_path( catfile( dirname(__FILE__), '..', @path ) ); |
| 56 |
} |
| 57 |
|
| 58 |
sub parse_options { |
| 59 |
my ($argv) = @_; |
| 60 |
|
| 61 |
my $opts = { |
| 62 |
'config' => dist_file( qw( helper_script constants.txt ) ), |
| 63 |
'constants-file' => dist_file( qw( constants.c ) ), |
| 64 |
'module-file' => dist_file( qw( lib Net SSLeay.pm ) ), |
| 65 |
'pod-file' => dist_file( qw( lib Net SSLeay.pod ) ), |
| 66 |
'test-file' => dist_file( qw( t local 21_constants.t ) ), |
| 67 |
}; |
| 68 |
|
| 69 |
GetOptionsFromArray( |
| 70 |
$argv, |
| 71 |
$opts, |
| 72 |
'config|C=s', |
| 73 |
'constants-file|c=s', |
| 74 |
'module-file|m=s', |
| 75 |
'pod-file|p=s', |
| 76 |
'test-file|t=s', |
| 77 |
); |
| 78 |
|
| 79 |
if ( !-e $opts->{'config'} ) { |
| 80 |
fatal("configuration file $opts->{config} does not exist"); |
| 81 |
} |
| 82 |
|
| 83 |
if ( !-e $opts->{'module-file'} ) { |
| 84 |
fatal("Net::SSLeay module file $opts->{'module-file'} does not exist"); |
| 85 |
} |
| 86 |
|
| 87 |
if ( !-e $opts->{'pod-file'} ) { |
| 88 |
fatal("Pod file $opts->{'pod-file'} does not exist"); |
| 89 |
} |
| 90 |
|
| 91 |
return wantarray |
| 92 |
? ( $opts, $argv ) |
| 93 |
: $opts; |
| 94 |
} |
| 95 |
|
| 96 |
sub load_config { |
| 97 |
my ($config_file) = @_; |
| 98 |
|
| 99 |
open my $fh, '<', $config_file |
| 100 |
or fatal( $config_file, $OS_ERROR ); |
| 101 |
|
| 102 |
my @constants; |
| 103 |
my $line_number = 0; |
| 104 |
|
| 105 |
while (<$fh>) { |
| 106 |
$line_number++; |
| 107 |
|
| 108 |
# Trim leading and trailing space |
| 109 |
s{^\s+|\s+$}{}g; |
| 110 |
|
| 111 |
# Skip empty lines and comments |
| 112 |
next if m{^(?:\#.*)?$}; |
| 113 |
|
| 114 |
# Check whether the given constant name is likely to be a valid |
| 115 |
# OpenSSL/LibreSSL constant name |
| 116 |
if ( $_ !~ m{^[A-Za-z_][A-Za-z0-9_]*$} ) { |
| 117 |
printf STDERR "%s:%d: badly-formatted constant name; skipping\n", |
| 118 |
$config_file, $line_number; |
| 119 |
|
| 120 |
next; |
| 121 |
} |
| 122 |
|
| 123 |
# Remove "SSL_" prefix from constant name, if present |
| 124 |
( my $exported_name = $_ ) =~ s{^SSL_}{}; |
| 125 |
|
| 126 |
push @constants, { |
| 127 |
exported_name => $exported_name, |
| 128 |
name => $_, |
| 129 |
}; |
| 130 |
} |
| 131 |
|
| 132 |
close $fh; |
| 133 |
|
| 134 |
return @constants; |
| 135 |
} |
| 136 |
|
| 137 |
sub generate_constants_c { |
| 138 |
my ( $file, @constants ) = @_; |
| 139 |
|
| 140 |
open my $fh, '>', $file |
| 141 |
or fatal($OS_ERROR); |
| 142 |
|
| 143 |
print $fh data_section('constants_c_header'); |
| 144 |
print $fh Net::SSLeay::ConstantsGenerator->C_constant( |
| 145 |
{ |
| 146 |
breakout => ~0, |
| 147 |
indent => 20, |
| 148 |
}, |
| 149 |
map { |
| 150 |
{ |
| 151 |
name => $_->{exported_name}, |
| 152 |
value => $_->{name}, |
| 153 |
} |
| 154 |
} |
| 155 |
( |
| 156 |
# This constant name isn't defined by any libssl implementation - it |
| 157 |
# is only intended to be used by the test script generated by this |
| 158 |
# script to ensure that Net::SSLeay behaves as expected when a |
| 159 |
# caller attempts to refer to an undefined constant |
| 160 |
{ |
| 161 |
exported_name => '_NET_SSLEAY_TEST_UNDEFINED_CONSTANT', |
| 162 |
name => '_NET_SSLEAY_TEST_UNDEFINED_CONSTANT', |
| 163 |
}, |
| 164 |
@constants, |
| 165 |
) |
| 166 |
); |
| 167 |
|
| 168 |
close $fh; |
| 169 |
|
| 170 |
printf "%s: generated\n", $file; |
| 171 |
|
| 172 |
return 1; |
| 173 |
} |
| 174 |
|
| 175 |
sub generate_constants_test { |
| 176 |
my ( $file, @constants ) = @_; |
| 177 |
|
| 178 |
open my $fh, '>', $file |
| 179 |
or fatal($OS_ERROR); |
| 180 |
|
| 181 |
print $fh data_section( |
| 182 |
'constants_test', |
| 183 |
{ |
| 184 |
constants => join( "\n", map { q{ } x 4 . $_ } @constants ), |
| 185 |
# 1 dies_like() test for each constant |
| 186 |
# 1 is() test for @EXPORT_OK |
| 187 |
# 1 dies_like() test for undefined constant |
| 188 |
tests => @constants + 2, |
| 189 |
} |
| 190 |
); |
| 191 |
|
| 192 |
close $fh; |
| 193 |
|
| 194 |
printf "%s: generated\n", $file; |
| 195 |
|
| 196 |
return 1; |
| 197 |
} |
| 198 |
|
| 199 |
sub update_content { |
| 200 |
my ( $file, $start_match, $end_match, @replacement ) = @_; |
| 201 |
|
| 202 |
open my $fh, '<', $file |
| 203 |
or fatal($OS_ERROR); |
| 204 |
|
| 205 |
my ( @file, $start, $end ); |
| 206 |
|
| 207 |
my $pos = 0; |
| 208 |
while (<$fh>) { |
| 209 |
push @file, $_; |
| 210 |
|
| 211 |
if ( !defined $start && $_ =~ $start_match ) { |
| 212 |
$start = $pos; |
| 213 |
} |
| 214 |
elsif ( defined $start && !defined $end && $_ =~ $end_match ) { |
| 215 |
$end = $pos; |
| 216 |
} |
| 217 |
|
| 218 |
$pos++; |
| 219 |
} |
| 220 |
|
| 221 |
close $fh; |
| 222 |
|
| 223 |
if ( !defined $start || !defined $end ) { |
| 224 |
fatal('could not find start/end markers'); |
| 225 |
} |
| 226 |
|
| 227 |
splice @file, $start + 1, max( 0, $end - $start - 1 ), @replacement; |
| 228 |
|
| 229 |
open $fh, '>', $file |
| 230 |
or fatal($OS_ERROR); |
| 231 |
|
| 232 |
for (@file) { |
| 233 |
print $fh $_; |
| 234 |
} |
| 235 |
|
| 236 |
close $fh; |
| 237 |
|
| 238 |
return 1; |
| 239 |
} |
| 240 |
|
| 241 |
sub update_module { |
| 242 |
my ( $file, @constants ) = @_; |
| 243 |
|
| 244 |
eval { |
| 245 |
update_content( |
| 246 |
$file, |
| 247 |
qr{^my \@constants = qw\(}, |
| 248 |
qr{^\);}, |
| 249 |
map { q{ } x 4 . "$_\n" } @constants |
| 250 |
) |
| 251 |
} or do { |
| 252 |
( my $err = $EVAL_ERROR ) =~ s{start/end markers$}{\@constants declaration}; |
| 253 |
fatal( $file, $err ); |
| 254 |
}; |
| 255 |
|
| 256 |
printf "%s: updated\n", $file; |
| 257 |
|
| 258 |
return 1; |
| 259 |
} |
| 260 |
|
| 261 |
sub format_constants { |
| 262 |
my ( $list, $indent, $columns, $separator ) = @_; |
| 263 |
|
| 264 |
my $per_column = ceil( @$list / $columns ); |
| 265 |
|
| 266 |
my @columns = map |
| 267 |
{ [ splice @$list, 0, $per_column ] } |
| 268 |
( 0 .. $columns - 1 ); |
| 269 |
|
| 270 |
my @max_length = map |
| 271 |
{ max( map { length } @$_ ) } |
| 272 |
@columns; |
| 273 |
|
| 274 |
my @formatted; |
| 275 |
for my $row ( 0 .. $per_column - 1 ) { |
| 276 |
my @row; |
| 277 |
for ( 0 .. $columns - 1 ) { |
| 278 |
my $this = $columns[$_]->[$row]; |
| 279 |
my $left = $columns[ $_ - 1 ]->[$row]; |
| 280 |
|
| 281 |
next if !defined $this; |
| 282 |
|
| 283 |
my $gap = $_ == 0 |
| 284 |
? $indent |
| 285 |
: $max_length[ $_ - 1 ] - length($left) + $separator; |
| 286 |
|
| 287 |
push @row, q{ } x $gap . $this; |
| 288 |
} |
| 289 |
push @formatted, join( '', @row ) . "\n"; |
| 290 |
} |
| 291 |
|
| 292 |
return @formatted; |
| 293 |
} |
| 294 |
|
| 295 |
sub update_pod { |
| 296 |
my ( $file, @constants ) = @_; |
| 297 |
|
| 298 |
eval { |
| 299 |
update_content( |
| 300 |
$file, |
| 301 |
qr{^=for start_constants$}, |
| 302 |
qr{^=for end_constants$}, |
| 303 |
( "\n", format_constants( \@constants, 4, 2, 2 ), "\n" ) |
| 304 |
) |
| 305 |
} or do { |
| 306 |
( my $err = $EVAL_ERROR ) =~ s{start/end markers$}{constants block}; |
| 307 |
fatal( $file, $err ); |
| 308 |
}; |
| 309 |
|
| 310 |
printf "%s: updated\n", $file; |
| 311 |
|
| 312 |
return 1; |
| 313 |
} |
| 314 |
|
| 315 |
sub max { |
| 316 |
my @numbers = @_; |
| 317 |
|
| 318 |
my $max = shift @numbers; |
| 319 |
while ( defined( my $number = shift @numbers ) ) { |
| 320 |
$max = $number if $number > $max; |
| 321 |
} |
| 322 |
|
| 323 |
return $max; |
| 324 |
} |
| 325 |
|
| 326 |
sub data_section { |
| 327 |
my ( $section, $tmpl ) = @_; |
| 328 |
|
| 329 |
seek DATA, 0, SEEK_SET; |
| 330 |
|
| 331 |
my @content = (); |
| 332 |
my $in_section; |
| 333 |
|
| 334 |
for (<DATA>) { |
| 335 |
if ( my ($name) = $_ =~ m{^\[section:(\w+)\]\n} ) { |
| 336 |
if ( $name eq $section ) { |
| 337 |
$in_section = 1; |
| 338 |
next; |
| 339 |
} |
| 340 |
elsif ($in_section) { |
| 341 |
# Reached the section following the requested section |
| 342 |
last; |
| 343 |
} |
| 344 |
} |
| 345 |
|
| 346 |
if ($in_section) { |
| 347 |
s/\{\{\s*(\w+)\s*\}\}/defined $tmpl->{$1} ? $tmpl->{$1} : ''/eg; |
| 348 |
push @content, $_; |
| 349 |
} |
| 350 |
} |
| 351 |
|
| 352 |
fatal("__DATA__ section '$section' not found") |
| 353 |
if !$in_section; |
| 354 |
|
| 355 |
return join '', @content; |
| 356 |
} |
| 357 |
|
| 358 |
sub fatal { |
| 359 |
my ( $message, $cause ) = @_; |
| 360 |
|
| 361 |
die Error->new( $message, $cause ); |
| 362 |
} |
| 363 |
|
| 364 |
package Net::SSLeay::ConstantsGenerator; |
| 365 |
|
| 366 |
use base 'ExtUtils::Constant::Base'; |
| 367 |
|
| 368 |
sub assignment_clause_for_type { |
| 369 |
my ( $self, $args, $value ) = @_; |
| 370 |
|
| 371 |
return main::data_section( |
| 372 |
'assignment_clause_for_type', |
| 373 |
{ |
| 374 |
value => $value, |
| 375 |
} |
| 376 |
); |
| 377 |
} |
| 378 |
|
| 379 |
sub C_constant_return_type { |
| 380 |
my $ret = <<'END'; |
| 381 |
#ifdef NET_SSLEAY_32BIT_CONSTANTS |
| 382 |
static double |
| 383 |
#else |
| 384 |
static uint64_t |
| 385 |
#endif |
| 386 |
END |
| 387 |
# Newline is automatically added, remove ours. |
| 388 |
chomp($ret); |
| 389 |
return $ret; |
| 390 |
} |
| 391 |
|
| 392 |
sub return_statement_for_notfound { |
| 393 |
return main::data_section('return_statement_for_notfound'); |
| 394 |
} |
| 395 |
|
| 396 |
package Error; |
| 397 |
|
| 398 |
use overload ( |
| 399 |
q{""} => sub { |
| 400 |
my ($self) = @_; |
| 401 |
|
| 402 |
return defined $self->{cause} |
| 403 |
? "$self->{message}: $self->{cause}" |
| 404 |
: $self->{message}; |
| 405 |
}, |
| 406 |
fallback => 1, |
| 407 |
); |
| 408 |
|
| 409 |
sub new { |
| 410 |
my ( $class, $message, $cause ) = @_; |
| 411 |
|
| 412 |
return bless { |
| 413 |
message => $message, |
| 414 |
cause => $cause, |
| 415 |
}, $class; |
| 416 |
} |
| 417 |
|
| 418 |
package main; |
| 419 |
|
| 420 |
=pod |
| 421 |
|
| 422 |
=encoding utf-8 |
| 423 |
|
| 424 |
=head1 NAME |
| 425 |
|
| 426 |
C<update-exported-constants> - Manage constants exported by Net::SSLeay |
| 427 |
|
| 428 |
=head1 VERSION |
| 429 |
|
| 430 |
This document describes version 1.96 of C<update-exported-constants>. |
| 431 |
|
| 432 |
=head1 USAGE |
| 433 |
|
| 434 |
# Edit constants.txt to add or remove a libssl/libcrypto constant |
| 435 |
|
| 436 |
# Export the new list of constants in Net::SSLeay, document them, and test |
| 437 |
# for their availability in the test suite: |
| 438 |
update-exported-constants |
| 439 |
|
| 440 |
=head1 DESCRIPTION |
| 441 |
|
| 442 |
Net::SSLeay exports a number of constants defined by libssl and libcrypto. |
| 443 |
Several time-consuming and error-prone steps must be performed whenever this set |
| 444 |
of constants changes: each one must be recognised as a valid constant name by |
| 445 |
Net::SSLeay's XS code, defined as an exportable symbol in Net::SSLeay's Perl |
| 446 |
code, documented in Net::SSLeay's user documentation, and tested in the |
| 447 |
Net::SSLeay test suite to ensure that referencing it either returns a defined |
| 448 |
value or raises an exception depending on whether it is defined in the version |
| 449 |
of OpenSSL or LibreSSL being used. |
| 450 |
|
| 451 |
C<update-exported-constants> simplifies the process of changing the set of |
| 452 |
exportable constants by automating it: it consumes a configuration file |
| 453 |
containing a list of constants, and performs each of the steps above for each of |
| 454 |
the constants listed in the file. |
| 455 |
|
| 456 |
=head1 DEPENDENCIES |
| 457 |
|
| 458 |
C<update-exported-constants> requires Perl 5.8.1 or higher. |
| 459 |
|
| 460 |
=head1 OPTIONS |
| 461 |
|
| 462 |
C<update-exported-constants> accepts the following command line options: |
| 463 |
|
| 464 |
=over 4 |
| 465 |
|
| 466 |
=item * |
| 467 |
|
| 468 |
B<-C I<FILE>>, B<--config=I<FILE>>: the path to a file defining the libssl and |
| 469 |
libcrypto constants that Net::SSLeay should attempt to export. See |
| 470 |
L</CONFIGURATION> for a description of the expected format. Defaults to |
| 471 |
C<constants.txt>, relative to the path to C<update-exported-constants>. |
| 472 |
|
| 473 |
=item * |
| 474 |
|
| 475 |
B<-c I<FILE>>, B<--constants-file=I<FILE>>: the path at which to write the C |
| 476 |
source file defining the C<constant> function; this file should be included by |
| 477 |
C<SSLeay.xs>. If a file exists at the given path, it will be overwritten. |
| 478 |
Defaults to C<../constants.c>, relative to the path to |
| 479 |
C<update-exported-constants>. |
| 480 |
|
| 481 |
=item * |
| 482 |
|
| 483 |
B<-m I<FILE>>, B<--module-file=I<FILE>>: the path to Net::SSLeay's source code; |
| 484 |
the value of the C<@constants> array defined in this file will be overwritten. |
| 485 |
Defaults to C<../lib/Net/SSLeay.pm>, relative to the path to |
| 486 |
C<update-exported-constants>. |
| 487 |
|
| 488 |
=item * |
| 489 |
|
| 490 |
B<-p I<FILE>>, B<--pod-file=I<FILE>>: the path to et::SSLeay's documentation; |
| 491 |
the list of constants given in the L<Net::SSLeay/Constants> section of this file |
| 492 |
will be overwritten. Defaults to C<../lib/Net/SSLeay.pod>, relative to the path |
| 493 |
to C<update-exported-constants>. |
| 494 |
|
| 495 |
=item * |
| 496 |
|
| 497 |
B<-t I<FILE>>, B<--test-file=I<FILE>>: the path at which to write the constant |
| 498 |
autoloading test script. If a file exists at the given path, it will be |
| 499 |
overwritten. Defaults to C<../t/local/21_constants.t>, relative to the path to |
| 500 |
C<update-exported-constants>. |
| 501 |
|
| 502 |
=back |
| 503 |
|
| 504 |
The above defaults ensure that C<update-exported-constants> can be executed |
| 505 |
from a directory containing the Net-SSLeay source code without needing to |
| 506 |
specify any options. |
| 507 |
|
| 508 |
=head1 CONFIGURATION |
| 509 |
|
| 510 |
The configuration file is a plain text file containing libssl and libcrypto |
| 511 |
constant names, one per line. Empty lines and lines beginning with C<#> are |
| 512 |
ignored. |
| 513 |
|
| 514 |
libssl and libcrypto constants are C preprocessor macro names. |
| 515 |
C<update-exported-constants> checks that constant names given in the |
| 516 |
configuration file appear to be valid macro names, and will output a |
| 517 |
I<badly-formatted constant name; skipping> warning on stderr whenever it |
| 518 |
encounters a line in the configuration file that does not appear to be a valid |
| 519 |
macro name. Since the set of valid constant names differs between versions of |
| 520 |
OpenSSL and LibreSSL, it is not possible to validate that constant names listed |
| 521 |
in the configuration file are in fact valid constant names for a particular |
| 522 |
libssl or libcrypto version. |
| 523 |
|
| 524 |
=head1 OUTPUT |
| 525 |
|
| 526 |
C<update-exported-constants> generates the following files (overwriting any file |
| 527 |
that already exists at that path): |
| 528 |
|
| 529 |
=over 4 |
| 530 |
|
| 531 |
=item * |
| 532 |
|
| 533 |
A C source file defining a function with the prototype |
| 534 |
C<static double constant(char*, size_t)>. For a given constant name and length, |
| 535 |
this function returns the value of the constant with the given name if it is |
| 536 |
recognised as exportable by Net::SSLeay and exists in libssl/libcrypto, returns |
| 537 |
C<0> and sets L<errno> to C<ENOENT> if the constant is exportable but does not |
| 538 |
exist in libssl/libcrypto, or returns C<0> and sets L<errno> to C<EINVAL> if the |
| 539 |
constant is not recognised as exportable by Net::SSLeay. This file is expected |
| 540 |
to be C<include>d by C<SSLeay.xs>. |
| 541 |
|
| 542 |
=item * |
| 543 |
|
| 544 |
A Net::SSLeay test script that ensures each constant is exportable if it is |
| 545 |
defined, or raises a specific exception if it is not. This test script is |
| 546 |
expected to run as part of the standard Net::SSLeay test suite. |
| 547 |
|
| 548 |
=back |
| 549 |
|
| 550 |
C<update-exported-constants> updates the following files (which therefore must |
| 551 |
already exist and be writable): |
| 552 |
|
| 553 |
=over 4 |
| 554 |
|
| 555 |
=item * |
| 556 |
|
| 557 |
The source file for the Net::SSLeay module - the value of the C<@constants> |
| 558 |
array defined in this file is overwritten with the new list of constants that |
| 559 |
the module can export. |
| 560 |
|
| 561 |
=item * |
| 562 |
|
| 563 |
The Pod file documenting the Net::SSLeay module - the list of exportable |
| 564 |
constants given in the L<Net::SSLeay/Constants> section of this file is |
| 565 |
overwritten with the new list of constants that the module can export. |
| 566 |
|
| 567 |
=back |
| 568 |
|
| 569 |
=head1 DIAGNOSTICS |
| 570 |
|
| 571 |
C<update-exported-constants> outputs a diagnostic message to stderr and |
| 572 |
immediately exits with exit code 1 if an error occurs. Error messages listed |
| 573 |
below indicate invalid input or a problem with the state of the system that can |
| 574 |
usually be fixed. Error messages not listed below are internal and should never |
| 575 |
be encountered under normal operation; please report any occurrences of such |
| 576 |
errors as bugs (see L</BUGS>). |
| 577 |
|
| 578 |
=over |
| 579 |
|
| 580 |
=item B<Failed to parse command line options: configuration file I<PATH> does |
| 581 |
not exist> |
| 582 |
|
| 583 |
The configuration file listing the constants to export, as specified by the |
| 584 |
B<-C> command line option (or C<constants.txt> in the same directory as |
| 585 |
C<update-exported-constants> if a value for B<-C> was not specified), does not |
| 586 |
exist. Ensure C<constants.txt> exists, or specify an alternative path with |
| 587 |
B<-C I<PATH>>. |
| 588 |
|
| 589 |
=item B<Failed to parse command line options: Net::SSLeay module file I<PATH> |
| 590 |
does not exist> |
| 591 |
|
| 592 |
C<update-exported-constants> updates and overwrites the Net::SSLeay module file |
| 593 |
specified by the B<-m> command line option (or C<../lib/Net/SSLeay.pm> relative |
| 594 |
to the path to C<update-exported-constants> if a value for B<-m> was not |
| 595 |
specified), but a file could not be found at this path. Ensure |
| 596 |
C<../lib/Net/SSLeay.pm> exists, or specify an alternative path with |
| 597 |
B<-m I<PATH>>. |
| 598 |
|
| 599 |
=item B<Failed to parse command line options: Pod file I<PATH> does not exist> |
| 600 |
|
| 601 |
C<update-exported-constants> updates and overwrites the Pod file containing the |
| 602 |
Net::SSLeay documentation at the path specified by the B<-p> command line option |
| 603 |
(or C<../lib/Net/SSLeay.pod> relative to the path to |
| 604 |
C<update-exported-constants> if a value for B<-p> was not specified), but a file |
| 605 |
could not be found at this path. Ensure C<../lib/Net/SSLeay.pod> exists, or |
| 606 |
specify an alternative path with B<-p I<PATH>>. |
| 607 |
|
| 608 |
=item B<Failed to load configuration file: I<REASON>> |
| 609 |
|
| 610 |
The configuration file could not be loaded because of I<REASON>, which is |
| 611 |
probably an OS-level error. Ensure the path given by the B<-C> option, or the |
| 612 |
default path if B<-C> was not specified, is readable. |
| 613 |
|
| 614 |
=item B<Failed to generate constants file: I<REASON>> |
| 615 |
|
| 616 |
The constants C source file could not be written because of I<REASON>, which is |
| 617 |
probably an OS-level error. Ensure that the path given by the B<-c> option, or |
| 618 |
the default path if B<-c> was not specified, is writable. |
| 619 |
|
| 620 |
=item B<Failed to generate constants test script: I<REASON>> |
| 621 |
|
| 622 |
The constants test script could not be written because of I<REASON>, which is |
| 623 |
probably an OS-level error. Ensure that the path given by the B<-t> option, or |
| 624 |
the default path if B<-t> was not specified, is writable. |
| 625 |
|
| 626 |
=item B<Failed to update Net::SSLeay module file: could not find @constants |
| 627 |
declaration> |
| 628 |
|
| 629 |
The Net::SSLeay module file was read, but an updated constants list could not be |
| 630 |
written to it because the definition of the C<@constants> array could not be |
| 631 |
found. C<update-exported-constants> expects this array to be defined with the |
| 632 |
following syntax: |
| 633 |
|
| 634 |
my @constants = qw( |
| 635 |
# <Constants list> |
| 636 |
); |
| 637 |
|
| 638 |
Ensure the C<@constants> array is defined in this way in the Net::SSLeay module. |
| 639 |
|
| 640 |
=item B<Failed to update Net::SSLeay module file: I<REASON>> |
| 641 |
|
| 642 |
The Net::SSLeay module file could not be either read or written because of |
| 643 |
I<REASON>, which is probably an OS-level error. Ensure that the path given by |
| 644 |
the B<-m> option, or the default path if B<-m> was not specified, is both |
| 645 |
readable and writable. |
| 646 |
|
| 647 |
=item B<Failed to update Pod file: could not find constants block> |
| 648 |
|
| 649 |
The Net::SSLeay documentation file was read, but an updated constants list could |
| 650 |
not be written to it because the Pod code block listing the constants could not |
| 651 |
be found. C<update-exported-constants> expects this block to be surrounded by |
| 652 |
the following Pod commands: |
| 653 |
|
| 654 |
=for start_constants |
| 655 |
|
| 656 |
<Constants list> |
| 657 |
|
| 658 |
=for end_constants |
| 659 |
|
| 660 |
Ensure the constants list is defined in this way in the documentation. |
| 661 |
|
| 662 |
=item B<Failed to update Pod file: I<REASON>> |
| 663 |
|
| 664 |
The Net::SSLeay documentation file could not be either read or written because |
| 665 |
of I<REASON>, which is probably an OS-level error. Ensure that the path given by |
| 666 |
the B<-p> option, or the default path if B<-p> was not specified, is both |
| 667 |
readable and writable. |
| 668 |
|
| 669 |
=back |
| 670 |
|
| 671 |
=head1 LIMITATIONS |
| 672 |
|
| 673 |
Net::SSLeay currently returns the values of libssl and libcrypto constants as |
| 674 |
double-precision floating-point numbers, regardless of the data type of the |
| 675 |
underlying constant as it is defined by OpenSSL and/or LibreSSL; the C source |
| 676 |
file generated by C<update-exported-constants> therefore defines a function |
| 677 |
C<constant> with the return type C<double>. While all constants currently |
| 678 |
exported by Net::SSLeay can be stored in this way without loss of precision, |
| 679 |
this may not necessarily be the case for all constants defined by libssl and |
| 680 |
libcrypto, either now or in the future. |
| 681 |
|
| 682 |
=head1 SEE ALSO |
| 683 |
|
| 684 |
The man pages for OpenSSL and LibreSSL, which describe the constants they define |
| 685 |
(and therefore the constants that may be exported by Net::SSLeay). |
| 686 |
|
| 687 |
=head1 BUGS |
| 688 |
|
| 689 |
If you encounter a problem with this program that you believe is a bug, please |
| 690 |
L<create a new issue|https://github.com/radiator-software/p5-net-ssleay/issues/new> |
| 691 |
in the Net-SSLeay GitHub repository. Please make sure your bug report includes |
| 692 |
the following information: |
| 693 |
|
| 694 |
=over |
| 695 |
|
| 696 |
=item * |
| 697 |
|
| 698 |
the list of command line options passed to C<update-exported-constants>; |
| 699 |
|
| 700 |
=item * |
| 701 |
|
| 702 |
the full configuration file given by the B<-C> command line option (or the |
| 703 |
default configuration file if B<-C> was not specified); |
| 704 |
|
| 705 |
=item * |
| 706 |
|
| 707 |
the full output of C<update-exported-constants>; |
| 708 |
|
| 709 |
=item * |
| 710 |
|
| 711 |
your operating system name and version; |
| 712 |
|
| 713 |
=item * |
| 714 |
|
| 715 |
the output of C<perl -V>; |
| 716 |
|
| 717 |
=item * |
| 718 |
|
| 719 |
the version of Net-SSLeay you are using. |
| 720 |
|
| 721 |
=back |
| 722 |
|
| 723 |
=head1 AUTHORS |
| 724 |
|
| 725 |
Originally written by Chris Novakovic. |
| 726 |
|
| 727 |
Maintained by Chris Novakovic and Heikki Vatiainen. |
| 728 |
|
| 729 |
=head1 COPYRIGHT AND LICENSE |
| 730 |
|
| 731 |
Copyright 2021- Chris Novakovic <[email protected]>. |
| 732 |
|
| 733 |
Copyright 2021- Heikki Vatiainen <[email protected]>. |
| 734 |
|
| 735 |
This module is released under the terms of the Artistic License 2.0. For |
| 736 |
details, see the C<LICENSE> file distributed with Net-SSLeay's source code. |
| 737 |
|
| 738 |
=cut |
| 739 |
|
| 740 |
__DATA__ |
| 741 |
[section:constants_c_header] |
| 742 |
/* |
| 743 |
* This file is automatically generated - do not manually modify it. |
| 744 |
* |
| 745 |
* To add or remove a constant, edit helper_script/constants.txt, then run |
| 746 |
* helper_script/update-exported-constants. |
| 747 |
*/ |
| 748 |
|
| 749 |
[section:assignment_clause_for_type] |
| 750 |
|
| 751 |
#ifdef {{ value }} |
| 752 |
return {{ value }}; |
| 753 |
#else |
| 754 |
goto not_there; |
| 755 |
#endif |
| 756 |
[section:return_statement_for_notfound] |
| 757 |
|
| 758 |
errno = EINVAL; |
| 759 |
return 0; |
| 760 |
|
| 761 |
not_there: |
| 762 |
errno = ENOENT; |
| 763 |
return 0; |
| 764 |
[section:constants_test] |
| 765 |
# This file is automatically generated - do not manually modify it. |
| 766 |
# |
| 767 |
# To add or remove a constant, edit helper_script/constants.txt, then run |
| 768 |
# helper_script/update-exported-constants. |
| 769 |
|
| 770 |
use lib 'inc'; |
| 771 |
|
| 772 |
use Net::SSLeay; |
| 773 |
use Test::Net::SSLeay qw(dies_like); |
| 774 |
|
| 775 |
# We rely on symbolic references in the dies_like() tests: |
| 776 |
no strict 'refs'; |
| 777 |
|
| 778 |
plan tests => {{ tests }}; |
| 779 |
|
| 780 |
my @constants = qw( |
| 781 |
{{ constants }} |
| 782 |
); |
| 783 |
|
| 784 |
my %exported = map { $_ => 1 } @Net::SSLeay::EXPORT_OK; |
| 785 |
my @missing; |
| 786 |
|
| 787 |
for my $c (@constants) { |
| 788 |
dies_like( |
| 789 |
sub { "Net::SSLeay::$c"->(); die "ok\n"; }, |
| 790 |
qr/^(?:ok\n$|Your vendor has not defined SSLeay macro )/, |
| 791 |
"constant is exported or not defined: $c" |
| 792 |
); |
| 793 |
push @missing, $c if !exists $exported{$c}; |
| 794 |
} |
| 795 |
|
| 796 |
is( |
| 797 |
join( q{,}, sort @missing ), |
| 798 |
'', |
| 799 |
'no constants missing from @EXPORT_OK (total missing: ' . scalar(@missing) . ')' |
| 800 |
); |
| 801 |
|
| 802 |
dies_like( |
| 803 |
sub { Net::SSLeay::_NET_SSLEAY_TEST_UNDEFINED_CONSTANT() }, |
| 804 |
qr/^Your vendor has not defined SSLeay macro _NET_SSLEAY_TEST_UNDEFINED_CONSTANT/, |
| 805 |
'referencing an undefined constant raises an exception' |
| 806 |
); |