pyjsbuild(1)
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 perplatform 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).