-
Notifications
You must be signed in to change notification settings - Fork 133
Doxygen
Chunhua Liao edited this page Jan 22, 2025
·
16 revisions
ROSE uses Doxygen-style comments to document source codes. HTML reference html files are then automatically generated by Doxygen.
Use default packages and versions on Red Hat 8.10
- sudo dnf install doxygen
- sudo dnf install java-1.8.0-openjdk-devel
- boost 1.66
Or the set of packages used by our CI/CD pipeline on Red Hat 8.10
| Software Package | Version | Description | Path |
|---|---|---|---|
| GCC | 8.5 | Compilers | /usr/bin/gcc |
| Bison | 3.1 | A parser generator for C and C++ | /opt/dev/bison/3.1/gcc8ts/release |
| Flex | 2.6.1 | A tool for generating scanners (lexical analyzers) | /opt/dev/flex/2.6.1/gcc8ts/release |
| Gettext | 0.19 | A tool for internationalization and localization | /opt/dev/gettext/0.19/gcc8ts/release |
| Libtool | 2.4.6 | A generic library support script | /opt/dev/libtool/2.4.6/gcc8ts/release |
| Boost | 1.66.0 | A collection of C++ libraries for various tasks | /opt/dev/boost/1.66.0/gcc8ts/release or /usr/include/boost/ |
| Doxygen | 1.9.8 | A documentation generator for C++, C, and other languages | /opt/dev/doxygen/1.9.8/gcc8ts/release |
| Byacc | 20170709 | A Berkeley Yacc-compatible parser generator | /opt/dev/byacc/20170709/gcc8ts/release |
| Xapian | 1.4.21 | An open-source search engine library | /opt/dev/xapian/1.4.21/gcc8ts/release |
| Java Development Kit (JDK) | 1.8.0_422.b05-2.el8.x86_64 | A software development kit for Java | /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.422.b05-2.el8.x86_64 |
environment settings
source /opt/dev/boost/1.66.0/gcc8ts/release/dev.rc
source /opt/dev/xapian/1.4.21/gcc8ts/release/dev.rc
source /opt/dev/doxygen/1.9.8/gcc8ts/release/dev.rc
source /opt/toolsets/ubi8-gcc8-rose.rc
export LD_LIBRARY_PATH=$XAPIAN_HOME/lib:$LD_LIBRARY_PATH
export JAVA_HOME=$(ls -d /usr/lib/jvm/java-1.8.0-openjdk-1.8.0*)
export LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/amd64/server/:$LD_LIBRARY_PATH
export PATH=$JAVA_HOME/bin:$PATH
export ROSE_SOURCE="$(pwd)"
export ROSE_BUILD="$(pwd)/build_tree"
export ROSE_INSTALL="$(pwd)/install_tree"
export config="--with-doxygen=${DOXYGEN_HOME}/bin/doxygen --with-boost=${BOOST_HOME} --enable-boost-version-check=false"
# expands to
/workspace/configure --prefix=/workspace/install_tree --with-doxygen=/opt/dev/doxygen/1.9.8/gcc8ts/release/bin/doxygen --with-boost=/opt/dev/boost/1.66.0/gcc8ts/release --enable-boost-version-check=false
# or default packages
../configure --prefix=/home/liao6/workspace/2.code2doc/rose/install_tree --with-boost=/usr --with-boost-libdir=/usr/lib64 --disable-binary-analysis
# one binary analysis file may cause hanging in compilation. we can disable binary analysis as a workaround.
time make -j${CORE_NUMBERS} core
time make -j${CORE_NUMBERS} install-tools || exit 1
#time make -j${CORE_NUMBERS} docs || exit 1
# not all tutorial tests pass. We only run these that are needed by doxygen for now
time make -C tutorial charmSupport.out -j${CORE_NUMBERS} || exit 1
time make -C docs/Rose/ doxygen_docs || (echo "Doxygen_docs failed!" && exit 1)
The doxygen related configurations are stored in docs/Rose/rose.cfg.in.
This config file contains important information about
- what file suffixes to scan (or ignore)
- which folders or files to look at
- what type of outputs are needed
- call graph
- xml dump
- dot or svg output
make html, html-am, html-recursive
For example, the following changes will turn on additional features, scan extra .C files
diff --git a/docs/Rose/rose.cfg.in b/docs/Rose/rose.cfg.in
index 3697ebff6..4a3e75dbf 100644
--- a/docs/Rose/rose.cfg.in
+++ b/docs/Rose/rose.cfg.in
@@ -720,6 +720,8 @@ INPUT = @top_srcdir@/docs/Rose/MainPage.dox \
@top_srcdir@/src/frontend/SageIII/astPostProcessing/checkIsModifiedFlag.C \
@top_srcdir@/src/frontend/SageIII/sageInterface \
@top_srcdir@/src/frontend/SageIII/sageInterface/sageInterface.C \
+ @top_srcdir@/src/frontend/SageIII/sageInterface/sageInterface_type.C \
+ @top_srcdir@/src/frontend/SageIII/sageInterface/sageInterfaceAda.C \
@top_srcdir@/src/frontend/SageIII/sageInterface/sageBuilder.C \
@top_srcdir@/src/frontend/SageIII/astFromString \
@top_srcdir@/src/frontend/SageIII/virtualCFG \
@@ -1839,7 +1841,7 @@ INCLUDED_BY_GRAPH = YES
# the time of a run. So in most cases it will be better to enable call graphs
# for selected functions only using the \callgraph command.
-CALL_GRAPH = NO
+CALL_GRAPH = YES
# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then
# doxygen will generate a caller dependency graph for every global function
@@ -1847,7 +1849,7 @@ CALL_GRAPH = NO
# the time of a run. So in most cases it will be better to enable caller
# graphs for selected functions only using the \callergraph command.
-CALLER_GRAPH = NO
+CALLER_GRAPH = YES
# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
# will generate a graphical hierarchy of all classes instead of a textual one.
@@ -1866,8 +1868,8 @@ DIRECTORY_GRAPH = YES
# If left blank png will be used. If you choose svg you need to set
# HTML_FILE_EXTENSION to xhtml in order to make the SVG files
# visible in IE 9+ (other browsers do not have this requirement).
-
-DOT_IMAGE_FORMAT = png
+# originally set to png
+DOT_IMAGE_FORMAT = svg
# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
# enable generation of interactive SVG images that allow zooming and panning.
@@ -1876,7 +1878,7 @@ DOT_IMAGE_FORMAT = png
# need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files
# visible. Older versions of IE do not have SVG support.
-INTERACTIVE_SVG = NO
+INTERACTIVE_SVG = YES
# The tag DOT_PATH can be used to specify the path where the dot tool can be
# found. If left blank, it is assumed the dot tool can be found in the path.
@@ -1919,7 +1921,7 @@ DOT_GRAPH_MAX_NODES = 200
# children (previously this dropped children from the graph when the unlimited depth
# caused more nodes in the graph than permitted by DOT_GRAPH_MAX_NODES (above)).
# MAX_DOT_GRAPH_DEPTH = 0
-MAX_DOT_GRAPH_DEPTH = 1
+MAX_DOT_GRAPH_DEPTH = 2
# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
# background. This is disabled by default, because dot on Windows does not
@@ -1934,7 +1936,7 @@ DOT_TRANSPARENT = NO
# makes dot run faster, but since only newer versions of dot (>1.8.10)
# support this, this feature is disabled by default.
-DOT_MULTI_TARGETS = NO
+DOT_MULTI_TARGETS = YES
# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
# generate a legend page explaining the meaning of the various boxes and
@@ -1946,4 +1948,4 @@ GENERATE_LEGEND = YES
# remove the intermediate dot files that are used to generate
# the various graphs.
-DOT_CLEANUP = YES
+DOT_CLEANUP = NO
time make -j core
time make -j install-tools
# not all tutorial tests pass. We only run these that are needed by doxygen for now
time make -C tutorial charmSupport.out -j
time make -C docs/Rose/ doxygen_docs -j
The Makefile has the following content
doxygen_docs: rose.cfg
$(DOXYGEN) rose.cfg
if [ "$(DOXYINDEXER)" != "" -a -e ROSE_WebPages/searchdata.xml ]; then \
$(DOXYINDEXER) ROSE_WebPages/searchdata.xml; \
fi
build_tree/docs/Rose/ROSE_WebPages/xml
cd build_tree/docs/Rose/ROSE_WebPages/ROSE_HTML_Reference
nohup python3.11 -m http.server 8000 &
In your web browser, you can open your localhost:8000 to view the html reference files generated by Doxygen.