xref: /netbsd-src/external/gpl3/gcc/dist/libstdc++-v3/scripts/run_doxygen (revision 0a3071956a3a9fdebdbf7f338cf2d439b45fc728)
1#!/bin/bash
2
3# Runs doxygen and massages the output files.
4# Copyright (C) 2001-2022 Free Software Foundation, Inc.
5#
6# Synopsis:  run_doxygen --mode=[html|latex|man|xml] --host_alias=<alias> \
7#                        v3srcdir \
8#                        v3builddir \
9#                        shortname
10#
11# Originally hacked together by Phil Edwards <pme@gcc.gnu.org>
12
13
14# We can check now that the version of doxygen is >= this variable.
15DOXYVER=1.7.0
16
17find_doxygen() {
18    local -r v_required=`echo $DOXYVER |  \
19		awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
20    local testing_version doxygen maybedoxy v_found
21    # thank you goat book
22    set `IFS=:; X="$PATH:/usr/local/bin:/bin:/usr/bin"; echo $X`
23    for dir
24    do
25      # AC_EXEEXT could come in useful here
26      maybedoxy="$dir/doxygen"
27      test -f "$maybedoxy" && testing_version=`$maybedoxy --version`
28      if test -n "$testing_version"; then
29       v_found=`echo $testing_version |  \
30		awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
31       if test $v_found -ge $v_required; then
32	 doxygen="$maybedoxy"
33	 break
34       fi
35      fi
36    done
37    if test -z "$doxygen"; then
38	fail "Could not find Doxygen $DOXYVER in path."
39    fi
40    # We need to use other tools from the same package/version.
41    echo :: Using Doxygen tools from ${dir}.
42    PATH=$dir:$PATH
43    hash -r
44}
45
46print_usage() {
47    cat <<EOF
48Usage:  run_doxygen --mode=MODE --host_alias=HOST_ALIAS [<options>]
49		    <v3-src-dir> <v3-build-dir> <shortnamesp>
50      MODE is one of:
51	  html           Generate user-level HTML library documentation.
52	  man            Generate user-level man pages.
53	  xml            Generate user-level XML pages.
54	  latex          Generate user-level LaTeX pages.
55
56      HOST_ALIAS is the GCC host alias triplet set at configure time.
57
58      shortnamesp is one of YES or NO and is used as the SHORT_NAMES value
59      in the Doxygen config file.
60
61      Supported options:
62
63      --help | -h      Print this message and exit.
64      --latex_cmd=CMD  Set LATEX_CMD_NAME=CMD in the Doxygen config file.
65
66Note:  Requires Doxygen ${DOXYVER} or later; get it at
67       ftp://ftp.stack.nl/pub/users/dimitri/doxygen-${DOXYVER}.src.tar.gz
68
69EOF
70}
71
72# Print an error message followed by usage to stderr, then exit.
73fail() {
74  echo "$0: error: $*" 1>&2
75  echo 1>&2
76  print_usage 1>&2
77  exit 1
78}
79
80parse_options() {
81  while [ $# -ne 0 ]
82  do
83    # Blatantly ripped from autoconf, er, I mean, "gratefully standing
84    # on the shoulders of those giants who have gone before us."
85    case "$1" in
86      -*=*) arg=`echo "$1" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
87      *) arg= ;;
88    esac
89
90    case "$1" in
91      --mode=*)
92	mode=$arg ;;
93      --host_alias=*)
94	host_alias=$arg ;;
95      --help | -h)
96	print_usage ; exit ;;
97      --mode | --host_alias)
98	fail "missing argument: $1" ;;
99      --latex_cmd=*)
100	latex_cmd=$arg ;;
101      --*)
102	fail "invalid option: $1" ;;
103      *)
104	break ;;
105    esac
106    shift
107  done
108
109  if [ $# -ne 3 ]
110  then
111    fail "wrong number of arguments"
112  fi
113  srcdir="$1"
114  builddir="$2"
115  outdir="$2/doc/doxygen"
116  shortname="$3"
117}
118
119
120# script begins here
121mode=unset
122host_alias=unset
123srcdir=unset
124outdir=unset
125shortname=unset
126do_html=false
127do_man=false
128do_xml=false
129do_latex=false
130latex_cmd=
131enabled_sections=
132generate_tagfile=
133DATEtext=`date '+%Y-%m-%d'`
134
135# Show how this script is called.
136echo run_doxygen $*
137
138parse_options $*
139find_doxygen
140
141if test $srcdir = unset || test $outdir = unset || test $mode = unset || test $shortname = unset || test $host_alias = unset; then
142    # this could be better
143    fail "You have not given enough information...!  $srcdir - "
144fi
145
146case x"$mode" in
147    xhtml)
148      do_html=true
149      enabled_sections=maint
150      generate_tagfile="$outdir/html/libstdc++.tag"
151      ;;
152    xlatex)
153      do_latex=true
154      enabled_sections=maint
155      ;;
156    xman)
157      do_man=true
158      ;;
159    xxml)
160      do_xml=true
161      enabled_sections=maint
162      ;;
163    *)
164      echo run_doxygen error:  $mode is an invalid mode 1>&2
165      exit 1 ;;
166esac
167
168case x"$shortname" in
169    xYES)
170      ;;
171    xNO)
172      ;;
173    *)
174      echo run_doxygen error:  $shortname is invalid 1>&2
175      exit 1 ;;
176esac
177
178
179mkdir -p $outdir
180chmod u+w $outdir
181
182# Run it
183(
184    set -e
185    cd $builddir
186    sed -e "s=@outdir@=${outdir}=g" \
187	-e "s=@srcdir@=${srcdir}=g" \
188	-e "s=@shortname@=${shortname}=g" \
189	-e "s=@builddir@=${builddir}=g" \
190	-e "s=@host_alias@=${host_alias}=g" \
191	-e "s=@enabled_sections@=${enabled_sections}=" \
192	-e "s=@do_html@=${do_html}=" \
193	-e "s=@do_latex@=${do_latex}=" \
194	-e "s=@latex_cmd@=${latex_cmd}=" \
195	-e "s=@do_man@=${do_man}=" \
196	-e "s=@do_xml@=${do_xml}=" \
197	-e "s=@generate_tagfile@=${generate_tagfile}=" \
198	${srcdir}/doc/doxygen/user.cfg.in > ${outdir}/${mode}.cfg
199    echo :: NOTE that this may take some time...
200    echo doxygen ${outdir}/${mode}.cfg
201    doxygen ${outdir}/${mode}.cfg
202)
203ret=$?
204test $ret -ne 0 && exit $ret
205
206if $do_xml; then
207    echo ::
208    echo :: XML pages begin with
209    echo :: ${outdir}/xml/index.xml
210fi
211
212if $do_latex; then
213    cd ${outdir}/${mode}
214
215    # Grrr, Doxygen 1.8.x changed the -w latex options.
216    need_footer=`doxygen -h | sed -n -e '/-w latex/s=.*footer.*=true=p'`
217
218    # Also drop in the header file (maybe footer file) and style sheet
219    if $need_footer; then
220      doxygen -w latex header.tex footer.tex doxygen.sty
221    else
222      doxygen -w latex header.tex doxygen.sty
223    fi
224
225    echo ::
226    echo :: LaTeX pages begin with
227    echo :: ${outdir}/latex/refman.tex
228fi
229
230if $do_html; then
231  cd ${outdir}/${mode}
232
233  #doxytag -t libstdc++.tag . > /dev/null 2>&1
234
235  # Strip pathnames from tag file.
236  sed -e '/<path>/d' libstdc++.tag > TEMP
237  mv TEMP libstdc++.tag
238
239  sed -e "s=@DATE@=${DATEtext}=" \
240      ${srcdir}/doc/doxygen/mainpage.html > index.html
241
242  # The following bit of line noise changes annoying
243  #   std::foo < typename _Ugly1, typename _Ugly2, .... _DefaultUgly17 >
244  # to user-friendly
245  #   std::foo
246  # in the major "Compound List" page.
247  sed -e 's=\(::[[:alnum:]_]*\)&lt; .* &gt;=\1=' annotated.html > annstrip.html
248  mv annstrip.html annotated.html
249
250  cp ${srcdir}/doc/doxygen/tables.html tables.html
251
252  echo ::
253  echo :: HTML pages begin with
254  echo :: ${outdir}/html/index.html
255fi
256
257# Mess with the man pages.  We don't need documentation of the internal
258# headers, since the man pages for those contain nothing useful anyhow.  The
259# man pages for doxygen modules need to be renamed (or deleted).  And the
260# generated #include lines need to be changed from the internal names to the
261# standard ones (e.g., "#include <stl_tempbuf.h>" -> "#include <memory>").
262if $do_man; then
263echo ::
264echo :: Fixing up the man pages...
265cd $outdir/man/man3
266
267# File names with embedded spaces (EVIL!) need to be....?  renamed or removed?
268find . -name "* *" -print0 | xargs -0r rm        # requires GNU tools
269
270# man pages are for functions/types/other entities, not source files
271# directly.  who the heck would type "man foo.h" anyhow?
272# FIXME: This also removes std.3 which is the only place that a lot of
273# functions are documented. Should we keep it?
274find . -name "[a-z]*" -a ! -name "std_*" -print | xargs rm
275rm -f *.h.3 *.hpp.3 *config* *.cc.3 *.tcc.3 *_t.3
276#rm ext_*.3 tr1_*.3 debug_*.3
277
278# this is used to examine what we would have deleted, for debugging
279#mkdir trash
280#find . -name "[a-z]*" -a ! -name "std_*" -print | xargs -i mv {} trash
281#mv *.h.3 *config* *.cc.3 *.tcc.3 *_t.3  trash
282
283gxx=$($builddir/scripts/testsuite_flags --build-cxx)
284cppflags=$($builddir/scripts/testsuite_flags --build-includes)
285cxxflags="-Og -g -std=gnu++23"
286
287# Standardize the displayed header names.  If anyone who knows perl cares
288# enough to rewrite all this, feel free.  This only gets run once a century,
289# and I'm off getting coffee then anyhow, so I didn't care enough to make
290# this super-fast.
291$gxx $cppflags $cxxflags ${srcdir}/doc/doxygen/stdheader.cc -o ./stdheader || exit 1
292# Doxygen outputs something like "\fC#include <unique_lock\&.h>\fP" and
293# we want that internal header to be replaced with something like <mutex>.
294problematic=`grep -E -l '#include <.*h>' [a-z]*.3`
295for f in $problematic; do
296    # this is also slow, but safe and easy to debug
297    oldh=`sed -n '/fC#include </s/.*<\(.*\)>.*/\1/p' $f`
298    newh=`echo $oldh | sed 's/\\\\&\\././g' | ./stdheader`
299    sed "s=${oldh/\\/.}=${newh}=" $f > TEMP && mv TEMP $f
300done
301rm stdheader
302
303# Some of the pages for generated modules have text that confuses certain
304# implementations of man(1), e.g. on GNU/Linux.  We need to have another
305# top-level *roff tag to /stop/ the .SH NAME entry.
306problematic=`grep -E --files-without-match '^\.SH SYNOPSIS' [A-Z]*.3`
307#problematic='Containers.3 Sequences.3 Assoc_containers.3 Iterator_types.3'
308
309for f in $problematic; do
310    sed '/^\.SH NAME/{
311n
312a\
313\
314.SH SYNOPSIS
315    }' $f > TEMP
316    mv TEMP $f
317done
318
319# Also, break this (generated) line up.  It's ugly as sin.
320problematic=`grep -l '[^^]Definition at line' *.3`
321for f in $problematic; do
322    sed 's/Definition at line/\
323.PP\
324&/'  $f > TEMP
325    mv TEMP $f
326done
327
328cp ${srcdir}/doc/doxygen/Intro.3 C++Intro.3
329
330# Why didn't I do this at the start?  Were rabid weasels eating my brain?
331# Who the fsck would "man std_vector" when the class isn't named that?
332
333# If no files match a glob, skip the for-loop:
334shopt -s nullglob
335# First, deal with nested namespaces.
336for ns in chrono filesystem ranges views literals; do
337  for f in std_${ns}_*; do
338      newname=`echo $f | sed "s/std_${ns}_/std::${ns}::/"`
339      mv $f $newname
340  done
341done
342for f in *__debug_*; do
343    newname=`echo $f | sed 's/__debug_/__debug::/'`
344    mv $f $newname
345done
346for f in *decimal_*; do
347    newname=`echo $f | sed 's/decimal_/decimal::/'`
348    mv $f $newname
349done
350for f in *__detail_*; do
351    newname=`echo $f | sed 's/__detail_/__detail::/'`
352    mv $f $newname
353done
354for f in *__gnu_pbds_detail_*; do
355    newname=`echo $f | sed 's/detail_/detail::/'`
356    mv $f $newname
357done
358for f in *__parallel_*; do
359    newname=`echo $f | sed 's/__parallel_/__parallel::/'`
360    mv $f $newname
361done
362
363# Remove inline namespaces used for versioning.
364for f in *_V2_*; do
365    newname=`echo $f | sed 's/_V2_/::/'`
366    sed 's/::_V2::/::/g' $f > $newname
367    rm $f
368done
369for f in *_experimental_filesystem_v?_*; do
370    newname=`echo $f | sed 's/_filesystem_v._/::filesystem::/'`
371    sed 's/::filesystem::v.::/::filesystem::/g' $f > $newname
372    rm $f
373done
374for f in *experimental_fundamentals_v?_*; do
375    newname=`echo $f | sed 's/experimental_.*_v[[:digit:]]_/experimental::/'`
376    sed 's/::experimental::fundamentals_v[[:digit:]]::/::experimental::/g' $f > $newname
377    rm $f
378done
379
380# Then, clean up other top-level namespaces.
381for f in std_tr1_*; do
382    newname=`echo $f | sed 's/^std_tr1_/std::tr1::/'`
383    mv $f $newname
384done
385for f in std_tr2_*; do
386    newname=`echo $f | sed 's/^std_tr2_/std::tr2::/'`
387    mv $f $newname
388done
389for f in std_*; do
390    newname=`echo $f | sed 's/^std_/std::/'`
391    mv $f $newname
392done
393for f in __gnu_cxx_*; do
394    newname=`echo $f | sed 's/^__gnu_cxx_/__gnu_cxx::/'`
395    mv $f $newname
396done
397for f in __gnu_debug_*; do
398    newname=`echo $f | sed 's/^__gnu_debug_/__gnu_debug::/'`
399    mv $f $newname
400done
401for f in __gnu_parallel_*; do
402    newname=`echo $f | sed 's/^__gnu_parallel_/__gnu_parallel::/'`
403    mv $f $newname
404done
405for f in __gnu_pbds_*; do
406    newname=`echo $f | sed 's/^__gnu_pbds_/__gnu_pbds::/'`
407    mv $f $newname
408done
409for f in __cxxabiv1_*; do
410    newname=`echo $f | sed 's/^__cxxabiv1_/abi::/'`
411    mv $f $newname
412done
413
414# Then piecemeal nested classes
415
416
417# Generic removal bits, where there are things in the generated man
418# pages that need to be killed.
419for f in *_libstdc__-v3_*; do
420    rm $f
421done
422
423for f in *_src_*; do
424    rm $f
425done
426
427# Remove all internal implementation details?
428# rm std::_[A-Z]*.3 std::__detail*.3
429
430shopt -u nullglob
431
432
433# Also, for some reason, typedefs don't get their own man pages.  Sigh.
434for f in ios streambuf istream ostream iostream stringbuf \
435	 istringstream ostringstream stringstream filebuf ifstream \
436	 ofstream fstream string
437do
438    echo ".so man3/std::basic_${f}.3" > std::${f}.3
439    echo ".so man3/std::basic_${f}.3" > std::w${f}.3
440done
441
442echo ::
443echo :: Man pages in ${outdir}/man
444fi
445
446# all done
447echo ::
448
449exit 0
450