 |
|
|
|
 | |
|
|
|
|
 |
Log In | Not a Member? |
Support
|
|
||
SYNTAX
ILink file1 [file2]… [-ac number] [-ad number] DESCRIPTION You use the ILink tool to link compiled 68K object files, static libraries, and shared libraries into an application, tool, shared library, or resource. ILink is an incremental linker that you can use to relink a program of any size after a simple change during the development cycle, in a fraction of the time it would take to relink the program using the Link tool. (See the Link command.)
IMPORTANT When you use ILink to link your program, the linker creates a state file in which it stores information that it can use the next time it links your program. This file includes a list of the files included in the link and information extracted from the files. ILink uses this information to resolve code and data references. The next time you link, ILink can reuse most of the information stored in this file and thus limit linking to the files that have changed. The state file is named outputfile.NJ, where outputfile is the name of the output file. The state file is created the first time you execute ILink; you should therefore expect the initial link to take longer than a subsequent link. Two command options relate to the incremental linker's use of the state file: • The -state option specifies whether you want ILink to use or rewrite the state file. The default is -state use -state norewrite. • The -newerdeps option allows you to control which files get relinked. When -newerdeps is specified, only those object files listed on the command line get relinked, all others are ignored. For example, the following command specifies that only the files MySource1.c.o and MySource2.c.o will be relinked. ILink -newerdeps MySource1.c.o MySource2.c.o Using the -newerdeps option can save some time because the ILink tool does not have to determine which files have changed. You can also use the -newerdeps option in your makefile.
Note INPUT ILink accepts the following input: • Object files of type 'OBJ '. • Static libraries of type 'OBJ '. • Shared libraries of type 'shlb'. • Stub library files of type 'stub'.
• CFM-68K runtime applications of type 'APPL'.
Note that the linker can combine object files written in different languages. The ILink tool does not accept standard input. OUTPUT ILink produces the following types of output files: • Classic 68K runtime application or tool • Classic 68K stand-alone code resource • CFM-68K runtime application
• CFM-68K runtime shared library By default, the linker names the output file Link.out. This is the same default file to which the Link tool sends output. You can rename the output file by using the -o option to specify a filename. Linked segments are placed in 'CODE' resources in the resource fork of the output file. The resources are given the same names as the corresponding segment names. If an output file for the program already exists, ILink adds, replaces, or patches code segments in the resource fork. If the output file does not exist, it is created.
Note If you specify -l, -la, or -map, ILink writes a link map to standard output. STATUS
ILink can return the following status codes:
PARAMETERS file1 [file2]… Specifies one or more object files, static libraries, and shared libraries to be linked. OPTIONS Numeric constants for options can be specified as decimal constants or as hexadecimal constants preceded by the dollar sign character ($). -ac number Aligns code modules to number-byte boundaries. The value of number must be a power of 2. The default value of number is 2 if linking with -model near or -model far, the default value is 8 if linking with -model cfmseg or -model cfmflat. -ad number Aligns data modules to number-byte boundaries. The value of number must be a power of 2. The default value of number is 2 if linking -model near or -model far, the default value is 4 if linking with -model cfmseg or -model cfmflat. -br 020 | 68k | on | off Controls whether ILink generates branch islands to remove the 32 KB limit on segment size. 020 Generates branch islands using MC68020 instructions. This produces smaller and faster code than the -br 68k option. Programs linked with this option require a 68020 or higher processor to run. 68k Generates branch islands using MC68000 instructions. on Same as using the -br 020 option. off Disables generation of branch islands (the default). -c creator Sets the output file creator to creator. By default the creator is set to '????'. -compact Forces the resource fork of the output file to be compacted, removing all gaps. ILink uses its own resource management scheme and for performance reasons it doesn't compact the resource fork. As a result, the resource fork may grow over time and RezDet may report errors when checking the resource fork. These problems go away when using -compact. -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'. -@export exportFile (CFM-68K runtime option.) 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 won't be dead-stripped if they aren't referenced. C++ users must specify the mangled symbol names in the file. -export name[,name]… (CFM-68K runtime option.) Specifies symbols that should be exported from the output file. 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 when using this option. -fragname fragName (CFM-68K runtime option. ) 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. The fragment name is stored in the container's 'cfrg' resource. -init initEntry (CFM-68K runtime option.) Sets the initialization entry point of the output file to the specified code module. The init entry point must be a non-imported code entry. The default init entry point for an application is __init_app. The default init entry point for a shared library is __init_lib. These entry points are defined in the library NuCPlusLib.o. If the -init option is not specified, ILink uses the appropriate default init entry point, if it exists. -initbefore fragName[,fragName]… (CFM-68K runtime option.) Specifies import libraries that should be marked as "initbefore" libraries. This is necessary only when the initialization of one library depends on the prior initialization of another. By default, libraries being imported are initialized before the client importing them. This rule is applied recursively. For mutually dependent libraries, one is arbitrarily chosen to be initialized first. In this case, the -initbefore option can be used to indicate which library should be initialized first. 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. -l Writes a link map to standard output for use by performance measurement tools and other scripts. Anonymous symbols are omitted. This option is usually used with output redirection. -la Writes a link map to standard output for use by performance measurement tools and other scripts. The link map includes anonymous symbols. This option is usually used with output redirection. -m[ain] mainEntry Sets the main entry point to mainEntry. The default main entry point is %__MAIN and is defined in the MacRuntime.o and NuMacRuntime.o libraries. If the -m option is not specified, ILink looks for the default main entry point when linking an application, but not when linking a shared library. The main entry point of a library must be called directly by the client and therefore isn't required. The main entry point for an application must be a non-imported code entry. The main entry point for a shared library may be either a non-imported code entry or a non-imported data entry. -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 a link map to standard output that provides the offsets and sizes of all modules. This link map is more readable than those produced by the -l or -la options. Note that if you also specify the -state nouse option, ILink generates the link map before writing the output file. This allows you to get a link map even if ILink encounters errors when writing the output file (reference out of range, for example). However, if you are using the state file for your link, the link map is not generated until after ILink writes the output file and updates the state file. -mf | -nomf Enables or suppresses the use of Process Manager temporary memory. Note that the ILink command's use of Process Manager temporary memory excludes other applications from using it, even the Finder. If temporary memory is unavailable, this option has no effect.
WARNING -model cfmflat | cfmseg | far | near Specifies what type of output file should be generated. cfmflat Generates a "flat" CFM-68K runtime output file. All code is output to a single segment named Main (the segment name can be overridden using the -sg or -sn options). This option is recommended for generating shared libraries only. The resulting shared library must still be flattened using the MakeFlat tool. This option can be used for linking -model cfmflat object files, -model cfmseg object files, or a combination of both. cfmseg Generates a segmented CFM-68K runtime output file. This option can be used for linking -model cfmseg object files only. If any -model cfmflat object files are supplied as input files on the command line, the -model cfmflat option must be used. far Generates a classic 68K runtime output file with 32-bit load-time relocatable references. This option can be used for linking -model far object files, -model near object files, or a combination of both. This option removes the 32 KB restriction on the size of segments, the jump table, and global data. near Generates a classic 68K runtime output file with 16-bit references (the default). This option can be used for linking -model near object files only. This option maintains the 32 KB restriction on the size of segments, the jump table, and global data. If any -model far object files are supplied as input files on the command line, the -model far option must be used. -msg keyword[,keyword]… Suppresses or enables certain warning messages by using the following keywords. [no]dup Suppresses or enables warning messages about duplicate symbols. The default is to enable these messages (dup). [no]warn Suppresses or enables all warning messages. The default is to enable these messages (warn). -newerdeps Specifies that only those object files listed on the ILink command line are to be relinked. You may also include the {NewerDeps} variable in your makefile to relink only those files that have changed. This can save link time since ILink does not need to check all of the object files to determine which ones have changed. -o outputFile Places the linker output in outputFile in the current directory. If you do not specify -o, the default output filename is Link.Out. -opt on | off | nobypass Controls the optimization of Object Pascal code. on Optimizes Object Pascal method tables (the default). For methods that are not overridden (monomorphic methods), ILink inserts a JSR directly to the method implementation, skipping the jumps to the method dispatcher. As a result, the %_MethTables segment and the jump table are smaller. off Disables Object Pascal optimization. nobypass Disables Object Pascal optimization. -p Writes progress and summary information to diagnostic output. -packdata on | off | faster (CFM-68K runtime option.) Controls the compression of the PEF container's data section. on Compresses the PEF container's data section (the default). off Disables compression of the PEF container's data section. faster Compresses the PEF container's data section using a potentially faster compression algorithm. Note that this algorithm may not produce optimal data compression. -pad number Pads segments to a number-byte boundary. The value of number must be 0 or a multiple of 512. If you specify 0, the jump table segment and all code segments are deleted and then rewritten. If you specify a nonzero argument, it will take effect only for segments that have to be rewritten for other reasons. For performance reasons, the default ILink behavior is to pad all segments to a 512-byte boundary. -pm on | off Controls whether purgeable memory is used when reading the object files. on Uses purgeable memory when reading the object files. This decreases the linker's memory requirements, but may increase the time required to link. off Disables the use of purgeable memory when reading the object files (the default). -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.)
The linker 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 in the output file. Normally, ILink sets resource names to the corresponding segment names. On incremental links, this option takes effect only for segments that have to be rewritten. -rt resType=resID Sets the output resource type and ID number. When linking a stand-alone code resource, ILink uses PC-relative offsets and attempts to convert JSR, JMP, LEA and PEA instructions from A5-relative addressing to PC-relative addressing. Instructions that specify the A5-relative addressing mode generate an error message. -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, ILink places all code in the segment newSeg. -sn oldSeg=newSeg Puts the code residing in oldSeg in the segment newSeg. If there is already code in newSeg this option has the effect of merging the code in oldSeg with the code already in newSeg. The -sn and -sg options are very similar. The -sg option allows you to specify multiple segments to merge. The -sn option is retained to maintain compatibility with old makefiles. -state [no]use | [no]rewrite Specifies whether to use a state file or whether to rewrite it. The default is to use a state file and just update it instead of rewriting it. -t type Sets the output file type to type. The default type is 'APPL' when generating an application and 'SPEF' when generating a shared library. -term termEntry (CFM-68K runtime option.) Sets the termination entry point of the output file to the specified code module. The term entry point must be a non-imported code entry. The default term entry point for an application is __term_app. The default term entry point for a shared library is __term_lib. These entry points are defined in the library NuCPlusLib.o. If the -term option is not specified, ILink uses the appropriate default term entry point, if it exists. -uf filename Writes a list of unreferenced code and data symbols to the text file filename. This option is useful for identifying dead source code. You can use the text file with the Lib tool's -df option to build a specialized static library that optimizes subsequent links. -unmangle on | off Controls whether C++ symbols used in warnings, error messages, and the link map will be mangled or unmangled. on Uses unmangled symbol names (the default). off Uses mangled symbol names. -vercur number (CFM-68K runtime option.) 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 'cfrg' resource. -verdef number (CFM-68K runtime option.) 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 'cfrg' resource. -verimp number (CFM-68K runtime option.) Sets the PEF container "implementation version" to the specified version number. The default version number is 0. -w[arn] Suppresses warning messages. -@weak weakFile (CFM-68K runtime option.) Specifies a text file that contains a list of imported symbols that should be marked as "weak" (also known as "soft" imports). 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]… (CFM-68K runtime option.) Specifies imported symbols that should be marked as "weak" (also known as "soft" imports). Weak imports 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]… (CFM-68K runtime option.) Specifies import libraries that should be marked as "weak". Weak libraries are not required to exist at runtime. If the library is not found at load time, all symbols imported from the library will 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. -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. This option is ignored when linking with -model far. -xm e[xecutable] | s[haredlibrary] (CFM-68K runtime option.) Controls whether ILink generates an application or a shared library. e[xecutable] Generates an application (the default). The default output file type is 'APPL'. s[haredlibrary] Generates a shared library. The default output file type is 'SPEF'. EXAMPLES You can use the -newerdeps option to restrict the set of input files included in the link to that defined by the Make tool's {NewerDeps} variable. This variable expands to a list of all the files that are newer than the target application--that is, that caused the target to be out of date. Using this information and the information it saved in the state file, ILink does not have to check each file to determine which ones have changed since the previous link. If you use the ILink command in your makefile and you want to take advantage of the -newerdeps option, you need to modify your makefile as shown below. The first time MyProgram is built, the second ILink command is executed; all subsequent times, the first ILink command is executed. OBJECTS = calc.c.o {Libraries}Interface.o {Libraries}MacRuntime.o
MyProgram ƒƒ {OBJECTS}
IF (`exists MyProgram.NJ`) #test for state file
ILink -newerdeps {NewerDeps} -o MyProgram
ELSE
ILink -o MyProgram {OBJECTS}
END
MyProgram ƒƒ MyResources.r
Rez -a -o MyProgram MyResources.r
LIMITATIONS ILink requires at least 8 MB of RAM. The memory requirements are greater for ILink than for Link. ILink requires approximately two to three times the total size of the object files used in the link. The memory can be either MPW heap memory or a combination of both temporary memory and MPW memory. SEE ALSO
|
 |
|
Get information on Apple products. Copyright © 2008 Apple Computer, Inc. |
|