Static Linking

From Freepascal Amiga wiki
Revision as of 14:13, 17 September 2016 by Molly (talk | contribs) (→‎introduction: Add initial content)
Jump to navigation Jump to search

This topic is about static linking against AROS sdk libraries/objects with FPC compiler.

First let's take this moment here to inform that the acquired information and results could not have been obtained and created without the really fantastic help and support provided by AROS developer Deadwood. We can't thank him enough for his patience and shared knowledge. Also a big thank you to Chain-Q for helping us through this process by implementing new calling mechanism support in FPC for AROS.


When source-code is compiled by the compiler, there is a special program being used to accomplish the task of generating a workable executable for you. That program is called a linker.

Wikipedia explains what is a linker:
In computing, a linker or link editor is a computer program that takes one or more object files generated by a compiler and combines them into a single executable file, library file, or another object file.

And on the topic of static linking wikipedia writes:
Static linking is the result of the linker copying all library routines used in the program into the executable image. This may require more disk space and memory than dynamic linking, but is more portable, since it does not require the presence of the library on the system where it is run.

TODO: add links to wiki articles

The latter description being what we would like to accomplish with Free Pascal and AROS. The AROS SDK comes accompanied with quite some interesting available static libraries which we would like to use. Besides the SDK, the AROS archives also contains static libraries that were ported to AROS.

Linking and Free Pascal

Free Pascal is just like any other compiler out there in that it uses the binutils provided linker (ld, or in the specific case of AROS it calls ld indirectly using the collect-aros binutil) in order to link against (static) objects in order to incorporate the linked code into the final produced executable.

An important thing to realize before any attempt is made to link against object files, is that the compiler is to be told where exactly it is able to locate those objects (in case you do not have them lined up side by side to your source-code).

TODO: Add links to setting up paths

Some keywords with regards to linking and Free Pascal

  • directive {$LINK}
  • directive {$LINKLIB}

TODO: Add links to keywords

Some (Free Pascal) caveats:

  • The Free Pascal compiler is only able to show linker results when the main program source is compiled
  • The Free Pascal compiler will only link when at least one functionality of the static libraries is actually invoked inside your code. Just linking against the object(s) does not necessarily means the linker will link in all the requested objects.
  • When exported symbols are not 'used' in the eyes of the compiler, they will get optimized away, even when optimizations are turned off. This is a very important caveat to realize and it requires some trickery in order to force the compiler to do our bidding.

There are also some additional caveats depending on which linking method is being used, for that please refer to their corresponding paragraphs which describes those caveats.


In the process of experimenting with this topic different approaches were taken in order to achieve results.

It is always a bit of a difficult spot to give a name to something that was recently accomplished as the mind is still full of impressions focused on accomplishing a single goal, thereby losing oversight of the bigger picture (so in case reader has a better name for them, please feel free to suggest). So, at first idea i describe the different approaches:

  • Method 1: controlled linking with FPC
  • Method 2: 'Abuse' AROS' default startup/linking system

Linking Method 1

For a practical example see ...

Linking Method 2

For a practical example see ...