top-level build target that triggers 'make doc-html-doxygen'

top-level build target that triggers 'make doc-html-doxygen'

[Saifi Khan]

Hi:

Does anyone know what is the top-level Makefile build target that 
triggers 'make doc-html-doxygen' in libstdc++ ?

Using the following top-level targets,

make html
or
make install-html

does not build libstdc++ doxygen-based API documentation.

The toolchain builds without any issues and i want to build the 
libstdc++ documentation with it. Any pointers ?

warm regards
Saifi.

Re: top-level build target that triggers 'make doc-html-doxygen'

[Jonathan Wakely]

On Sun, 13 Nov 2022 at 07:29, Saifi Khan <saifi.khan@nishan.io> wrote:
>
> Hi:
>
> Does anyone know what is the top-level Makefile build target that
> triggers 'make doc-html-doxygen' in libstdc++ ?
>
> Using the following top-level targets,
>
> make html
> or
> make install-html
>
> does not build libstdc++ doxygen-based API documentation.
>
> The toolchain builds without any issues and i want to build the
> libstdc++ documentation with it. Any pointers ?

make -C */libstdc++-v3 doc-html-doxygen will work


>
> warm regards
> Saifi.

Re: top-level build target that triggers 'make doc-html-doxygen'

[Saifi Khan]

On 2022-11-13 08:29, Jonathan Wakely via Gcc-help wrote:
> On Sun, 13 Nov 2022 at 07:29, Saifi Khan <saifi.khan@nishan.io> wrote:
>> 
>> Does anyone know what is the top-level Makefile build target that
>> triggers 'make doc-html-doxygen' in libstdc++ ?
>> 
> make -C */libstdc++-v3 doc-html-doxygen will work
> 

Thanks for your reply Jonathan.

Since, i am doing a 'out-of-source-tree' build, the layout looks like 
this

/opt/gcc
├── build
└── src

Given the layout, the build/b02.sh (configure script) is as follows

DIR_SRC=/opt/gcc/src
DIR_DST=/opt/gcc
DIR_ISL=/opt/isl
   CFLAGS="-O2 -pipe"
CXXFLAGS="${CFLAGS}"

${DIR_SRC}/configure                        \
           --prefix=${DIR_DST}               \
           --exec-prefix=${DIR_DST}          \
           --datarootdir=${DIR_DST}/doc/share   \
           --datadir=${DIR_DST}/doc          \
           --docdir=${DIR_DST}/doc           \
           --htmldir=${DIR_DST}/doc          \
           --mandir=${DIR_DST}/doc/man       \
           --infodir=${DIR_DST}/doc/info     \
           --with-isl=${DIR_ISL}             \
           --enable-languages=c,jit,c++      \
           --enable-bootstrap                \
  <snipped>

Post build/b04.sh ie. 'make -j4', there is one directory created for 
libstdc++

build/x86_64-pc-linux-gnu/libstdc++-v3

Now, if i execute the command that you suggested, the doxygen html build 
goes through (which is what i was did prior to posting on gcc-help).

Unfortunately, on executing build/b08.sh script file ie. 'make install' 
errors out !

That leaves only one option and that first perform 'make install' and 
then 'make -C */libstdc++-v3 doc-html-doxygen'.

Does that seem like a sensible thing to do ?

In addition, i observed that the html documentation for the various lib* 
also doesn't get copied as part of 'make install', wich means that a 
custom script will be required to recursively copy the 'html' 
directories from all 'lib*' including 'libstdc++-v3'.

Is that how the online gcc docs are getting updated ?

warm regards
Saifi.

Re: top-level build target that triggers 'make doc-html-doxygen'

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 2698 bytes --]

On Sun, 13 Nov 2022, 09:11 Saifi Khan, <saifi.khan@nishan.io> wrote:

> On 2022-11-13 08:29, Jonathan Wakely via Gcc-help wrote:
> > On Sun, 13 Nov 2022 at 07:29, Saifi Khan <saifi.khan@nishan.io> wrote:
> >>
> >> Does anyone know what is the top-level Makefile build target that
> >> triggers 'make doc-html-doxygen' in libstdc++ ?
> >>
> > make -C */libstdc++-v3 doc-html-doxygen will work
> >
>
> Thanks for your reply Jonathan.
>
> Since, i am doing a 'out-of-source-tree' build, the layout looks like
> this
>
> /opt/gcc
> ├── build
> └── src
>
> Given the layout, the build/b02.sh (configure script) is as follows
>
> DIR_SRC=/opt/gcc/src
> DIR_DST=/opt/gcc
> DIR_ISL=/opt/isl
>    CFLAGS="-O2 -pipe"
> CXXFLAGS="${CFLAGS}"
>
> ${DIR_SRC}/configure                        \
>            --prefix=${DIR_DST}               \
>            --exec-prefix=${DIR_DST}          \
>            --datarootdir=${DIR_DST}/doc/share   \
>            --datadir=${DIR_DST}/doc          \
>            --docdir=${DIR_DST}/doc           \
>            --htmldir=${DIR_DST}/doc          \
>            --mandir=${DIR_DST}/doc/man       \
>            --infodir=${DIR_DST}/doc/info     \
>            --with-isl=${DIR_ISL}             \
>            --enable-languages=c,jit,c++      \
>            --enable-bootstrap                \
>   <snipped>
>
> Post build/b04.sh ie. 'make -j4', there is one directory created for
> libstdc++
>
> build/x86_64-pc-linux-gnu/libstdc++-v3
>
> Now, if i execute the command that you suggested, the doxygen html build
> goes through (which is what i was did prior to posting on gcc-help).
>
> Unfortunately, on executing build/b08.sh script file ie. 'make install'
> errors out !
>
> That leaves only one option and that first perform 'make install' and
> then 'make -C */libstdc++-v3 doc-html-doxygen'.
>

