Lumberyard
Guía del usuario (Version 1.21)

Controladores de plantilla

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

Los controladores de plantillas son scripts de Python que procesan los datos JSON intermedios y los enrutan a las plantillas de salida de Jinja2. Los scripts preprocesan los datos del front-end de Clang, ejecutan la representación de la plantilla y controlan dónde se graba en el disco la salida generada.

Estos scripts suelen ser convocados por una o más pases de generación de código en archivos wscript de WAF. Cada script de Python puede hacer referencia a varias plantillas. Esto ofrece una gran flexibilidad en la implementación, especialmente cuando varias plantillas confían en los mismos datos preprocesados. 

Especificación de controladores en Waf

Los controladores se especifican por nombre de archivo en cada pase de generación de código. La ruta de archivo es relativa a la raíz del destino wscript. Todos los controladores se invocan en cada archivo de entrada.

A continuación, se muestra la estructura de una entrada Waf de ejemplo.

'az_code_gen' = [ { 'files': [ <files to gen> ], 'scripts': [ <list of script file paths relative to current wscript folder> ] } ]

Para obtener más información sobre cómo especificar los pases, consulte Integración de AZ Code Generator con Waf .

Creación de un controlador de plantillas en Python

Para crear un controlador de plantillas en Python, debe importar la clase de base TemplateDriver y anular sus métodos. El código de la clase puede encontrarse en el archivo dev/Code/Tools/AzCodeGenerator/Scripts/az_code_gen/base.py.

AZ Code Generator inyecta automáticamente esta clase en Python y solo tiene que importarse como az_code_gen.base, como en el siguiente ejemplo.

from az_code_gen.base import *

Métodos de anulación en la clase TemplateDriver

Para implementar su controlador de plantillas, anule los siguientes métodos en la clase TemplateDriver.

add_dependency

Llame al método add_dependency para añadir manualmente una dependencia a la tarea az_code_gen en Waf. La ruta de archivo proporcionada debe ser absoluta para que la plantilla de representación pueda especificar las dependencias adicionales que Waf no incluye automáticamente. Estas dependencias pueden ser archivos de datos externos utilizados para representar las plantillas o archivos que se utilizaron para generar los datos de entrada.

Sintaxis

add_dependency(self, dependency_file)

apply_transformations

Anule el método apply_transformations para manipular el objeto JSON sin procesar, que se transfiere como el parámetro obj. Las manipulaciones se realizan en el lugar sobre el objeto. El objeto se reenvía a continuación por la canalización y se transfiere finalmente a jinja_args de render_templates. Cualquier objeto devuelto por este método se proporciona al entorno Jinja como extra_data.

Sintaxis

apply_transformations(self, obj)

Para ver un ejemplo de este método, consulte Preprocesamiento de datos intermedios.

get_expected_tags

Anule el método get_expected_tags para que devuelva una lista de las etiquetas que deben encontrarse en cualquier archivo inicial. Si las etiquetas requeridas no están presentes, este controlador se omitirá.

importante

Este método dejará de utilizarse a partir de Lumberyard v1.6. Después de Lumberyard v1.6, todos los scripts se procesarán independientemente de las etiquetas esperadas y get_expected_tags no se invocará.

Sintaxis

get_expected_tags(self)

render_template_to_file

Representa una plantilla en el disco. Este método también añade el valor de output_file que una dependencia de la tarea az_code_gen en Waf.

Sintaxis

render_template_to_file(self, template_file, template_kwargs, output_file, should_add_to_build=False)

Parámetros

Parámetro Descripción
template_file Especifica la ruta a una plantilla en relación con el directorio que contiene el archivo .py del controlador de plantillas.
template_kwargs Especifica un diccionario de pares clave–valor que se transferirá a Jinja. Por lo general, debería tratarse como una variable para el jinja_args dado a render_templates, pero puede proporcionar más pares clave–valor.
output_file Especifica el archivo de destino de la salida Jinja representada. La ruta es relativa a la carpeta de salida de destino.
should_add_to_build Un valor booleano que especifica si Waf debe añadir este archivo a la compilación y vinculador C++. El valor predeterminado es false.

