Log In | Not a Member? | Support | |
SYNTAX
Link objectFile1 [objectFile2]… [-ac number] [-ad number] DESCRIPTION The Link tool links object files, including library files, into an executable program, tool, or desk accessory. Normally the Link tool assumes that you are creating an application and places the output code and data segments into 'CODE' resources. When you link an application, Link automatically deletes old 'CODE' resources before writing the new ones. It also identifies unused code and data modules and omits them from segments. Aside from its default behavior, Link allows you to do the following: • Link a desk accessory, tool, or driver. You can link a desk accessory by specifying -da. You use the -t option to specify the output file type to link a tool or driver. • Change code segmentation by using -sg and -sn. • Generate location maps (-l, -la, -lf, and -map) for use with debugging and performance tools. • Create symbolic debugging information for use by SADE, SourceBug, and the profiling performance monitoring library Proff (-sym on or -sym full). • Take advantage of Process Manager temporary memory (-mf). • Expand the size of segments, jump tables, and code and global data beyond the 32 KB limit (-br 020, -br on, and -model far). The -model far option provides "32-bit everything" compatibility. INPUT Object files of type 'OBJ ', including both individual files and libraries. Note that Link can combine object files written in different languages. The Link tool does not accept standard input. OUTPUT Linked segments are placed in 'CODE' resources in the resource fork of the output file. Link gives the resources the same name as the corresponding segment names. Normally Link names the output file Link.out. However, you can use the -o option either to rename the output file or to specify a directory in which Link places the Link.out file. If an output file for the program already exists, Link adds or replaces code segments in the resource fork. If the output file does not exist, it is created with file type 'APPL' and creator '????'. You can use the -t and -c options to set the output file type and creator to other values.
Note If you specify -l, -la, -lf, or -map, Link writes a location map to standard output. STATUS
Link can return the following status codes:
PARAMETERS objectFile1 [objectFile2]… Specifies one or more object files, including libraries, to be linked. OPTIONS Numeric values for options can be specified as decimal constants or as hexadecimal constants preceded by the dollar sign character ($). -ac number Aligns code to number-byte boundaries. The value of number must be a power of 2. The default value of number is 2. -ad number Aligns data to number-byte boundaries. The value of number must be a power of 2. The default value of number is 2. -br 020 | on | off Controls whether Link produces branch islands to remove the 32 KB limit on segment size. 020 Generates long branch islands to remove the 32 KB limit on segment size. Any function call can be implemented using a single long branch, no matter how large the distance between the calling and called modules. This improves code size and execution speed over the -br on option. Programs linked with the -br 020 option require an MC68020 CPU or above to run. Do not use this option in conjunction with the -model far option. on Generates short branch islands to remove the 32 KB limit on segment size. Some code is slightly slower because multiple branches are executed in place of one. Do not use this option in conjunction with the -model far option. off Inhibits the generation of branch islands. This is the default setting. -c creator Sets the output file creator to creator. Normally the creator is set to '????'. -csym creator Specifies the creator attribute of the generated SYM file. -d Suppresses warnings for duplicate symbol definitions for both data and code. -da Converts segment names to desk accessory names at output time. Desk accessory names begin with a leading null character ($00). Use this option when linking assembly-language code into a final desk accessory with a resource type of 'DRVR'. -f Treats duplicate data definitions as Fortran common regions (that is, multiple data modules with the same name). The size of the largest module is used. There can be at most one initialization of the data. -l Writes a location-ordered map to standard output. The map is sorted by segNum and segOffset and divided into several fields: name segName segNum, segOffset [@JTOffset] [#] [E] [C] [fileNum, defOffset] The performance measurement tools and other scripts often rely on this option. It is usually used with output redirection. -la Lists anonymous symbols in the location map. Otherwise, anonymous symbols are omitted by default. -lf Writes to standard output a location map that includes the symbol definition location of the input file--that is, the file number and byte offset of the module or entry point record. Normally Link omits the symbol definition location. Specifically, these are the fields listed in the -l option as [fileNum, defOffset]. -m mainEntry Sets or overrides the main entry point specified in the object files.
Note -ma name=alias Gives the module or entry point name the specified alias. You can use this option to resolve undefined external symbols at link time when the problem is caused by differences in spelling or capitalization. Note that you cannot use an alias specification to override an existing module or entry point because the original name is retained. -map Writes to standard output a location map that provides the A5 world with the correct offsets and sizes of all modules. This location map is more readable than those produced by -l, -la, and -lf. -mf | -nomf Enables or suppresses the use of Process Manager temporary memory. Note that the Link 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 -mfMax Allows the linker to use all available Process Manager temporary memory. -model near | far Determines whether Link uses references to 32-bit addresses for MPW's "32-bit everything." The far parameter controls the removal of the 32 KB (16-bit) restriction on code and data size. near Links normally with 16-bit references (the default). This maintains the 32K restriction on the size of segments, jump tables, and global code and data. far Links with 32-bit references. This removes the 32 KB restriction on the size of segments, jump tables, and global code and data. -msg [[no]dup][,[no]multiple][,[no]warn]] Suppresses or enables certain warning and error messages by using the following key words: [no]dup Suppresses or enables warning messages about duplicate symbols. The default is to suppress these messages (nodup). [no]multiple Suppresses or enables multiple error messages on undefined references to a label. This lets you catch all references to an undefined symbol with one link. The default is to suppress these messages (nomultiple). [no]warn Suppresses or enables all warnings. The default is to enable these warnings (warn). -newerdeps This option is only for compatibility with the ILink tool and has no effect when used on the Link command line. -o [resourceFile | directory] Places the linker output in either a resource file or directory. If you do not specify -o, the default output filename is Link.Out. resourceFile Places the linker output in the file resourceFile in the current directory. directory Places the linker output file Link.Out in the directory you name. -opt [off | on][,nobypass][,names][,info] Controls the optimization of Object Pascal code. off Disables Object Pascal optimization. on Optimizes Object Pascal method tables (the default). This parameter can be followed by one or more of the following keywords, separated by commas or MPW Shell-quoted (∂) spaces: ,nobypass Never bypasses the jump table (that is, it does not optimize monomorphic method calls to PC-relative JMP instructions). ,names Appends MacsBug symbols to SelectorProc modules, making selector names visible in MacsBug disassemblies. ,info Writes information about method table optimization to diagnostic output. -p Writes progress and summary information to diagnostic output. -pg size Sets the .sym file page size to size bytes; the default page size is 4 KB and the minimum is 2 KB. For example, this option sets the .sym file page size to 8192 bytes, or 8 KB: -pg 8192 -ra [seg]=attr[,attr]… Sets the resource attributes of a segment or segments. seg Specifies the segment. If you specify the segment (seg), the single segment named seg is given the attribute value attr. If you omit seg, all segments except 0 and 1 are given the attribute value attr. You must set the segment containing the main entry point (that is, the 'CODE' resource with ID=1) individually to override the default resource attributes. If you intend to set the attributes of all segments, you must specify this option before any other options that name segments, such as -sn and -sg. attr
Specifies the resource attribute as a list of comma-separated attributes or decimal or hexadecimal numbers. A list of attributes and their corresponding decimal and hexadecimal values follows. (Note that you can omit the initial res
for resource attributes.)
Link essentially ignores the resChanged attribute and does not check or enforce settings for the other resource attributes. Bits 0 and 7 ($01 and $80) are currently reserved and should not be set.
The default resource attributes for the 'CODE'
resources of an application are listed as follows:
Note -rn Suppresses the setting of resource names. Normally, Link sets resource names to the corresponding segment names. Note that desk accessories must always be named. -rt type=ID Sets the output resource type and ID.
Note -sg newSeg=[oldSeg1[,oldSeg2]…]… Changes segmentation so that code in the old segments (oldSeg1,oldSeg2,…) is placed in the segment newSeg. If you do not specify the old segments, Link places all segments in newSeg. -sn oldSeg=newSeg Puts the code residing in oldSeg in the segment newSeg. If there is already code in the segment newSeg this option has the effect of merging the code in the oldSeg segment with the code already in the newSeg segment. The -sn and -sg options are very similar. The option -sg allows you to specify multiple segments to merge. The -sn option is retained to maintain compatibility with old makefiles. For example, the first option below combines the three specified segments into one segment named Main; the second option renames Main to MyDA.
Link… ∂ -srt Sorts global data by "near" and "far" references. -srtsg segName | all Places modules referenced through the jump table low in the segment. If a segment is greater than 32 KB, references from the jump table still reach (that is, the references are still in range). This may help if you get the message "Jump table offset into code segment is > 32K." -state This option is only for compatibility with the ILink tool and has no effect when used on the Link command line. -sym [on | full[,nolines][,nolabels][,novars][,notypes]]| off Determines whether Link generates symbolic debugging information for SourceBug or SADE. Note that the parameters on and full are equivalent. on | full Generates a .sym file with symbolic debugger information. You can limit -sym on | full by also specifying one or more of the following parameters. ,nolines Omits line information. ,nolabels Omits label information. ,novars Omits variable information. ,notypes Omits type information. off Does not generate a .sym file containing information for SourceBug or SADE (the default). -t type Sets the output file type to type. The default type is 'APPL'. -uf deleteFile Outputs a list of unreferenced modules to the text file deleteFile. This option is useful in identifying dead source code. The output file, deleteFile, can be used with the Lib tool's -df option to build a specialized library that optimizes subsequent links. -w Suppresses warning messages.
Note -wrap If the jump table is larger than 32 KB, -wrap places excess jump-table entries in available global data space. Note that this option is not applicable if the global data area is filled. -x crossRefFile Generates a cross-reference listing of active modules and entry points. The listing is ordered by module within each segment. For each module, the following information is listed: each active entry point in the module, other modules and entry points that are referenced by the module, and other modules that reference this module. For each entry point in a module, the modules that reference the entry point are listed. EXAMPLES The following command line links myFile.c.o and anotherFile.c.o and places the output in the file named Linked: Link myFile.c.o anotherFile.c.o -o Linked The next example links the files defined in the MPW Shell variable {LinkList} into a ROM image file, placing the output in the file MyROMImage. The ROM is created as a resource of type 'MROM' with ID=8. The file is specified as being created by MPW with a creator of 'MPS ' and a file type of 'ZROM'. The Link tool's location-ordered listing is placed in the file ROMLocListing.
Link -rt MROM=8 -c 'MPS ' -t ZROM ∂ You can enable your program to generate its own profiling performance data by running it with Proff.o library code embedded. Embed the code by merging the stand-alone segment of the Proff.o library, ProffSeg, with a resident segment of your program using the -sn option. At the same time generate the symbolic debugging information using the -sym full option on a command line as follows: Link -sn ProffSeg=main -sym full When you run the resulting program, an output file containing profiling and performance data is placed in the same directory as the target program. It is given the application name with .proff appended as a suffix. You then analyze this data file using PrintProff. SEE ALSO
|