Changes between Version 2 and Version 3 of ModParrotHLLDocs

12/25/08 18:36:20 (13 years ago)



  • ModParrotHLLDocs

    v2 v3  
    11= mod_parrot HLL Module Developer's Guide = 
     3== Overview == 
     5This is the mod_parrot HLL module developer's guide.  The target audience is developers wishing to embed their language in Apache using mod_parrot.  The benefits of this are one-time compilation of scripts, a persistent execution environment, direct access to the Apache API, and the ability to write custom hooks in the embedded language.  Some languages can be self-hosted, meaning the code to implement mod_foo is written in the "foo" language. 
     7Most examples are taken from the PIR HLL module, with several from mod_perl6 to illustrate self-hosting. 
    39== Prerequisites == 
     11Any language targeted to Parrot can use mod_parrot to execute code in a persistent environment.  However, to best take advantage of mod_parrot's features, including self-hosting, languages should support the following: 
     13 * namespaces 
     14 * lexical and global variables 
     15 * an Parrot-compatible object model 
     17Using mod_parrot without these features is still possible with some PIR scaffolding. 
    519== Bootstrapping == 
     21Each HLL in mod_parrot is contained in its own Apache module, known as an ''HLL module''.  All steps leading up to and including the registration of the HLL module  with Apache is called bootstrapping.  The bootstrapping process typically follows this procedure: 
     23 1. Load the HLL compiler. 
     24 1. Declare server and directory configuration hooks. 
     25 1. Declare Apache directive hooks. 
     26 1. Declare Apache directives. 
     27 1. Declare metahandlers (hooks for Apache phases). 
     28 1. Register the Apache module. 
     30As of mod_parrot 0.5, step 1 must be written (or compiled to) PIR, but all subsequent steps can be written in the HLL itself (a self-hosting HLL module).  The PIR bootstrap file MUST be compiled to bytecode and located in {{{ModParrot/HLL/hllname.pbc}}} in Parrot's library path.  HLL code can be located anywhere, though conventions will eventually be defined.  If there is HLL bootstrap code, it must be loaded and executed using PIR in the bootstrap file. 
     32Bootstrap code must be placed in a PIR subroutine marked with the {{{:load}}} adverb so it is run when the file is loaded.  This subroutine can be named or anonymous (using the {{{:anon}}} adverb). 
     34'''Example: mod_perl6''' 
     36The first part of the bootstrap file from mod_perl6 loads the compiler and supporting libraries, then executes Perl 6 code from {{{}}}: 
     39.sub __onload :anon :load 
     40    load_bytecode 'languages/perl6/perl6.pbc' 
     41    load_bytecode 'ModParrot/Apache/Module.pbc' 
     42    load_bytecode 'ModParrot/Constants.pbc' 
     44    # load, which may be precompiled 
     45    $P0 = compreg 'Perl6' 
     46    $P1 = $P0.'compile'('use mod_perl6') 
     47    $P1() 
     49    ... 
    753== Configuration == 
     55Each HLL module provides two configuration data structures to Apache: server and directory.  Server configurations are specific to the main server and individual virtual hosts.  Directory configurations are specific to individual ''sections'', which can be real directories or locations defined in the Apache configuration file.  All configuration structures can be merged with parent configurations to implement inheritance or overriding behavior. 
    957=== Creating HLL Configurations === 
    1161=== Merging HLL Configurations === 
    2777== Registering the HLL Apache Module == 
     79== Miscellany == 
     81=== Persistence === 
     83=== Sharing an Interpreter with Other Languages ===