render_templates

Anule render_templates para invocar la representación de plantillas llamando a render_template_to_file.

Sintaxis

render_templates(self, input_file, **jinja_args)

Parámetros

Parámetro Descripción
input_file La ruta en relación con la ruta de entrada que se utiliza para invocar a Clang.
jinja_args Los datos sin procesar en el objeto JSON intermedio después de que el controlador de plantillas realice el procesamiento previo en el objeto.

Controlador mínimo de plantillas

El código mínimo necesario para un controlador de plantillas se obtiene de la clase de base TemplateDriver e implementar una función de fábrica para construir el controlador de plantillas.

from az_code_gen.base import * class MyTemplateDriver(TemplateDriver): pass # Factory function - called from launcher def create_drivers(env): return [MyTemplateDriver(env)]

AZ Code Generator proporciona automáticamente el módulo az_code_gen. Contiene TemplateDriver y otros métodos útiles desde el archivo base.py.

La función create_drivers simplemente reenvía el entorno Jinja que se utiliza para representar plantillas. Sin embargo, puede modificar la función para realizar otros trabajos cuando el controlador está instanciado.

nota

La implementación esquelética anterior funciona, pero no genera ninguna salida.

Plantillas de representación

Para generar una salida, debe implementar el método render_templates, como en el siguiente ejemplo.

from az_code_gen.base import * class MyTemplateDriver(TemplateDriver): def render_templates(self, input_file, **jinja_args): self.render_template_to_file("MyTemplate.tpl", jinja_args, 'GeneratedCode.cpp') # Factory function - called from launcher def create_drivers(env): return [MyTemplateDriver(env)]

El método render_templates toma la ruta relativa de input_file y cualquier argumento que se transfiera desde la utilidad AZCodeGenerator.exe. La ruta input_file contiene normalmente entradas como el json_object intermedio creado por Clang.

Los controladores de plantillas pueden ampliar esta información mediante la implementación del método apply_transformations. Para obtener más información, consulte Preprocesamiento de datos intermedios.

El método render_template_to_file tiene un archivo de plantilla y pares clave–valor de argumento para pasar al motor de plantillas directamente y una ruta de salida para escribir la salida de representación del motor de plantillas en el disco.

Configuración de inyección de compilación automática

En este momento, el ejemplo genera un archivo .cpp mínimo. El ejemplo anterior no compila o vincula el archivo .cpp. Esto resulta adecuado si desea incluir el código generado manualmente utilizando un #include en otro archivo.

Para inyectar el archivo generado de forma automática, añada el parámetro should_add_to_build al método render_template_to_file y pase al parámetro el valor de true. El parámetro should_add_to_build informa a Waf de que el archivo generado necesita compilarse y vincularse en el destino actual.

Nota

El parámetro should_add_to_build no se recomienda para archivos de encabezado u otros archivos generados que no sean código C++ que deban compilarse y vincularse.

El siguiente ejemplo muestra algunas salidas inyectadas por compilación.

from az_code_gen.base import * class MyTemplateDriver(TemplateDriver): def render_templates(self, input_file, **jinja_args): self.render_template_to_file("MyTemplate.tpl", jinja_args, 'GeneratedCode.cpp', should_add_to_build=True) # Factory function - called from launcher def create_drivers(env): return [MyTemplateDriver(env)]

Preprocesamiento de datos intermedios

Algunos casos requieren el procesamiento previo de los datos intermedios para una utilización más sencilla por el motor de plantillas. Para ello, implemente el método apply_transformations en su controlador de plantillas. Puede utilizar este método para acceder al objeto de datos JSON intermedio directamente antes de que se pase a render_templates. Ejemplo:

from az_code_gen.base import * class MyTemplateDriver(TemplateDriver): def render_templates(self, input_file, **jinja_args): self.render_template_to_file("MyTemplate.tpl", jinja_args, 'GeneratedCode.cpp') def apply_transformations(self, obj): obj['my_custom_data'] = 42 # Factory function - called from launcher def create_drivers(env): return [MyTemplateDriver(env)]

Para obtener información sobre el contenido de la variable obj, consulte Formato de datos JSON intermedio.