Expandir macro dentro de doxygen comentario para imprimir la versión del software

Question

Tengo un código base en C++, documentado con doxygen y compilado con GNU make. Información de la versión que está centralizado en el Makefile, en el que tengo algo así como:

VERSION = 1.2.3.4

En mi makefile, las CFLAGS añadir la siguiente definición:

CFLAGS + = -DAPP_VERSION = $ (VERSIÓN)

Esto me permite obtener la versión en código, así:

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

Ahora, lo que me gustaría es tener esto en los archivos html doxygen producidos:

versión actual del software es 1.2.3.4

he conseguido exportar el variable de makefile en el archivo de configuración doxygen con: (editar: doxygen se llama desde makefile, a través de un objetivo 'hacer-doc')

PREDEFINIDAS = APP_VERSION = $ (VERSIÓN)

Pero entonces, si lo intento en el doxygen \ comando MainPage algo como esto, se produce un error, debido a que (por supuesto), los nombres de macro no conseguir ampliada en los comentarios ...

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

Preguntas

• ¿conoce una forma de "expandir" esa macro en los comentarios doxygen? Esto podría hacerse mediante algún procesamiento de sed en el archivo que contiene el comentario en el archivo MAKE, pero quizás esto se puede resolver directamente con doxygen?

• ¿Cómo manejan el manejo de versiones otros proyectos (además de la herramienta automática de versiones que proporciona VCS), de forma que el ID de la versión está definido exclusivamente en un archivo, por lo que puede ser obtenido tanto por el sistema de compilación del software y la documentación sistema de construcción.

relacionadas: How to display a defined value

Answer 1

Es necesario utilizar la funcionalidad "exportación" de maquillaje es decir, un archivo de maquillaje muy simple con

project_name=FooBar 
export project_name 
all: 
    doxygen Doxyfile 

Se permitirá utilizar los siguientes comentarios en C++

/*! \mainpage Project $(project_name) Lorem ipsum dolor 

Puedo ver que esto Convertirse en un PITA con un gran conjunto de exportaciones, pero es una forma bastante simple de hacerlo. Alternativamente, puede ejecutar doxygen desde un script BASH separado con todas las exportaciones para evitar contaminar demasiado su Makefile.

Answer 2

la commands manual sugiere que $(VARIABLE) expande las variables de entorno. Entonces, ¿quizás puede poner su versión en una variable de entorno?

Answer 3

Las macros en los comentarios generalmente no se expanden (ver, por ejemplo, this answer). Esto no es exclusivo de doxygen y no puedo pensar en una forma de hacerlo utilizando la opción de configuración PREDEFINED.

Como indica en la pregunta, puede usar sed, consulte el tercer punto de la viñeta en this answer.Por ejemplo, utilizando la siguiente

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

sustituirá a todas las instancias de VERSION con 1.0 en todos los archivos de origen (puede especificar los archivos que desea procesar con INPUT_FILTER, en lugar de procesar todos los archivos de origen). Es posible que no desee que VERSION se expanda en todas partes, por lo que quizás sea mejor utilizar algo como $(VERSION) y sed este token. Además, necesitará una forma de obtener su número de versión de su archivo MAKE y en su archivo de configuración doxygen. Esto se puede hacer con otro sed.

Para abordar su último punto, doxygen tiene la opción de configuración FILE_VERSION_FILTER para determinar el número de versión de cada archivo. Al usar esto, se imprimirá información de la versión (lo que se imprima a la salida estándar del comando especificado en FILE_VERSION_FILTER) en la parte superior de cada página de archivo. En la documentación, hay ejemplos de cómo obtener el número de versión utilizando varios sistemas de control de versiones diferentes. Además, here es una página que describe cómo usar git y doxygen para extraer información de la versión.

El único inconveniente con esta opción de configuración es que no sé cómo especificar dónde debe aparecer la información de la versión del archivo en la documentación final. Supongo que puede usar un archivo de diseño: supongo que puede change the layout of pages, pero nunca lo he hecho y no sé cuán fácil sería usar esto para incluir información de la versión en la página principal.