Разверните макрос внутри комментария doxygen для печати версии программного обеспечения

У меня есть некоторая база кода C++, документированная с помощью doxygen, и сборка с помощью GNU make. Информация о версии централизована в файле makefile, где у меня есть что-то вроде:

Версия=1.2.3.4

В моем файле makefile CFLAGS добавляют следующее определение:

CFLAGS + = - DAPP_VERSION=$(VERSION)

Это позволяет мне получить версию в коде, например: 

#define STR_EXPAND(tok) #tok
#define STR(tok) STR_EXPAND(tok)
int main()
{
    cout << "software version is << STR(APP_VERSION) << endl;
}

Теперь, что я хотел бы иметь это в doxygen-произведенном html файлы:

Текущая версия программного обеспечения 1.2.3.4

Мне удалось экспортировать переменную makefile в конфигурационный файл doxygen с помощью: (edit: doxygen вызывается из makefile, через цель 'make-doc')

PREDEFINED = APP_VERSION=$(VERSION)

Но тогда, если я попытаюсь в команде doxygen mainpage что-то подобное, это не удастся, потому что (конечно), имена макросов не расширяются в комментарии...

/**
mainpage this is the doc
Current version is $(APP_VERSION) -- or -- ... is APP_VERSION
*/

Вопросы

  • Знаете ли Вы способ "расширить" этот макрос в комментариях doxygen ? Это может быть сделано некоторой обработкой sed файла, содержащего комментарий в файле makefile, но, возможно, это можно решить непосредственно с помощью doxygen ?

  • Как другие проекты обрабатывают управление версиями (помимо автоматического инструмента управления версиями, который предоставляет VCS, я имею в виду), таким образом, что идентификатор версии однозначно определен в файле, поэтому его можно извлечь как программное обеспечение системы и документацию, построить систему.

Related: Как отобразить определенное значение

3 7
c++ makefile doxygen

3 ответа:

Вы должны использовать "экспорт" программы сделать т. е. очень просто сделать файл - 

project_name=FooBar
export project_name
all:
    doxygen Doxyfile

Позволит вам использовать следующие комментарии в C++

/*! \mainpage Project $(project_name) Lorem ipsum dolor
Я вижу, что это становится пита с большим набором экспорта, но это довольно простой способ сделать это. Кроме того, вы можете запустить doxygen из отдельного скрипта BASH со всеми экспортами в нем, чтобы избежать слишком большого загрязнения вашего Makefile.
2

Макросы в комментариях обычно не расширяются (см., например, Этот ответ). Это не уникально для doxygen, и я не могу придумать способ сделать это с помощью опции конфигурации PREDEFINED.

Как вы утверждаете в вопросе, вы можете использовать sed, смотрите третий пункт маркера в этот ответ. Например, используя следующие

INPUT_FILTER  = "sed -e 's/VERSION/1.0/'"

Заменит все экземпляры VERSION на 1.0 во всех ваших исходных файлах (вы можете указать, какие файлы обрабатывать INPUT_FILTER, вместо обработки всех исходных файлов). Возможно, вы не захотите, чтобы VERSION был расширен везде, поэтому, возможно, лучше использовать что-то вроде $(VERSION) и sed этого маркера. Кроме того, вам понадобится способ получения номера версии из файла makefile и в конфигурационный файл doxygen. Это можно сделать и с другим sed.

Чтобы решить ваш последний вопрос, doxygen имеет FILE_VERSION_FILTER параметр конфигурации для определения номера версии каждого файла. С помощью это выведет некоторую информацию о версии (все, что печатается по стандарту из команды, указанной в FILE_VERSION_FILTER) в верхней части каждой страницы файла. В документации приведены примеры получения номера версии с помощью различных систем управления версиями. Кроме того, здесь - Страница, описывающая, как использовать git и doxygen для извлечения информации о версии.

Единственным недостатком этой опции конфигурации является то, что я не знаю, как указать, где находится версия файла. информация должна содержаться в итоговой документации. Я предполагаю, что вы можете использовать файл макета: я предполагаю, что вы можете изменить макет страниц, но я никогда не делал этого и не знаю, насколько легко было бы использовать это, чтобы включить информацию о версии на главной странице.

3

Руководство по командам предполагает, что $(VARIABLE) расширяет переменные среды. Так, может быть, вы можете поместить свою версию в переменную окружения?

2