SWAG >> SWAG Kit >> Usage Instructions

Using SWAG Kit

Using Swagkit is not very difficult, although it is assumed that the user is familiar with compiler technology. Before trying SWAG Kit on a large system, we suggest you try the two examples found below.

The pipeline currently consists of 5 major steps:

  • cppx: Extract the facts. Produces *.ta from the original source files
  • prep: Prepare the facts. Produces *.o.ta from the extracted facts
  • linkplus: Link the facts. Produces out.ln.ta from *.o.ta
  • layoutplus: Layout the facts. Produces out.ls.ta from out.ln.ta
  • lsedit: Visualize the facts.

Small example

Applying SWAG Kit to this small example is an ideal test of whether the Kit is installed correctly. At the same time, this example illustrates all the major steps you have to take to perform fact extraction.

  • Download main.c
  • Download lib.h
  • Download lib.c
  • Extract main.c: [%] cppx main.c
  • Extract lib.c: [%] cppx lib.c
  • Prep main.c.ta: [%] prep main.c.ta
  • Prep lib.c.ta: [%] prep lib.c.ta
  • Link the system: [%] linkplus *.o.ta
  • Layout the system: [%] layoutplus out.ln.ta
  • View the system:[%] lsedit out.ls.ta

A bigger example

In this example, we'll apply SWAG Kit to a slightly larger example: a toy compiler used in a computer science course at the University of Toronto.

  • Download C488.tar.gz
  • Unpack the archive: [%] tar -xvzf c488.tar
  • Change to c488 directory: [%] cd c488
  • Build the system: [%] make
  • View the system using lsedit: [%] lsedit out.ls.ta

A real example

Extracting the architecture of the vi editor is a perfect way to start using the CPPX pipeline on real systems. vi is small enough to be manageable (91 files, 257Kloc) but is nevertheless a real, complex system, with its own configuration scripts and makefiles.

For systems of more than trivial size it is impractical to apply cppx by hand (as we did in our small example) or write custom scripts to do the processing (as we did in the bigger example). Large systems typically come with makefiles that we can use to help us perform the extraction. In order to use existing makefiles to perform fact extraction for us we need to modify them so that they would invoke cppx and prep in addition to compiling and linking the program itself.

The CPPX pipeline is shipped with the gce utility, which is meant to replace gcc in makefiles of large applications. When invoked, gce does the following things:

  • Invokes cppx on the file supplied;
  • Invokes prep on the resulting ta file;
  • Removes temporary ta files generated during the prep stage;
  • Invokes gcc on the file supplied, passing to it all the command line parameters it received.
Substituting gce for gcc in a makefile can range from very easy to extremely difficult. Most makefiles have a single line that defines the utility that will be used for compilation. Typically, that line defines a variable called $CC, whith the value of the variable being the pathname of the compiler. For these files, the substitution only involves finding this line and changing it so that gce is invoked.

In systems that use many makefiles, or that are specifically dependent on the value of the $CC variable, the substitution task may be considerably more difficult, and additional modifications of the makefile may be required. In cases of extreme difficulty, it may be tempting to revert to hand-invocation of cppx, as shown in the small example above. In practice, however, it is almost always better to modify the makefile to suit your needs, as hand-application of cppx to large systems is always very labour-intensive.

In the case of vi, the extraction is relatively simple. Here is a step-by-step guide to extracting the architecture of vi:

  • Download the vim-6.3.tar.bz2 file containing the zipped sources, or get the latest version of vi from http://www.vim.org;
  • Unzip the archive: tar jxvf vim-6.3.tar.bz a directory named vim63 will be created.
  • Enter the newly created directory and run the configuration script:
    cd vim63
    ./configure
  • Enter the source directory and edit the file Makefile; search through the makefile for the place where the CC variable is set, using the comments as guidelines to making changes. On line 478 of the makefile enter the line
    CC = gce
    This will change the default compiler from gcc to gce
  • Save the makefile and run make by typing: make
  • Link the generated ta files: linkplus *.o.ta
  • Lay out the landscape: layououtplus out.ln.ta
  • View the landscape with LSEdit: lsedit out.ls.ta

The steps outlined above will not work for all complicated projects. The vi example illustrates the general approach of makefile modification for fact extraction with the CPPX pipeline.