Linking your modules

To link your application against a library, use the -l option to qcc, omitting the lib prefix and any extension from the library's name. For example, to link against libsocket, specify -l socket. You can specify more than one -l option. The qcc configuration files might specify some libraries for you; for example, qcc usually links against libc. The description of each function in the BlackBerry 10 OS Library Reference tells you which library to link against. By default, the tool chain links dynamically.

If you want to link statically, then you should specify the -static option to qcc, which will cause the link stage to look in the library directory only for static libraries (identified by a .a extension).

For this release of BlackBerry 10 OS, you can't use the floating point emulator (fpemu.so) in statically linked executables.

Although we generally discourage linking statically, it does have this advantage: in an environment with tight configuration management and software QA, the very same executable can be regenerated at link time and known to be complete at runtime.

To link dynamically (the default), you don't have to do anything.

To link statically and dynamically (some libraries linked one way, other libraries linked the other way), the two keywords -Bstatic and -Bdynamic are positional parameters that can be specified to qcc. All libraries specified after the particular -B option will be linked in the specified manner. You can have multiple -B options:

qcc ... -Bdynamic -l1 -l2 -Bstatic -l3 -l4 -Bdynamic -l5

This will cause libraries lib1, lib2, and lib5 to be dynamically linked (that is, will link against the files lib1.so, lib2.so and lib5.so), and libraries lib3 and lib4 to be statically linked (that is, will link against the files lib3.a and lib4.a).

You may see the extension .1 appended to the name of the shared object (that is, libc.so.1). This is a version number. Use the extension .1 for your first revision, and increment the revision number if required.

You might want to use the above mixed-mode linking because some of the libraries you are using are needed by only one executable or because the libraries are small (less than 4 KB), in which case you are wasting memory to use them as shared libraries. Note that shared libraries are typically mapped in 4-KB pages and require at least one page for the text section and possibly one page for the data section.

When you specify -Bstatic or -Bdynamic, all subsequent libraries are linked in the specified manner.

Creating shared objects

To create a shared object suitable for linking against:

  1. Compile the source files for the library using the -shared option to qcc.
  2. To create the library from the individual object modules, simply combine them with the linker (this is done via the qcc compiler driver as well, also using the -shared command-line option).

Make sure that all objects and static libs that are pulled into a .so are position-independent as well (that is, also compiled with -shared).

If you make a shared library that has to static-link against an existing library, you can't static-link against the .a version (because those libraries themselves aren't compiled in a position-independent manner). Instead, there's a special version of the libraries that has a capital S just before the .a extension. For example, instead of linking against libsocket.a, you link against libsocketS.a. You shouldn't static-link, but rather link against the .so shared object version.

Specifying an internal name

When you're building a shared object, you can specify the following option to qcc:

"-Wl,-h name"

(You might need the quotes to pass the option through to the linker intact, depending on the shell.)

This option sets the internal name of the shared object to name instead of to the object's pathname, so use name to access the object when dynamically linking. You might find this useful when doing cross-development (that is, from a Windows system to a BlackBerry 10 OS target).

Last modified: 2014-12-11



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus