doc/man-pages/pod1/afs_compile_et.pod

   1 =head1 NAME
   2
   3 afs_compile_et - Produce error text tables for compilation
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<afs_compile_et> [B<-debug>] S<<< [B<-language> <I<lang>>] >>>
  11     S<<< [B<-prefix> <I<prefix>>] >>> S<<< [B<-v> <I<version>>] >>>
  12     S<<< [B<-h> <I<include>>] >>> <S<<< [B<-emit> <I<output>>] >>>
  13     I<error_table>>
  14
  15 =for html
  16 </div>
  17
  18 =head1 DESCRIPTION
  19
  20 The B<afs_compile_et> command builds the error text tables for compilation.
  21 This includes both a header file that contains a set of mappings between
  22 error names and values and a F<.c> (or F<.msf>) file that provides a text
  23 table of descriptions.
  24
  25 The <I<error_table>> argument specifies which error table to generate.
  26 The error table specification should exist in the current working
  27 directory or in the directory specified with B<-prefix> and should be
  28 named F<error_table.et>.
  29
  30 By default, B<afs_compile_et> generates two files in one invocation. This is
  31 problematic for parallel build systems. The B<-emit> option may be used to
  32 generate the output files independently with two separate invocations of
  33 B<afs_compile_et> for a given error table. This allows parallel build systems
  34 to generate the source and header files, and the targets which depend on the
  35 generated source and headers files, in parallel.
  36
  37 =head1 CAUTIONS
  38
  39 This command is used internally within the build process for OpenAFS.
  40 Most users will access this information via L<translate_et(1)> rather than
  41 via B<afs_compile_et>.
  42
  43 This command does not use the standard AFS command-line parsing package.
  44
  45 =head1 OPTIONS
  46
  47 =over 4
  48
  49 =item B<-debug>
  50
  51 Does nothing.  It neither adds debugging information to the output nor
  52 provides additional information on its operation.
  53
  54 =item B<-language> <I<lang>>
  55
  56 Specifies the type of output to generate.  Currently, only ANSI C and K&R
  57 are supported values (via the B<c> and B<k&r-c> values, respectively).
  58 The default is ANSI C.  There is some support for C++ started, but that is
  59 not yet supported.
  60
  61 The B<-lang> <I<lang>> option is a synonym for B<-language> <I<lang>>>.
  62
  63 =item B<-prefix> <I<prefix>>
  64
  65 Specifies the directory to search for the F<error_table.et> file. Specifies
  66 the directory to search for the prolog file when the B<-h> option is
  67 given.  The B<-p> <I<prefix>> option is a synonym for B<-prefix> <I<prefix>>.
  68
  69 =item B<-h> <I<include>>
  70
  71 Specifies an input file, called a prolog file, and modifies the name of the
  72 header file generated by B<afs_compile_et>.
  73
  74 When the B<-h> option is given, B<afs_compile_et> will search for a prolog file
  75 named <I<include>>F<.p.h>.  B<afs_compile_et> will search the current working
  76 directory for the prolog file, unless the B<-p> option is given.  If the prolog
  77 file is found, B<afs_compile_et> will place a verbatim copy of the prolog
  78 file contents into the generated header file.
  79
  80 When the B<-h> option is given, the name of the header file generated by
  81 B<afs_compile_et> is <I<include>>F<.h>, instead of <I<error_table>>F<.h>.
  82
  83 The B<-h> option does not affect the source file generated by B<afs_compile_et>.
  84
  85 =item B<-v> <I<version>>
  86
  87 Specified the type of output file: valid values are 1 (the default, for C
  88 files) or 2, for B<.msf> file generation.
  89
  90 =item B<-emit> <I<output>>
  91
  92 Specifies which program file to generate; the header file or the source file.
  93 Specify B<-emit header> (or B<-emit h>) to generate the F<.h> header file.
  94 Specify B<-emit source> (or B<-emit c>) to generate the F<.c> (or F<.msf>)
  95 source file.
  96
  97 =back
  98
  99 =head1 EXAMPLES
 100
 101 The following command generates the files F<pterror.h> and F<pterror.c>,
 102 suitable for use with C programs:
 103
 104    % afs_compile_et -p path/to/src/ptserver pterror
 105
 106 The following command generates K&R style files instead:
 107
 108    % afs_compile_et -p path/to/src/ptserver -lang 'k&r-c' pterror
 109
 110 The following command generates the F<pterror.h> file, but not the F<pterror.c>
 111 file.
 112
 113    % afs_compile_et -p path/to/src/ptserver -emit header pterror
 114
 115 The following command generates the F<pterror.c> file, but not the F<pterror.h>
 116 file.
 117
 118    % afs_compile_et -p path/to/src/ptserver -emit source pterror
 119
 120 =head1 SEE ALSO
 121
 122 L<translate_et(1)>
 123
 124 =head1 COPYRIGHT
 125
 126 Copyright 2009 Steven Jenkins <steven@endpoint.com>
 127
 128 This documentation is covered by the IBM Public License Version 1.0.  This
 129 man page was written by Steven Jenkins for OpenAFS.