Sun WorkShop(TM) 6 Inremental Link Editor README
Updated 00/04/04
 
Contents 
  • Introduction
  • About Sun WorkShop 6 ild
  • New Features 
  • Software Corrections 
  • Problems and Work Arounds 
  • Limitations and Incompatibilities 
  • Documentation Errata 
  • Shippable Libraries 

  • Introduction

    Sun WorkShop 6 Release

    This document contains last minute information about Sun WorkShop 6 Incremental Link Editor, ild. It describes the software corrections addressed by this release and lists the known problems, limitations, and incompatibilities. 

    You can invoke the incremental link editor by typing the ild command at a shell prompt. 

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

    To access the HTML version of this document, point your Netscape(TM) Communicator 4 or compatible Netscape version browser to: 

        file:/opt/SUNWspro/docs/index.html 
    Note -  with the path to your Sun WorkShop installation directory. In a default If your Sun WorkShop software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system.

    For more information about this product, see: 

    • Sun WorkShop 6 Release Notes -- Describes installation-related and late-breaking information about this Final release. Information in the release notes overrides information in all readme files.
    • About Sun WorkShop 6 Documentation -- Describes the documentation available with this Sun WorkShop release and how to access it.
    • What's New in Sun WorkShop 6 -- Describes the new features in this release.
    • Full ild documentation can be found in the Sun WorkShop 6 C User's Guide.
    These documents are accessible in HTML by pointing your browser to file:/opt/SUNWspro/docs/index.html. If your Sun WorkShop software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system. 
    About Sun WorkShop 6 Incremental Link Editor

    Sun WorkShop 6 ild runs on SPARC(TM) processors running Solaris(TM) SPARC Platform Edition versions 2.6, 7, and 8, and Intel(R) x86 processors running Solaris Intel Platform Edition, versions 2.6, 7, and 8. 


    New Features

    This release of Sun WorkShop 6 ild includes the following new features - see the ild(1) man page for details:

    • Support for COMDAT -

    • COMDAT allows symbols to be defined in multiple modules.  The first module on a command line that defines a specific COMDAT symbol is selected as the defining module.  A COMDAT symbol with the same name, encountered in a module later on the command line, will be ignored. 
      On a relink, if the defining module of a COMDAT symbol has been  changed and no longer defines the COMDAT symbol, and if no module on the command line previous to the defining module is modified to supply the COMDAT symbol, then a FULL LINK must be done.
      See the Solaris "Linker and Libraries Guide" for details about COMDAT.
    • Partially Initialized Symbols -

    • With Solaris 7, ld accepts a construct allowing for symbols to be partially initialized.  In this manner, such elements as very large sparse matrixes can be initialized at runtime rather than allocating a large area in the a.out file for the symbol, when most of the values are 0. 

      Using this facility, compilers, linkers, and the runtime linker (RTLD) are capable of specifying how large arrays are initialized, without actually initializing them in the a.out file.  The action can result in significant savings in the size of the a.out file.

      Several notes should be made when considering this capability:

        1) It can only be used for dynamically linked executables since it is RTLD that does the initializations so that the program can use the data.
        2) While there may be a savings in execution time for the compilers and the linkers, there is added cost during the startup of the a.out executable since RTLD must initialize the symbol.  The benefits depend on the symbol and how populated it is with data.
    Features Introduced in the Sun WorkShop 5.0 Release:
    The following ild features were introduced in the previous release of Sun WorkShop and are listed here for reference:
    0. Support for building
    a. 32-bit executables on a 32-bit machine. 
    b. 64-bit executables on a Solaris 7 kernel booted in 32-bit mode. 
    c. 64-bit executables on a Solaris 7 kernel booted in 64-bit mode.

    1. LD_LIBRARY_PATH_64    Introduced in Solaris 7, this environment variable is similar to    LD_LIBRARY_PATH but overrides it when searching for 64-bit dependencies.

       When running Solaris 7 on a SPARC processor and linking in 32-bit mode,    LD_LIBRARY_PATH_64 is ignored.  If only LD_LIBRARY_PATH is defined, it is       used for both 32-bit and 64-bit linking.  If both LD_LIBRARY_PATH and    LD_LIBRARY_PATH_64 are defined, the 32-bit linking will be done using    LD_LIBRARY_PATH and the 64-bit linking using LD_LIBRARY_PATH_64.

    2. -z allextract | defaultextract | weakextract    
    Alter the extraction criteria of objects from any archives that follow.    By default archive members are extracted to satisfy  undefined references and to promote tentative definitions with data definitions. Weak symbol references do not trigger extraction. Under 
    -z allextract  all archive members are extracted from the archive. Under 
    -z weakextract weak references trigger archive extraction.  
    -z defaultextract provides a  means of returning to the default following use of the former extract options. 

    3. $ORIGIN token correctly passed to Runtime linker.    See the Solaris Linker and Libraries Guide for details. 

    4. Register Symbols:   ild supports named and scratch register symbols as    defined in the SPARC V9 ABI. A new set of messages are provided to    detail any errors due to the illegal use of these symbols. Register    symbols may be added on relinks, but if an object file that already    had a register symbol definition is modified, a full link must be done. 



    Software Corrections

    Reported bugs fixed in this release:

    4194951 "../src/ild-common.h", line 79: cannot find include file: "ild-regsym.h"

    4196586 V9: regression: __exdbg_notify_of_throw provides null catch_description - .ex_shared and .exception_ranges corruption 

    4199709 ild: Fatal error -- signal 11. Exiting.   ps_call_ild() overwrite of buffer newname by 1 byte (\0 forgotten). 

    4200410 full relink if change any input file containing a  scratch register symbol -SPARC 

    4205569 ILD problem on V9 relink, file to big when plenty of room (related 4204595-jeanko bug) 

    4221151 ild: Fatal error -- Assertion failed:  file "../src/ild-symtab.c" line 102[24]  { COMDAT capability missing } 

    4230791 Partially Initialized Symbols AKA Partially Initialized Common Blocks 

    4255617 DT_SPARC_REGISTER has invalid value associated with it. - LD bug#4254171 

    4262328 (warning) ild: removing potentially corrupted file gamma_g / Fatal error

    4263566 Occasionally ILD doesn't supply _START_ and _END_ : c++ 

    4265346 overwrites read-only file 


    Problems and Work Arounds

    This section discusses the following software bugs that could not be fixed in time for this release. (Check Hot News for Sun WorkShop 6 (http://www.sun.com/workshop/users/ws.html) for updated information): 

    The following are ILD issues in this release:

    * C++ COMDAT:
    C++ will be have an option to use COMDAT for template instantiations. C++ will be using extensions to the original RFE for COMDAT that are supported by LD(1), but not by ILD(1).  For this reason, when the compiler uses the COMDAT template-instantiation option, it must not         call ILD as its linker.

    * 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 the section on ild  Relink Messages in the chapter on incremental linking in the Sun WorkShop 6 C User's Guide.

    * Normally, ILD is used when the developer compiles with the -g   optimization level.  At this optimization level, register symbols are   not used.

      ILD currently supports an add-only policy for register symbol   definitions.  This policy means that if an object (*.o file) uses   register symbols, then a modification of that file will cause ILD to do   a full link, rather than an incremental link.

      Compiling with an optimization level other than -g can result in the   use of register symbols.  Therefore, care should be exercised to obtain   the full benefits of ILD whLD when used with programs not compiled with   -g.

    Other known software bugs:
       1. ild uses the time stamp 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 
    % 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");
    }


    Limitations and Incompatibilities

    There is no new information at this time. 


    Documentation Errata 

    There is no new information at this time. 


    Shippable Libraries

    If your executable uses a Sun dynamic library listed in the file named below, your license includes the right to redistribute the library to your customer.

    <install-directory>/SUNWspro/READMEs/runtime.libraries
    In a default install of Sun WorkShop, <install-directory> will be /opt
    You may not redistribute or otherwise disclose the header files, source code, object modules, or static libraries of object modules in any form.

    The License to Use appears in the End User Object Code License, viewable from the back of the plastic case containing the CDROM. 


    Copyright 2000 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303, U.S.A. All rights reserved. Sun, Sun Microsystems, the Sun logo, docs.sun.com, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries.