From 018c5f50c35cda3126699423c95c48a7b01dcec6 Mon Sep 17 00:00:00 2001 From: pme Date: Tue, 5 Aug 2003 01:20:15 +0000 Subject: 2003-08-04 Phil Edwards * 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. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@70164 138bc75d-0d04-0410-961f-82ee72b054a4 --- libstdc++-v3/docs/doxygen/guide.html | 2 +- libstdc++-v3/docs/doxygen/mainpage.html | 13 ++ libstdc++-v3/docs/doxygen/run_doxygen | 18 +- libstdc++-v3/docs/doxygen/user.cfg.in | 2 +- libstdc++-v3/docs/html/17_intro/confdeps.dot | 14 ++ libstdc++-v3/docs/html/17_intro/confdeps.png | Bin 0 -> 3486 bytes libstdc++-v3/docs/html/17_intro/configury.html | 285 +++++++++++++++++++++++++ libstdc++-v3/docs/html/Makefile | 4 + libstdc++-v3/docs/html/install.html | 8 +- libstdc++-v3/docs/html/test.html | 48 ++++- 10 files changed, 378 insertions(+), 16 deletions(-) create mode 100644 libstdc++-v3/docs/html/17_intro/confdeps.dot create mode 100644 libstdc++-v3/docs/html/17_intro/confdeps.png create mode 100644 libstdc++-v3/docs/html/17_intro/configury.html (limited to 'libstdc++-v3/docs') diff --git a/libstdc++-v3/docs/doxygen/guide.html b/libstdc++-v3/docs/doxygen/guide.html index 0628521f427..814dc1debea 100644 --- a/libstdc++-v3/docs/doxygen/guide.html +++ b/libstdc++-v3/docs/doxygen/guide.html @@ -28,7 +28,7 @@ 'make doxygen-maint', and 'make doxygen-man' 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, Doxygen diff --git a/libstdc++-v3/docs/doxygen/mainpage.html b/libstdc++-v3/docs/doxygen/mainpage.html index fdd40edcbe3..2ff090230c8 100644 --- a/libstdc++-v3/docs/doxygen/mainpage.html +++ b/libstdc++-v3/docs/doxygen/mainpage.html @@ -58,6 +58,19 @@

+

If you are using Doxygen for your own projects, you can use + a tag file for the appropriate version and + an entry such as +

+ TAGFILES = "libstdc++.tag = + http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen" +
+ 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. +

+

Generating the documentation

These HTML pages are automatically generated, along with the man pages. See docs/doxygen/guide.html in the source tree for how to diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen index 76b51110dff..28868807b7e 100644 --- a/libstdc++-v3/docs/doxygen/run_doxygen +++ b/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 - $doxygen ${outdir}/${mode}.cfg + echo 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 diff --git a/libstdc++-v3/docs/doxygen/user.cfg.in b/libstdc++-v3/docs/doxygen/user.cfg.in index 9911490e84c..87653ebe512 100644 --- a/libstdc++-v3/docs/doxygen/user.cfg.in +++ b/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 diff --git a/libstdc++-v3/docs/html/17_intro/confdeps.dot b/libstdc++-v3/docs/html/17_intro/confdeps.dot new file mode 100644 index 00000000000..a62d28ce9dd --- /dev/null +++ b/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"; +} diff --git a/libstdc++-v3/docs/html/17_intro/confdeps.png b/libstdc++-v3/docs/html/17_intro/confdeps.png new file mode 100644 index 00000000000..5075aa869b1 Binary files /dev/null and b/libstdc++-v3/docs/html/17_intro/confdeps.png differ diff --git a/libstdc++-v3/docs/html/17_intro/configury.html b/libstdc++-v3/docs/html/17_intro/configury.html new file mode 100644 index 00000000000..8b44ff381dc --- /dev/null +++ b/libstdc++-v3/docs/html/17_intro/configury.html @@ -0,0 +1,285 @@ + + + + + + + + + + libstdc++-v3 configury + + + + +

> open configury door

+

> look

+ +

You are in a maze of twisty passages, all +different.

+

It is dark. You are likely to be eaten by a +Canadian cross build.

+ + +
+

Notes on libstdc++-v3 configury

+
+No problem is insoluble in all conceivable circumstances.
+-- The Cosmic AC, +The +Last Question, by Isaac Asimov +
+ + +
+

what comes from where

+

Dependency graph in PNG graphics format. (Get a better browser!)

+ +

Regenerate using a command sequence like + "aclocal-1.7 && autoconf2.50 && autoheader2.50 + && automake-1.7" as needed. And/or configure with + --enable-maintainer-mode. +

+ + +
+

storing information in non-AC files, like + configure.host

+

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. +

+ +

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. +

+ +

Alas, writing macros like "AC_DEFINE(HAVE_A_NICE_DAY)" 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. +

+ + +
+

general config notes

+

Lots of stuff got thrown out because the new autotools kindly generate + the same (or better) shell code for us. +

