FindSymbols

FindSymbols reports the shared libraries that contain the specified symbols.

Syntax

    FindSymbols [ -match_substrings ] [ 'symbol' ... ]

Arguments -match_substrings Enables substring searches, a very slow operation. By default, FindSymbols searches by exact match.
'symbol' The mangled, demangled, or mixed-form symbol to locate. The argument must be enclosed in single quotes (').

Usage

Use FindSymbols when MakeSharedLib or MakeSharedApp reports unresolved symbols, and you want to know which libraries you should add to the link list in your *.PinkMake file.

The first time you run FindSymbols, it builds a cache file: $TaligentExports/_AllSymbols. Subsequent runs consult that cache file. To rebuild or update the file, delete it and rerun FindSymbols. When you install a new build, InterimInstall should delete the cache.

NOTE If FindSymbols can't locate a symbol that you are certain exists, the symbol is probably an inline. There is no way to find inlines, because they are compiled into client code, as opposed to being compiled into and exported from a library for use by clients.

Because the implementation of an inline must be compiled with the header, you should be able to find the inline declaration if you do enough searching: it will be hidden either down near the bottom of the header or in another file that is an #include in the header (typically similar to "XXXXImp.[ih]").

A compiler is free to not inline an inline if doing so would generate worse code. This means that some symbols declared inline might not actually be inlined, and they can wind up compiled into and exported from a library which, if not in the *.PinkMake's link list, would lead to an unresolved symbol error.

Examples

Typically you will use FindSymbols to locate the library that caused an "Undefined symbol" error when your build fails. For example, Makeit might list errors for undefined symbols encountered when MakeSharedLib executes. In the messages, look for errors like these below the MakeSharedLib command line:

      ... MakeSharedLib -o JustAViewLib ...
  ld: 0711-317 ERROR: Undefined symbol: .TGArea::~TGArea()
  ld: 0711-317 ERROR: Undefined symbol: .TRGBColor::~TRGBColor()
  ld: 0711-317 ERROR: Undefined symbol: .TGRect::~TGRect()
  ld: 0711-317 ERROR: Undefined symbol: __vtt12TContentView
To find the library files in which these symbols are defined, run FindSymbols and specify the symbol exactly as it appears in the error listing. The symbol name must be enclosed within single quotes (`).

    FindSymbols `.TGArea::~TGArea()`
Which produces a listing like this:

    TGArea::~TGArea(): HighLevelAlbert This is the unique set of libraries identified: HighLevelAlbert
This listing indicates that the symbol is in HighLevelAlbert.

To look for multiple symbols at once, include each as a separate argument on the FindSymbols command line:

    FindSymbols `.TRGBColor::~TRGBColor()` `.TGRect::~TGRect()` `__vtt12TContentView`
Which produces this listing:

    TRGBColor::~TRGBColor(): LowLevelAlbert TGRect::~TGRect(): CommonAlbert HighLevelAlbert __vtt12TContentView: NewGraphicApplicationLib This is the unique set of libraries identified: CommonAlbert HighLevelAlbert LowLevelAlbert NewGraphicApplicationLib
Notice that TGRect::~TGRect(): appears in CommonAlbert and HighLevelAlbert. When you get multiple libraries, you probably need to include only one. Try one, and if you still get errors for the symbol, try the other. In a worst case, include both. This example needed only HighLevelAlbert.

It's also possible to find symbols before using Makeit. To do so, you must take a symbol from C++ code and put it into the canonical form used by the linker. This isn't easy. Here are some rules for functions that work 80 to 90% of the time:

  1. Remove the return value.
  2. Preface the function with the ClassName followed by "::".
  3. Remove all argument names.
  4. Remove all whitespace, except:
    1. There should be exactly one blank after all const keywords inside a function's argument-parenthesis.
    2. There should be exactly one blank after a function's closing parentheses ")" and before a const keyword.
For example:

      class TSomeClass {
      int SomeFunc( const TSomeType* someArg,
                      TOtherType& otherArg ) const;
  }
becomes:

    TSomeClass::SomeFunc(const TSomeType*,TOtherType&) const
Complications creep in when one or more of the types involved are #defines or typedefs. In such cases, it's better to choose a different function.

With practice, you can use this technique well, and can even find other kinds of symbols (enums, for example). This may seem like a lot of work, but at least you don't have to keep running the linker.

Use this technique when you have a program that is already compiled and working, and you are adding new functionality to it. Then you have a good idea of what new symbols you've introduced, and what symbols to search for.

[Contents] [Previous] [Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.

Generated with WebMaker