guide.html: run_doxygen uses bash.

2003-08-04  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/guide.html:  run_doxygen uses bash.
	* docs/doxygen/mainpage.html:  We'll be shipping tag files.
	* docs/doxygen/run_doxygen:  Tweaks and improvements.
	* docs/doxygen/user.cfg.in:  Set GENERATE_TAGFILE.
	* docs/html/install.html:  Update autoconf/automake requirements.
	* docs/html/test.html:  Add section describing DejaGNU support.
	* docs/html/17_intro/confdeps.dot:  New file, generates...
	* docs/html/17_intro/confdeps.png:  ...this new file.
	* docs/html/Makefile:  Generated here.
	* docs/html/17_intro/configury.html:  New file.

From-SVN: r70164

libstdc++-v3/ChangeLog

@@ -1,3 +1,16 @@
+2003-08-04  Phil Edwards  <pme@gcc.gnu.org>
+
+	* docs/doxygen/guide.html:  run_doxygen uses bash.
+	* docs/doxygen/mainpage.html:  We'll be shipping tag files.
+	* docs/doxygen/run_doxygen:  Tweaks and improvements.
+	* docs/doxygen/user.cfg.in:  Set GENERATE_TAGFILE.
+	* docs/html/install.html:  Update autoconf/automake requirements.
+	* docs/html/test.html:  Add section describing DejaGNU support.
+	* docs/html/17_intro/confdeps.dot:  New file, generates...
+	* docs/html/17_intro/confdeps.png:  ...this new file.
+	* docs/html/Makefile:  Generated here.
+	* docs/html/17_intro/configury.html:  New file.
+
 2003-07-31  Phil Edwards  <pme@gcc.gnu.org>
 
 	* testsuite/lib/libstdc++-v3-dg.exp:  Rename...

libstdc++-v3/docs/doxygen/guide.html

@@ -28,7 +28,7 @@
    <code>'make doxygen-maint'</code>, and <code>'make doxygen-man'</code>
    in the libstdc++-v3 build directory generate the user-level HTML docs, the
    maintainer-level HTML docs, and the man pages, respectively.  Prerequisite
-   tools are
+   tools are Bash 2.x, 
    <a href="http://www.doxygen.org/">
    <!-- snagged from the generated page -->
    <img src="doxygen.png" alt="Doxygen" align=center border=0 width=110 height=53>

libstdc++-v3/docs/doxygen/mainpage.html

@@ -58,6 +58,19 @@
    </ul>
 </p>
 
+<p>If you are using Doxygen for your own projects, you can use
+   <a href="libstdc++.tag">a tag file for the appropriate version</a> and
+   an entry such as
+   <blockquote>
+   TAGFILES = "libstdc++.tag = 
+   http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen"
+   </blockquote>
+   Be sure to adjust the URL for the right version.  If you download a
+   local copy of the source documentation for faster viewing, you can use
+   the doxytag/installdox programs (part of Doxygen) to adjust the links
+   for you.
+</p>
+
 <h2>Generating the documentation</h2>
 <p>These HTML pages are automatically generated, along with the man pages.
    See <code>docs/doxygen/guide.html</code> in the source tree for how to

libstdc++-v3/docs/doxygen/run_doxygen

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 
 # Runs doxygen and massages the output files.
 # Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
@@ -10,12 +10,11 @@
 
 # We can check now that the version of doxygen is >= this variable.
 DOXYVER=1.2.15
-doxygen=
 
 find_doxygen() {
-    v_required=`echo $DOXYVER |  \
+    local -r v_required=`echo $DOXYVER |  \
                 awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
-    testing_version=
+    local testing_version doxygen maybedoxy v_found
     # thank you goat book
     set `IFS=:; X="$PATH:/usr/local/bin:/bin:/usr/bin"; echo $X`
     for dir
@@ -36,6 +35,10 @@ find_doxygen() {
         echo run_doxygen error:  Could not find Doxygen $DOXYVER in path. 1>&2
         print_usage
     fi
+    # We need to use other tools from the same package/version.
+    echo :: Using Doxygen tools from ${dir}.
+    PATH=$dir:$PATH
+    hash -r
 }
 
 print_usage() {
@@ -142,8 +145,8 @@ test $do_man = yes && {
       -e "s=@do_man@=${do_man}=" \
       ${srcdir}/docs/doxygen/user.cfg.in > ${outdir}/${mode}.cfg
   echo :: NOTE that this may take some time...
-  echo $doxygen ${outdir}/${mode}.cfg
+  echo doxygen ${outdir}/${mode}.cfg
-  $doxygen ${outdir}/${mode}.cfg
+  doxygen ${outdir}/${mode}.cfg
   echo :: Finished, exit code was $?
 )
 ret=$?
@@ -151,6 +154,9 @@ test $ret -ne 0 && exit $ret
 
 test $do_html = yes && {
   cd ${outdir}/html_${mode}
+
+  #doxytag -t libstdc++.tag . > /dev/null 2>&1
+
   sed -e "s=@LEVEL@=${LEVELtext}=" \
       -e "s=@DATE@=${DATEtext}=" \
       ${srcdir}/docs/doxygen/mainpage.html > index.html

libstdc++-v3/docs/doxygen/user.cfg.in

@@ -902,7 +902,7 @@ TAGFILES               =
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create 
 # a tag file that is based on the input files it reads.
 
-GENERATE_TAGFILE       = 
+GENERATE_TAGFILE       = @outdir@/@html_output_dir@/libstdc++.tag
 
 # If the ALLEXTERNALS tag is set to YES all external classes will be listed 
 # in the class index. If set to NO only the inherited external classes 

libstdc++-v3/docs/html/17_intro/confdeps.dot

@@ -0,0 +1,14 @@
+# Blatantly ripped out of the graphviz examples and modified.  -pme
+digraph v3conf {
+    size="6,6";
+    node [color=lightblue2, style=filled];
+    "aclocal.m4" -> "acinclude.m4";
+    "configure" -> "aclocal.m4";
+    "configure" -> "configure.ac";
+    "configure" -> "crossconfig.m4";
+    "configure" -> "linkage.m4";
+    "[*/]Makefile.in" -> "Makefile.am";
+    "[*/]Makefile.in" -> "configure.ac";
+    "config.h.in" -> "acconfig.h";
+    "config.h.in" -> "configure.ac";
+}

libstdc++-v3/docs/html/17_intro/configury.html

@@ -0,0 +1,285 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html
+          PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+   <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
+   <meta name="DESCRIPTION" content="configury for libstdc++" />
+   <meta name="GENERATOR" content="vi and eight fingers" />
+   <title>libstdc++-v3 configury</title>
+<link rel="StyleSheet" href="../lib3styles.css" />
+</head>
+<body>
+
+<h1><code>&gt; open configury door</code></h1>
+<h1><code>&gt; look</code></h1>
+
+<p class="larger"><code>You are in a maze of twisty passages, all
+different.</code></p>
+<p class="larger"><code>It is dark.  You are likely to be eaten by a
+Canadian cross build.</code></p>
+
+
+<hr />
+<h2>Notes on libstdc++-v3 configury</h2>
+<blockquote>
+No problem is insoluble in all conceivable circumstances.<br />
+-- The Cosmic AC,
+<a href="http://people.inf.elte.hu/simi/szovegek/Asimov1.html">The
+Last Question</a>, by Isaac Asimov
+</blockquote>
+<ul>
+ <li><a href="#deps">what comes from where</a></li>
+ <li><a href="#breakout">storing information in non-AC files, like
+                         configure.host</a></li>
+ <li><a href="#general">general config notes</a></li>
+ <li><a href="#aclayout">acinclude.m4 layout</a></li>
+ <li><a href="#enable"><code>--enable</code> howto</a></li>
+</ul>
+
+<hr />
+<h3><a name="deps">what comes from where</a></h3>
+<p class="centered"><img src="confdeps.png"
+  alt="Dependency graph in PNG graphics format.  (Get a better browser!)"></p>
+
+<p>Regenerate using a command sequence like
+   <code>"aclocal-1.7 &amp;&amp; autoconf2.50 &amp;&amp; autoheader2.50
+   &amp;&amp; automake-1.7"</code> as needed.  And/or configure with
+   --enable-maintainer-mode.
+</p>
+
+
+<hr />
+<h3><a name="breakout">storing information in non-AC files, like
+                       configure.host</a></h3>
+<p>Until that glorious day when we can use AC_TRY_LINK with a cross-compiler,
+   we have to hardcode the results of what the tests would have shown if
+   they could be run.  So we have an inflexible mess like crossconfig.m4.
+</p>
+
+<p>Wouldn't it be nice if we could store that information in files like
+   configure.host, which can be modified without needing to regenerate
+   anything, and can even be tweaked without really knowing how the configury
+   all works?  Perhaps break the pieces of crossconfig.m4 out and place them in
+   their appropriate config/{cpu,os} directory.
+</p>
+
+<p>Alas, writing macros like "<code>AC_DEFINE(HAVE_A_NICE_DAY)</code>" can
+   only be done inside files which are passed through autoconf.  Files which
+   are pure shell script can be source'd at configure time.  Files which
+   contain autoconf macros must be processed with autoconf.  We could still
+   try breaking the pieces out into "config/*/cross.m4" bits, for instance,
+   but then we would need arguments to aclocal/autoconf to properly find
+   them all when generating configure.  I would discourage that.
+</p>
+
+
+<hr />
+<h3><a name="general">general config notes</a></h3>
+<p>Lots of stuff got thrown out because the new autotools kindly generate
+   the same (or better) shell code for us.
+</p>
+
+<p>Most comments should use {octothorpes, shibboleths, hash marks, pound
+   signs, whatevers} rather than "dnl".  Nearly all comments in configure.ac
+   should.  Comments inside macros written in ancilliary .m4 files should.
+   About the only comments which should <em>not</em> use #, but use dnl
+   instead, are comments <em>outside</em> our own macros in the ancilliary
+   files.  The difference is that # comments show up in <code>configure</code>
+   (which is most helpful for debugging), while dnl'd lines just vanish.
+   Since the macros in ancilliary files generate code which appears in odd
+   places, their "outside" comments tend to not be useful while reading
+   <code>configure</code>.
+</p>
+
+<p>Do not use any <code>$target*</code> variables, such as
+   <code>$target_alias</code>.  The single exception is in configure.ac,
+   for automake+dejagnu's sake.
+</p>
+
+<p>
+</p>
+
+<hr />
+<h3><a name="aclayout">acinclude.m4 layout</a></h3>
+<p>The nice thing about acinclude.m4/aclocal.m4 is that macros aren't actually
+   performed/called/expanded/whatever here, just loaded.  So we can arrange
+   the contents however we like.  As of this writing, acinclude.m4 is arranged
+   as follows:
+</p>
+<pre>
+    GLIBCXX_CHECK_HOST
+    GLIBCXX_TOPREL_CONFIGURE
+    GLIBCXX_CONFIGURE
+</pre>
+<p>All the major variable "discovery" is done here.  CXX, multilibs, etc.
+</p>
+<pre>
+    fragments included from elsewhere
+</pre>
+<p>Right now, "fragments" == "the math/linkage bits".
+</p>
+<pre>
+    GLIBCXX_CHECK_COMPILER_FEATURES
+    GLIBCXX_CHECK_LINKER_FEATURES
+    GLIBCXX_CHECK_WCHAR_T_SUPPORT
+</pre>
+<p>Next come extra compiler/linker feature tests.  Wide character support
+   was placed here because I couldn't think of another place for it.  It will
+   probably get broken apart like the math tests, because we're still disabling
+   wchars on systems which could actually support them.
+</p>
+<pre>
+    GLIBCXX_CHECK_SETRLIMIT_ancilliary
+    GLIBCXX_CHECK_SETRLIMIT
+    GLIBCXX_CHECK_S_ISREG_OR_S_IFREG
+    GLIBCXX_CHECK_POLL
+    GLIBCXX_CHECK_WRITEV
+
+    GLIBCXX_CONFIGURE_TESTSUITE
+</pre>
+<p>Feature tests which only get used in one place.  Here, things used only in
+   the testsuite, plus a couple bits used in the guts of I/O.
+</p>
+<pre>
+    GLIBCXX_EXPORT_INCLUDES
+    GLIBCXX_EXPORT_FLAGS
+    GLIBCXX_EXPORT_INSTALL_INFO
+</pre>
+<p>Installation variables, multilibs, working with the rest of the compiler.
+   Many of the critical variables used in the makefiles are set here.
+</p>
+<pre>
+    GLIBGCC_ENABLE
+    GLIBCXX_ENABLE_C99
+    GLIBCXX_ENABLE_CHEADERS
+    GLIBCXX_ENABLE_CLOCALE
+    GLIBCXX_ENABLE_CONCEPT_CHECKS
+    GLIBCXX_ENABLE_CSTDIO
+    GLIBCXX_ENABLE_CXX_FLAGS
+    GLIBCXX_ENABLE_C_MBCHAR
+    GLIBCXX_ENABLE_DEBUG
+    GLIBCXX_ENABLE_DEBUG_FLAGS
+    GLIBCXX_ENABLE_LIBUNWIND_EXCEPTIONS
+    GLIBCXX_ENABLE_LONG_LONG
+    GLIBCXX_ENABLE_PCH
+    GLIBCXX_ENABLE_SJLJ_EXCEPTIONS
+    GLIBCXX_ENABLE_SYMVERS
+    GLIBCXX_ENABLE_THREADS
+</pre>
+<p>All the features which can be controlled with enable/disable configure
+   options.  Note how they're alphabetized now?  Keep them like that.  :-)
+</p>
+<pre>
+    AC_LC_MESSAGES
+    libtool bits
+</pre>
+<p>Things which we don't seem to use directly, but just has to be present
+   otherwise stuff magically goes wonky.
+</p>
+
+
+<hr />
+<h3><a name="enable"><code>--enable</code> howto</a></h3>
+<p>All the GLIBCXX_ENABLE_FOO macros use a common helper, GLIBCXX_ENABLE.
+   (You don't have to use it, but it's easy.)  The helper does two things
+   for us:
+</p>
+
+<ol>
+ <li>Builds the call to the AC_ARG_ENABLE macro, with --help text properly
+     quoted and aligned.  (Death to changequote!)</li>
+ <li>Checks the result against a list of allowed possibilities, and signals
+     a fatal error if there's no match.  This means that the rest of the
+     GLIBCXX_ENABLE_FOO macro doesn't need to test for strange arguments,
+     nor do we need to protect against empty/whitespace strings with the
+     <code>"x$foo" = "xbar"</code> idiom.</li>
+</ol>
+
+<p>Doing these things correctly takes some extra autoconf/autom4te code,
+   which made our macros nearly illegible.  So all the ugliness is factored
+   out into this one helper macro.
+</p>
+
+<p>Many of the macros take an argument, passed from when they are expanded
+   in configure.ac.  The argument controls the default value of the
+   enable/disable switch.  Previously, the arguments themselves had defaults.
+   Now they don't, because that's extra complexity with zero gain for us.
+</p>
+
+<p>There are three "overloaded signatures".  When reading the descriptions
+   below, keep in mind that the brackets are autoconf's quotation characters,
+   and that they will be stripped.  Examples of just about everything occur
+   in acinclude.m4, if you want to look.
+</p>
+
+<pre>
+    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING)
+    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)
+    GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)
+</pre>
+
+<ul>
+ <li><p>FEATURE is the string that follows --enable.  The results of the test
+     (such as it is) will be in the variable $enable_FEATURE, where FEATURE
+     has been squashed.  Example:  <code>[extra-foo]</code>, controlled by the
+     --enable-extra-foo option and stored in $enable_extra_foo.</p></li>
+ <li><p>DEFAULT is the value to store in $enable_FEATURE if the user does not
+     pass --enable/--disable.  It should be one of the permitted values
+     passed later.  Examples:  <code>[yes]</code>, or <code>[bar]</code>, or
+     <code>[$1]</code> (which passes the argument given to the
+     GLIBCXX_ENABLE_FOO macro as the default).</p>
+     <p>For cases where we need to probe for particular models
+     of things, it is useful to have an undocumented "auto" value here (see
+     GLIBCXX_ENABLE_CLOCALE for an example).</p></li>
+ <li><p>HELP-ARG is any text to append to the option string itself in the
+     --help output.  Examples: <code>[]</code> (i.e., an empty string,
+     which appends nothing),
+     <code>[=BAR]</code>, which produces
+     <code>--enable-extra-foo=BAR</code>, and
+     <code>[@&lt;:@=BAR@:&gt;@]</code>, which produces
+     <code>--enable-extra-foo[=BAR]</code>.  See the difference?  See what
+     it implies to the user?</p>
+     <p>If you're wondering what that line noise in the last example was,
+     that's how you embed autoconf special characters in output text.
+     They're called
+<a href="http://www.gnu.org/manual/autoconf/html_node/autoconf_95.html#SEC95"><em>quadrigraphs</em></a>
+     and you should use them whenever necessary.</p></li>
+ <li><p>HELP-STRING is what you think it is.  Do not include the "default"
+     text like we used to do; it will be done for you by GLIBCXX_ENABLE.
+     By convention, these are not full English sentences.
+     Example:  [turn on extra foo]</p></li>
+</ul>
+
+<p>With no other arguments, only the standard autoconf patterns are
+   allowed:  "<code>--{enable,disable}-foo[={yes,no}]</code>"  The
+   $enable_FEATURE variable is guaranteed to equal either "yes" or "no"
+   after the macro.  If the user tries to pass something else, an
+   explanatory error message will be given, and configure will halt.
+</p>
+
+<p>The second signature takes a fifth argument,
+   "<code>[permit <em>a</em>|<em>b</em>|<em>c</em>|<em>...</em>]</code>"
+   This allows <em>a</em> or <em>b</em> or ... after the equals sign in the
+   option, and $enable_FEATURE is guaranteed to equal one of them after the
+   macro.  Note that if you want to allow plain --enable/--disable with no
+   "=whatever", you must include "yes" and "no" in the list of permitted
+   values.  Also note that whatever you passed as DEFAULT must be in the list.
+   If the user tries to pass something not on the list, a semi-explanatory
+   error message will be given, and configure will halt.
+   Example:  <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code>
+</p>
+
+<p>The third signature takes a fifth argument.  It is arbitrary shell code
+   to execute if the user actually passes the enable/disable option.  (If
+   the user does not, the default is used.  Duh.)  No argument checking at
+   all is done in this signature.  See GLIBCXX_ENABLE_CXX_FLAGS for an
+   example of handling, and an error message.
+</p>
+
+<hr />
+</body>
+</html>

