-qmkshrobj

Description

Creates a shared object from generated object files.

Syntax

Read syntax diagramSkip visual syntax diagram>>- -q--mkshrobj--+-------------+------------------------------><
                  '-=--priority-'

where priority specifies the priority level for the file. priority may be any number from -214782623 (highest priority-initialized first) to 214783647 (lowest priority-initialized last). Numbers from -214783648 to -214782624 are reserved for system use. If no priority is specified the default priority of 0 is used. The priority is not used when linking shared objects (using the xlc command) written in C.

Notes

This option, together with the related options described below, should be used instead of the makeC++SharedLib command to create a shared object. The advantage to using this option is that the compiler will automatically include and compile the template instantiations in the tempinc directory.

The following table shows equivalent options between makeC++SharedLib and -qmkshrobj:

makeC++SharedLib options -qmkshrobj and related options
-p nnn -qmkshrobj=nnn
-e file_name -qexpfile=file_name
-E export_file -bE:export_file
-I export_file -bI:export_file
-x -qnolib
-x 32 -q32
-x 64 -q64
-n entry_point -e entry_point

The compiler will automatically export all global symbols from the shared object unless one explicitly specifies which symbols to export with the -bE:, -bexport: or -bexpall options.

The priority suboption has no effect if you link with the C or C++ compiler, or if the shared object has no static initialization.

Specifying -qmkshrobj implies -qpic.

Also, the following related options can be used with the -qmkshrobj compiler option:

-o shared_file Is the name of the file that will hold the shared file information. The default is shr.o.
-qexpfile=filename Saves all exported symbols in filename.  This option is ignored unless xlc++ automatically creates the export list.
-e name Sets the entry name for the shared executable to name.  The default is -enoentry.

If you use -qmkshrobj to create a shared library, the compiler will:

  1. If the user doesn't specify -bE:, -bexport:, -bexpall or -bnoexpall, create an export list containing all global symbols using the CreateExportList command, described below. You can specify another script with the -tE/-B or -qpath=E: options.
  2. If CreateExportList, described below, was used to create the export list and -qexpfile was specified, the export list is saved.
  3. Call the linkage editor with the appropriate options and object files to build a shared object.
CreateExportList Command

The CreateExportList command creates a file containing a list of global symbols found in a given set of object files.

Read syntax diagramSkip visual syntax diagram>>-CreateExportList--+-----+--exp_list--+- -f--file_list-+--+-------------+-><
                     '- -r-'            '-obj_files------'  |      .-32-. |
                                                            '- -X--+-64-+-'

Parameters for the CreateExportList command are as follows:

-r If specified, template prefixes are pruned. The resource file symbol (__rsrc) is not added to the resource list.
exp_list The name of a file that will contain a list of global symbols found in the object files. This file is overwritten each time the CreateExportList command is run.
-f file_list filelist is the name of a file that contains a list of object filenames.
obj_files One or more names of object files.
-X32 Generates names from 32-bit object files in the input list specified by -f file_list or obj_files. This is the default.
-X64 Generates names from 64-bit object files in the input list specified by -f file_list or obj_files.

The CreateExportList command creates an empty list if any of the following are true:

Example

The following example shows how to construct a shared library containing two shared objects using the -qmkshrobj option, and the AIX ar command. The shared library is then linked with a file that contains the main function. Different priorities are used to ensure objects are initialized in the specified order.

The diagram below shows how the objects in this example are arranged in various files.

The first part of this example shows how to use the -qpriority=N option and the #pragma priority(N) directive to specify the initialization order for objects within the object files.

The example shows how to make two shared objects: animals.o containing object files compiled from house.C, farm.C, and zoo.C, and fish.o containing object files compiled from fresh.C and salt.C. The -qmkshrobj=P option is used to specify the priority of the initialization of the shared objects.

The priority values for the shared objects are chosen so that all the objects in fish.o are initialized before the objects in myprogram.o, and all the objects in animals.o are initialized after the objects in myprogram.o.

To specify this initialization order, follow these steps:

  1. Develop an initialization order for the objects in house.C, farm.C, and zoo.C:
    1. To ensure that the object lion L in zoo.C is initialized before any other objects in either of the other two files, compile zoo.C using a -qpriority=N option with N less than zero so that the lion L object has a priority number less than any other objects in farm.C and house.C:
      xlc++ zoo.C -c -qpriority=-42
    2. Compile the house.C and farm.C files without specifying the -qpriority=N option so objects within the files retain the priority numbers specified by their #pragma priority(N) directives:
      xlc++ house.C farm.C -c 
    3. Combine these three files in a shared library. Use xlc++ -qmkshrobj to construct a library animals.o with a priority of 40:
      xlc++ -qmkshrobj=40 -o animals.o house.o farm.o zoo.o
  2. Develop an initialization order for the objects in fresh.C, and salt.C:
    1. Compile the fresh.C and salt.C files:
      xlc++ fresh.C salt.C -c
    2. To assure that all objects in fresh.C and salt.C are initialized before any other objects, use xlc++ -qmkshrobj to construct a library fish.o with a priority of -100.
      xlc++ -qmkshrobj=-100 -o fish.o fresh.o salt.o
      Because the shared library fish.o has a lower priority number (-100) than animals.o (40), when the files are placed in an archive file with the ar command, their objects are initialized first.
  3. Compile myprogram.C that contains the function main to produce an object file myprogram.o. By not specifying a priority, this file is compiled with a default priority of 0, and the objects in main have a priority of 0.
    xlc++ myprogram.C -c
  4. To create a library that contains the two shared objects animals.o and fish.o, you use the ar command. To produce an archive file, libzoo.a, enter the command:
    ar -rv libzoo.a animals.o fish.o
    where:
    rv  The ar options. -r replaces a named file if it already appears in the library, and -v writes to standard output a file-by-file description of the making of the new library.
    libzoo.a  Is the name you specified for the archive file that will contain the shared object files and their priority levels.
    animals.o
    fish.o
    Are the two shared files you created with xlc++ -qmkshrobj.
  5. To produce an executable file, animal_time, so that the objects are initialized in the order you have specified, enter:
    xlc++ -oanimal_time myprogram.o -L -lzoo
  6. The order of initialization of the objects is shown in the following table.
    Order of Initialization of Objects in libzoo.a 
    File Class Object Priority Value Comment
    "fish.o"   -100 All objects in "fish.o" are initialized first because they are in a library prepared with -qmkshrobj=-100 (lowest priority number, -100, specified for any files in this compilation)
    "shark S" -100(-200) Initialized first in "fish.o" because within file, #pragma priority(-200) specifies the highest priority.
    "trout A" -100(-80) #pragma priority(-80)
    "tuna T" -100(10) #pragma priority(10)
    "bass B" -100(500) #pragma priority(500)
    "myprog.o"   0 File generated with priority 0.
    "CAGE" 0(0) Object generated in main with priority 0.
    "animals.o"   40 File generated with -qmkshrobj=40
    "lion L" 40(-42) Initialized first in file "animals.o" compiled with -qpriority=-42.
    "horse H" 40(0) Follows with priority of 0 (since -qpriority=N not specified at compilation and no #pragma priority(N) directive).
    "dog D" 40(20) Next priority number (specified by #pragma priority(20))
    "zebra Z" 40(50) Next priority number from #pragma priority(50)
    "cat C" 40(100) Next priority number from #pragma priority(100)
    "pig P" 40(500) Next priority number from #pragma priority(500) (Initialized last)

    You can place both nonshared and shared files with different priority levels in the same archive library using the ar command.