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 be present in the job for the current key to function properly. E.g. the key compile 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.
Add a pre-fabricated JS file to the application. Takes a list.
"add-script" :
[
{
"uri" : "<script-uri>"
}
]
Note
peer-keys: compile
Triggers the generation of a custom Apiviewer application. Takes a map.
"api" :
{
"path" : "<path>",
"verify" : [ "links" ]
}
Defines macros that will be replaced in #asset hints. Takes a map.
"asset-let" :
{
"<macro_name>" : [ "foo", "bar", "baz" ]
}
Each entry is
Define the paths to cache directories, particularly to the compile cache. Takes a map.
"cache" :
{
"compile" : "<path>",
"downloads" : "<path>",
"invalidate-on-tool-change" : (true|false)
}
Possible keys are
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>"
]
}
Note
peer-keys: cache
Each key is a doc string that will be used in logging when deleting the corresponding files.
Triggers the collection of information about the qooxdoo environment, and prints it to the console. Takes a map.
"collect-environment-info" : {}
Note
peer-keys: cache
This key currently takes no subkeys, but you still have to provide an empty map. The information collected includes the qooxdoo version, the Python version, the path to the cache, stats about the cache contents, whether the current application has been built, asf.
Triggers the creation of combined image files that contain various other images. Takes a map. This action key requires an external program (ImageMagic) to run successfully.
"combine-images" :
{
"images" :
{
"<output_image>" :
{
"prefix": [ "<string>", "<altstring>" ],
"layout": ("horizontal"|"vertical"),
"input" :
[
{
"prefix" : [ "<string>", "<altstring>" ],
"files" : [ "<path>", "<path>" ]
}
]
}
}
}
Note
peer-keys: cache
images : map with combine entries
<output_image> : path of output file; may be relative to the config file location
prefix (required): takes a list; the first element is a prefix of the path given in <output_image>, leading up to, but not including, the library name space of the output image; this prefix will be stripped from the ouput path, and will be replaced by an optional second element of this setting, to eventually obtain the image id of the output image;
layout : either "horizontal" or "vertical"; defines the layout of images within the combined image (default: "horizontal")
input (required): list of groups of input files, each group sharing the same prefix; each group consists of:
- prefix (required): takes a list; analogous to the prefix attribute of the ouput image, the first element of the setting will be stripped from the path of each input file, and replaced by an optional second element, to obtain the corresponding image id
- files : the list of input image files (file globs allowed); may be relative to config file location
The image id's of both the input and output files will be collected in an accompanying <output_name>.meta file, for later processing by the generator when creating source and build versions of the app. You may move these files around after creation, but you'll have to keep the combined image and its .meta file together in the same directory. At generation time, the generator will look for an accompanying .meta file for every image file it finds in a library. The combined image's image id will be refreshed from its current location relative to the library's resource path. But the clipped images (the images inside the combined image) will be registered under the image id's given in the .meta file (and for browser that don't support combined images, they'll have to be available on disk under this exact image id).
Triggers the generation of a source or build version of the app. Takes a map.
"compile" :
{
"type" : "(source|build)"
}
Note
peer-keys: compile-options, cache, include, library
Generate Javascript file(s) for the application that can be loaded in the browser. This includes an inital file that acts as a bootstrap/loader file, and possibly other JS files with class code, I18N files, asf. All necessary settings for the compile run are given in the compile-options key, so make sure this one is properly filled.
Possible keys are
Specify various options for compile (and other) keys. Takes a map.
"compile-options" :
{
"paths" :
{
"file" : "<path>",
"app-root" : "<path>",
"gzip" : (true|false),
"loader-template" : "<path>",
"scripts-add-hash": (true|false)
},
"uris" :
{
"script" : "script",
"resource" : "resource",
"add-nocache-param" : (true|false)
},
"code" :
{
"format" : (true|false),
"locales" : ["de", "en"],
"optimize" : ["variables", "basecalls", "privates", "strings"],
"decode-uris-plug" : "<path>"
}
}
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 (<type> refers to the compile/type, e.g. source or build)
Triggers files/directories to be copied. Takes a map.
"copy-files" :
{
"files" : [ "<path>", "<path>" ],
"source" : "<path>",
"target" : "<path>"
}
Note
peer-keys: cache
Possible keys are
Triggers the copying of resources. Takes a map.
"copy-resources" :
{
"target" : "<path>"
}
Possible keys are
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 "shadow" 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.
Default job to be run. Takes a string.
"default-job" : "source"
If this key is present in a configuration file, the named job will be run by default when no job argument is passed to the generator on the command line.
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)
}
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 from processing in the job. Takes an array of class specifiers.
"exclude" : ["qx.util.*"]
Classes specified through the exclude key are excluded from the job processing, e.g. from the generated build output. The class specifiers can include simple wildcards like "qx.util.*" denoting class id's matching this pattern, including sub-name spaces.
A leading '=' in front of a class specifier (like "=qx.util.*") means 'without dependencies'. That means the classes themselves are exempted, but their dependencies added in. Be aware that this requires that all dependencies have to be calculated upfront, including for those classes specified in this key, resulting in increased compile time and generator logging. It also means that the final class list might contain classes that are not used by any of the remaining classes. Usually, specifying classes without '=' is what you want.
List of jobs to be exported if this config file is included by another, or to the generator if it is an argument.
"export" : ["job1", "job2", "job3"]
Only exported jobs will be seen by importing config files. If the current configuration file is used as an argument to the generator (either implicitly or explicitly with -c), these are the jobs the generator will list with generate.py x, and only these jobs will be runnable with generate.py <jobname>.
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).
Fix white space in Javascript class files. Takes a map.
"fix-files" :
{
"eol-style" : "(LF|CR|CRLF)",
"tab-width" : 2
}
Note
peer-keys: library
fix-files will normalize white space in source code, by converting tabs to spaces, removing trailing white space in lines, and unifying the line end character sequence.
Possible keys are
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
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}").
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>"
}
]
Each map can contain the keys
Check Javscript source code with a lint-like utility. Takes a map.
"lint-check" :
{
"allowed-globals" : [ "qx", "qxsettings", "qxvariants", "${APPLICATION}" ]
}
Keys are:
Configure log/reporting features. Takes a map.
"log" :
{
"classes-unused" : [ "custom.*", "qx.util.*" ],
"privates" : ("on"|"off"),
"resources" :
{
"file" : "<filename>"
}
"filter" :
{
"debug" : [ "generator.code.PartBuilder.*" ]
},
"dependencies" :
{
"type" : ("using"|"used-by"),
"phase" : ("runtime"|"loadtime")
"format" : ("txt"|"dot"|"json"|"provider"|"flare"|"term"),
"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.
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.
Define packages for this app. Takes a map.
"packages" :
{
"parts" :
{
"<part_name>" :
{
"include" : [ "app.class1", "app.class2", "app.class3.*" ],
"expected-load-order" : 1
"no-merge-private-package" : (true|false)
}
},
"sizes" :
{
"min-package" : 1,
"min-package-unshared" : 1
},
"init" : "<part_name>",
"loader-with-boot" : (true|false),
"i18n-with-boot" : (true|false),
"additional-merge-constraints" : (true|false),
"verifier-bombs-on-error" : (true|false)
}
Keys are
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.
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.
Collects application classes, resources, translateable strings and dependency information in a specific directory structure, under the provider root directory. Takes a map.
"provider" :
{
"app-root" : "./provider",
"include" : ["${APPLICATION}.*"],
"exclude" : ["${APPLICATION}.test.*"]
}
Keys are:
Define prerequisite classes needed at load time. Takes a map.
"require" :
{
"<class_name>" : [ "qx.util", "qx.fx" ]
}
Each key is a
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).
Define qooxdoo settings. Takes a map.
"settings" :
{
"qx.application" : "myapp"
}
Possible keys are valid
Triggers the execution of external commands. Takes a map.
"shell" :
{
"command" : ("echo foo bar baz"|["echo foo", "echo bar", "echo baz"])
}
Note
peer-keys: cache
Possible keys are
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 - be sure to encode this as '\\' on Windows as '\' is the Json escape character). Those strings are regarded as paths and - unless they are already absolute - are absolutized, relative to the path of the current config. So e.g. instead of writing
"cp file1 file2"
you should write
"cp ./file1 ./file2"
and it will work from everywhere.
Runs a suite of GUI tests (simulated interaction). Takes a map.
"simulate" :
{
"java-classpath" : ["../rhino/js.jar", "../selenium/selenium-java-client-driver.jar"],
"qxselenium-path" : "${SIMULATOR_ROOT}/tool",
"rhino-class" : "org.mozilla.javascript.tools.shell.Main",
"simulator-script" : "${BUILD_PATH}/script/simulator.js"
}
Possible keys are
Triggers cutting images into regions. Takes a map.
"slice-images" :
{
"images" :
{
"<input_image>" :
{
"prefix" : "<string>",
"border-width" : (5 | [5, 10, 5, 10]),
"trim-width" : (true|false)
}
}
}
Note
peer-keys: cache
(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" ],
"pofile-with-metadata" : (true|false)
"poentry-with-occurrences" : (true|false)
}
Define prerequisite classes needed at run time. Takes a map.
"use" :
{
"<class_name>" : [ "qx.util", "qx.fx" ]
}
Each key is a
Define variants for the current app. Takes a map.
"variants" :
{
"qx.debug" : [ "on" , "off" ]
}
Possible keys are valid
As soon as you specify more than one element in the list value for a variant, the generator will generate different builds for each element. If the current job has multiple variants defined, some of them with multiple elements in the value, the generator will generate a variant for each possible combination of the given values.