

August 1996
                        <Incremental Link Editor (ild)>            
                         
=============================================================================

Introduction: The Incremental Link Editor (ild) replaces link editor ld 
for incremental linking.



Table of Contents:
          A. New Features
          B. Changes to Features 
          C. Software Incompatibilities
          D. Current Software Bugs
          E. Fixed Software Bugs
          F. Documentation Errata
       
____________________________________________________________________________
A. New Features

The Incremental Link Editor (ild) is allows you to complete the
development sequence (the edit, compile, link, and debug loop)
efficiently and more quickly than by using a standard linker.

____________________________________________________________________________
B. Changes to Features

In the original release, the compilation systems would only invoke ild 
in place of ld when given the option "-xildon".

For this (and most recent previous) release, the compilation systems
also invoke ild in place of ld when the "-g" option (whose normal use
is to instruct the compiler to output debugging information) is given,
UNLESS any of the following are true:

	+ the "-G" option (produce a shared library) was given
	+ the "-xildoff" option is present
	+ any source files are named on the command line

____________________________________________________________________________
C. Software Incompatibilities

When ild is invoked to create shared objects, ild invokes ld to do the link.

Do not use ild to produce the final production code for shipment. ild makes 
the file larger because parts of the program have been spread out due to 
padding. Because of the padding and additional time required to link, it is 
recommended that you do not use the -xildon option for production code.

ild may not link small programs much faster, and the increase in size of the 
executable is greater than that for larger programs.

Third party tools that work on executables may have unexpected results on 
ild produced binaries.

Any program that modifies an executable, for example strip or mcs, might 
affect the ability of ild to perform an incremental link. When this happens, 
ild issues a message and performs an initial link. See "ild Relink Messages", 
"Example 2: running strip," of the "Incremental Link Editor (ild)"
manual.

____________________________________________________________________________
D. Current Software Bugs
  

1. ild uses the timestamp associated with an archive library object file to 
determine which files have been updated. If multiple definitions of the same 
symbol do not exist in any of the libraries, ild works correctly. However, 
multiple definitions of the same symbol in one or more libraries can confuse 
ild. In these cases, ild may silently produce an incorrect program. 

2. The -m option produces a memory map, but it does not produce a listing of 
the nonfatal multiply-defined symbols on the standard output. 

3. Once an object file is extracted from an archive file and linked into an 
incremental executable, that object file remains in the executable, even if 
all references to it are removed, until the next initial link. In the test 
case shown here, the first link has a reference to myfunc1 and myfunc2. Both
one.o and two.o are correctly extracted from the archive. See code at the 
end of the bug description.

% cc -c main1.c main2.c one.c two.c
main1.c:
main2.c:
one.c:
two.c:

% cc -c main1.c main2.c one.c two.c 
% ar cr libfoo.a one.o two.o        
% rm -f a.out
% cp main2.o main.o			# references myfunc1 and myfunc2
% cc -xildon main.o libfoo.a		# first link (initial link)
% ./a.out
Calling myfunc1!
myfunc1 called!
Calling myfunc2!
myfunc2 called!
% nm a.out | grep myfunc
[59]    |     68912|      32|FUNC |GLOB |0    |8      |myfunc1
[60]    |     68960|      32|FUNC |GLOB |0    |8      |myfunc2

In the second link, myfunc2 is no longer referenced but it still appears in the 
executable (as well as any other symbols defined in two.o). Then by removing 
the a.out, a new initial link is forced which the third link demonstrates as no 
longer containing myfunc2.

% cp main1.o main.o          		# myfunc2 no longer referenced
% cc -xildon main.o libfoo.a 		# second link (incremental link)
% ./a.out
Calling myfunc1
myfunc1 called!
% nm a.out | grep myfunc     
[59]    |     68912|      32|FUNC |GLOB |0    |8      |myfunc1
[60]    |     68960|      32|FUNC |GLOB |0    |8      |myfunc2


                                        # Removing a.out fixes the problem.

% rm a.out				# force a new initial link
% cc -xildon main.o libfoo.a 		# third link (initial link)
% nm a.out | grep myfunc     
[58]    |     68832|      32|FUNC |GLOB |0    |8      |myfunc1

The scenarios that can cause problems are: 

Some symbols defined by two.o are defined elsewhere in the program, and 
including two.o either gets the wrong definition or a multiply-defined 
symbol error. 

dbx and other tools that examine the a.out still detect that two.o is 
included. For example, if you run dbx on the output of the second link, you 
can request stop in myfunc2. This is not really a problem, but it can be 
confusing.

It is possible to also have cascading errors. That is, two.o can contain the only 
reference in the program to symbols that appear in other object files of the 
archive, causing more object files to be extracted unnecessarily. These new 
archives can suffer from any of the problems listed above, as well.

PROGRAM CODE:

% cat main1.c
#include <stdio.h>
extern void myfunc1(void);

int main(void)
{

	(void)printf("Calling myfunc1\n"); myfunc1();
	return 0;

}

% cat main2.c
#include <stdio.h>

extern void myfunc1(void), myfunc2(void);

int main(void)
{

	(void)printf("Calling myfunc1!\n"); myfunc1();
 	(void)printf("Calling myfunc2!\n"); myfunc2();
	return 0;

}

% cat one.c
#include <stdio.h>

void myfunc1(void)
{

		(void)printf("myfunc1 called!\n");

}

% cat two.c
#include <stdio.h>

void myfunc2(void)
{

	(void)printf("myfunc2 called!\n");

}

____________________________________________________________________________
E. Fixed Software Bugs

Fixed various bugs found during internal testing.
____________________________________________________________________________
F. Documentation Errata
 
No documentation errata.

