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 CSS files to the application. Takes a list.
"add-css" :
[
{
"uri" : "<css-uri>"
}
]
Note
peer-keys: compile
Add pre-fabricated JS files 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.
"combine-images" :
{
"images" :
{
"<output_image>" :
{
"prefix": [ "<string>", "<altstring>" ],
"layout": ("horizontal"|"vertical"),
"input" :
[
{
"prefix" : [ "<string>", "<altstring>" ],
"files" : [ "<path>", "<path>" ]
}
]
}
}
}
Note
peer-keys: cache
Note
Unless you are generating a base64 combined image, this key requires an external program (ImageMagic) to run successfully.
images : map with combine entries
<output_image> : path of output file; may be relative to the config file location; the file ending determins the file format; use .png, .gif, etc. for binary formats, or .b64.json for base64 combined image
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|hybrid)"
}
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 the loader and needs to be included by e.g. the hosting index.html page, 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" : ["basecalls", "comments", "privates", "strings", "variables", "variants"],
"decode-uris-plug" : "<path>",
"except" : ["myapp.classA", "myapp.util.*"]
}
}
The compile-options key informs all compile actions of the generator. Settings of this key are used e.g. by the jobs that create the source and the build version of an application, though in varying degrees (e.g. the source job only utilizes a few of the settings in this key, and ignores the others). Output Javascript file(s) are generated into the directory of the paths/file value, with path/file itself being the primary output file. If paths/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. For further information see the individual key descriptions to find out which build type utilizes it (in the descriptions, (<type>) refers to the compile/type, e.g. source or build)
Possible keys are
(experimental)
Taylor configuration warnings. This key can appear both at the config top-level, or at the job-level. Takes a map.
"config-warnings" :
{
"job-shadowing" : ["source-script"],
"tl-unknown-keys" : ["baz", "bar"],
"job-unknown-keys" : ["foo", "bar"],
"<config_key>" : ["*"]
}
Turn off warnings printed by the generator to the console for specific configuration issues. The key is honored both at the top level of the configuration map, and within individual jobs, but some of the sub-keys are only sensible if used at the top-level (This is indicated with the individual key in the list below). Warnings are on by default (equivalent to assigning e.g. ["*"] to the corresponding key). Like with the global let, a top-level config-warnings key is inherited by every job in the config, so its settings are like job defaults. If a given key is not applicable in its context, it is ignored. To turn off all warnings for a single generator run (independent of settings given in this key) use the generator -q command line option.
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).
Define global key-value mappings for the application. Takes a map.
"environment" :
{
"<key>" : (value | [<value>, ... ])
}
The "environment" of a qooxdoo application can be viewed as a global, write-once key-value store. The environment key in a configuration allows you to pre-define values for such keys. All key-value pairs are available at run time through qx.core.Environment. There are pre-defined keys that are established by qooxdoo, and you can add user-defined keys. Both are handled the same.
Possible keys are
As soon as you specify more than one element in the list value for a key, the generator will generate different builds for each element. If the current job has more than one key defined with multiple elements in the value, the generator will generate a dedicated build for each possible combination of the given keys. See special section.
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 those from sub-name spaces.
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 all classes starting with the 'qx.util' name space. A leading '=' in front of a class specifier (e.g. '=qx.util.*') means 'without dependencies'. In this case, exactly the listed classes are included (wildcards expanded), but not their dependencies. Otherwise, for the given classes their dependencies are calculated recursively, and those classes are also included.
Include external config files. Takes a list of maps.
"include" :
[
{
"path" : "<path>",
"as" : "<name>",
"import" : ["job1", "job2", "job3"],
"block" : ["job4", "job5"]
}
]
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", "${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"),
"include-transitive-load-deps" : (true|false),
"force-fresh-deps" : (true|false),
"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)
},
"json" :
{
"file" : "<filename>",
"pretty" : (true|false)
},
"flare" :
{
"file" : "<filename>",
"pretty" : (true|false)
}
}
}
Note
peer-keys: cache, include, library, compile-options
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>",
"separate-loader" : (true|false),
"i18n-as-parts" : (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" :
{
"block" :
{
"add" : true
},
"trailing" :
{
"keep-column" : false,
"comment-cols" : [50, 70, 90],
"padding" : " "
}
},
"code" :
{
"align-with-curlies" : false,
"open-curly" :
{
"newline-before" : "m",
"indent-before" : false
}
}
}
Keys are:
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).
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