ECOOP 2013 Artifact Evaluation

Introduction

The artifact we're submitting is our tool C2Eif/AutoOO that fully automatically translates C programs (applications and libraries) into object-oriented Eiffel programs:

AutoOO has been added to the user interface of C2Eif. When we use the name C2Eif later on this page, we always mean C2Eif and AutoOO.

The next section will explain how to get C2Eif and describe the various options in the GUI.
Then two sections follow with example usages of C2Eif:

The translation of the mongoDB library.
This example shows only how to use C2Eif and discusses the created O-O Eiffel library. The overhead of CIL preprocessing (see picture above) and Eiffel compilation is omitted. The required CIL C files are provided.
This example should run on any Windows and Linux machine.
The translation of the xeyes application.
This is a full example going the whole way from getting the C application from the git repository until running the compiled Eiffel translation.
This example should run on any Linux machine^[1] with an X Window System.

[1] Tested on recent Kubuntu (x86), SuSE (x86) and RedHat (x64) distributions.

C2Eif

You can download C2Eif here. The archive contains Windows and Linux binaries. Simply extract it and run the appropriate binary ("C2Eif.exe" on Windows, "C2Eif" on Linux). You'll see this window:

Explanation of the user interface:

CIL File: Specify the CIL C file of the program you want to translate.
Output Directory: Where to save the translated program.
Required Libraries: If the program depends on system libraries, specify them here.
Required Include Dirs: If the program needs additional system include directories, specify them here.
Disable O-O structs/unions: There are two modes of how to translate C structs and unions: (1) O-O style; create classes with regular fields and (2) C style; create classes that are basically thin wrappers around C memory. Both approaches have advantages and disadvantages. But explaining them would go beyond this artifact evaluation. Feel free to play around with this setting.
Disable O-O Reengineering: Here you can disable AutoOO to compare the translations with enabled and disabled reengineering.
Multithreaded: If the program you're translating uses threads, check this box (Eiffel treats threaded and non-threaded programs differently).
Disable pointer/array bounds checking: The translated program by default monitors pointer and array bounds. Disable it here if your program depends on dirty memory tricks.
Steps: Once you specified the CIL File and the output directory, you'll see the 46 steps making up the translation.
Compile/Step/Show Tree/Show Source: If you just want to translate your program, press "Compile". If you want to see what's happening exactly, select the step you're interested in and press "Step". The translation will stop after that step and you can inspect the current state (AST/source code) by clicking on the "Show Tree" and "Show Source" buttons.
On Linux (the C2Eif development platform) you can get further information in the AST view through the context menu (right mouse button). You can look at the source code of subtrees, control flow graphs^[2] and type binding information. The menu entries are enabled after the step producing the information has been executed.
Disable Contracts: Doesn't do anything. Only needed in development mode.
Log: Information about the translation will be printed here.

[2] Requires the packages "graphviz" and "okular" (the binaries have to be in PATH).

Example 1: mongoDB library

Resources: Windows CIL file, Linux CIL file

Open the appropriate CIL file in C2Eif, select an output directory and press "Compile"^[3]. About 5 seconds later the translation is done.
Please do this once with AutoOO enabled (default) and once with AutoOO disabled (check "Disable O-O Reengineering") and save the translation into different directories.

You can now, with any text editor, inspect and compare the created code. For instance in chapter 6 of the paper we present sample code of how to connect to a mongoDB instance using the translated library. Comparing pd_mongo.e from the translation with enabled reengineering to the translation with disabled reengineering, you can see that routines (methods) such as connect2^[4], is_connected, disconnect, destroy and others have been moved to the class.
Also you can find many preconditions (require clause at the beginning of routines) as explained in the paper in section 4.1.

[3] For this example, we suggest you check "Disable O-O structs/unions" to remove some noise from the created code (but feel free to keep it enabled).
[4] A superclass already defines connect, therefore the reengineering renamed "our" connect routine to connect2.

Example 2: xeyes; the whole way

This example requires that some common packages are installed on your machine:
bash, git, ocaml, make, wget, tar, autoconf, xutils-dev/xorg-x11-util-macros, sed, unzip
libXmu and libXrender (x86 devel packages)

To make this example easier, we provide all the necessary commands that you can just copy-paste into a bash shell.
Please create a temporary directory (all software will be put in there) and set the environment variable EXAMPLE_DIR to it. E.g.:

EXAMPLE_DIR=~/Desktop/tmp mkdir $EXAMPLE_DIR

Preparation

CIL is needed for preprocessing C projects and EiffelStudio for compiling the created Eiffel source code. Temporarily installing them should be as easy as:

CIL

cd $EXAMPLE_DIR git clone git://cil.git.sourceforge.net/gitroot/cil/cil; cd cil ./configure make export PATH=`pwd`/bin:$PATH

EiffelStudio

cd $EXAMPLE_DIR wget http://goo.gl/kuTVC -O Eiffel71_gpl_88986-linux-x86.tar.bz2 tar xfj Eiffel71_gpl_88986-linux-x86.tar.bz2 export ISE_EIFFEL=$EXAMPLE_DIR/Eiffel71 export ISE_PLATFORM=linux-x86 export PATH=$ISE_EIFFEL/studio/spec/$ISE_PLATFORM/bin:$PATH

Translating xeyes

CIL preprocessing

cd $EXAMPLE_DIR git clone git://anongit.freedesktop.org/xorg/app/xeyes; cd xeyes # downloading it ./autogen.sh # Configuring it sed -i "s/ -O2//" Makefile # Removing gcc optimization flags (results in more readable code) make CC="cilly --merge --save-temps" # Building it

This created the regular xeyes binary that you can execute and the merged C file xeyes.cil.c which we need in the next step.

C2Eif

cd $EXAMPLE_DIR wget http://se.inf.ethz.ch/research/c2eif/files/C2Eif-0.6a.zip unzip C2Eif-0.6a.zip mkdir eiffel_xeyes C2Eif/C2Eif -cil-file xeyes/xeyes.cil.c -out-dir eiffel_xeyes -disable-oo-structs -L -lXmu -L -lXrender -L -lm

This starts C2Eif and you can run the translation as in Example 1 (e.g. just press "Compile").
If you add "-cmd" to the command, C2Eif won't start the gui and just compile the project.

EiffelStudio

cd $EXAMPLE_DIR estudio eiffel_xeyes/xeyes.ecf

This will open EiffelStudio and compile the project (press "Ok" and "Yes" in the two appearing dialogs).
After compilation is done, you can press "Run" in the menu bar (or the F5 key) and enjoy xeyes running in Eiffel.
As in the previous example, you can inspect the code and by comparing compilations with enabled and disabled AutoOO see the object-oriented constructs that were introduced by the reengineering.

Of course you can now also adapt and extend the program in Eiffel. You could for instance create a pirate by changing the routine eye_ball in the class PD_EYES_REC; put the existing body into an if block: if a_num = 1 then [original body] end and run the adapted program.

Questions? Problems?

We're happy to help and provide further information.
Just write this guy.