You can replace the * with the correct path, which is the
x86_64-pc-linux-gnu one for your case.


> Does that seem like a sensible thing to do ?
>
> In addition, i observed that the html documentation for the various lib*
> also doesn't get copied as part of 'make install', wich means that a
> custom script will be required to recursively copy the 'html'
> directories from all 'lib*' including 'libstdc++-v3'.
>

There is a doc-install-html target in the $target/libstdc++-v3 dir, but
that will also try to build the main manual as well as the doxygen pages.



> Is that how the online gcc docs are getting updated ?
>

A script that copies them to the web server directory after building them.
They are not "installed" by the makefile.



> warm regards
> Saifi.
>

Re: top-level build target that triggers 'make doc-html-doxygen'

[Saifi Khan]

On 2022-11-13 09:29, Jonathan Wakely via Gcc-help wrote:
> 
> There is a doc-install-html target in the $target/libstdc++-v3 dir, but
> that will also try to build the main manual as well as the doxygen 
> pages.
> 

yes, this seems even better. So, i tried to build the 'doc-install-html' 
target

xsltproc --param toc.section.depth 4 --param generate.consistent.ids 1 
--nonet --xinclude -o 
/opt/gcc/build/x86_64-pc-linux-gnu/libstdc++-v3/doc/docbook/html/ \
  --stringparam chunker.output.encoding UTF-8 \
/xhtml/chunk.xsl \
../../../../src/libstdc++-v3/doc/xml/spine.xml
warning: failed to load external entity "/xhtml/chunk.xsl"
cannot parse /xhtml/chunk.xsl
make[1]: *** [Makefile:1046: stamp-html-docbook] Error 4
make[1]: Leaving directory 
'/opt/gcc/build/x86_64-pc-linux-gnu/libstdc++-v3/doc'
make: *** [Makefile:784: doc-install-html] Error 2
make: Leaving directory 
'/opt/gcc/build/x86_64-pc-linux-gnu/libstdc++-v3'

There isn't any 'chunk.xsl' in the entire source tree.

Am i missing something ?

warm regards
Saifi.

Re: top-level build target that triggers 'make doc-html-doxygen'

[Jonathan Wakely]

On Mon, 14 Nov 2022 at 16:25, Saifi Khan <saifi.khan@nishan.io> wrote:
>
> On 2022-11-13 09:29, Jonathan Wakely via Gcc-help wrote:
> >
> > There is a doc-install-html target in the $target/libstdc++-v3 dir, but
> > that will also try to build the main manual as well as the doxygen
> > pages.
> >
>
> yes, this seems even better. So, i tried to build the 'doc-install-html'
> target
>
> xsltproc --param toc.section.depth 4 --param generate.consistent.ids 1
> --nonet --xinclude -o
> /opt/gcc/build/x86_64-pc-linux-gnu/libstdc++-v3/doc/docbook/html/ \
>   --stringparam chunker.output.encoding UTF-8 \
> /xhtml/chunk.xsl \
> ../../../../src/libstdc++-v3/doc/xml/spine.xml
> warning: failed to load external entity "/xhtml/chunk.xsl"
> cannot parse /xhtml/chunk.xsl
> make[1]: *** [Makefile:1046: stamp-html-docbook] Error 4
> make[1]: Leaving directory
> '/opt/gcc/build/x86_64-pc-linux-gnu/libstdc++-v3/doc'
> make: *** [Makefile:784: doc-install-html] Error 2
> make: Leaving directory
> '/opt/gcc/build/x86_64-pc-linux-gnu/libstdc++-v3'
>
> There isn't any 'chunk.xsl' in the entire source tree.
>
> Am i missing something ?

Yes, you're missing a docbook installation.

https://gcc.gnu.org/onlinedocs/libstdc++/manual/documentation_hacking.html#doc.docbook

Re: top-level build target that triggers 'make doc-html-doxygen'

[Saifi Khan]

>  >
>  > There isn't any 'chunk.xsl' in the entire source tree.
>  > Am i missing something ?
>  
>  Yes, you're missing a docbook installation.
>  
>  https://gcc.gnu.org/onlinedocs/libstdc++/manual/documentation_hacking.html#doc.docbook
>  

Yep. Thanks for the catch !

Once my doxygen build is done (18.4K graphs to process), i will give the 'doc-html-target' a try.

warm regards
Saifi.

Re: top-level build target that triggers 'make doc-html-doxygen'

[Saifi Khan]

On 2022-11-13 08:29, Jonathan Wakely via Gcc-help wrote:
> On Sun, 13 Nov 2022 at 07:29, Saifi Khan <saifi.khan@nishan.io> wrote:
>> 
>> Does anyone know what is the top-level Makefile build target that
>> triggers 'make doc-html-doxygen' in libstdc++ ?
>> 
> make -C */libstdc++-v3 doc-html-doxygen will work
> 

Thanks for the help Jonathan, much appreciated !

i also tweaked the libstdc++-v3/doc/doxygen/user.cfg.in to generate more 
detailed documentation with UML diagrams cross-referenced with the 
source code. Here is the result,

https://softwarehub.sourceforge.io/

i hope this will help onboard more newbies, beginners and enthusiastic 
learners to modern C++20/23 and also project externally the wonderful 
work of so many compiler hackers and free software contributors.

warm regards
Saifi.