Yhc web service
(API Documentation link)
Revision as of 02:23, 12 March 2008
|Part of Yhc|
Yhc Web Service
The service is currently available at the following URL: http://www.golubovsky.org:5984/static/yhcws/MainGUI.html
3 Technical overview
The service runs a slightly modified version of SearchPath to chase imports across the Internet. This removes the limitation on the number of modules compiled simultaneously, while only one Haskell module may be submitted via user interface.
The Service runs under Linux inside a 32-bit virtual machine which is an instance of KVM administered by KVMADM on a 64-bit Linux host. Since CouchDB currently lacks any access control to its databases, Squid is used as reverse proxy with proper access control settings.
4 Users guide
4.1 User interface
Initially, the Service displays the following form in the web browser window. Each row of the form corresponds to a single pastebin entry. The links column contains icons that correspond to possible user actions that can be performed over each document. The author column identifies the submitter (author name is arbitrary: the Service does not authrnticate users). The time column shows the submission time (UTC). The title column shows the title that author gave to the entry. The status column shows whether the code submitted with the entry is being comipled, or that compilation was successful, or it failed.
The view Haskell source icon is always present regardless of current status of an entry. Clicking on it shows the source code submitted with the entry. Clicking on the Close button restores the document browser.
The view compilation log and view error log icons when clicked, show either the compilation log, or error log depending on success or failure of compilation. These icons appear only after compilation is complete (successful or failed). Similarly, the Close button restores the document browser.
Clicking on the edit source code icon opens the new entry form with the source of the corresponding entry. Thus, source code may be edited and resubmitted. The service does not keep track of source code revisions: each time source is edited, it is submitted as a new entry. This icon is always present with each entry.
On the document browser form, buttons << Prev and Next >> "turn pages" of the pastebin. Upon startup, the document browser shows the most recent entries. The New Entry button invokes the new entry form with all fields empty, so new code may be entered from scratch.
On the new entry form, the Clear All button clears all entry fields, Browse switches back to the document browser (showing the most recent entries) regardless of whether the new code was submitted or not. The Submit button sends the user input for compilation. After pressing the Submit button, the new entry form remains active, and submission results appear in the Source field. If submission was successful (that is, successfully stored in the database), new document's DocId appears in the Source field. Otherwise (e. g. HTTP error) error message appears in the Source field. Compilation results never appear in the new entry form.
Yhc Web Service does not limit the size of Haskell code entered.
4.2 Typical usage scenario
- In the document browser, press the New Entry button. The new entry form appears.
- Type or paste into the Source field whatever is desired to be submitted. Also fill in the Author and Title form. If empty, these fields will be initialized with default values at the moment of submission.
- Press the Submit button. Make sure that new DocId appears in the Source field.
- Press the Browse button to switch back to the document browser. Locate the entry just submitted by author and title. Note the compilation status.
- Press the << Prev button several times with approximately 5 second interval and wait until compilation status changes to 'Success' or 'Error'.
- If the status becomes 'Error', observe the error log by clicking on icon, then click on icon to correct the source code in error.
- If the status becomes 'Success', click on icon to load the compiled page.
5 Build it yourself
There is no unified way to build the instance of the Service as it depends largely upon other software distributions. The version presently online was built based on Arch Linux Duke, however Arch Linux users are advised to see this message.
In order to build the Service, make sure CouchDB is built and running; follow instructions.
Check out the Yhc darcs repo:
darcs get http://darcs.haskell.org/yhc
Change to the root of Yhc source tree. Build Yhc:
scons core=1 build && scons prefix=/where/you/install install
(cd src/translator/js; make all cdbtools install)
At this point CouchDB must be running. It is assumed that everything runs at the same host, that is, the database is accessed at http://localhost:5984.
Stay at the root of Yhc source tree. Build the Service:
(cd src/yhcws; make all init-db install)
At the moment of making
init-db, you will be asked to remove and re-create several databases in the running CouchDB instance. Make sure you are not going to lose any valuable data.
Everything will be installed relatively to Yhc binary location. That is, if yhc is located as
/usr/bin/yhc, all binaries associated with the Service will be installed in the same directory. Make sure that this directory is on your path.
Create a user account under which the compiler will run. All that such a user needs is just a home directory.
Start the service by running
ywsd. This program acts as a compile job scheduler polling the database for updates every second, and running Yhc if there is anything new to compile.
As the database is accessed every second, logs of the database itself and also http access logs grow fast. It makes sense to cut those logs frequently as they are of little value: use an utility provided with your distro, or write your own, similar to
logcut shell script found at
src/yhcws relatively to the root of Yhc source tree.
It however saves you a lot of time just to use the online version of the Service.