StackThreads/MP: version 0.77 User's Guide

7.2: STLINK: A Wrapper for Linker

stlink is a command that is invoked from stgcc. It is again a shell script that eventually calls a linker (it actually calls gcc or g++). When an assembly file is postprocessed, stgcc generates pieces of information about procedures in the file and attaches them in the assembly file. The assembly file is then compiled into an object file. At link time, stlink collects all these tables and generate a single table that point to tables of all files. The table is generated in a form of a C source file, compiled by gcc (by default), and then linked together with all other files. It also collects thread startup hooks and worker startup hooks and generate a table of them.

Since this command is implicitly invoked by stgcc, it should be usually of no interest for the programmer. We nevertheless describe it for its potential use in debugging strange link-time errors.

Accepted command line options are again the same as those of gcc or g++ (specified by --linker= option described below). Most options are passed as is to gcc or g++. Here is the list of options specific to stlink.

1. --dbg shows the command lines of the invoked subcommands. If you get a strange link time error, run the same command with this option. You normally implicitly use stlink from stgcc, you may not know how stlink is invoked. In this case, first run stgcc with --dbg option and see its output. You will find a line that invokes stlink. Copy the line and add --dbg option.
2. --linker=cc specifies the underlying linker (which actually must be either gcc or g++) invoked by stlink. The default is gcc.
3. --compiler=cc specifies the compiler used to compile the generated table file. The default is gcc and I don't think of any reason why you have to change this (even if you are linking C++ programs).

We describe a little more details about its semantics and machinery. It collects all procedure tables and thread/worker startup hooks from files specified via explicit filenames (such as xxx.o or xxx.a) or libraries found under explicit search pathos (via -Lxxx). For example,

stlink a.o b.a c.o -L. -L../lib -lmylib

c.o which are assumed to be found in the current directory and may collect them also from libmylib.a, if it is found in the current directory (.) or ../lib directory. Tables and hooks in libmylib.a will not be collected when it is found in other directories that do not explicitly appear in the command line. Specifically, standard libraries such as libc or pthread are not examined. In short, stlink does not know standard library search paths.

stlink uses nm command to collect tables and hooks from object files. For each file to be examined, it invokes nm and scans the output to find the table and hooks. Simple naming rules are assumed to find them. A surprising thing might occur when you accidently use names that are recognized as hooks or tables. To list them,

• Any static symbol in data segment (initialized static variable) whose name ends with _proc_info is assumed to be the name of the procedure table of the file.
• Any global symbol in text segment (external procedure) whose name begins with sthreads_thread_start_hook_ is assumed to be a name of a thread startup hook.
• Any global symbol in text segment (external procedure) whose name begins with sthreads_worker_start_hook_ is assumed to be a name of a worker startup hook.