使用 makefile 的 Doxygen 文档答案

【问题标题】：Doxygen Documentation using makefile使用 makefile 的 Doxygen 文档
【发布时间】：2014-03-11 21:24:04
【问题描述】：

我用 C++ 编写了一个程序，我想使用 makefile 生成可执行文件。这可行，但是我的代码中也有一些 Doxygen 样式的 cmets，我希望我的 makefile 自动生成带有文档的 HTML 页面。不幸的是，我无法弄清楚这应该如何正确完成。到目前为止，我的 makefile 的文档部分看起来像：

docs:
    doxygen ./Doxyfile

我猜我需要添加一些额外的文件，有人可以为我澄清一下过程吗？

【问题讨论】：

您能详细说明问题所在吗？到目前为止，您尝试过的结果如何？
@PeterSw - 问题是我以前从未做过，我不知道该怎么做。目前我的代码什么都不做
直接运行doxygen ./Doxyfile 什么都不做吗？ make docs 呢？您是否尝试将行 PHONY: docs 添加到您的 Makefile 中？
这是 stackoverflow.com/questions/13777301/…> 的副本
不是.PHONY: docs（开头有句号吗？）。我认为只有在 doxygen 将其输出放在 docs/ 目录中时才真正需要它。在这种情况下，make 会注意到该目录已经存在，并且由于没有列出依赖项，因此它不会重建它。如果没有名为“docs”的文件或目录，则每次都会重建目标，但我同意将其标记为假的仍然更干净。更好的做法是将所有源文件和头文件列为依赖项（这样只有在发生任何变化时才重新运行 doxygen）。

标签： c++ makefile doxygen

【解决方案1】：

您可能希望添加依赖项，以便在源代码更改时生成文档。最容易做到这一点的地方是应用程序的构建规则。当源发生变化并且需要构建应用程序时，您可以将其用作构建文档的触发器：

$(PROGRAM): $(OBJECTS)
    @echo Building $@
    $(CC) $(LDFLAGS) -o $@ $(OBJECTS) $(LIBS)
    @echo Updating Docs $@
    @doxygen

我想同样可以单独工作

DOCS=MyProject_html

docs: $(DOCS)/MyProject.html

$(DOCS)/MyProject.html: $(PROGRAM) $(OBJECTS)
    @echo Building Docs
    @doxygen

clean:
     rm -rf $(PROGRAM) $(OBJECTS) $(DOCS)

有一种更自动的方式来进行生成，但这应该可以工作。

【讨论】：

文档生成应该依赖于源而不是对象，因为在生成文档之前不需要构建对象（尽管在这种情况下建议代码已经由编译器，因此 doxygen 得到某些有效的代码）。在“编译”构建过程中可能会生成一些文件源文件，当然也应该添加它们。
@albert 同意，此外，即使目标文件没有更改，您也可能需要重新运行 doxygen，例如如果您只更改了文档。

【解决方案2】：

我从 make 文件生成文档的方法是：

docs:
    @doxygen
    @open doxygen/html/index.html

然后您可以通过运行make docs 来访问它。

【讨论】：

【解决方案3】：

如果问题是如何确保make（而不是make docs）也重建您的文档：

创建一个 docs 目标，它要么是虚假的，要么将所有源文件和头文件列为依赖项。
确保您的默认目标（makefile 中的第一个目标）同时具有 docs 和您的可执行文件作为依赖项。

例如

all: hello docs

.PHONY: docs
docs:
    @doxygen ./Doxyfile

hello: hello.o foo.o
    ...

hello.o: hello.cpp hello.h foo.h
    ...

foo.o: foo.cpp foo.h
    ...

只有在任何输入发生变化时才会重新运行 Doxygen 的替代方案（尽管需要维护更多工作）：

all: hello docs

# Doxygen needs to be rerun if the Doxyfile changed, or if any source or
# header file with Doxygen comments changed.  If all your comments are in
# the headers, you don't need to include the .cpp files.
docs: hello.cpp hello.h foo.cpp foo.h ./Doxyfile
    @doxygen ./Doxyfile

hello: hello.o foo.o
    ...

hello.o: hello.cpp hello.h foo.h
    ...

foo.o: foo.cpp foo.h
    ...

（确保在实际 Makefile 中用制表符替换构建规则前的空格）

【讨论】：