libstdc++-v3/docs/html/Makefile

@@ -5,6 +5,7 @@ INC=../../../gcc/doc/include
 
 all: documentation.html                  \
      faq/index.txt                       \
+     17_intro/confdeps.png               \
      17_intro/porting.html               \
      17_intro/porting-howto.html
 
@@ -34,4 +35,7 @@ faq/index.txt: faq/index.html
 17_intro/porting-howto.html: 17_intro/porting-howto.xml
 	xltproc -o $@ /usr/share/xml/docbook/xsl-stylesheets-1.48-2/html/docbook.xsl $<
 
+17_intro/confdeps.png: 17_intro/confdeps.dot
+	dot -Tpng -o $@ $<
+
 # vim:noet ts=4

libstdc++-v3/docs/html/install.html

@@ -57,10 +57,10 @@
 
    <p>In addition, if you plan to modify the makefiles or regenerate the
       configure scripts you'll need recent versions of the GNU Autotools:
-      autoconf (version 2.50 or later),
+      autoconf (version 2.57 or later) and
-      automake (version 1.4 or later),    <!-- special version? -->
+      automake (version 1.7.6 or later),
-      and libtool (multilanguage, version 1.4 or later),  <!-- really? -->
+      in order to rebuild the files.  Libtool is built from special sources
-      in order to rebuild the files.
+      in the GCC source tree.
       These tools are all required to be installed in the same location
       (most linux distributions install these tools by default, so no
       worries as long as the versions are correct).

