.. _pages/tool/generator_usage#generator_usage: Generator Usage *************** The generator is a command-line utility which serves as the single entry point front-end for all qooxdoo tool chain functions (nearly; there are a few functions that are available through other programs, but these really serve special-case purposes). The generator is started to execute various jobs. Those jobs represent the feature set of the tool chain. This page is about how to invoke the generator. .. _pages/tool/generator_usage#files_and_folder_structure: Files and Folder Structure ========================== The qooxdoo SDK has a dedicated ``tool`` folder that contains all elements that make up the tool chain. The general structure is like this: :: tool |- app -- helper apps |- bin -- stand-alone programs and scripts |- data -- various data files |- pylib -- Python modules The generator is actually the program under ``tool/bin/generator.py``. .. _pages/tool/generator_usage#generate.py: generate.py =========== To make it easier to invoke the generator, each library in the SDK (framework, applications, components) contains a ``generate.py`` script that is really just a proxy for the generator itself. It is also part of each project structure created by the :ref:`create-application.py ` wizard. The aim is to hide the actual path to the generator program. .. _pages/tool/generator_usage#command-line_options: Command-line Options ==================== Since the generator is nearly complete driven by its config files, there are very few command-line options: :: shell> generator.py -h Usage: generator.py [options] job,... Arguments: job,... a list of jobs (like 'source' or 'copy-files', without the quotes) to run x use 'x' (or some undefined job name) to get a list of all available jobs from the configuration file Options: -h, --help show this help message and exit -c CFGFILE, --config=CFGFILE path to configuration file containing job definitions (default: config.json) -q, --quiet quiet output mode (extra quiet) -v, --verbose verbose output mode (extra verbose) -w, --config-verbose verbose output mode of configuration processing -l FILENAME, --logfile=FILENAME log file -s, --stacktrace enable stack traces on fatal exceptions -m KEY:VAL, --macro=KEY:VAL define/overwrite a global 'let' macro KEY with value VAL The most important options are the path of the config file to use (*-c* option), and the list of jobs to execute. The *-m* option allows Json-type values, scalars like strings and numbers, but also maps *{...}* and lists *[...]*. .. _pages/tool/generator_usage#configuration_files: Configuration Files =================== The singe most-important way to control the actions of the generator is through specialized config files. These files have a `JSON `_ syntax and contain the definitions for the various jobs the generator is supposed to execute. There is a :doc:`whole section ` in this manual dedicated to these config files. .. _pages/tool/generator_usage#usage_patterns: Usage Patterns ============== As a few quick hints at how you would invoke the generator, here are the most common use cases. All these examples name a single job to run, and rely on the availability of the default config file ``config.json`` in the current directory: * ``generate.py source`` -- when you just started to create your application and every time you have added new classes to it. * ``generate.py build`` -- when you have completed your application and/or want to create an optimized, deployable version of it. * ``generate.py api`` -- when your application is getting complex and/or you want to have a local version of the standard `Apiviewer `_ application that includes the documentation of all of your application classes. * ``generate.py test`` -- when you have created unit test classes for your application and want to run them in the `Testrunner `_ frame application. The :doc:`/pages/getting_started/helloworld` tutorial will give the complete steps how to start a project and get going. .. _pages/tool/generator_usage#default_jobs: Default Jobs ============ Arguments like ``source`` or ``api``, as shown in the previous section, are so called *jobs* in qooxdoo lingo. If you are working on a skeleton-based application you automatically get a whole list of such pre-defined jobs to work with. For a quick overview, invoke the generator script with an undefined job argument, like :: generate.py X This gives you a list of all jobs available through your current config file, many of them with a few words of explanation about what they do: :: - api -- create api doc for the current library - build -- create build version of current application - clean -- remove local cache and generated .js files (source/build) - distclean -- remove the cache and all generated artefacts of this library (source, build, ...) - fix -- normalize whitespace in .js files of the current library (tabs, eol, ...) - inspector -- (since 0.8.2) create an inspector instance in the current library - lint -- check the source code of the .js files of the current library - migration -- migrate the .js files of the current library to the current qooxdoo version - pretty -- pretty-formatting of the source code of the current library - profiling -- includer job, to activate profiling - source -- create source version of current application - source-all -- create source version of current application, with all classes - test -- create a test runner app for unit tests of the current library - test-source -- create a test runner app for unit tests (source version) of the current library - translation -- create .po files for current library For an exhaustive reference of these default jobs, see the :doc:`default jobs page `.