joan

Joan is a tool to clean up C source code generated by the SmallEiffel compiler. It replaces the cryptic mangled names by more meaningful ones, removes distracting comments, and reformats the indention.

Introduction

The idea behind joan is of course stupid and sick. But as of 2001, SmallEiffel does not yet include native debugging and profiling tools.</p> In some cases, print is good enough. If not, many people use C tools.

Looking at the C source generated by SmallEiffel is not much fund. Naturally, the code optimized to be short in order to compile faster and use less disk space. Joan cleans up this C code, making it easier to interpret.

To get most out of it, it helps to know how to implement exception handling, garbage collection, and multiple inheritance. But even with only some basic C knowledge, you should be able to step through Eiffel routines and read profiler output.

In 2017, when SmallEiffel has an own IDE and tools, joan will not be of much use anymore, except for tracking down Eiffel compiler bugs.

Installation

1. Get the SmallEiffel compiler.
2. Get GNU indent, which reformats C source code. Just make sure it is in the search path. Don't read the manual, Joan knows about the proper options.
3. Get vahunz, which replaces names in C source code. Apart from the installation instructions, don't read the manual, Joan knows about the proper options.
4. Get joan.zip, which contains the actual tool.
5. Compile joan using SmallEiffel:

   compile -boost -no_split joan
   

6. Copy joan to some place in your search path.

That's it.

Usage

Joan operates on the C source code and *.id file SmallEiffel generates. All of these must exist. It then simple replaces the "ugly" *.c by a one that will be easier to read.

The general pattern of operation is:

1. Compile your Eiffel source using for example

   compile -no_split my_class
   

   It is important to have "-no_split" and not to have "-clean".
2. Use joan like

   joan my_class
   

3. Manually recompile the C source code joan created, for example

   gcc my_class.c -o my_class
   

   You can specify C compiler options for debugging, profiler, and coverage information at will.
4. Run my_class, using all your C debugging and profiling tools.

Tutorial

If you just compiled joan as described above, there still should be three files in your current directory: joan.id, joan.h, and joan.c.

Take a look at joan.c - it is ugly.

Now type

joan joan

and watch.

If everything works out, you will have a new joan.c. Take a look at it, it should be nicer (as far as C can be nice).

Copyright and Support

Joan is released under the GNU GPL. (It has to be like that because it uses code from SmallEiffel's "lib_se".)

Known Bugs and Limitations

• Docs need some additions, especially the copyright stuff.
• Only works if "-no_split" is used. Technically, it's not difficult to support SE's incremental C sources.
• Some command line options could be nice. Internally, they are there (see JOAN_OPTIONS_SINGLETON), but there's no parser.

History

Version 1.0, 17-Apr-2001

• First, (somewhat) public release to get some feedback