libstdc++-v3/docs/html/test.html

@@ -35,6 +35,7 @@
    <li><a href="#new">How to write a new test case</a></li>
    <li><a href="#check">Options for running the tests</a></li>
    <li><a href="#future">Future</a></li>
+   <li><a href="#internals">DejaGNU internals</a></li>
 </ul>
 
 <hr />
@@ -79,13 +80,13 @@ thread		  Tests for threads.
    
    <p>
       Some directories don't have test files, but instead contain
-      auxiliary information:
+      auxiliary information (<a href="#internals">more information</a>):
    </p>
 
    <pre>
 config		  Files for the dejagnu test harness.
 lib		  Files for the dejagnu test harness.
-libstdc++-v3.dg	  Files for the dejagnu test harness.
+libstdc++*     	  Files for the dejagnu test harness.
 data		  Sample text files for testing input and output.
    </pre>
 
@@ -218,7 +219,7 @@ cat 27_io/objects/char/3_xin.in | a.out
         Used to check correctness of symbol versioning, visibility of
         exported symbols, and compatibility on symbols in the shared
         library, for hosts that support this feature. More information
-	can be found in the ABI documentation <a href="abi.txt"> here</a>
+        can be found in the ABI documentation <a href="abi.txt"> here</a>
        </p>
      </li>
      <li>
