projects.standblue.net -> Moto Documentation -> The mmc Compiler

mmc - The Moto Module Compiler

Introduction
The Steps
mmc Usage
An Example Site
Compiling Your Site
Troubleshooting

Introduction

The really neat thing about Moto is that once you have a Moto site developed and tweaked then you can compile it into an apache module. The takes the interpreted mode out of the picture and allows apache to serve up Moto pages at super quick speeds. In fact, pages served via a mmc-compiled Moto module are served faster than even static html files. Tempting, isn't it?

The Steps

So, its actually pretty simple. Here is a quick run down of the steps involved, and I will elaborate later.

  1. Create a site (or just a page) using Moto, test it until you are happy with it
  2. Compile the site (or page) using mmc
  3. If you are going to run mmc as a user that doesn't have write perms to the apache module directory then you will need to pass the -d flag and manually copy /tmp/mmc_<module-name>.$pid/mod_<module-name>.so into your apache module directory (probably /usr/local/apache/libexec/).
  4. If you want to run the module on a different web accessible path than the one you developed on then you will need to make that directory now, and touch index.moto in that directory
  5. Add the appropriate lines to your httpd.conf file
  6. Restart apache

mmc Usage

To see the current usage of Moto just type something like: 


  shell$ mmc -?
  /usr/local/moto/bin/mmc: illegal option -- ?
  Usage: mmc [options] 

    -n [Module Name]      Specifies the name of the module to be created
    -X [Paths]            Prepends the specified paths to the list
                          of paths in which to look for moto extensions
    -a [Annoucement]      Add the following announcement to the Server:
                          response header.
    -d                    do not delete the folder /tmp/ after
                          compilation
    -e                    Compile files ending with the specified extensions
                          in addition to all .moto files in the specified path
    -q                    execute in quit mode
    -?                    this screen

This is all pretty self explanatory, but there is one thing you might want to think about. If you are going to be compiling the site as a non-root user then you are going to want to use the -d option, because otherwise mmc will try to mv the module to apaches module directory before deleting all the temp files that were created. The -d option tells mmc not to delete these files, therefore allowing you the chance to log in as root and manually copy over the module.

An Example Site

For the development of Markive I use a separate directory in http://projects.standblue.net/tmarkive. This way, I can make changes to the source in a separate location, and then when I am ready to make the changes live I can just compile with mmc and setup httpd.conf to look for /markive/ instead. So, I am going to use this setup as my example for this guide. /tmarkive is my development directory and /markive is the directory being handled by mod_markive.

Compiling Your Site

First, be sure to do step 1 and write the code, thats sort of important here. After you have tested everything and are sure that you want to make your site a module, decide on the URL layout that you want to use. Like I said, I use /tmarkive for testing, and /markive for the live site. If you decide to use separate paths then you will need to create the directory on the filesystem where you want apache to map the module to. You will also need to touch the filename that is your directory index listing, most people will be using index.moto: 


  shell$ cd /usr/local/apache/htdocs
  shell$ mkdir markive
  shell$ touch markive/index.moto
Now you are ready to compile the site with mmc. For my site I use the name markive and I pass the -d option so that I can run mmc as my normal user, not root. This is up to you, but I try to do as little as possible as root. 

  shell$ /usr/local/moto/bin/mmc -n markive -d tmarkive/
This will produce lots of output, and when its finished it will print out what you need to put in your httpd.conf file to make use of the module: 

  ##################################################################

  Done.

  To run this module...

  Add the following directives to your httpd.conf file:

  LoadModule markive_module libexec/mod_markive.so
  <IfModule mod_markive.c>
     <Location /[your location]>
        MarkiveOption Location /[your location]
        SetHandler markive
     </Location>
  </IfModule>

  Once you have added these directives, restart Apache. All
  pages within the subtree you compiled will be available
  off of

  http://[your machine]/[your location]/

  Note that if you compiled only a single moto page the URL
  will be

  http://[your machine]/[your location]/[your page].moto

  ##################################################################
One thing to remember that tripped me up the first time: If you are using the module inside a virtual domain then you need to put it inside your <VirtualHost> block instead of just anywhere in httpd.conf. projects.standblue.net is hosted as a virtual domain for me, so the first few times I tried to compile markive I was listing it in httpd.conf in the default host.

Okay, onto the stuff that requires root permissions. If you passed mmc the -d option (as I recommend) then the module is still going to be hanging around in the /tmp directory. Go there and look around for something that looks a little like /tmp/mmc_<module-name>.$pid/mod_<module-name>.so where $pid is the process id of the mmc command. Copy this file to your apache module directory, which is typically /usr/local/apache/libexec on source installations, or /usr/lib/apache on most modern redhat machines where apache was installed via rpm (or during the OS installation). 


  shell# cp /tmp/mmc_markive.1523/mod_markive.so /usr/local/apache/libexec/
Now, using your $EDITOR of choice, open up httpd.conf and add lines such as these: 

  LoadModule markive_module libexec/mod_markive.so

  # remember to put this in your <VirtualHost> directive if you
  # are using your module on a virtual domain
  <IfModule mod_markive.c>
    <Location /markive>
       MarkiveOption Location /markive
       SetHandler markive
    </Location>
  </IfModule>
Now, restart apache and you should be able to point your browser to the URL where these paths lead to.

Troubleshooting

Probably the thing that trips up most people is when they compile a site and then configure apache to handle it for a different path than where the actual Moto files reside. If you change the Location or <Module-name>Option to something other than what mmc spits out, then you need to remember to make the directory on the filesystem and then touch index.moto in the directory.




cwright@standblue.net