Integración de AZ Code Generator con Waf

La versión publicada de AZ Code Generator es preliminar y está sujeta a cambios.

AZ Code Generator es totalmente accesible para cualquier destino Waf como la función az_code_gen. El archivo dev\Tools\Build\waf-<version_number>\lmbrwaflib\az_code_generator.py contiene el núcleo del código de integración Waf. Incluye la característica az_code_gen que puede utilizar cualquier archivo wscript.

El mínimo de información obligatoria es una lista de los archivos que desea transferir al generador de código y al menos un controlador de plantillas. Esta lista envía al generador de código un archivo cada vez e invoca las plantillas especificadas por el controlador. Las salidas de los archivos del controlador se añaden como dependencias de la tarea de compilación. Los archivos de salida también tienen la opción de volver a inyectarse en la versión C++ para la compilación. Las rutas de archivo de salida se añaden automáticamente ya que incluyen rutas tanto para la compilación de destino como las entradas de export_header.

Integración básica

En el archivo wscript para el destino que requiera código generado, añada la función az_code_gen como se indica a continuación.

features = ['az_code_gen'],

A continuación, especifique los archivos que desea transferir como entrada al generador de código, como en el siguiente ejemplo.

az_code_gen = [
    {
        'files' : ['MySourceFile.h'],
        'scripts' : ['MyTemplateDriver.py']
    }
],

Las rutas proporcionadas son relativas a la ruta de destino en ambos casos.

Siempre que se compila el objetivo especificado, una se pasa una tarea de generación de código en el archivo MySourceFile.h al generador de código. También invoca al archivo MyTemplateDriver.py para controlar la salida. Para obtener más información sobre cómo escribir un controlador de plantillas, consulte Controladores de plantilla.

Integración avanzada

La integración con Waf del AZ Code Generator utiliza pases para definir las tareas que el generador de código debe ejecutar durante el tiempo de compilación. Cada pase determina el conjunto de archivos, controladores y configuración del entorno para los que se ejecuta el generador de código. En la actualidad, todos los pases se ejecutan en paralelo sin comprobación de dependencias entre pases.

El siguiente ejemplo muestra la configuración de varios pases.

az_code_gen = [
    {
        'files' : ['MyCode/MySourceFile.h'],
        'scripts' : ['MyCode/MyTemplateDriver.py']
    },
    {
        'files' : ['MyOtherCode/MyOtherSourceFile.h'],
        'scripts' : ['MyOtherCode/MyOtherTemplateDriver.py']
    }
],

Este ejemplo genera las siguientes dos tareas de generación de código.

1. Pasar el archivo MyCode/MySourceFile.h al generador de código e invocar al archivo MyCode/MyTemplateDriver.py para controlar la salida.

2. Pasar MyOtherCode/MyOtherSourceFile.h al generador de código e invocar a MyOtherCode/MyOtherTemplateDriver.py para controlar la salida.

Archivos de entrada

Cada pase proporciona una lista de los archivos que se utilizarán como entrada para el generador de código. Esta lista también puede contener rutas de cadena, nodos y listas. Las rutas de cadenas de nivel superior y nodos se pasan individualmente al generador de código. Tenga en cuenta lo siguiente:

• Si proporciona una lista, el generador de código utiliza todos los archivos o nodos en dicha lista al mismo tiempo. Esto permite la máxima flexibilidad, pero el uso habitual es una entrada por tarea.

• La sobrecarga de la tarea de Waf y el proceso de arranque de AZ Code Generator puede ser importante. Para mejorar el desempeño, puede pasar varios archivos de entrada en una lista.

• El generador de código invoca la misma canalización de controlador de plantillas y Clang para cada archivo de entrada.

El siguiente ejemplo muestra varias especificaciones de archivos de entrada.

# Finds this file relative to the build context source node
'files' : [bld.srcnode.find_or_declare('Code/Framework/AzCore/Tests/CodeGen.h')],

'files' : [
# Pass both MyClass.h and MyClass.cpp at the same time to code generator to get more 
# information about MyClass than just the header. Note the nested lists.
    ['MyClass.h', 'MyClass.cpp'] 
]
 
'files' : [
    # Any and all variations are allowed, but because lists provide only one layer of grouping,
    # lists are allowed only at the top level.
    'MySourceFile.h',
    'MyOtherSourceFile.cpp',
    bld.srcnode.find_or_declare('Code/Framework/AzCore/Tests/CodeGen.h'),
    ['MyClass.h', 'MyClass.cpp']
]

Controladores de plantilla

Para especificar controladores de plantilla que utilizar para cada pase de generación de código, proporcione una lista de las rutas de cadena relativas a la ruta de destino, como en el siguiente ejemplo.

'scripts' : [
    '../../../Framework/AzFramework/CodeGen/AzClassCpp.py', 
    '../../../Framework/AzFramework/CodeGen/AzEBusInline.py', 
    '../../../Framework/AzFramework/CodeGen/AzReflectionCpp.py', 
    '../../../Framework/AzFramework/CodeGen/AzClassInline.py'
],

Parámetros de línea de comandos

Todos los parámetros de línea de comando para la utilidad de generación de código pueden especificarse en cada pase de generación de código. Para ello, proporcione una lista de argumentos, como en el siguiente ejemplo.

'arguments' : [
    '-OnlyRunDiagnosticsOnMainFile=true',
    '-SuppressDiagnostics=false',
    '-SuppressErrorsAsWarnings=false',
    '-output-redirection=file',
],

Para obtener una lista completa de los parámetros, consulte Parámetros de AZ Code Generator.

Opciones específicas de Waf

La integración de Waf proporciona opciones adicionales que se pueden especificar en una lista para cada pase de generación de código, como en el siguiente ejemplo.

'options' : ['PrintOutputRedirectionFile'],

PrintOutputRedirectionFile: esta opción, cuando se utiliza en combinación con el parámetro -output-redirection=file, pide a Waf que proporcione a AZ Code Generator una ruta para guardar la salida adicional durante la generación de código. La ruta a este archivo se indica para cada tarea durante la compilación si se producen errores.

Profile: esta opción habilita los tiempos del creador de perfiles de la ejecución de scripts y análisis de clang dentro de la herramienta Generator AZ Code.