![]() |
![]() |
![]() |
|
![]() | |
![]() |
![]() |
![]() |
![]() |
![]() |
Log In | Not a Member? |
Support
![]() |
![]() |
SYNTAX
PPCLink filename1 [filename2]
DESCRIPTION You use the PPCLink tool to link compiled object files, static libraries, and shared libraries into a static library, a shared library, a drop-in addition, or an executable code fragment such as an application. You can mix options and filenames on the command line. By default, PPCLink keeps object files in memory in purgeable handles. This minimizes I/O time and improves performance. However, if linking fails because the linker ran out of memory, you should use the -linkfaster off option. When using PPCLink to build an accelerated resource, you must specify the -packdata off and -term none command line options. INPUT Object files of type 'XCOF', static libraries of type 'XCOF', and shared libraries of any type. The PPCLink tool does not accept standard input. OUTPUT A static library, a shared library, a drop-in addition, or an executable code fragment with the default name PPCLink.out. To give the output file a more meaningful name, use the -o option. STATUS
PPCLink can return the following status codes:
PARAMETERS filename1 [filename2] Specifies one or more object files, static libraries, and shared libraries to be linked. OPTIONS -ac n Aligns code modules on n-byte (minimum) boundaries. The value of n must be a power of 2. By default, code modules are aligned on 4-byte (minimum) boundaries. -ad n Aligns data modules on n-byte (minimum) boundaries. The value of n must be a power of 2. By default, data modules are aligned on 4-byte (minimum) boundaries. -blocksize n Specifies the maximum number of 512-byte blocks to read/write at one time. This option can be used to increase the frequency of SpinCursor calls when linking large files. -c creator Sets the output file creator to creator. The default creator depends on the setting of the -outputformat option, as follows: 'MPS ' if -outputformat xcoff '????' if -outputformat pef -codeorder source | staticcall | reference | segment | file=filename Specifies the order in which functions are written to the output file. source Writes the functions in the order in which they appear in the input files on the command line. staticcall Writes the functions in the order they appear to be called, as inferred from the static link information. Thus, if function A calls B and C, and B calls D, the functions are written in the order A B D C. Though not guaranteed, -codeorder staticcall may improve locality of reference and yield a minor performance improvement. reference Writes the functions in the order they appear during a graph traversal. Thus, if function A calls B and C, and B calls D, the functions are written in the order A B C D. segment Groups the functions into "segments" as specified by the .segment sections of the input files. Within each "segment" the functions are written in the order in which they appear in the input files on the command file. This is the default. file=filename Writes the functions in the order specified by the text file filename. You can write this file yourself or generate one using the MrPlus tool. The file should contain one function name per line. If a function has local scope, its name must be followed by a space or tab and then the name of the XCOFF file that contains the function. Note that the mangled function names must be used for C++ functions. Lines beginning with "#" or "*" are treated as comments. -codestart address Sets the base address of the .text/Code section to address. -d Suppresses warning messages for duplicate symbol definitions. -datastart address Sets the base address of the data section to address.
-dead on | off Specifies whether unused code and data is excluded from the output file. on Excludes unused code and data. off Includes unused code and data. The default setting for this option depends on the setting of the -xm option as follows: on if -xm executable, -xm sharedlibrary, or -xm dropin off if -xm library -@export filename Specifies a text file that contains a list of symbols to be exported from the output file. The file should contain one symbol name per line. Lines beginning with "#" or "*" are treated as comments. Only global data modules, global code modules and imported symbols may be exported. Exported symbols are forced active and therefore will not be dead-stripped if they are not referenced. C++ users must specify the mangled symbol names in the file. -export name[,name] Exports the specified symbols--that is, makes the symbols visible to other fragments. This option applies only to executable programs and shared libraries; you cannot export a symbol from a static library. Only global data modules, global code modules and imported symbols may be exported. Exported symbols are forced active and therefore will not be dead-stripped if they are not referenced. C++ users must specify the mangled symbol names. -exportglue on | off Specifies whether glue code should be generated for calls to exported routines. Note that if a routine is marked as both exported and imported, calls to the routine will always go through glue code regardless of the setting of this option. on Generates glue code for calls to exported routines. If a branch to an exported routine is followed by a TOC reload slot (a NOP instruction), the branch will go through the glue code. Otherwise, the branch will go directly to the exported routine. Note that all generated glue code is written to the output file even if the glue code is not used. off Does not generate glue code for calls to exported routines. All calls to exported routines become direct branches even if the call site is followed by a TOC reload slot (a NOP instruction). This option can result in smaller and faster code, however, exported routines will not be patchable. -@filelist filename Links the files listed in the specified text file. The text file should contain one filename per line. This option can be used instead of, or in addition to, specifying input files on the command line. -fragname fragName Sets the PEF container's fragment name to the specified name. The default is to use the name of the output file minus any directory information. For example, if you are creating a shared library named MySharedLib, but the output file is named MySharedLib.ppc, you would specify -fragname MySharedLib to ensure that the library's fragment name is set correctly. -h[elp] Displays a brief summary of PPCLink options. This option overrides all other options. -@ignoredups filename Suppresses "duplicate symbol definition" warnings for the symbols listed in the specified text file. The file should contain one symbol name per line. Lines beginning with "#" or "*" are treated as comments. C++ users must specify the mangled symbol names in the file. -ignoredups name[,name] Suppresses "duplicate symbol definition" warnings for the specified symbols. C++ users must specify the mangled symbol names. -init default | none | initEntry Specifies the initialization entry point of the output file. default Sets the initialization entry point to the default initialization routine, if the routine is defined in any of the files being linked. The default initialization routine is __init_app for executables and __init_lib for shared libraries. If the default routine does not exist, the initialization entry point is set to NULL. none Sets the initialization entry point to NULL. initEntry Sets the initialization entry point to the specified routine. -initbefore fragName[,fragName] Tells the Code Fragment Manager to initialize the specified import libraries before other import libraries. Use this option only when the initialization of an import library depends on the prior initialization of another import library. By default, the Code Fragment Manager initializes an import library before the client importing it. This rule is applied recursively. For mutually dependent import libraries, the Code Fragment Manager arbitrarily initializes one of the import libraries first. You can use this option to indicate which library should be initialized first. Be sure to specify the library's fragment name--that is, the name that appears in the library's 'crfg' resource--and not the name of the file containing the library. -librename old=new Replaces the name of the specified import library with a new name. -linkfaster on | off By default, PPCLink keeps object files in memory in purgeable handles. This minimizes I/O time and improves performance. However, if linking fails because the linker ran out of memory, you should use the -linkfaster off option. -m[ain] entryPoint Specifies the name of a fragment's main entry point. The default main entry point for executables is __start which is defined in the StdCRuntime.o library. There is no default main entry point for shared libraries. -map filename Generates a link map and places it in the specified file. -mf | -nomf Enables or suppresses the use of Process Manager temporary memory. Note that the PPCLink tool's use of Process Manager temporary memory excludes other applications from using it, including the Finder. If Process Manager temporary memory is unavailable, this option has no effect.
WARNING -o filename Specifies the name of the output file. If you do not specify this option, the linker places its output in a file named PPCLink.out. -outputformat default | pef | xcoff Specifies the format of the output file. default Uses the default format for the type of file specified by the -xm option. pef if -xm executable, -xm sharedlibrary, or -xm dropin xcoff if -xm library pef Uses the Preferred Executable Format. xcoff Uses the Extended Common Object File Format. Executable programs and shared libraries can use either the XCOFF or PEF format, but static libraries can use only the XCOFF format. -p Writes progress and summary information to diagnostic output. -packdata on | off Specifies whether to compress the PEF container's data section. on Compresses the data section. off Does not compress the data section. -profile on | off | exclude=name[,name] ] Specifies whether special monitoring routines should be added to the generated application or shared library in order to enable the collection of profiling and performance information at runtime. When the program is executed, the monitoring routines collect information and write it to the file Profiler.pgh. The PPCProff tool can then be used to analyze and display this information. on Enables the collection of profiling and performance information at runtime. This option requires linking to the PPCProffLib.o and PPCProffLib libraries. PPCProffLib must also be available at runtime. off Disables profiling. This is the default. exclude=name[,name] Enables the collection of profiling and performance information at runtime but excludes the specified routines. This option requires linking to the PPCProffLib.o and PPCProffLib libraries. PPCProffLib must also be available at runtime.. -rodatais data | code | constant Specifies which section in the output file should contain read-only data. This option can override, or be overridden by, the -roistext option. data The read-only data is placed in the PEF Data (or XCOFF .data) section. code The read-only data is placed in the PEF Code (or XCOFF .text) section. constant The read-only data is placed in the PEF Constant section. This option is only valid when using the PEF output format. -roistext on | off Specifies whether to place read-only data in the .text (Code) or .data (Data) section. on Places read-only data in the .text/Code section. off Places read-only data in the .data/Data section. The default is off because the .text/Code section is not write-protected at runtime. If you use this option, turn on virtual memory when you test your application to determine if you are writing to read-only data. -sg newSeg=oldSeg[,oldSeg] Changes segmentation so that the code in the old segments (oldSeg,oldSeg ) is placed in the segment newSeg. -share context | global | protected Specifies the sharing mode for the PEF container's data section as follows: context Shared within a context. global Shared across all contexts. protected Readable by all contexts; writable by only privileged contexts. -sym on | off | big Specifies whether to copy symbolic information from the object files to an XCOFF file (for -outputformat pef) or to the output file (for -outputformat xcoff). on Copies the symbolic information. off Does not copy the symbolic information. big Copies the symbolic information but does not condense it. Use this option if attempting to link with -sym on results in error messages that say you are out of memory. If your fragment takes a long time to link when using -sym on, using -sym big instead might help the link process go faster. Using -sym big results in a much larger XCOFF file than -sym on. -t type Sets the output file type to type. The default type depends on the settings of the -outputformat and -xm options, as follows: 'XCOF' if -outputformat xcoff 'APPL' if -outputformat pef and -xm executable 'shlb' if -outputformat pef and -xm sharedlibrary '????' if -outputformat pef and -xm dropin -term default | none | termEntry Specifies the termination entry point of the output file. default Sets the termination entry point to the default termination routine, if the routine is defined in any of the files being linked. The default termination routine is __term_app for executables and __term_lib for shared libraries. If the default routine does not exist, the termination entry point is set to NULL. none Sets the termination entry point to NULL. termEntry Sets the termination entry point to the specified routine. -tocdataref on | off Controls the optimization of runtime calculations of data addresses. on Optimizes the runtime calculations of data addresses by replacing memory references with address calculations when the TOC entry being loaded is the address of a variable within 32 KB of the TOC anchor. This option replaces this line of code 1wz Rx,xxx{TC}(RTOC) ; get pointer to data with addi Rx,RTOC,yyy ; compute address of data when the contents of xxx{TC} is the address of a data item located yyy bytes from the TOC anchor. This optimization improves the performance of the linked application or shared library by avoiding a memory reference at runtime. off Does not optimize the runtime calculations of data addresses. -uf filename Writes a list of unreferenced symbols to the specified text file. -unmangle on | off Specifies whether C++ symbol names used in warnings, error messages, and the link map will be mangled or unmangled. on Unmangles the names. off Leaves the names mangled. -v Writes verbose progress information to diagnostic output. Specifying this option also implies -p. -vercur n Sets the PEF container "current version" to the specified version number. The default version number is 0. The "current version" is also stored in the container's 'crfg' resource. -verdef n Sets the PEF container "definition version" to the specified version number. The default version number is 0. The "definition version" is also stored in the container's 'crfg' resource. -verimp n Sets the PEF container "implementation version" to the specified version number. The default version number is 0. -w[arn] Suppresses the display of warning messages. -@weak filename Specifies a text file that contains a list of imported symbols that should be marked "weak". The file should contain one import name per line. Lines beginning with "#" or "*" are treated as comments. Note that if all of the symbols imported from an import library are marked as "weak," the import library itself is also marked as "weak." C++ users must specify the mangled symbol names in the file. -weak name[,name] Marks the specified imported symbols as ones that are not required to exist in any of the client's import libraries at runtime. The client must first check for the existence of the imports before using them. Note that if all of the symbols imported from an import library are marked as "weak," the import library itself is also marked as "weak." C++ users must specify the mangled symbol names when using this option. -weaklib fragName[,fragName] Marks the specified import libraries as ones that are not required to exist at runtime. If the specified library is not found when the program is loaded, all symbols imported from the library have their addresses set to 0. The client must first check for the existence of the imports before using them. Note that when an import library is marked as "weak," all of the symbols imported from the library are also marked as "weak." When using this option, you must specify the import library's fragment name, not the name of the file containing the library. The fragment name is the name that appears in the library's 'cfrg' resource. -xm e[xecutable] | l[ibrary] | s[haredlibrary] | d[ropin] Controls whether PPCLink generates an application, a static library, a shared library, or a drop-in addition. e[xecutable] Generates an application. l[ibrary] Generates a static library. s[haredlibrary] Generates a shared library. d[ropin] Generates a drop-in addition. Drop-in additions are generated like shared libraries except that the fragment's "usage" type is set to kDropInAdditionCFrag instead of kImportLibraryCFrag and the default file type is '????' instead of 'shlb'. SEE ALSO
|