home *** CD-ROM | disk | FTP | other *** search
/ ftp.rsa.com / 2014.05.ftp.rsa.com.tar / ftp.rsa.com / pub / dsg / public / doxygen / doxytmpl.pl < prev    next >
Perl Script  |  2014-05-02  |  14KB  |  627 lines
  1. #!/usr/local/bin/perl
  2. #
  3. # $Id: doxytmpl.pl,v 1.54 2002/11/24 22:07:33 jleiseboer Exp $
  4. #
  5. #/**
  6. # * @file
  7. # *
  8. # * This file handles the generation of doxygen templates.
  9. # *
  10. # * There is a standard set of doxygen options that make sense to have
  11. # * in all projects. doxytmpl sets up those settings as changes from the
  12. # * default doxygen configuration file.
  13. # *
  14. # * @see doxytmpl.pl, doxyfilt.pl
  15. # *
  16. # */
  17. #
  18.  
  19. use Cwd;
  20. use File::Basename;
  21.  
  22. # progname = lowercase program name without the .pl removed
  23. $progname = $0;
  24. $progname =~ s/\\/\//g;
  25.  
  26. # figure out a nice user friendly name for the program
  27. $program = $progname;
  28. $program =~ s/\.pl$//;
  29. $program = lc $program;
  30. $program = &basename($program);
  31.  
  32. # debug - output trace messages in script
  33. $debug=0;
  34.  
  35. $internal=0;
  36. $review=0;
  37. $todo=0;
  38.  
  39. $VARS{"DOXYGEN"}="doxygen";
  40. $VARS{"DOXYFILT"}="doxyfilt.pl";
  41.  
  42. # dot is used for diagrams
  43. $dot="dot";
  44.  
  45. # inputlist - the filename from -inputlist=file which contains the
  46. #             list of files to process (rather than recursive from
  47. #             current directory)
  48. $inputlist="";
  49.  
  50. #
  51. # The path we search to find templates - which we handle
  52. # differently depending on Win32 or Unix environments
  53. #
  54. if ($^O =~ /Win/)
  55.   {
  56.   $VARS{"PATH_SEP"}=";";
  57.   $VARS{"TEMPLATE_PATH"}="c:/bin;c:/bin/doxygen";
  58.   $VARS{"TEMPLATE_PATH"}.=";c:/lib;c:/lib/doxygen";
  59.   $VARS{"TEMPLATE_PATH"}.=";c:/usr/local/bin;c:/usr/local/bin/doxygen";
  60.   $VARS{"TEMPLATE_PATH"}.=";c:/usr/local/lib;c:/usr/local/lib/doxygen";
  61.   $VARS{"LOCAL_BIN"}="c:/bin;c:/usr/local/bin";
  62.   $VARS{"LOCAL_BIN"}.=";".$ENV{"HOME"}."/bin";
  63.   $VARS{"LOCAL_BIN"}.=";".$ENV{"PATH"};
  64.   $VARS{"DIR_SEP"}='\\';
  65.   }
  66. else
  67.   {
  68.   $VARS{"PATH_SEP"}=":";
  69.   $VARS{"TEMPLATE_PATH"}="/usr/local/lib/doxygen";
  70.   $VARS{"LOCAL_BIN"}="/usr/local/bin";
  71.   $VARS{"LOCAL_BIN"}.=":".$ENV{"HOME"}."/bin";
  72.   $VARS{"LOCAL_BIN"}.=":".$ENV{"PATH"};
  73.   $VARS{"DIR_SEP"}='/';
  74.   }
  75.  
  76. #
  77. # If we have a $HOME/doxygen directory it is used in preference to
  78. # anything (other than the DOXYGEN_TEMPLATE env var)
  79. #
  80. if ($ENV{"HOME"})
  81.   {
  82.   if (-d $ENV{"HOME"}."/doxygen")
  83.     {
  84.     $VARS{"TEMPLATE_PATH"}=$ENV{"HOME"}."/doxygen".$VARS{"PATH_SEP"}.
  85.               $VARS{"TEMPLATE_PATH"};
  86.     }
  87.   }
  88.  
  89. #
  90. # If we have a DOXYGEN_TEMPLATE environment variable then it is used
  91. # in preference to anything else
  92. #
  93. if ($ENV{"DOXYGEN_TEMPLATE"})
  94.   {
  95.   $VARS{"TEMPLATE_PATH"}=$ENV{"DOXYGEN_TEMPLATE"}.$VARS{"PATH_SEP"}.
  96.               $VARS{"TEMPLATE_PATH"};
  97.   }
  98.  
  99.  
  100. #
  101. # Process args
  102. #
  103. foreach (@ARGV)
  104.   {
  105.   if (/^-internal$/)
  106.     {
  107.     $internal=1;
  108.     }
  109.   elsif (/^-review$/)
  110.     {
  111.     $review=1;
  112.     }
  113.   elsif (/^-inputlist=(.*)$/)
  114.     {
  115.     $inputlist=$1;
  116.     }
  117.   elsif (/^-d$/)
  118.     {
  119.     $debug++;
  120.     }
  121.   elsif (/^([^=]*)=(.*)$/)
  122.     {
  123.     $VARS{$1}=$2;
  124.     }
  125.   else
  126.     {
  127.     &do_help("$prog: ERROR: Unknown option $_",1);
  128.     }
  129.   }
  130.  
  131. &get_date();
  132. $doxygen=$VARS{"DOXYGEN"};
  133. $doxyfilt=$VARS{"DOXYFILT"};
  134. $path_sep=$VARS{"PATH_SEP"};
  135.  
  136.  
  137. #
  138. # dump out a list of var=value if we are debugging things
  139. #
  140. if ($debug)
  141.   {
  142.   local($var);
  143.  
  144.   foreach $var (sort keys %VARS)
  145.     {
  146.     print STDERR "$var=" . $VARS{"$var"} . "\n";
  147.     }
  148.   }
  149.  
  150.  
  151. #
  152. # locate doxygen in the path
  153. #
  154. $doxygen="";
  155. $doxyfilt="";
  156. $dot_path="";
  157. if (-f $VARS{"DOXYGEN"} || -f $VARS{"DOXYGEN"}.".exe" )
  158.   {
  159.   $doxygen=$VARS{"DOXYGEN"};
  160.   }
  161.  
  162. if (-f $VARS{"DOXYFILT"} || -f $VARS{"DOXYFILT"}.".exe" )
  163.   {
  164.   $doxyfilt=$VARS{"DOXYFILT"};
  165.   }
  166.  
  167. if (-f $dot ||  -f "${dot}.exe")
  168.   {
  169.   $dot_path=$dot;
  170.   }
  171.  
  172. #
  173. # - second search the provided path list
  174. #
  175. foreach $dir (split(/$path_sep/,$VARS{"LOCAL_BIN"}))
  176.   {
  177.   if (!$doxygen)
  178.     {
  179.     if (-f "$dir/".$VARS{"DOXYGEN"} || -f "$dir/".$VARS{"DOXYGEN"}.".exe" )
  180.       {
  181.       $doxygen="$dir/".$VARS{"DOXYGEN"};
  182.       }
  183.     }
  184.   if (!$doxyfilt)
  185.     {
  186.     if (-f "$dir/".$VARS{"DOXYFILT"})
  187.       {
  188.       $doxyfilt="$dir/".$VARS{"DOXYFILT"};
  189.       }
  190.     }
  191.   if (!$dot_path)
  192.     {
  193.     if (-f "$dir/$dot" || -f "$dir/${dot}.exe")
  194.       {
  195.       $dot_path="$dir";
  196.       }
  197.     }
  198.   if($doxygen && $doxyfilt)
  199.     {
  200.     last;
  201.     }
  202.   }
  203.  
  204. if (!$doxygen)
  205.   {
  206.   print STDERR "unable to locate doxygen executable\n";
  207.   exit(1);
  208.   }
  209.  
  210. if (!$doxyfilt)
  211.   {
  212.   print STDERR "unable to locate doxyfilt script\n";
  213.   exit(1);
  214.   }
  215.  
  216. if (!$dot_path)
  217.   {
  218.   print STDERR "\nWARNING: unable to locate dot in path - no diagrams\n\n";
  219.   sleep(2);
  220.   }
  221. else
  222.   {
  223.   $dot_path=~s/[\\\/]/$VARS{"DIR_SEP"}/g;
  224.   ##$VARS{"HAVE_DOT"}="YES";
  225.   $VARS{"DOT_PATH"}="$dot_path";
  226.   }
  227.  
  228. %defaults = (
  229.     'PROJECT_NAME', "$basename",
  230.     'DETAIL_SECTION_FIRST', "YES",
  231.     'OUTPUT_DIRECTORY', "doc",
  232.     'HIDE_UNDOC_MEMBERS', "YES",
  233.     'HIDE_UNDOC_CLASSES', "YES",
  234.     'INTERNAL_DOCS', "NO",
  235.     'INVARIANT_DOCS',"NO",
  236.     'CLASS_DIAGRAMS', "NO",
  237.     'SOURCE_BROWSER', "YES",
  238.     'DEFINED_AT_RELATION', "NO",
  239.     'REFERENCED_BY_RELATION', "NO",
  240.     'REFERENCES_RELATION', "NO",
  241.     'STRIP_CODE_COMMENTS', "YES",
  242.     'CASE_SENSE_NAMES', "YES",
  243.     'JAVADOC_AUTOBRIEF', "YES",
  244.     'GENERATE_TODOLIST', "NO",
  245.     'GENERATE_TESTLIST', "NO",
  246.     'GENERATE_BUGLIST', "NO",
  247.     'MAX_INITIALIZER_LINES', "0",
  248.     'OPTIMIZE_OUTPUT_FOR_C', "YES",
  249.     'SHOW_USED_FILES', "NO",
  250.     'WARNINGS', "YES",
  251.     'WARN_IF_UNDOCUMENTED', "YES",
  252.     'INPUT', ".",
  253.     #
  254.     # file patterns should include all scripts
  255.     #
  256.     # 'FILE_PATTERNS', "*.h *.c *.s *.asm *.cpp";
  257.     #
  258.     'FILE_PATTERNS', "*.h *.c *.s *.asm *.cpp *.bat *.sh *.pl *.dox *.bas *.cls *.vbs *.txt",
  259.     'RECURSIVE', "YES",
  260.     'EXCLUDE', "tmp out outinc",
  261.     'INPUT_FILTER',       "\"perl -S $doxyfilt\"",
  262.     'FILTER_SOURCE_FILES',  "NO",
  263.     'ALPHABETICAL_INDEX', "NO",
  264.     'GENERATE_HTML', "YES",
  265.     'HTML_ALIGN_MEMBERS', "YES",
  266.     'TOC_EXPAND', "NO",
  267.     'GENERATE_TREEVIEW',  "YES",
  268.     'DISABLE_INDEX', "YES",
  269.     'ENUM_VALUES_PER_LINE', "4",
  270.     'GENERATE_TREEVIEW', "YES",
  271.     'TREEVIEW_WIDTH', "275",
  272.     'GENERATE_LATEX',     "NO",
  273.     'GENERATE_RTF',       "NO",
  274.     'GENERATE_MAN',       "NO",
  275.     'ENABLE_PREPROCESSING', "YES",
  276.     'PREDEFINED', "NO_SPLIT",
  277.     'HAVE_DOT', "NO",
  278.     'SEARCHENGINE', "NO",
  279.     'EXTRACT_LOCAL_CLASSES', "NO",
  280.     'TOC_EXCLUDE_PATTERNS', "*.c *.cpp *.dox *.txt",
  281.     'HIDE_SCOPE_NAMES', "YES",
  282.     'EXAMPLE_PATH', "docsrc",
  283.     'EXAMPLE_PATTERNS', "*.c *.h *.cpp *.dox *.txt",
  284.     'EXAMPLE_RECURSIVE', "YES",
  285.     'IMAGE_PATH', "docsrc/images",
  286.     'OUTPUT_TYPEDEFS', "YES",
  287.     #'TOC_STYLE', "original,extracrispy",
  288.     'TOC_STYLE', "spicy",
  289.     'COLS_IN_ALPHA_INDEX', "3",
  290.     'ALIASES', '"eg=\par Example:\n<br>" "br=@code @endcode\n"',
  291.     'INLINE_CLASS_DECL', "YES",
  292. );
  293.  
  294. %internal_defaults = (
  295.     'EXTRACT_ALL', "YES",
  296.     'EXTRACT_PRIVATE', "YES",
  297.     'EXTRACT_STATIC', "YES",
  298.     'HIDE_UNDOC_MEMBERS', "NO",
  299.     'INTERNAL_DOCS', "YES",
  300.     'INVARIANT_DOCS', "YES",
  301.     'CLASS_DIAGRAMS', "YES",
  302.     'DEFINED_AT_RELATION', "YES",
  303.     'REFERENCED_BY_RELATION', "YES",
  304.     'REFERENCES_RELATION', "YES",
  305.     'STRIP_CODE_COMMENTS', "NO",
  306.     'ENABLED_SECTIONS', "internal todo",
  307.     'GENERATE_TODOLIST', "YES",
  308.     'GENERATE_TESTLIST', "YES",
  309.     'GENERATE_BUGLIST', "YES",
  310.     'CLASS_GRAPH', "YES",
  311.     'COLLABORATION_GRAPH', "YES",
  312.     'INCLUDE_GRAPH', "YES",
  313.     'GRAPHICAL_HIERARCHY', "YES",
  314.     'EXTRACT_LOCAL_CLASSES', "YES",
  315.     'TOC_EXCLUDE_PATTERNS', "",
  316. );
  317.  
  318. %review_defaults = (
  319.     'EXTRACT_ALL', "YES",
  320.     'EXTRACT_PRIVATE', "YES",
  321.     'EXTRACT_STATIC', "YES",
  322.     'HIDE_UNDOC_MEMBERS', "NO",
  323.     'INTERNAL_DOCS', "YES",
  324.     'INVARIANT_DOCS', "YES",
  325.     'CLASS_DIAGRAMS', "YES",
  326.     'INLINE_SOURCES', "YES",
  327.     'STRIP_CODE_COMMENTS', "NO",
  328.     'ENABLED_SECTIONS', "internal todo",
  329.     'DEFINED_AT_RELATION', "YES",
  330.     'GENERATE_TODOLIST', "YES",
  331.     'GENERATE_TESTLIST', "YES",
  332.     'GENERATE_BUGLIST', "YES",
  333.     'CLASS_GRAPH', "YES",
  334.     'COLLABORATION_GRAPH', "YES",
  335.     'INCLUDE_GRAPH', "YES",
  336.     'GRAPHICAL_HIERARCHY', "YES",
  337.     'EXTRACT_LOCAL_CLASSES', "YES",
  338.     'TOC_EXCLUDE_PATTERNS', "",
  339. );
  340.  
  341.  
  342. #
  343. # do_help - report usage
  344. #
  345. sub do_help
  346.   {
  347.   local($message,$exit_value)=@_;
  348.  
  349.   #
  350.   # the help needs expanded - but this is all there is for the moment
  351.   #
  352.   print <<"EOF";
  353. $message
  354. $prog - generate doxygen template
  355. options:
  356.         -d                          - switch on debug (for the script)
  357.         VAR=VALUE                   - set the value of VAR
  358.  
  359. vars:
  360.         DOXYGEN=program             - name of doxygen executable
  361.         DOXYFILT=perl_program       - name of perl doxyfilt.pl program
  362.     doxygen_config_var=value    - set doxygen config variable to
  363.                       value (overrides other settings)
  364.  
  365. EOF
  366.   exit($exit_value);
  367.   }
  368.  
  369. #
  370. # Each template file has a separate variable and if the user
  371. # has not supplied a value then we search the template path to
  372. # see if there is an override
  373. #
  374. %template_vars = (
  375.   'HTML_HEADER',     'header.html',
  376.   'HTML_FOOTER',     'footer.html',
  377.   'HTML_STYLESHEET',     'rsa.css',
  378.   'HTML_EXTRA_FILES',    'rsa.gif',
  379.   'LATEX_HEADER',    'header.tex',
  380.   'RTF_STYLESHEET_FILE', 'stylesheet.rtf',
  381. );
  382.  
  383. foreach $template (keys %template_vars)
  384.   {
  385.   local($found)=0;
  386.  
  387.   #
  388.   # if we have no setting then we use the defaults we have in the
  389.   # table above
  390.   #
  391.   if (!defined($VARS{$template}))
  392.     {
  393.     $VARS{$template}=$template_vars{$template};
  394.     }
  395.  
  396.   #
  397.   # now try and locate the file - first as a direct value and
  398.   # then using the template path
  399.   #
  400.   if ( -f $VARS{$template} )
  401.     {
  402.     $found=1;
  403.     }
  404.   else
  405.     {
  406. DIR:
  407.     foreach $dir (split(/$path_sep/,$VARS{"TEMPLATE_PATH"}))
  408.       {
  409.       if ( -f "$dir/".$VARS{$template} )
  410.         {
  411.     $VARS{$template}="$dir/".$VARS{$template};
  412.     $found=1;
  413.     last DIR;
  414.     }
  415.       }
  416.     }
  417.  
  418.   if (!$found)
  419.     {
  420.     undef $VARS{$template};
  421.     }
  422.  
  423.   if ($debug)
  424.     {
  425.     print STDERR "TEMPLATE $template = " . $VARS{$template} . "\n";
  426.     }
  427.   }
  428.  
  429. #
  430. # we need to know the current directory - as we add that into the
  431. # configuration file
  432. #
  433. $currentdir=&cwd();
  434. $basename=&basename($currentdir);
  435. $dirname=&dirname($currentdir);
  436.  
  437. #
  438. # If we have not had a doxyfile (the doxygen configuration file)
  439. # specified then we use the basename of the directory with .doxy
  440. # appended
  441. #
  442. if (!$VARS{"DOXYFILE"})
  443.   {
  444.   $VARS{"DOXYFILE"}="${basename}.doxy";
  445.   }
  446.  
  447. $outfile=$VARS{"DOXYFILE"};
  448.  
  449.  
  450. if ($debug)
  451.   {
  452.   print STDERR "prog: $progname  pdir=$pdir dir=$dirname base=$basename\n";
  453.   }
  454.  
  455. #
  456. # Write out a simple header so it is clear what generated this
  457. # configuration file (and when it was generated) and the settings
  458. # (command line args) that were used.
  459. #
  460. $output="#\n# generated by $progname - $date\n#\n";
  461. $output.="# " . join(" ",@ARGV) . "\n";
  462. $output.="#\n";
  463.  
  464. $doxygen=~s/[\\\/]/$VARS{"DIR_SEP"}/g;
  465.  
  466. # if we have an input list then we need to load that in now
  467. if ($inputlist && !$VARS{"INPUT"} && !$VARS{"INPUT_FILE"})
  468.   {
  469.   $VARS{"RECURSIVE"}="NO";
  470.   $VARS{"INPUT"}=" \\\n";
  471.   open(INPUT,"<$inputlist") || die "Unable to open $inputlist - $!\n";
  472.   while(<INPUT>)
  473.     {
  474.     # ignore comments
  475.     next if /^#/;
  476.     chop;
  477.     $VARS{"INPUT"}.="\t\t$_ \\\n";
  478.     }
  479.   $VARS{"INPUT"}.="\n";
  480.   close(INPUT);
  481.   }
  482.  
  483.  
  484. #
  485. # Handling loading patterns from files ...
  486. #
  487. foreach $var (keys %VARS)
  488.   {
  489.   if ($var =~ m/(.*_PATTERNS)_FILE$/ || $var =~ m/^(INPUT_FILE)$/)
  490.     {
  491.     $pattern_var=$1;
  492.     if ($pattern_var eq "INPUT_FILE")
  493.       {
  494.       $pattern_var = "INPUT";
  495.       }
  496.     $value=$VARS{$var};
  497.     if ($debug)
  498.       {
  499.       print STDERR "PATTERN FILE VAR $pattern_var\n";
  500.       }
  501.     if (open(PATTERN,"<$value"))
  502.       {
  503.       $VARS{"$pattern_var"}=" \\\n";
  504.       while(<PATTERN>)
  505.     {
  506.     # ignore comments
  507.     next if /^#/;
  508.     chop;
  509.     $VARS{"$pattern_var"}.="\t\t$_ \\\n";
  510.     }
  511.       close(PATTERN);
  512.       $VARS{"$pattern_var"}.="\n";
  513.       }
  514.     else
  515.       {
  516.       print STDERR "Warning - unable to open $var file - $!\n";
  517.       }
  518.     }
  519.   }
  520.  
  521. $exec="$doxygen -g- |";
  522. if ($debug)
  523.   {
  524.   print STDERR "EXECUTE: \"$exec\"\n";
  525.   }
  526.  
  527. open(DOXYGEN,"$exec") || die "unable to run $doxygen - $!\n";
  528. while(<DOXYGEN>)
  529.   {
  530.   local($changed);
  531.  
  532.   chop;
  533.   if ( /^([A-Z0-9_]+)\s*=\s*(.*)/ )
  534.     {
  535.     $var=$1;
  536.     $value=$2;
  537.     $changed=0;
  538.     if ($debug)
  539.       {
  540.       print STDERR "$var $value\n";
  541.       }
  542.  
  543.     #
  544.     # if we have a default value for a variable we use it
  545.     #
  546.     if (defined $defaults{"$var"})
  547.       {
  548.       $value=$defaults{"$var"};
  549.       $changed=1;
  550.       }
  551.  
  552.     #
  553.     # if we are generating internal documentation then if we match
  554.     # an internal variable we use its value
  555.     #
  556.     if ($internal && defined $internal_defaults{"$var"})
  557.       {
  558.       $value=$internal_defaults{"$var"};
  559.       $changed=1;
  560.       }
  561.  
  562.     #
  563.     # if we are generating review documentation then if we match
  564.     # an internal variable we use its value
  565.     #
  566.     if ($review && defined $review_defaults{"$var"})
  567.       {
  568.       $value=$review_defaults{"$var"};
  569.       $changed=1;
  570.       }
  571.  
  572.     #
  573.     # if we got a doxygen config variable value on the command line
  574.     # then we use it - this provides a generic mechanism for just
  575.     # updating values so that hand-editing of doxygen config files
  576.     # should not be necessary
  577.     #
  578.     if (defined $VARS{"$var"})
  579.       {
  580.       $value=$VARS{"$var"};
  581.       $changed=1;
  582.       }
  583.     #
  584.     # Now simply write out the value (which may be what was there
  585.     # originally or may have been changed by any of the conditions
  586.     # above)
  587.     #
  588.     if ($changed && $debug)
  589.         {
  590.         print STDERR "*** $var $value\n";
  591.         }
  592.     $output.="$var = $value\n";
  593.     }
  594.   else
  595.     {
  596.     #
  597.     # If it isn't VAR=value then we simply output it intact
  598.     #
  599.     $output.="$_\n";
  600.     }
  601.   }
  602. close(DOXYGEN);
  603.  
  604. #
  605. # Write the output to the configuration file
  606. #
  607. open(OUT,">$outfile") || die "unable to create $outfile - $!\n";
  608. print OUT "$output";
  609. close(OUT);
  610.  
  611. print "$program: created doxygen config file $outfile\n";
  612.  
  613. exit(0);
  614.  
  615. sub get_date
  616.   {
  617.   local(@month,@a);
  618.  
  619.   @month=('Jan','Feb','Mar','Apr','May','Jun',
  620.           'Jul','Aug','Sep','Oct','Nov','Dec');
  621.   @a=localtime(time());
  622.   $date=sprintf("%02d-%s-%04d",$a[3],$month[$a[4]],$a[5]+1900);
  623.  
  624.   return($date);
  625.   }
  626.  
  627.