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

Mandatory keys in a context are marked ‘(required)’, all other keys can be considered optional (most have default values). Special note boxes starting with ‘peer-keys’ indicate interactions of the current key with other configuration keys that should to be present in the job for the current key to function properly. E.g. the key compile-dist will use the peer-key cache in the job definition for its workings. Again, in many cases fall-back defaults will be in place, but relying on them might lead to sub-optimal results.

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.

(0.8.1)

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

 
"asset-let" :
{
  "<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

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}“ [0.8: “./cache”])
• downloads : directory where to put downloads (e.g. contrib:// libraries), relative to the current (default: “${CACHE}/downloads” [0.8: “./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 (default: “horizontal”)

(0.8.1+)

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

 
"compile-dist" :
{
  "paths" :
  {
    "file"     : "<path>",
    "gzip"     : (true|false)
  },
  "uris" :
  {
    "script"   : "script",
    "resource" : "resource"
  },
  "code" :
  {
    "format"   : (true|false),
    "locales"  : ["de", "en"],
    "optimize" : ["variables", "basecalls", "privates", "strings"]
  }
}

Output Javascript file(s) are generated into dirname(<file>), with <file> being the primary file. Within the files, references to other script files are generated using the <script> URI prefix, references to resources will use a <resource> URI prefix. If <file> is not given, the APPLICATION macro has to be set in the global let section with a proper name, in order to determine a default output file name.

Possible keys are

• paths : paths for the generated output
  • file : the path to the compile output file (default: “build/script/<appname>.js”)
  • gzip : whether to gzip output file(s) (default: false)
• uris : URIs used to reference code and resources
  • script : URI from application root to code directory (default: “script”)
  • resource : URI from application root to resource directory (default: “resource”)
• code : code options
  • format : whether to apply simple output formatting (it adds some sensible line breaks to the output code) (default: false)
  • locales : a list of locales to include (default: [”C”])
  • optimize : list of dimensions for optimization, max. ‘[”variables”, “basecalls”, “privates”, “strings”]’ (default: []) special section

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

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

Possible keys are

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

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.

(with 0.8.3+ the features of this key have been merged into the log key)

Allows you to debug certain aspects of the application (through specific logging). Takes a map.

 
"debug" : 
{
  "privates"      : ("on"|"off"),
  "dependencies"  : ("on"|"off")
}

• privates : print out list of classes that use a specific private member
• dependencies : print out list of classes that depend on a specific class; this only works together with the -v (verbose) command line switch of the generator

(since 0.8.3)

Allows you to influence the way class dependencies are processed by the generator. Takes a map.

 
"dependencies" : 
{
  "follow-static-initializers"  : (true|false),
  "sort-topological"            : (true|false)
}

• follow-static-initializers (experimental!): Try to resolve dependencies introduced in class definitions when calling static methods to initialize map keys (default: false).
• sort-topological (experimental!): Sort the classes using a topological sorting of the load-time dependency graph (default: false).

Provides some descriptive text for the job.

 
"desc" : "Some text."

The descriptive string provided here will be used when listing jobs on the command line. (Be aware since this is a normal job key it will be passed on through job inheritance, so when you look at a specific job in the job listing you might see the job description of some ancestor job).

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

 
"exclude" : ["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. excluded from the generated Javascript.

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

Fix white space in Javascript class files. Takes a map.

 
"fix-files" : {}

fix-files will normalize white space in source code, by removing trailing white space in lines, and unifying the line end character (to the Unix line end character). Since there are currently no sub-keys, the argument map has to be empty.

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. (0.8.1): A single entry can also be a map of the form {”name”: <jobname>, “as”: <alias>}, so you can import individual jobs under a different name.
• 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 [0.8.1: optional]) : 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

Check Javscript source code with a lint-like utility. Takes a map.

 
"lint-check" :
{
  "allowed-globals" : [ "qx", "qxsettings", "qxvariants", "${APPLICATION}" ]
}

Keys are:

• allowed-globals : list of names that are not to be reported as bad use of globals

Configure log/reporting features. Takes a map.

 
"log" :
{
  "classes-unused" : [ "custom.*", "qx.util.*" ],
  "privates"       : ("on"|"off"),
  "dependencies"   : 
  {
    "type"         : ("using"|"used-by"),
    "using"        :
    {
      "phase"      : ("runtime"|"loadtime")
    },
    "format"       : ("txt"|"dot"|"json"|"flare"),
    "dot"          :
    {
      "root"           : "custom.Application",
      "file"           : "<filename>",
      "radius"         : 5,
      "span-tree-only" : (true|false),
      "compiled-class-size" : (true|false),
      "optimize"   : [<optimize-keys>]
    },
    "json"         :
    {
      "file"       : "<filename>",
      "pretty"     : (true|false)
    },
    "flare"        :
    {
      "file"       : "<filename>",
      "pretty"     : (true|false)
    }
  }
}

This key allows you to enable logging features along various axes.

• classes-unused : Report unused classes for the name space patterns given in the list.
• privates (0.8.3+): print out list of classes that use a specific private member
• dependencies (0.8.3+): print out dependency relations of classes
  • type (required): which kind of dependencies to log
    • using: dependencies of the current class to other classes; uses the using key; supports txt, dot, json and flare output formats
    • used-by: dependencies of other classes to the current class; supports only txt format
  • using :
    • phase : limit logging to runtime or loadtime dependencies
  • format : format of the dependency output (default: txt)
    • txt: textual output to the console
    • dot: generation of a Graphviz dot file; uses the dot key
    • json: “native” Json data structure (reflecting the hierarchy of the txt output class → [run|load]); uses the json key
    • flare: Json output suitable for Prefuse Flare depencency graphs; uses the flare key
  • dot:
    • span-tree-only: only create the spanning tree from the root node, rather than the full dependency graph; reduces graph complexity by limiting incoming edges to one (i.e. for all classes at most one arrow pointing to them will be shown), even if more dependency relations exist
    • root : the root class for the dot format output; only dependencies starting off of this class are included
    • file : output file path (default deps.dot)
    • radius : include only nodes that are within the given radius (or graph distance) to the root node
    • compiled-class-size : use compiled class size to highlight graph nodes, rather than source file sizes; if true classes might have to be compiled to determine their compiled size, which could cause the log job to run longer (default true)
    • optimize : if compiled-class-size is true, provide optimization settings here so classes are compiled with the correct optimizations; see compile-dist/code/optimize for possible values (default [])
  • json:
    • file : output file path (default deps.json)
    • pretty : produce formatted Json, with spaces and indentation; if false produce compact format (default: false)
  • flare:
    • file : output file path (default flare.json)
    • pretty : produce formatted Json, with spaces and indentation; if false produce compact format (default: false)

Special section.

Migrate source files to current qooxdoo version. Takes a map.

 
"migrate-files" :
{
   "from-version" : "0.7",
   "migrate-html" : false
}

This key will invoke the mechanical migration tool of qooxdoo, which will run through the class files an apply successive sequences of patches and replacements to them. This allows to apply migration steps automatically to an existing qooxdoo application, to make it better comply with the current SDK version (the version the key is run in). Mind that you might have to do further adaptions by hand after the automatic migration has run. The migration tool itself is interactive and allows entering migration parameters by hand.

• from-version : qooxdoo version of the code before migration
• migrate-html : whether to patch .html files in the application (e.g. the index.html)

(0.8.1+)

Define packages for this app. Takes a map.

 
"packages" :
{
  "parts"    : 
  {
    "<part_name>" : [ "app.class1", "app.class2", "app.class3.*" ]
  },
  "sizes"    : 
  {
    "min-package" : 1,
    "min-package-unshared" : 1
  },
  "init"             : "<part_name>",
  "loader-with-boot" : (true|false),
  "collapse"         : [ "<part_name1>", "<part_name2>" ]
}

Keys are

• parts : map of part names and their lists of root classes, e.g.
  • <part_name> : [”app.class1”, “app.class2”, “app.class3.*”]
• sizes : size constraints on packages
  • min-package : minimal size of a package in KB (default: 0)
  • min-package-unshared : minimal size of an unshared package in KB (default: <min-package>)
• init : name of the initial part, i.e. the part to be loaded first (default: “boot”)
• loader-with-boot (0.8.3+): whether loader information should be included with the boot part, or be separate; if set false, the loader package will contain no class code (default: true)
• 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

Define packages for this app. Takes a map.

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

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 (default: “boot”)
• size : minimal size of a package in KB (default: 0)
• 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"        : "  "
  },
  "comments" :
  {
    "trailing" :
    {
      "keep-column"        : false,
      "comment-cols"       : [50, 70, 90],
      "padding"            : "  "
    }
  },
  "blocks" :
  {
    "align-with-curlies"   : false,
    "open-curly" :
    {
      "newline-before"     : "m",
      "indent-before"      : false
    }
  }
}

Keys are:

• general : General settings.
  • indent-string : “<whitespace_string>”, e.g. “\t” for tab (default: " " (2spaces))
• 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 (default: false)
    • comment-cols : [n1, n2, ..., nN] Column positions to start trailing comments at, e.g. [50, 70, 90] (default: [])
    • padding : “<whitespace_string>” White space to be inserted after statement end and beginning of comment (default: " " (2spaces))
• 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 (default: false)
  • 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) depending on block complexity (default: “m”)
    • indent-before : (true|false) Whether to indent the opening curly if it is on a new line (default: false)

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.

(0.8)

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 current 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”]’)