NAME
pyjsbuild - builds a web application
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.
SEE ALSO
pyjscompile(1), http://pyjs.org
AUTHOR
pyjamas was written by Luke Kenneth Casson Leighton <lkcl@lkcl.net>,
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
<lkcl@lkcl.net>, for the Debian project (but may be used by others).
April 28, 2009