Chapter 5
Debugging Knitted Programs

This chapter will be expanded in the future. For now, it only outlines the basics of what one must know in order to debug Knitted programs.

To debug a Knit-generated program, you must (1) compile the program for debugging, i.e., by giving the -g option to your C compiler, (2) run the Knit-generated program under a debugger such as gdb, and (3) understand how Knit has renamed (“mangled”) the names of the objects — the variables and functions — that make up the program. The rest of this chapter describes how Knit mangles the names of objects. Knit renames objects in different units to avoid name clashes. In particular, Knit prefixes every object name with a string that identifies the unit instance that contains the object. Knit assigns a unique name to every unit instance it creates as follows:

• The topmost unit instance — i.e., the instance of the unit named on the knit command line — has the same name as its unit definition.
• A named unit instance within a compound unit has a name of the form:

  parent _bundle

  bundle is the name of the first bundle exported by the unit instance. Within the link section of a compound unit definition, every unit instance exports at least one bundle, and all of the exported bundle names are unique. Therefore, bundle is a unique name within the compound unit.

  parent is the name of the “parent unit instance” — i.e., the name that Knit assigns to the instance of the containing compound unit. This name is, of course, determined by recursively applying these rules.

Every object that is not exported by the topmost unit instance is renamed by prepending the name of the unit instance in which the object is defined. The new name of the object is the name of this unit instance, followed by an underscore, followed by the object’s original name. For example, consider the following unit definitions:

If A is named as the topmost unit, then the three unit instances in the Knit-generated code are assigned the names:

A

The topmost unit instance.

A_v

The first instance of PQ within the instance A.

A_x

The second instance of PQ within A.

The instances of p and q are assigned the names:

A_v_p

The object p in the unit instance A_v.

A_v_q

The object q in the unit instance A_v.

A_x_p

The object p in the unit instance A_x.

A_x_q

The object q in the unit instance A_x.

The four names above are the names that you would use within your debugger to set breakpoints or examine variable values.

Final notes:

• In fact, gdb will let you use the original name of a function if it is unambiguous, but always requires the “fully qualified” name for variables.
• You may find it faster to locate a symbol by executing a command like this:
  
    nm *.a | grep free_number

  instead of applying the above rules to determine the name of the unit instance.