This page contains the complete list of configuration keys and their sub-structures.

Mandatory keys in a context are marked ‘(required)’. Special note boxes starting with ‘required keys’ indicate dependencies for the current key in the form of other peer-keys that have to be present in the job for the current key to function properly. E.g. the key compile-dist has a mandatory sub-key file, but also depends on the peer-key cache being present in the job (sorry for this double use of the term “required” on two different axes).

Triggers the generation of a custom Apiviewer application. Takes a map.

 
"api" :
{
  "path" : "<path>"
}

• path (required) : Path where the Apiviewer application is to be stored, relative to the current directory.

Define the paths to cache directories, particularly to the compile cache. Takes a map.

 
"cache" :
{
  "compile"     : "<path>",
  "downloads" : "<path>"
}

Possible keys are

• compile : path to the “main” cache, the directory where compile results are cached, relative to the current (default: “./cache”)
• downloads : directory where to put downloads (e.g. contrib:// libraries), relative to the current (default: “./cache-downloads”)

Special section

Triggers clean-up of files and directories within a project and the framework, e.g. deletion of generated files, cache contents, etc. Takes a map.

 
"clean-files" :
{
  "<doc_string>" :
  [
    "<path>",
    "<path>"
  ]
}

Each key is a doc string that will be used in logging when deleting the corresponding files.

• <doc_string> : arbitrary string
• <path> : file/path to be deleted; may be relative to config file location

Triggers the creation of a combined image file that contains various images. Takes a map.

 
"combine-images" :
{
  "images" :
  {
    "<output_image>" :
    {
        "input" : [ "<path>", "<path>" ],
        "layout": ("horizontal"|"vertical")
    }
  }
}

• images : map with combine entries
• <output_image> : path of output file; may be relative to the config file location
• input (required): lists the input image files (file globs allowed); may be relative to config file location
• layout : either “horizontal” or “vertical”; defines the layout of images within the combined image

Triggers the generation of the build version of the app. Takes a map.

 
"compile-dist" :
{
  "file" : "<path>",
  "root" : "<path_to_html_dir>",
  "uri"  : "<from_html_to_output>",
  "gzip" : (true|false),
  "optimize"    : ["variables", "basecalls", "privates", "strings"],
  "resourceUri" : "<path_from_html_to_root>",
  "locales" : ["de", "en"],
  "format"      : ("on"|"off")
}

Possible keys are

• file (required) : the path to the compile output file, may be relative to config file location
• root (required) : relative path to the directory containing the app’s HTML
• uri : the path to the output file(s), relative to the application’s index.html
• gzip : “true” or “false”
• optimize : list of dimensions for optimization, max. ‘[”variables”, “basecalls”, “privates”, “strings”]’
• resourceUri : relative path from html file to root of resource tree
• locales : a list of locales to include (default: [”C”])
• format : “on”/”off”, for simple output formatting (it adds some sensible line breaks to the output code)

Triggers generation of the source version of the application. Takes a map.

 
"compile-source" :
{
  "file" : "<filepath>",
  "root" : "<path_to_html_dir>",
  "locales" : ["de", "en"],
  "gzip" : (true|false)
}

Possible keys are

• file (required): path to the source output file, may be relative to the config file location
• root (required): relative (in the above sense) path to the directory containing the app’s HTML.
• locales : a list of locales to include (default: [”C”])
• gzip : whether to gzip the output file, “true” or “false”.

Triggers files/directories to be copied. Takes a map.

 
"copy-files" :
{
  "files"     : [ "<path>", "<path>" ],
  "source" : "<path>",
  "target"  : "<path>"
}

Possible keys are

• files (required) : an array of files/directories to copy; entries will be interpreted relative to the source key value
• source : root directory to copy from; may be relative to config file location (default: “source”)
• target : root directory to copy to; may be relative to config file location (default: “build”)

Triggers the copying of resources. Takes a map.

 
"copy-resources" :
{
  "target" : "<path>"
}

Possible keys are

• target : root target directory to copy resources to; may be relative to the config file location (default: “build”)

Unlike copy-files, copy-resources does not take either a “source” key, nor a “files” key. Rather, a bit of implicit knowledge is applied. Resources will be copied from the involved libraries’ source/resource directories (this obviates a “source” key). The list of needed resources is derived from the class files (e.g. from #asset hints - this obviates the “files” key), and then the libraries are searched for in order. From the first library that provides a certain resource, this resource is copied to the target folder. This way you can use most resources from a standard library (like the qooxdoo framework library), but still “shaddow” a few of them by resources of the same path from a different library, just by tweaking the order in which these libraries are listed in the library key.

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

 
"export" : ["job1", "job2", "job3"]

Extend the current job with other jobs. Takes an array of job names.

 
"extend" : [ "job1", "job2", "job3" ]

The information of these (previously defined) jobs are merged into the current job description. Keys and their values missing in the current description are added, existing keys take precedence and are retained (with some keys that are merged).

Special section

Include classes to be processed in the job. Takes an array of class specifiers.

 
"include" : ["qx.util.*"]

The class specifiers can include simple wildcards like ‘qx.util.*’ denoting a whole set of classes. A leading ‘=’ in front of a class specifier means ‘without dependencies’ (like ‘=qx.util.*’). These classes are e.g. included in generated Javascript.

Include external config files. Takes a list of maps.

 
"include" : 
[
    {
       "path" : "<path>",
       "as"    : "<name>",
       "import" : ["extjob1", "extjob2", "extjob3"],
       "block"   : ["extjob4", "extjob5"]
    }
]

Within each specifying map, you can specify

• path (required): Path string to the external config file which is interpreted relative to the current config file
• as : Identifier that will be used to prefix the external job names on import; without it, job names will be imported as they are.
• import : List of job names to import; this list will be intersected with the export list of the external config, and the resulting list of jobs will be included.
• block : List of job names to block during import; this is the opposite of the import key and allows you to block certain jobs from being imported (helpful if you want to import most but not all of the jobs offered by the external configuration).

Special section

Define jobs for the generator. Takes a map.

 
"jobs" :
{
  "<job_name>" : { <job_definition> }
}

Job definitions can take a lot of the predefined keys that are listed on this page (see the overview to get a comprehensive list). The can hold “actions” (keys that cause the generator to perform some action), or just settings (which makes them purely declarative). The latter case is only useful if those jobs are included by others (through the extend key, and thus hold settings that are used by several jobs (thereby saving you from typing).

Define macros. Takes a map.

 
"let" :
{
  "<macro_name>"  : "<string>",
  "<macro_name1>" : [ ... ],
  "<macro_name2>" : { ... }
}

Each key defines a macro and the value of its expansion. The expansion may contain references to previously defined macros (but no recursive references). References are denoted by enclosing the macro name with ${...} and can only be used in strings. If the value of the macro is a string, references to it can be embedded in other strings (e.g. like “/home/${user}/profile”); if the value is a structured expression, like an array or map, references to it must fill the entire string (e.g. like “${MyList}”).

• <macro_name> : The name of the macro.

Special section

Define default macros. Takes a map (see the other 'let'). Everything of the normal ‘let’ applies here, except that this let map is included automatically into every job run. There is no explicit reference to it, so be aware of side effects.

Define libraries to be taken into account for this job. Takes an array of maps.

 
"library" :
{
  "manifest"   : "<path>",
  "uri"        : "<from_html_to_manifest_dir>",
  "namespace"  : "<string>"
}

Each map can contain the keys

• manifest (required) : path to the “Manifest” file of the library; may be relative to config file location; may use contrib:// scheme
• uri (required) : URI prefix from your HTML file to the directory of the library’s “Manifest” file
• namespace : alternative name space string, which takes precedence of the one provided by the library’s “Manifest” file.

Special section

Configure log/reporting features. Takes a map.

 
"log" :
{
  "classes-unused" : [ "custom.*", "qx.util.*" ]
}

This key allows you to tailor log output during generator runs along various axes.

• classes-unused : Report unused classes for the name space patterns given in the list.

Special section.

Define packages for this app. Takes a map.

 
"packages" :
{
  "parts"    : 
  {
    "<part_name>" : [ "app.class1", "app.class2", "app.class3.*" ]
  },
  "init"     : "app.class1",
  "size"     : 1,
  "collapse" : [ "app.class1", "app.class3.*" ]
}

Keys are

• parts : map of part names and their lists of root classes, e.g.
• <part_name> : [”app.class1”, “app.class2”, “app.class3.*”]
• init : name of the initial part, i.e. the part to be loaded first
• size : minimal size of a package in MB
• collapse : list of parts to collapse into a single package; this “collapsed” package will automatically be the initial package and will contain the part optionally specified with init.

Special section

Triggers code beautification of source class files (in-place-editing). An empty map value triggers default formatting, but further keys can tailor the output.

 
"pretty-print" : 
{
  "general" :
  {
    "indent-string"            : "\t"
  },
  "comments" :
  {
    "trailing" :
    {
      "keep-column"         : true,
      "comment-cols"       : [50, 70, 90],
      "padding"                : "  "
    }
  },
  "blocks" :
  {
    "align-with-curlies"     : true,
    "open-curly" :
    {
      "newline-before"      : "m",
      "indent-before"        : true
    }
  }
}

• general : General settings.
• indent-string : “<whitespace_string>”, e.g. “\t” for tab
• comments : Settings for pretty-printing comments.
• trailing : Settings for pretty-printing line-end (”trailing”) comments (”// ...”).
• keep-column : (true|false) Tries to fix the column of the trailing comments to the value in the original source.
• comment-cols : [n1, n2, ..., nN] Column positions to start trailing comments at, e.g. “[50, 70, 90]”.
• padding : “<whitespace_string>” White space to be inserted after statement end and beginning of comment.
• blocks : Settings for pretty-printing code blocks.
• align-with-curlies : (true|false) Whether to put a block at the same column as the surrounding/ending curly bracket.
• open-curly : Settings for the opening curly brace ‘{’.
• newline-before : “(a|A|n|N|m|M)” Whether to insert a line break before the opening curly always (aA), never (nN) or mixed (mM - default) depending on block complexity.
• indent-before : (true|false) Whether to indent the opening curly

Define prerequisite classes. Takes a map.

 
"require" :
{
  "<class_name>" : [ "qx.util", "qx.fx" ]
}

Each key is a

• <class_name> : each value is an array of required classes for this class.

Define a list of jobs to run. Takes an array of job names.

 
"run" : [ "<job1>", "<job2>", "<job3>" ]

These jobs will all be run in place of the defining job (which is sort of a ‘meta-job’). All further settings in the defining job will be inherited by the listed jobs (so be careful of side effects).

Special section

Define qooxdoo settings. Takes a map.

 
"settings" :
{
  "qx.application" : "myapp"
}

Possible keys are valid

• <qooxdoo_settings> : along with their desired values

Triggers the execution of an external command. Takes a map.

 
"shell" :
{
  "command" : "echo foo bar baz"
}

Possible keys are

• command : command string to execute by shell
  Note: Generally, the command string is passed to the executing shell “as is”, with one exception: Relative paths are absolutized, so you can run those jobs from remote directories. In order to achieve this, all strings of the command are searched for path separators (e.g. ‘/’ on Posix systems, ‘\’ on Windows, etc.). Those strings are regarded as paths and - unless they are already absolute - are absolutized, relative to the path of the current config. So instead of writing

  "cp file1 file2"

  you should write

  "cp ./file1 ./file2"

  and it will work from everywhere.

Triggers cutting images into regions. Takes a map.

 
"slice-images" :
{
  "images" : 
  {
    "<input_image>" :
    {
        "prefix"       : "<string>",
        "border-width" : 5
    }
  }
}

• images : map with slice entries.
• <input_image> : path to input file for the slicing; may be relative to config file location
• prefix (required) : file name prefix used for the output files; will be interpreted relative to the input file location (so a plain name will result in output files in the same directory, but you can also navigate away with ../../.... etc.)
• border-width : pixel width to cut into original image when slicing borders etc.

Defines theme keys that will be replaced in #asset hints. Takes a map.

 
"themes" :
{
  "<macro_name>" : [ "foo", "bar", "baz" ]
}

Each entry is

• <macro_name> : [<list of replacement strings>] Like with macros, references (through ‘${macro_name}’) to these keys in #asset hints in source files will be replaced. Unlike macros, each listed value will be used, and the result is the list of all ensuing expressions, so that all resulting assets will be honored.

Special section

(Re-)generate the .po files (usually located in source/translation) from source classes. Takes a map. The source classes of the specified name space are scanned for translatable strings. Those strings are extracted and put into map files (.po files), one for each language. Those .po files can then be edited to contain the proper translations of the source strings. For a new locale, a new file will be generated. For existing .po files, re-running the job will add and remove entries as appropriate, but otherwise keep existing translations.

 
"translate" :
{
  "namespaces" : [ "qx.util" ],
  "locales"        : [ "en", "de" ]
}

• namespaces (required) : List of name spaces for which .po files should be updated.
• locales : List of locale identifiers to update.

Define variants for the curren app. Takes a map.

 
"variants" :
{
  "qx.debug" : [ "on" , "off" ]
}

Possible keys are valid

• <qooxdoo_variants> : (e.g. “qx.debug”), with a list of their desired values (e.g. ‘[”off”]’)