+ +

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 not use #, but use dnl + instead, are comments outside our own macros in the ancilliary + files. The difference is that # comments show up in configure + (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 + configure. +

+ +

Do not use any $target* variables, such as + $target_alias. The single exception is in configure.ac, + for automake+dejagnu's sake. +

+ +

+

+ +
+

acinclude.m4 layout

+

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: +

+
+    GLIBCXX_CHECK_HOST
+    GLIBCXX_TOPREL_CONFIGURE
+    GLIBCXX_CONFIGURE
+
+

All the major variable "discovery" is done here. CXX, multilibs, etc. +

+
+    fragments included from elsewhere
+
+

Right now, "fragments" == "the math/linkage bits". +

+
+    GLIBCXX_CHECK_COMPILER_FEATURES
+    GLIBCXX_CHECK_LINKER_FEATURES
+    GLIBCXX_CHECK_WCHAR_T_SUPPORT
+
+

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. +

+
+    GLIBCXX_CHECK_SETRLIMIT_ancilliary
+    GLIBCXX_CHECK_SETRLIMIT
+    GLIBCXX_CHECK_S_ISREG_OR_S_IFREG
+    GLIBCXX_CHECK_POLL
+    GLIBCXX_CHECK_WRITEV
+
+    GLIBCXX_CONFIGURE_TESTSUITE
+
+

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. +

+
+    GLIBCXX_EXPORT_INCLUDES
+    GLIBCXX_EXPORT_FLAGS
+    GLIBCXX_EXPORT_INSTALL_INFO
+
+

Installation variables, multilibs, working with the rest of the compiler. + Many of the critical variables used in the makefiles are set here. +

+
+    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
+
+

All the features which can be controlled with enable/disable configure + options. Note how they're alphabetized now? Keep them like that. :-) +

+
+    AC_LC_MESSAGES
+    libtool bits
+
+

Things which we don't seem to use directly, but just has to be present + otherwise stuff magically goes wonky. +

+ + +
+

--enable howto

+

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: +

+ +
    +
  1. Builds the call to the AC_ARG_ENABLE macro, with --help text properly + quoted and aligned. (Death to changequote!)
    2. +
  2. 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 + "x$foo" = "xbar" idiom.
    3. +
+ +

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. +

+ +

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. +

+ +

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. +

+ +
+    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)
+
+ + + +

With no other arguments, only the standard autoconf patterns are + allowed: "--{enable,disable}-foo[={yes,no}]" 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. +

+ +

The second signature takes a fifth argument, + "[permit a|b|c|...]" + This allows a or b 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: [permit generic|gnu|ieee_1003.1-2001|yes|no|auto] +

+ +

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. +

+ +
+ + diff --git a/libstdc++-v3/docs/html/Makefile b/libstdc++-v3/docs/html/Makefile index c252ca2631b..a0b335aaa2d 100644 --- a/libstdc++-v3/docs/html/Makefile +++ b/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 diff --git a/libstdc++-v3/docs/html/install.html b/libstdc++-v3/docs/html/install.html index 038291b8acc..6c983710b86 100644 --- a/libstdc++-v3/docs/html/install.html +++ b/libstdc++-v3/docs/html/install.html @@ -57,10 +57,10 @@

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), - automake (version 1.4 or later), - and libtool (multilanguage, version 1.4 or later), - in order to rebuild the files. + autoconf (version 2.57 or later) and + automake (version 1.7.6 or later), + in order to rebuild the files. Libtool is built from special sources + 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). diff --git a/libstdc++-v3/docs/html/test.html b/libstdc++-v3/docs/html/test.html index a4140beeb87..8c570f3fa3b 100644 --- a/libstdc++-v3/docs/html/test.html +++ b/libstdc++-v3/docs/html/test.html @@ -35,6 +35,7 @@

  • How to write a new test case
  • Options for running the tests
  • Future
    • +
  • DejaGNU internals
    • @@ -79,13 +80,13 @@ thread Tests for threads.

    Some directories don't have test files, but instead contain - auxiliary information: + auxiliary information (more information): 

     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.
    @@ -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 here + can be found in the ABI documentation here

  • @@ -260,7 +261,7 @@ cat 27_io/objects/char/3_xin.in | a.out
  • time_counter
  • resource_counter
  • report_performance
    • - +

  • @@ -585,6 +586,45 @@ Currently plans for supported keywords include: +
    +

    DejaGNU internals

    + +

    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. +

    + +

    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++". +

    + +

    The lib subdir contains support routines. The +lib/libstdc++.exp 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 lib. +

    + +

    Some routines in lib/libstdc++.exp 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-*". +

    + +

    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 .exp file is +considered a test file, and will be run in turn. Our main test file is called +normal.exp; it runs all the tests in testsuite_files using the +callbacks loaded from the support library. +

    + +

    The config directory is searched for any particular "target +board" information unique to this library. This is currently unused and sets +only default variables. +

    + +
    -- cgit v1.2.1