@@ -260,7 +261,7 @@ cat 27_io/objects/char/3_xin.in | a.out
          <li>time_counter</li>
          <li>resource_counter</li>
          <li>report_performance</li>
-      </ul>	
+      </ul>
        <p></p> 
      </li>
      <li>
@@ -585,6 +586,45 @@ Currently plans for supported keywords include:
 </dd>
 </dl>
 
+<hr />
+<h2><a name="internals">DejaGNU internals</a></h2>
+
+<p>This is information for those looking at making changes to the testsuite
+structure, and/or needing to trace dejagnu's actions with --verbose.  This
+will not be useful to people who are "merely" adding new tests to the existing
+structure.
+</p>
+
+<p>The first key point when working with dejagnu is the idea of a "tool".
+Files, directories, and functions are all implicitly used when they are
+named after the tool in use.  Here, the tool will always be "libstdc++".
+</p>
+
+<p>The <code>lib</code> subdir contains support routines.  The
+<code>lib/libstdc++.exp</code> file ("support library") is loaded
+automagically, and must explicitly load the others.  For example, files can
+be copied from the core compiler's support directory into <code>lib</code>.
+</p>
+
+<p>Some routines in <code>lib/libstdc++.exp</code> are callbacks, some are
+our own.  Callbacks must be prefixed with the name of the tool.  To easily
+distinguish the others, by convention our own routines are named "v3-*".
+</p>
+
+<p>The next key point when working with dejagnu is "test files".  Any
+directory whose name starts with the tool name will be searched for test files.
+(We have only one.)  In those directories, any <code>.exp</code> file is
+considered a test file, and will be run in turn.  Our main test file is called
+<code>normal.exp</code>; it runs all the tests in testsuite_files using the
+callbacks loaded from the support library.
+</p>
+
+<p>The <code>config</code> directory is searched for any particular "target
+board" information unique to this library.  This is currently unused and sets
+only default variables.
+</p>
+
+
 <!-- ####################################################### -->
 
 <hr />