如何正确结合Doxygen与GNU Autotools编译安装文档

问题背景 #

使用GNU构建系统自动通过Doxygen编译C++文档并安装HTML、PDF产物，采用autoconf-archive中的ax_prog_doxygen脚本，遇到两个核心问题：

• Doxygen配置文件的INPUT路径为相对运行目录的路径，无法适配用户任意的构建目录与源码目录相对位置；
• 构建目录内生成的文档无法正确安装，autotools的_DATA目标会自动给构建目录的绝对路径添加源码目录的相对前缀，导致路径错误。

现有配置 #

configure.ac #

DX_HTML_FEATURE(ON)
DX_CHM_FEATURE(OFF)
DX_CHI_FEATURE(OFF)
DX_MAN_FEATURE(OFF)
DX_RTF_FEATURE(OFF)
DX_XML_FEATURE(OFF)
DX_PDF_FEATURE(ON)
DX_PS_FEATURE(OFF)

DX_INIT_DOXYGEN([$PACKAGE_NAME], [$(top_srcdir)/Doxygen.config], [doc/doxygen])

Doxygen.config存放于顶层源码目录，设置OUTPUT_DIRECTORY = doc/doxygen，指定宏输出到构建目录的doc/doxygen路径下。

Makefile.am #

EXTRA_DIST=Doxygen.config

# include Doxygen rules (requires autoconf-archive >2016-03-20)
@DX_RULES@

clean-local:
        -rm -rf doc/doxygen/*

doxygen-prepare:
        mkdir -p doc/doxygen

docs: doxygen-prepare doxygen-doc

# Try to tell autotools to install documentation
htmldir = $(docdir)/html
latexdir = $(docdir)/latex
html_DATA = $(abs_top_builddir)/doc/doxygen/html
latex_DATA = $(abs_top_builddir)/doc/doxygen/latex

测试场景与错误 #

在源码目录下创建构建目录$(top_srcdir)/my_compile，执行：

../configure --prefix=/u/software/project/

• 先执行make docs再make可成功构建，但直接执行make报错：

  make[2]: *** No rule to make target `/u/project/mycompile/doc/doxygen/html', needed by `all-am'.  Stop.
  

• 执行make install时错误：

  make[2]: Entering directory `/u/project/mycompile'
  make[2]: Nothing to be done for `install-exec-am'.
   /usr/bin/mkdir -p '/u/software/project/share/doc/project/html'
   /usr/bin/install -c -m 644 ../u/project/mycompile/doc/doxygen/html '/u/software/project/share/doc/project/html'
  /usr/bin/install: cannot stat ‘../u/project/mycompile/doc/doxygen/html’: No such file or directory
  make[2]: *** [install-htmlDATA] Error 1
  make[2]: Leaving directory `/u/project/mycompile'
  

错误根源：autotools自动给构建目录的绝对路径添加了../前缀，导致路径无效。

解决建议 #

1. 模板化Doxygen.config（规范推荐） #

这是符合Autotools设计规范的方案，彻底解决路径适配问题：

• 将源码中的Doxygen.config重命名为Doxygen.config.in作为模板；
• 模板中把INPUT路径替换为@abs_top_srcdir@/src（根据实际源码路径调整），OUTPUT_DIRECTORY设为@abs_top_builddir@/doc/doxygen；
• 在configure.ac中添加配置文件生成规则：

  AC_CONFIG_FILES([Doxygen.config])
  

configure运行时会自动在构建目录生成适配后的Doxygen.config，所有路径均为绝对路径，不受用户构建目录位置影响。

2. 修正安装目标的路径处理 #

放弃_DATA目标的自动路径处理，改用自定义安装规则：

• 在Makefile.am中删除原有的html_DATA和latex_DATA定义，替换为：

  htmldir = $(docdir)/html
  latexdir = $(docdir)/latex
  
  # 让安装流程依赖文档生成
  install-data-local: doxygen-doc
  	$(INSTALL) -d $(DESTDIR)$(htmldir)
  	cp -r $(top_builddir)/doc/doxygen/html/* $(DESTDIR)$(htmldir)/
  	$(INSTALL) -d $(DESTDIR)$(latexdir)
  	cp -r $(top_builddir)/doc/doxygen/latex/* $(DESTDIR)$(latexdir)/
  	# 单独安装PDF产物
  	if [ -f $(top_builddir)/doc/doxygen/latex/refman.pdf ]; then \
  		$(INSTALL) -d $(DESTDIR)$(docdir); \
  		$(INSTALL_DATA) $(top_builddir)/doc/doxygen/latex/refman.pdf $(DESTDIR)$(docdir)/$(PACKAGE_NAME).pdf; \
  	fi
  

• 若需默认构建文档，可在Makefile.am中添加：

  all-local: docs
  

更推荐通过--enable-docs配置选项让用户自主选择是否默认构建文档，避免无需求用户的编译负担。

额外优化 #

• 利用ax_prog_doxygen脚本的检查功能，确保用户系统已安装Doxygen；
• 在clean-local中添加删除构建目录下生成的Doxygen.config（若使用模板方案）；
• 给PDF产物命名为带包名的形式，方便用户识别。

内容的提问来源于stack exchange，提问作者sel