How to compile and run services

There are five sample WIG compilers available:

  • wig4 and wig18, written in C by groups at the University of Aarhus in fall 1998;
  • wig10, written in Java using SableCC at McGill in fall 1999;
  • pwig (perfectwig), written in C at McGill in fall 2001; and
  • lkwig (Louis & Kacper's WIG), written in C at McGill in fall 2004.

You will probably find that wig10, wig18, and pwig are most stable, but lkwig also looks fairly promising. wig18 is interesting because it generates stack code, and lkwig is interesting because it generates Perl.

Currently there are binary versions for FreeBSD, Linux, and Solaris available, with wrapper scripts that attempt to select the right one automatically for you. We have the source code and can possibly compile a version for a different system if it would help you. The wig10 compiler, being written in Java, will run anywhere that Java runs.

In order to actually compile CGI scripts from the generated C-based WIG services, required for all compilers except lkwig, you will need to log in to freebsd.cs.mcgill.ca, the webserver that hosts www.cs.mcgill.ca. Compiled C binaries must target that machine, and while you may have some luck on other FreeBSD lab machines, there have been reports of incompatibilities.

1. Making sure prerequisites are installed

Before you can use these instructions, you should first follow the instructions on using Subversion in this class and setting up your environment for JOOS programs. This will ensure that Java 1.5 is on your PATH and that you have a local copy of the example WIG binaries.

2. Setting up your environment

As usual, we need to set up some additional environment variables:

WIGDIR

Assuming you have checked out the public_html directory from the class SVN repository to $HOME/cs520/public_html, add the following: 

      setenv WIGDIR $HOME/cs520/public_html/wig

or 

      export WIGDIR=$HOME/cs520/public_html/wig

to your .cshrc or .bash_profile for tcsh or bash respectively.

PATH

We want to be able to execute the WIG compiler binaries from anywhere. Add the following: 

      setenv PATH $WIGDIR/bin:$PATH

or 

      export PATH=$WIGDIR/bin:$PATH

to your .cshrc or .bash_profile if you are using tcsh or bash respectively.

Note that we can possibly make binaries for other platforms available, just send your request to your instructor or TA.

cgi-bin directory

Finally, in order for WIG services to execute within a browser they need to be placed in a sub-directory of $HOME/public_html/ on the SOCS machines. The WIG installation scripts assume that this directory has the conventional name cgi-bin. 
      $ cd $HOME
      $ mkdir -p public_html/cgi-bin
      $ chmod 711 public_html/
      $ chmod 711 public_html/cgi-bin
You can access this directory by pointing your web browser at the URL http://www.cs.mcgill.ca/~`whoami`/cgi-bin/.

3. Compiling your WIG service

  • Create or find a WIG service, making sure it has a .wig extension. Assume your service is called foo.wig.

  • Compile foo.wig with some WIG compiler using one of the following commands: 

          $ wig4 foo.wig
      $ wig10 foo.wig 
      $ wig18 foo.wig
      $ pwig foo.wig
      $ lkwig foo.wig
    For the first four compilers, the compilation will produce two files, foo.c and foo.install. For the lkwig compiler it will produce foo.pl.

  • Check that foo.install has its execute permission bit set using ls -l foo.install, and if not change it using chmod +x foo.install. The same applies for foo.pl.

  • For the compilers that target C, execute the file foo.install on freebsd.cs.mcgill.ca; other FreeBSD machines may or not work. For lkwig simply copy foo.pl to ~/public_html/cgi-bin, or compile with -o ~/public_html/cgi-bin/foo.pl.

    The install scripts perform the following 3 actions:

    1. Call gcc to produce a binary:

      • foo4.cgi, when using wig4;
      • foo10.cgi, when using wig10;
      • foo18.cgi, when using wig18; or
      • foo.cgi, when using pwig.

      This binary is made by compiling foo.c and including the appropriate runtime support files in $WIGDIR/lib:

      • runwig4.c and runwig4.h, when using wig4;
      • runwig10.c, when using wig10;
      • runwig18.c and runwig18.h, when using wig18; or
      • perfectwig_run.h, when using pwig.

    2. Set the executable permission bit of the binary foo(4|10|18|).cgi.

    3. Move target binary foo(4|10|18|).cgi to ~/public_html/cgi_bin.

    Remember that if you are ever unsure of the type of a file, you can use the file command: 
          $ file foo.install 
      foo.install: Bourne shell script text executable
    and that this is often enough knowledge to know whether you can meaningfully use the cat command to examine it: 
          $ cat foo.install 
      #!/bin/sh
      gcc -I$WIGDIR/lib foo.c -o foo10.cgi
      chmod a+rx foo10.cgi
      mv -f foo10.cgi ~/public_html/cgi-bin
    (You should now understand everything that the script does.)

4. Running your WIG service

You can now run your service by using one of the following URLs: 
      http://www.cs.mcgill.ca/~`whoami`/cgi-bin/foo4.cgi?SessionName
      http://www.cs.mcgill.ca/~`whoami`/cgi-bin/foo10.cgi?SessionName
      http://www.cs.mcgill.ca/~`whoami`/cgi-bin/foo18.cgi?SessionName
      http://www.cs.mcgill.ca/~`whoami`/cgi-bin/foo.cgi?SessionName
      http://www.cs.mcgill.ca/~`whoami`/cgi-bin/foo.pl?SessionName
where `whoami` expands to your CS user ID, and SessionName is one of the sessions defined in foo.wig.

For example, consider the following service that might be in foo.wig: 

      service {
        const html ...
        const html ...
        ...
        session Init() { ... }
        session Doit() { ... }
        session Report() { ... }
      }
Here there are three different sessions, Init, Doit, and Report that can substitute for SessionName in the above links. Note that the better WIG compilers provide links to all available sessions. (It may be an interesting language extension to have public and private sessions.)

5. Batch compilation and installation of WIG examples

WIG compilers come with their examples. You may want to compile and run them to check how they manage to parse files and generate codes.

The examples have been already listed in benchmark lists:

  • classic_benchmark_list
  • perfectewig_benchmark_list
  • wig04_benchmark_list
  • wig10_benchmark_list
  • wig18_benchmark_list

5.1 Compiling

In the $WIGDIR, just run:

./compile <a_benchmark_list>

This will try to compile all examples listed in the benchmark list file using all possible compilers.

Note that some of the examples may fail because these compilers are not completely compatible.

5.2 Installing

After compiling, run:

./install <a_benchmark_list>

This will try to install all compiled codes listed in the benchmark list file into your public_html/cgi-bin and generate an index.html in that folder. If you've already put your own index.html in cgi-bin, please backup first.

5.3 Running

After installing, just go to this URL:

http://cs.mcgill.ca/~`whoami`/cgi-bin/index.html

If you've got some error message saying "permission denied", please try to change the permission of the index.html generated in setp 2:

chmod a+r $HOME/public_html/cgi-bin/index.html

5.4 Benchmark list file format

You may want to write your own benchmark list file so that it will save a lot of your time when debugging your wig compiler. Actually it is quite easy, the format of benchimark_list is just a plain text file in which one line defines a wig program:

wig_program_id <tab> path <tab> wig_file_name<line break>

the wig_program id is used in script only;

path should tell the script where your .wig located

wig_file_name is the wig file you want to compile, DO NOT annex the file extension(.wig). For example, you want to compile wig programs in $HOME/yourwig/foo.wig and bar.wig, you should write a "my_benchmark_list" like this:

foo $HOME/yourwig foo
bar $HOME/yourwig bar

and then you can compile and install codes using:

./compile my_benchmark_list
./install my_benchmark_list

Maintained by Chris Pickett. [HOME]