.. _pages/tool/generator/generator#generator_overview: Generator Overview ****************** This is a high-level overview of some important generator features. There is also a more comprehensive :doc:`feature overview `. Quick links: * :doc:`generator_usage` * :doc:`Configuration file details ` .. _pages/tool/generator/generator#configuration: Configuration ============= * Load project configuration from JSON data file * Each configuration can define multiple so named jobs * Each job defines one action with all configuration * A job can extend any other job and finetune the configuration * Each execution of the generator can execute multiple of these jobs .. _pages/tool/generator/generator#cache_support: Cache Support ============= * Advanced caching system which dramatically reduces the runtime in repeated calls. * The cache stores data on the disk using the ``pickle`` Python module. * Invalidation of cache files happens through a comparison of modification dates. * Cache filenames use hash keys to keep them short and unique. * Among the information which is being cached by the generator there are * class meta data * syntax trees * code dependencies * compiler results * api data * localization data .. _pages/tool/generator/generator#class_selection: Class Selection =============== * Use include/exclude lists to define the set of classes to use. * Allows simple wildcards, e.g. ``qx.*``. * By default, prerequisite classes are added to the class set, except those specified by an exclude. * This can be toggled using a ``=`` prefix. This switches to a mode where exactly the classes listed in the config are included. * As a fallback all known classes will be added when no includes are defined. .. _pages/tool/generator/generator#variants: Variants ======== * From a single code base multiple variants can be created. * This is controlled by *environment* variables, the values of which can be queried in the code. * Given a set of environment bindings, code parts that are never executed as a consequence, can be pruned from the final application, saving code size. * It is possible to generate multiple variant combinations. This means that a single job execution can create multiple files at once using different sets of environment bindings ("variant sets"). * Variants are combinable and all possible combinations are automatically created. For example: gecko+debug, mshtml+debug, gecko+nodebug, mshtml+nodebug. .. _pages/tool/generator/generator#api_data: API Data ======== * Creation of split API data which loads incrementally as needed. * Creation of a searchable index containing all relevant names of the API (e.g. classes, properties, functions, events, ...) .. _pages/tool/generator/generator#internationalisation: Internationalisation ==================== * Creation and update of "po" files based on marked strings in the class files. * Inclusion of translation information in the generated application. * Dynamic creation of localization data based on the standardized information available at unicode.org. The "main" package of CLDR which is used, is locally mirrored in the SDK. .. _pages/tool/generator/generator#parts: Parts ===== * Each part can be seen as a logical or visual component of the application. * Each part may result in multiple packages (script output files). * The number of packages could be exponential to the number of parts (but through the optimization this is often not the case). * Packages are merged given some constraints (e.g. minimal size), to reduce their overall number. * The parts are defined in the application configuration, using a similar include key like the class selection. * There is one signified initial part, named 'boot', that is loaded automatically at application startup, and contains the initial set of functionality. * Other parts are loaded explicitly by the application code, using a specific ``PartLoader`` API of the framework.