| **Circular references with static libraries** |
| |
| Some linkers are one-pass only so to handle circular references between |
| static libraries, the following feature can be used: |
| |
| ``RESCAN`` |
| The specified static libraries are searched repeatedly until no |
| new undefined references are created. Normally, an static library is searched |
| only once in the order that it is specified on the command line. If a symbol |
| in that library is needed to resolve an undefined symbol referred to by an |
| object in an library that appears later on the command line, the linker would |
| not be able to resolve that reference. By grouping the static libraries, they |
| all be searched repeatedly until all possible references are resolved (use |
| linker options ``--start-group`` and ``--end-group`` or, on ``SunOS``, |
| ``-z rescan-start`` and ``-z rescan-end``). |
| |
| Using this feature has a significant performance cost. It is best to use it |
| only when there are unavoidable circular references between two or more |
| static libraries. |
| |
| This feature is available on ``Linux``, ``BSD``, and ``SunOS`` target |
| platforms as well as ``Windows`` when ``GNU`` toolchain is used. |
