The configuration file that drives the generator adheres to the JSON specification. It has the following general structure:

{
  "jobs" :
  {
    "job1" : { ... },
    "job2" : { ... },
    ...
    "jobN" : { ... }
  }
}

The job names job1, ..., jobN are freely chooseable but must form a valid key. JavaScript-style comments (/*...*/ and //...) are permissible but only in rather robust places, like after a comma or directly after opening or before closing parentheses, but e.g. not between a key and its value.

Quick links:

• Reference Listing of Config Keys
• Configuration Detail Articles

Here is an example of a minimal config file that defines a single job to create the source version of an application:

{
  "jobs" :
  {
    "source" : 
    {
      "let" :
      [
        [ "QOOXDOO_PATH" , "../.." ],
        [ "QOOXDOO_URI"  , "${QOOXDOO_PATH}/.." ],
        [ "APPLICATION_NAMESPACE" , "custom" ]
      ],
 
      "library" :
      [
        {
          "encoding" : "utf-8",
          "path"     : "${QOOXDOO_PATH}/framework/source",
          "uri"      : "${QOOXDOO_URI}/framework/source"
        },
 
        {
          "encoding" : "utf-8",
          "path"     : "./source",
          "uri"      : "../source"
        }
      ],
 
      "script" :
      {
        "file" : "./source/script/${APPLICATION_NAMESPACE}.js"
      },
 
      "require" :
      {
        "qx.log.Logger" : ["qx.log.appender.Native"]
      },
 
      "settings" : 
      {
        "qx.application" : "${APPLICATION_NAMESPACE}.Application",
        "qx.resourceUri" : "${QOOXDOO_URI}/framework/source/resource"
      },
 
      "cache" :
      {
        "path" : "../../cache2"
      }
    }
  }
}
 

The value of each job is a map where the keys are not freely chooseable, but are predefined.

Keys can be grouped into several categories:

• structure-changing - Keys that influence the configuration itself, e.g. the contents or structure of jobs, the job queue, or the config file as a whole (e.g. extend, include (top-level), run).
• actions - Keys that if present trigger a certain action in the generator, which usually results in some output (e.g. compile-source, api, localize).
• input/output-setting - Keys that specify input (e.g. classes or ranges of classes to deal with) and output (e.g. packaging, variants) options (e.g. library, require, include).
• runtime-settings - Keys pertaining to the working needs of the generator (e.g. chache).

First, here is an overview table, to list all possible keys in a job (unless otherwise noted). Below that you’ll find a structured listing of all possible configuration keys in their respective context, with links to further information for each key.

This shows the complete possible contents of the top-level configuration map. Further information is linked from the respective keys.

• include
  Include external config files. Takes a list of maps, where each map specifies an external configuration file, and options how to include it. (See special section on the include key)

• let
  Define default macros. Takes a map (see the description of the job-level ‘let’ further down). This let map is included automatically into every job run. There is no explicit reference to it, so be aware of side effects.

• export
  List of jobs to be exported if this config file is included by another.

• jobs
  Map of jobs. Each key is the name of a job, each job’s value is a map describing the job. The describing map can have any number of the following keys:
  • api
    Triggers the generation of a custom Apiviewer application.
  • cache
    Define the path to cache directories, most importantly to the compile cache. (See special section on the cache_key key).
  • clean-files
    Triggers clean-up of files and directories within a project and the framework, e.g. deletion of generated files, cache contents, etc. [TODOC]
  • combine-images
    Triggers creation of a combined image file that contains various images.
  • compile-dist
    Triggers the generation of the build version of the application.
  • compile-source
    Triggers generation of the source version of the application.
  • copy-files
    Triggers files/directories to be copied, usually between source and build version.
  • copy-resources
    Triggers the copying of resources, usually between source and build version.
  • extend
    Extend the current job with other jobs. Takes an array of job names. The information of these jobs are merged into the current job description, so the current job sort of “inherits” their settings. (See the special section on "extend" semantics).
  • include
    List classes to be processed in the job. Takes an array of class specifiers.
  • let
    Define macros. Takes a map where each key defines a macro and the value its expansion. (See the special section on macros).
  • library
    Define libraries to be taken into account for this job. Takes an array of maps, each map specifying one library to consider. The most important part therein is the “manifest” specification. (See special section on Manifest files).
  • packages
    Define packages for the application. (See special section on packages).
  • pretty-print
    Triggers code beautification of source class files (in-place-editing). An empty map value triggers default formatting, but further keys can tailor the output.
  • require
    Define prerequisite classes. Takes a map, where the keys are class names and the values lists of prerequisite classes.
  • run
    Define a list of jobs to run in place of the current job. (See the special section on "run" semantics).
  • settings
    Define qooxdoo settings for the generated application.
  • shell
    Triggers the execution of an external command.
  • slice-images
    Triggers cutting images into regions.
  • themes
    Defines theme keys that will be replaced in #asset hints in source files. (See special section on the "themes" key).
  • translate
    (Re-)generate .po files from source classes.
  • variants
    Define variants for the generated application.