]>
Commit | Line | Data |
---|---|---|
f7ab5fa4 | 1 | #!/bin/bash |
bfcafa4f | 2 | |
2f9d51b8 | 3 | # Runs doxygen and massages the output files. |
a945c346 | 4 | # Copyright (C) 2001-2024 Free Software Foundation, Inc. |
e03f70b3 | 5 | # |
0f752f44 | 6 | # Synopsis: run_doxygen --mode=[html|latex|man|xml] --host_alias=<alias> \ |
40e053e3 BK |
7 | # v3srcdir \ |
8 | # v3builddir \ | |
9 | # shortname | |
e03f70b3 | 10 | # |
b0037845 | 11 | # Originally hacked together by Phil Edwards <pme@gcc.gnu.org> |
bfcafa4f | 12 | |
e03f70b3 | 13 | |
cff75d2e | 14 | # We can check now that the version of doxygen is >= this variable. |
30f276c1 | 15 | DOXYVER=1.7.0 |
864e133c PE |
16 | |
17 | find_doxygen() { | |
f7ab5fa4 | 18 | local -r v_required=`echo $DOXYVER | \ |
0f752f44 | 19 | awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'` |
f7ab5fa4 | 20 | local testing_version doxygen maybedoxy v_found |
864e133c PE |
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` | |
cff75d2e MK |
28 | if test -n "$testing_version"; then |
29 | v_found=`echo $testing_version | \ | |
0f752f44 | 30 | awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'` |
cff75d2e | 31 | if test $v_found -ge $v_required; then |
0f752f44 BK |
32 | doxygen="$maybedoxy" |
33 | break | |
cff75d2e | 34 | fi |
864e133c PE |
35 | fi |
36 | done | |
37 | if test -z "$doxygen"; then | |
e3b6d3a8 | 38 | fail "Could not find Doxygen $DOXYVER in path." |
864e133c | 39 | fi |
f7ab5fa4 PE |
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 | |
864e133c | 44 | } |
e03f70b3 PE |
45 | |
46 | print_usage() { | |
e3b6d3a8 JW |
47 | cat <<EOF |
48 | Usage: run_doxygen --mode=MODE --host_alias=HOST_ALIAS [<options>] | |
0f752f44 | 49 | <v3-src-dir> <v3-build-dir> <shortnamesp> |
e03f70b3 | 50 | MODE is one of: |
0f752f44 BK |
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. | |
e03f70b3 | 55 | |
e3b6d3a8 JW |
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. | |
3ebf2eba | 65 | |
e03f70b3 PE |
66 | Note: Requires Doxygen ${DOXYVER} or later; get it at |
67 | ftp://ftp.stack.nl/pub/users/dimitri/doxygen-${DOXYVER}.src.tar.gz | |
68 | ||
69 | EOF | |
e3b6d3a8 JW |
70 | } |
71 | ||
72 | # Print an error message followed by usage to stderr, then exit. | |
73 | fail() { | |
74 | echo "$0: error: $*" 1>&2 | |
75 | echo 1>&2 | |
76 | print_usage 1>&2 | |
77 | exit 1 | |
e03f70b3 PE |
78 | } |
79 | ||
80 | parse_options() { | |
e3b6d3a8 | 81 | while [ $# -ne 0 ] |
e03f70b3 PE |
82 | do |
83 | # Blatantly ripped from autoconf, er, I mean, "gratefully standing | |
84 | # on the shoulders of those giants who have gone before us." | |
e3b6d3a8 JW |
85 | case "$1" in |
86 | -*=*) arg=`echo "$1" | sed 's/[-_a-zA-Z0-9]*=//'` ;; | |
e03f70b3 PE |
87 | *) arg= ;; |
88 | esac | |
89 | ||
e3b6d3a8 | 90 | case "$1" in |
e03f70b3 | 91 | --mode=*) |
0f752f44 | 92 | mode=$arg ;; |
7e7432e2 | 93 | --host_alias=*) |
0f752f44 | 94 | host_alias=$arg ;; |
e3b6d3a8 JW |
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" ;; | |
e03f70b3 | 103 | *) |
e3b6d3a8 JW |
104 | break ;; |
105 | esac | |
106 | shift | |
e03f70b3 | 107 | done |
e3b6d3a8 JW |
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" | |
e03f70b3 PE |
117 | } |
118 | ||
119 | ||
120 | # script begins here | |
121 | mode=unset | |
7e7432e2 | 122 | host_alias=unset |
e03f70b3 PE |
123 | srcdir=unset |
124 | outdir=unset | |
40e053e3 | 125 | shortname=unset |
a43d13fb | 126 | do_html=false |
0f752f44 BK |
127 | do_man=false |
128 | do_xml=false | |
129 | do_latex=false | |
e3b6d3a8 | 130 | latex_cmd= |
ffe94f83 | 131 | enabled_sections= |
4bc8ae23 | 132 | generate_tagfile= |
efe44c60 | 133 | DATEtext=`date '+%Y-%m-%d'` |
e03f70b3 | 134 | |
00aca6e8 BK |
135 | # Show how this script is called. |
136 | echo run_doxygen $* | |
137 | ||
e03f70b3 | 138 | parse_options $* |
864e133c | 139 | find_doxygen |
e03f70b3 | 140 | |
40e053e3 | 141 | if test $srcdir = unset || test $outdir = unset || test $mode = unset || test $shortname = unset || test $host_alias = unset; then |
e03f70b3 | 142 | # this could be better |
e3b6d3a8 | 143 | fail "You have not given enough information...! $srcdir - " |
e03f70b3 PE |
144 | fi |
145 | ||
146 | case x"$mode" in | |
4312e020 | 147 | xhtml) |
4bc8ae23 PE |
148 | do_html=true |
149 | enabled_sections=maint | |
4312e020 | 150 | generate_tagfile="$outdir/html/libstdc++.tag" |
4bc8ae23 | 151 | ;; |
0f752f44 BK |
152 | xlatex) |
153 | do_latex=true | |
154 | enabled_sections=maint | |
155 | ;; | |
4bc8ae23 PE |
156 | xman) |
157 | do_man=true | |
158 | ;; | |
8a165db0 BK |
159 | xxml) |
160 | do_xml=true | |
161 | enabled_sections=maint | |
162 | ;; | |
e03f70b3 PE |
163 | *) |
164 | echo run_doxygen error: $mode is an invalid mode 1>&2 | |
165 | exit 1 ;; | |
166 | esac | |
167 | ||
40e053e3 BK |
168 | case x"$shortname" in |
169 | xYES) | |
170 | ;; | |
171 | xNO) | |
172 | ;; | |
173 | *) | |
174 | echo run_doxygen error: $shortname is invalid 1>&2 | |
175 | exit 1 ;; | |
176 | esac | |
177 | ||
178 | ||
669f7a03 PE |
179 | mkdir -p $outdir |
180 | chmod u+w $outdir | |
ffe94f83 | 181 | |
60f8b2e2 | 182 | # Run it |
e03f70b3 | 183 | ( |
60f8b2e2 BK |
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}=" \ | |
e3b6d3a8 | 194 | -e "s=@latex_cmd@=${latex_cmd}=" \ |
60f8b2e2 BK |
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 | |
0f752f44 BK |
202 | ) |
203 | ret=$? | |
204 | test $ret -ne 0 && exit $ret | |
205 | ||
60f8b2e2 BK |
206 | if $do_xml; then |
207 | echo :: | |
208 | echo :: XML pages begin with | |
209 | echo :: ${outdir}/xml/index.xml | |
0f752f44 BK |
210 | fi |
211 | ||
60f8b2e2 BK |
212 | if $do_latex; then |
213 | cd ${outdir}/${mode} | |
214 | ||
710d672b JW |
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 | |
60f8b2e2 BK |
224 | |
225 | echo :: | |
226 | echo :: LaTeX pages begin with | |
227 | echo :: ${outdir}/latex/refman.tex | |
228 | fi | |
229 | ||
a43d13fb | 230 | if $do_html; then |
60f8b2e2 | 231 | cd ${outdir}/${mode} |
f7ab5fa4 PE |
232 | |
233 | #doxytag -t libstdc++.tag . > /dev/null 2>&1 | |
c0ffa2ba BK |
234 | |
235 | # Strip pathnames from tag file. | |
a43d13fb PE |
236 | sed -e '/<path>/d' libstdc++.tag > TEMP |
237 | mv TEMP libstdc++.tag | |
f7ab5fa4 | 238 | |
4312e020 BK |
239 | sed -e "s=@DATE@=${DATEtext}=" \ |
240 | ${srcdir}/doc/doxygen/mainpage.html > index.html | |
e1bff39a | 241 | |
bd2726e0 PE |
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. | |
a1fa4e31 PE |
247 | sed -e 's=\(::[[:alnum:]_]*\)< .* >=\1=' annotated.html > annstrip.html |
248 | mv annstrip.html annotated.html | |
e1bff39a | 249 | |
4312e020 | 250 | cp ${srcdir}/doc/doxygen/tables.html tables.html |
60f8b2e2 | 251 | |
a1fa4e31 PE |
252 | echo :: |
253 | echo :: HTML pages begin with | |
4312e020 | 254 | echo :: ${outdir}/html/index.html |
a43d13fb | 255 | fi |
e03f70b3 | 256 | |
2f9d51b8 PE |
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>"). | |
a43d13fb | 262 | if $do_man; then |
ffe94f83 | 263 | echo :: |
2f9d51b8 | 264 | echo :: Fixing up the man pages... |
ffe94f83 PE |
265 | cd $outdir/man/man3 |
266 | ||
729e3d3f | 267 | # File names with embedded spaces (EVIL!) need to be....? renamed or removed? |
a43d13fb | 268 | find . -name "* *" -print0 | xargs -0r rm # requires GNU tools |
2f9d51b8 | 269 | |
ffe94f83 PE |
270 | # man pages are for functions/types/other entities, not source files |
271 | # directly. who the heck would type "man foo.h" anyhow? | |
394f60e6 JW |
272 | # FIXME: This also removes std.3 which is the only place that a lot of |
273 | # functions are documented. Should we keep it? | |
7850920c | 274 | find . -name "[a-z]*" -a ! -name "std_*" -print | xargs rm |
aac2878e | 275 | rm -f *.h.3 *.hpp.3 *config* *.cc.3 *.tcc.3 *_t.3 |
7850920c | 276 | #rm ext_*.3 tr1_*.3 debug_*.3 |
aac2878e | 277 | |
04b7c941 PE |
278 | # this is used to examine what we would have deleted, for debugging |
279 | #mkdir trash | |
ffe94f83 PE |
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 | |
2f9d51b8 | 282 | |
394f60e6 JW |
283 | gxx=$($builddir/scripts/testsuite_flags --build-cxx) |
284 | cppflags=$($builddir/scripts/testsuite_flags --build-includes) | |
285 | cxxflags="-Og -g -std=gnu++23" | |
286 | ||
2f9d51b8 PE |
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. | |
394f60e6 JW |
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>. | |
fa4e9790 | 294 | problematic=`grep -E -l '#include <.*h>' [a-z]*.3` |
2f9d51b8 PE |
295 | for f in $problematic; do |
296 | # this is also slow, but safe and easy to debug | |
53e0a447 | 297 | oldh=`sed -n '/fC#include </s/.*<\(.*\)>.*/\1/p' $f` |
394f60e6 JW |
298 | newh=`echo $oldh | sed 's/\\\\&\\././g' | ./stdheader` |
299 | sed "s=${oldh/\\/.}=${newh}=" $f > TEMP && mv TEMP $f | |
2f9d51b8 PE |
300 | done |
301 | rm stdheader | |
302 | ||
b0037845 | 303 | # Some of the pages for generated modules have text that confuses certain |
70c6e9cb GP |
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. | |
fa4e9790 | 306 | problematic=`grep -E --files-without-match '^\.SH SYNOPSIS' [A-Z]*.3` |
aac2878e | 307 | #problematic='Containers.3 Sequences.3 Assoc_containers.3 Iterator_types.3' |
7850920c BK |
308 | |
309 | for f in $problematic; do | |
310 | sed '/^\.SH NAME/{ | |
311 | n | |
312 | a\ | |
313 | \ | |
314 | .SH SYNOPSIS | |
315 | }' $f > TEMP | |
316 | mv TEMP $f | |
317 | done | |
b0037845 | 318 | |
bd2726e0 PE |
319 | # Also, break this (generated) line up. It's ugly as sin. |
320 | problematic=`grep -l '[^^]Definition at line' *.3` | |
321 | for f in $problematic; do | |
322 | sed 's/Definition at line/\ | |
323 | .PP\ | |
324 | &/' $f > TEMP | |
325 | mv TEMP $f | |
326 | done | |
327 | ||
4312e020 | 328 | cp ${srcdir}/doc/doxygen/Intro.3 C++Intro.3 |
bd2726e0 PE |
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? | |
4312e020 | 332 | |
394f60e6 JW |
333 | # If no files match a glob, skip the for-loop: |
334 | shopt -s nullglob | |
4312e020 | 335 | # First, deal with nested namespaces. |
394f60e6 JW |
336 | for 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 | |
a2edd3e9 BK |
341 | done |
342 | for f in *__debug_*; do | |
343 | newname=`echo $f | sed 's/__debug_/__debug::/'` | |
344 | mv $f $newname | |
345 | done | |
346 | for f in *decimal_*; do | |
347 | newname=`echo $f | sed 's/decimal_/decimal::/'` | |
348 | mv $f $newname | |
349 | done | |
4312e020 BK |
350 | for f in *__detail_*; do |
351 | newname=`echo $f | sed 's/__detail_/__detail::/'` | |
352 | mv $f $newname | |
353 | done | |
a345e45d BK |
354 | for f in *__gnu_pbds_detail_*; do |
355 | newname=`echo $f | sed 's/detail_/detail::/'` | |
356 | mv $f $newname | |
357 | done | |
4312e020 BK |
358 | for f in *__parallel_*; do |
359 | newname=`echo $f | sed 's/__parallel_/__parallel::/'` | |
360 | mv $f $newname | |
361 | done | |
362 | ||
6b4f8906 JW |
363 | # Remove inline namespaces used for versioning. |
364 | for f in *_V2_*; do | |
365 | newname=`echo $f | sed 's/_V2_/::/'` | |
366 | sed 's/::_V2::/::/g' $f > $newname | |
367 | rm $f | |
368 | done | |
369 | for 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 | |
373 | done | |
374 | for 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 | |
378 | done | |
379 | ||
4312e020 | 380 | # Then, clean up other top-level namespaces. |
0aa06b18 BK |
381 | for f in std_tr1_*; do |
382 | newname=`echo $f | sed 's/^std_tr1_/std::tr1::/'` | |
383 | mv $f $newname | |
384 | done | |
08624e90 BK |
385 | for f in std_tr2_*; do |
386 | newname=`echo $f | sed 's/^std_tr2_/std::tr2::/'` | |
387 | mv $f $newname | |
388 | done | |
bd2726e0 PE |
389 | for f in std_*; do |
390 | newname=`echo $f | sed 's/^std_/std::/'` | |
391 | mv $f $newname | |
392 | done | |
393 | for f in __gnu_cxx_*; do | |
394 | newname=`echo $f | sed 's/^__gnu_cxx_/__gnu_cxx::/'` | |
395 | mv $f $newname | |
396 | done | |
4312e020 BK |
397 | for f in __gnu_debug_*; do |
398 | newname=`echo $f | sed 's/^__gnu_debug_/__gnu_debug::/'` | |
399 | mv $f $newname | |
400 | done | |
401 | for f in __gnu_parallel_*; do | |
402 | newname=`echo $f | sed 's/^__gnu_parallel_/__gnu_parallel::/'` | |
403 | mv $f $newname | |
404 | done | |
8d079e67 BK |
405 | for f in __gnu_pbds_*; do |
406 | newname=`echo $f | sed 's/^__gnu_pbds_/__gnu_pbds::/'` | |
407 | mv $f $newname | |
408 | done | |
7850920c BK |
409 | for f in __cxxabiv1_*; do |
410 | newname=`echo $f | sed 's/^__cxxabiv1_/abi::/'` | |
411 | mv $f $newname | |
412 | done | |
6309eefc | 413 | |
a2edd3e9 | 414 | # Then piecemeal nested classes |
a2edd3e9 BK |
415 | |
416 | ||
4312e020 | 417 | # Generic removal bits, where there are things in the generated man |
6309eefc BK |
418 | # pages that need to be killed. |
419 | for f in *_libstdc__-v3_*; do | |
0f752f44 | 420 | rm $f |
66fda8b2 | 421 | done |
6309eefc BK |
422 | |
423 | for f in *_src_*; do | |
0f752f44 | 424 | rm $f |
bd2726e0 PE |
425 | done |
426 | ||
394f60e6 JW |
427 | # Remove all internal implementation details? |
428 | # rm std::_[A-Z]*.3 std::__detail*.3 | |
429 | ||
430 | shopt -u nullglob | |
431 | ||
6309eefc | 432 | |
bd2726e0 PE |
433 | # Also, for some reason, typedefs don't get their own man pages. Sigh. |
434 | for f in ios streambuf istream ostream iostream stringbuf \ | |
0f752f44 | 435 | istringstream ostringstream stringstream filebuf ifstream \ |
394f60e6 | 436 | ofstream fstream string |
bd2726e0 PE |
437 | do |
438 | echo ".so man3/std::basic_${f}.3" > std::${f}.3 | |
439 | echo ".so man3/std::basic_${f}.3" > std::w${f}.3 | |
440 | done | |
e03f70b3 | 441 | |
ffe94f83 PE |
442 | echo :: |
443 | echo :: Man pages in ${outdir}/man | |
a43d13fb | 444 | fi |
2f9d51b8 PE |
445 | |
446 | # all done | |
e03f70b3 | 447 | echo :: |
e03f70b3 PE |
448 | |
449 | exit 0 |