Debian Codegraph @

helper_script/update-exported-constants

raw
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 );