SYNOPSIS

pyjsbuild [options]application

DESCRIPTION

This manual page documents briefly the pyjsbuild command.

pyjsbuild is a program that compiles python (pyjamas) web applications into javascript, automatically adding suitable boilerplate, "loader" infrastructure and run-time libraries, for detection and support of all major web browsers. Typical usage is simply "pyjsbuild {Application}.py" and the compiled application will be created in a subdirectory called "output". If a subdirectory called "public" exists in the same directory in which pyjsbuild is run, its contents will be copied verbatim and recursively into the "output" directory.

To load the compiled application, as usual for any web application, simply point the web browser at the {Application}.html file, which can be found in the output directory. If at compile-time a file named {Application}.html was not found in the same directory as {Application}.py or in the "public" folder, pyjsbuild will create a stub html file, automatically.

As applications are expected to run in a web browser as javascript, the "standard" python libraries are not accessible to the web application. Hence, the pyjamas framework provides independent reimplementations of standard python builtins, types and libraries (that are written in, or compiled to, javascript, along with the rest of the application). It is essential that a developer not confuse standard python libraries with the pyjamas libraries if the -I option is used to specify additional library paths.

OPTIONS

These programs follow the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.

-h, --help

Show summary of options.

-v, --version

Show version of program.

-o OUTPUT, --output=OUTPUT

directory to which the webapp should be written

-j JS_INCLUDES, --include-js=JS_INCLUDES

javascripts to load into the same frame as the rest of the script

-I LIBRARY_DIRS, --library_dir=LIBRARY_DIRS

additional paths appended to PYJSPATH

-D DATA_DIR, --data_dir=DATA_DIR

path for data directory

-m, --dynamic-modules

Split output into separate dynamically-loaded modules (experimental)

-P PLATFORMS, --platforms=PLATFORMS

platforms to build for, comma-separated (default is all)

-d, --debug

-O, --optimize

Optimize generated code (removes all print statements)

-c, --cache_buster

Enable browser cache-busting (MD5 hash added to output filenames)

PLATFORM SUPPORT

Supported platforms are IE6, Mozilla, Safari, OldMoz and Opera. The -P option allows a subset of platforms to be compiled, if desired. Platform support is done by looking for platform-specific "overrides" in a subdirectory called "platform". So, if the application is called "Hello.py", and there exists a file "platform/HelloIE6.py" then any functions or classes in HelloIE6.py will "override" any such functions or classes in the "Hello.py" module, specifically when the code for the IE6 platform is compiled.

There are plenty of examples and instances throughout the pyjamas libraries where platform-overrides are used (for example, the BrowserDetect.py example). Note that because pyjamas takes care of "merging" the platform-specific overrides in each module, it is not necessary to override an entire class: only make alternatives for those functions or class methods which absolutely need replacing on a per-platform basis, and it is good practice to split the application design into functions and classes where as few platform-specific lines of code as possible go into the platform-specific overrides.

CACHE BUSTING

Browsers, Web Servers and Web Frameworks have a nasty habit of cacheing HTML and Javascript files, which throws a spanner in the works of rapid application development as the developer has to clear the browsers' cache, delete the HTTP proxy cache, locate and delete the Web Framework's cache (e.g. Joomla), clear the Web Browser cache, restart the web server, restart the web browser etc. To help avoid such stupidities, use the -c option to add a unique MD5 hash to the end of all output filenames. The MD5 hash that is appended is the MD5 hash of the contents of each file.

OPTIMISATION

pyjsbuild is not a javascript compressor, it is a compiler. Use -m to enable dynamic (shared) modules if space is at a premium, or consider running the javascript through a standard javascript compressor such as YUI Compressor. Also bear in mind that the -d option increases the size of the compiled javascript by four to five times, so do not use -d for release builds.

DEBUGGING

pyjsbuild is not an interpreter, it is a compiler, and the resultant javascript output will be interpreted by the web browser, not the standard python interpreter. It is worth emphasising this because python developers who are expecting pyjsbuild to perform all the usual tricks that the standard python interpreter performs are in for a bit of a shock. Therefore, just as with all Web 2.0 Javascript applications, debugging needs to be done using javascript tools, such as the Microsoft Script Debugger for IE, and Firebug and Venkman for Firefox (use of both is thoroughly recommended). However, there are circumstances where script debugging is either impossible or inconvenient. For that, there is the "-d" option which, whilst not perfect, provides a reasonable approximation of python run-time stack trace exception handling.

AUTHOR

pyjamas was written by Luke Kenneth Casson Leighton <[email protected]>, James Tauber and others. It originated from a port of Google Web Toolkit, which is Copyright Google, Inc.

This manual page was written by Luke Kenneth Casson Leighton <[email protected]>, for the Debian project (but may be used by others).