========================
Build tool web frontend
========================

What is it?
============

This document describes the web front-end for the 'build tool' that is part of
the PyPy package, and used to compile PyPy on clients that participate in the
PyPy build network. Both the build tool and this web front-end are generic, so
they can be used for other projects too.

See the `buildtool`_ description for more details about the tool itself.

.. _`buildtool`: ../buildtool.html 

Overview
=========

The front-end consists of a single page, and uses XMLHttpRequest to communicate
with the server. It presents a form that lets the user provide:

  * an email address

    this to send mail to when a build is done, or has failed

  * system information

    certain specifications of the system the build will run on, such as the
    operating system and cpu type

  * compilation options

    the features the build should contain

  * svn revision/range

    what svn revision to use, optionally with a range that specifies which
    other revisions are allowed

Once the user has filled in the form, the information is sent to the server
where it is validated. If validation is not successful, a message is sent to
the client about what fields need to be filled in, or clash (certain
compilation options can clash); the user can modify the form and re-submit. If
validation succeeds, a build is requested, which can either result in a URL
returned (if a build is already available) or a message about whether a build
is already in progress, or if the request is queued instead.

Technical details
==================

The form is a single static HTML page, that is blank when the user enters the
page. The client then requests (using XMLHttpRequest) the form fields that are
not static (system information + compilation options, email and svn info are
hard-coded in the form), and presents them (using JavaScript that is generated
from RPython using PyPy). The user can now fill in the form, when done it can
press 'submit' to send the form contents to the server (again using XHR) for
validation and (if validation is successful) execution. The results are sent
back to the client and presented to the user: if it consists of validation
error information it is presented in the form (as red fields or something),
if it's a url it is presented as a download, and if it's a message it's
alerted.

Notes
======

Some random notes about implementation:

  * If this was a 'personal project', I would have used some simple templating
    language I wrote myself (`Templess`_), but to not depend on some external
    lib, and to make it easier for others to work with this (or is it?) I
    decided to work with static HTML that is filled with JSON data from JS
    instead... Not sure if it indeed works out well, who knows at some point
    we may decide to use a templating language of some sort (you probably
    guess which I'd vote for ;) after all... Another option would be
    py.xml.html, although I don't like having to deal with presentation details
    from code too much...

  * The first idea I had for this application was to use
    pypy.translator.js.examples.web for the web server, which provides 
    transparent XMLHttpRequest and JSON functionality... However, because this
    is rather ad-hoc, and doesn't seem suitable for production situations,
    I decided that was not a good idea... Making it more suitable for
    production doesn't seem like an easy task (currently it uses
    BaseHTTPServer for instance), although very tempting, since this can imo
    become one of the most interesting web application frameworks available...
    If this would be made solid and more usable (read: more docs and a cleaner,
    higher level API), especially after adding features like transparent
    session handling, better HTTP support and more browser abstractions, it 
    can make development of larger web applications that use 'AJAX'
    (XMLHttpRequest, perhaps with some XML) a lot easier, I think...

.. _`Templess`: http://templess.johnnydebris.net/
    
