text: These notes are for the MacOS X Xcode 3.2.1 Release of the compiler tools. They contain information about the following topics:
  There only new feature is supporting the iPhone 3.0 sdk and there have been bug fixes.
  There are no new features and only bug fixes.
  There are no new features and only bug fixes.
  The previous Mach-O static link editor is now named ld_classic(1).
  The otool(1) program now handles 64-bit object as well as 32-bit objects and there is no longer an otool64(1) program.
  The tools now support development of 64-bit Mach-O binaries for Intel with the -arch x86_64 flag..
  The one feature of this release is support for the Intel Vanderpool instructions in the assembler and disassembler.
  The major new feature for this release is the support of the use of DWARF for debug information.:
  addi r11, r11, (-33120 << 16) >> 16
  will now generate an error of the form:
  x.s:1:Parameter error: expression out of range (parameter 3)
  The correct way this should be coded is:
  addi r11, r11, lo16(-33120)
  There are no new features and only bug fixes. But there are some changes to improve the performance of the static link editor.
  The static link editor now supports the new option -Sp to strip, edit and add debugging symbols so the debugger can used most of the debugging symbols from the object files.
  The ar(1) tool has the new -S option to suppress building the table of contents.
  The tools now have support for the handful of x86 sse3 instructions..
  The static link editor now can do dead code stripping. The new ld(1) option to do this is -dead_strip. There is also an additional option -no_dead_strip_inits_and_terms that can be used when -dead_strip is specified to cause all constructors and destructors to never be dead code stripped. The load map printed with the ld(1) option -M notes what was dead stripped from the input files.
  There is one known bug with the tools that do dead code stripping. It is possible for some debugging information for types made to be stripped. This can lead to the debugger not being able to print the values of some variables and get unknow type errors.
  For testing, the environment variable LD_DEAD_STRIP can be set. which causes -dead_strip to specified for all ld(1) commands that don't specify the -r option. The environment variable LD_NO_DEAD_STRIP_INITS_AND_TERMS likewise causes -no_dead_strip_inits_and_terms to specified for all ld(1) commands that don't specify the -r option. And the environment variable LD_DEAD_STRIP_DYLIB causes -dead_strip to specified for all ld(1) commands that have the -dylib option specified.
  The static link editor determines what unreachable code and data can be stripped based on the references from the initial live symbols and blocks. The initial live symbols include the symbols to be exported in the linked output. The set of exported symbols are specified with the -exported_symbols_list option or a list of symbols not to be exported is specified with the -unexported_symbols_list option. If no exported symbols are specified and the output is not an executable (shared library, bundle, etc) it is assumed all global symbols are to be exported. If the output is a shared library and a shared library initialization symbol is specified with -init symbol_name option then that symbol_name is an initial live symbol. If the output is an executable then the block that contains the entry point or the symbol specified with the -e symbol _environ from /usr/lib/crt1.o, they are also part of the initial live symbols.
  Before turning on the -dead_strip -exported_symbols_list.
  Various auto configure test programs that expect to get undefined symbol errors when they have a possible undefined symbol referenced from dead code can't use the -dead_strip option. Because the dead code and the unused undefined reference will be stripped allowing the program to successfully linked. We have geneally found that auto configure programs on UNIX based system can't be configured with the -dead_strip option.
  The new compiler unconditionally marks the object files it creates as OK to divide up. There may be cases, especially with asm() statements, that it should not mark the object it creates as OK to divide up. In these cases turning on the -dead_strip -sectorder.
  As a workaround to the problem of incorrectly strip a live block you can produce a -sectorder file for objects that have section contents that must be linked whole. You would create a line in the sectorder file specifying the object and the psuedo symbol .section_all. For example if .text section of crt1.o and the archive member of darwin-tramp.o in libgcc.a must be linked whole, you would add the following:
  /usr/lib/crt1.o:.section_all
  /usr/lib/libgcc.a:darwin-tramp.o:section_all
  to your order_file for the __TEXT __text section. Then use the ld(1) option -sectorder __TEXT __text order_file when linking..
  By default when there are multiply defined symbols in the linked objects this is treated as an error. Even when the -dead_strip option is specified. Unused multiply defined symbols can be stripped if the strongly discouraged -m option is also specified. The duplicate symbols other than the first symbol may still end up being used in the resulting output file through local references however.
  Symbols from the linked objects in the output file that are only referenced via a shared library will not be dead stripped. Currently the static linker marks them with the REFERENCED_DYNAMICALLY bit in <mach-o/nlist.h> which causes them to be live.
  There is no support in the current design to dead strip branch islands created with the compiler option -mlongcall.
  The marking of object files which are OK to divide their section contents into individual blocks is done with the new assembler directive .subsections_via_symbols. This directive sets a previously unused bit in the object file's mach_header structure in the flags field. This bit is defined as the following new constant in the header file <mach-o/loader.h>:
  #define MH_SUBSECTIONS_VIA_SYMBOLS 0x2000 /* safe to divide up the sections into
  sub-sections via symbols for dead
  code stripping */
  This can be see with otool(1)'s -hv options and shows up as SUBSECTIONS_VIA_SYMBOLS in the following output:
  % otool.NEW -hv a.out
  a.out:
  Mach header
  magic cputype cpusubtype filetype ncmds sizeofcmds flags
  MH_MAGIC PPC ALL OBJECT 3 228 SUBSECTIONS_VIA_SYMBOLS
  The new assembler directive .subsections_via_symbols.
  For example this assembly code contains only two individual blocks but four symbols:
  .text
  .globl _plus_three
  _plus_three:
  addi r3, r3, 1
  .globl _plus_two
  _plus_two:
  addi r3, r3, 1
  .globl _plus_one
  _plus_one:
  addi r3, r3, 1
  blr
  .globl _some_other_routine
  _some_other_routine:
  blr
  And if the new assembler directive .subsections_via_symbols were added to the above code the static link editor would make 4 blocks about of the above code. Then if the program uses _add_three but not _add_two or _add_one it will get the wrong answer if the -dead_strip option is used. As the blocks for _add_two or _add_one will be dead stripped. And if _some_other_routine is not live then when _add_three is called it will fall through to what ever bit of code follows it and likely crash.
  The new assembler directive .no_dead_strip symbol_name can be used to specify that a symbol is not to be dead stripped. For example:
  .no_dead_strip _my_version_string
  .cstring
  _my_version_string:
  .ascii "cctools-501"
  This can be seen (in object files only) with nm(1)'s -m option and shows up as [no dead strip] in the following output:
  % nm -m x.o
  00000000 (__TEXT,__cstring) non-external [no dead strip] _my_version_string
  The .no_dead_strip directive is generated by the new compiler when the __attribute__((used)) is specified on a symbol.
  In object files, this bit is N_NO_DEAD_STRIP as defined in <mach-o/nlist.h>. And is set in relocatable .o files (MH_OBJECT filetype) only in the n_desc field of an nlist struct.
  The new section attribute no_dead_strip can be specified on a section to cause its entire contents to not to be dead stripped. The new compiler uses this for all Objective-C sections it creates. For example:
  .section __OBJC, __image_info, regular, no_dead_strip
  In object files, this bit is S_ATTR_NO_DEAD_STRIP as defined in <mach-o/loader.h>. And is set in the flags field of a section struct.
  The new section attribute live_support can be specified on a section to cause its blocks to not be dead stripped if they reference something that is live. The new compiler uses this for C++ exception frame information. For example:
  .section __TEXT, __eh_frame, coalesced, no_toc+strip_static_syms+live_support
  In object files, this bit is S_ATTR_LIVE_SUPPORT as defined in <mach-o/loader.h>. And is set in the flags field of a section struct.
  The assembler now takes a new .machine directive as an alternate to using the command line -arch arch_name option. It is specified as for example as:
  .machine ppc970
  Where ppc970 can be any arch_name that would appear in the -arch arch_name option as listed on the arch(3) man page for the assembler's architecture family.
  The dynamic linker has been changed that improve launch times of applications.
  The redo_prebinding(1) command has a new option, .
  Added the -executable_path path_name option to ld(1) where path_name is is used to replace @executable_path for dependent libraries.
  The compiler tools now support the PowerPC 970 processor. The architecture specific flag -arch ppc970 is used to specify this specific processor. The assembler will only assemble 64-bit instructions and other PowerPC AS User Instruction Set Architecture Version 2.00 instructions supported by the PowerPC 970 processor when -arch ppc970 or -force_cpusubtype_ALL is specified.
  To specify branch predictions which use the AT bit encodings for The branch is very likely to be taken and The branch is very likely not to be taken the two character suffixes ++ and -- are used. For example:
  bge-- foo
  The single character suffixes + and - continue to encode branch predictions which use the Y-bit encoding by default. The encoding can be changed for the single character suffixes to use the AT bit encodings with the assembler flag -static_branch_prediction_AT_bits (see the as(1) man page for more details).
  The compiler tools now support stub libraries created from dynamic libraries which are used in the SDKs. Stub libraries are created via strip(1) and the new -c option. And can be linked against in place of the actual dynamic library.
  By default when the -dynamic flag is in effect, the -lx and -weak-lx options first search for a file of the form libx.dylib in each directory in the library search path, then a file of the form libx.a is searched for in the library search paths. The new option -search_paths_first changes it so that in each path libx.dylib is searched for then libx.a before the next path in the library search path is searched.
  Added the -weak_framework, -weak_library and -weak-l options to ld(1) to force the dynamic library and the symbols referenced from it to be marked as weak imports. See the ld(1) man page for more details.
  Added the -undefined define_a_way option to ld(1) as a work a round to not having dead-code stripping that also strips out references to undefined symbols from the dead code. Which leads to link time failures due to undefined symbols. With this option ld(1) defines the remaining undefined symbols as private definitions and allows the link to succeed. The program then runs as long as it does not use any of the undefined symbols.
  The static link editor, ld(1), now has two new options, -exported_symbols_list filename and -unexported_symbols_list filename to limit the global symbols in the linked output file. This was previously done by with an nmedit(1). By using the new options to ld(1) the use of nmedit(1) can be eliminated resulting in faster build times.
  The static link editor, ld(1), now has a new option, -single_module, to build a dynamic library containing only one module. This was previously done by first creating a master.o file with an ld(1) -r step and then using the master.o to created the dynamic library. By using the new -single_module option to ld(1) this first step can be eliminated resulting in faster build times.
  The default in the static link editor remains the same and dynamic libraries are built with multiple modules. The new flag -multi_module has also been added to allow this to be explicitly specified.
  The static link editor's -s option can now be used to strip an executable that use the dynamic link editor. This will produce the same result as running strip(1) with no options on the executable. By using the -s option when building an executable the strip(1) step can be eliminated resulting in faster build times.)  now can slide dymamic libraries to new prefered addresses (see the man page for more details)..
  By default the compiler tools build images using the new two-level namespace binding semantics, which has important consequences for compatibility with Mac OS X 10.0 (see below for more information).
  The following new features have been added to the Compiler Tools for the Mac OS X 10.1 system release.
  The following new features have been added to the Compiler Tools since the Mac OS X Developer Release 4.
  The following new features have been added to the Compiler Tools since the Mac OS X Developer Release 2.
  The following new features have been added to the Compiler Tools since the Mac OS X Developer Preview Release..
  The following new features have been added to the Compiler Tools since the Mac OS X Server Release.
  to:
  with the options as follows:
  The first two are the same as bindNow with a value of FALSE and TRUE. The private options are used to load a private module. The API for getting to the symbols of a NSModule that has been privately linked is:
  Then to get the address of the returned NSSymbol, the existing NSAddressOfSymbol() API can be used.
  The NSUnLinkModule() API is now implemented with enough functionality to make Apache work (reference number 2262020). It currently has the following limitations (to be fixed in future releases):
  The interface to NSUnLinkModule has changed in a compatible way from:
  to:
  where the options.
  Support for module termination functions has been added for plugins (only). Currently the compiler pragma CALL_ON_UNLOAD (as well as CALL_ON_LOAD) is not yet implemented to use this feature as intended. A work around can be done in place of having the pragma:
  The following new features have been added to the Compiler Tools since the Rhapsody Developer Release 2.
  The following new features have been added to the compiler tools since OPENSTEP 4.2 (NeXT).
  -arch ppcswitch.
  These bugs are known to exist in the compiler tools:
  The following bug has been fixed:
  Register names can't be designated with just a number. You must
  refer to them with their register name. This restriction includes
  general registers (
  rN), floating point registers,
  (
  fN), condition registers
  (
  crN), and segment registers
  (
  srN). However, you can refer to special
  registers by their register number or their special register names.
  The special register names are in lowercase only (for example,
  mq,
  xer,
  lr,
  ctr,
  and
  dsisr).
  For instance, for the ppcasm assember you could code a move from segment register instruction as:
  mfsr r24,9 ; ppcasm assembler
  But, for the Mac OS X assembler, this same move would be coded as:
  mfsr r24,sr9 ; Mac OS X assembler
  For instructions that take the value 0 or a register, shown in the processor manual as "(rA|0)", r0 can't be used and 0 must be coded. The Mac OS X assembler generates an error messages in these cases.
  Where a numeric value is expected as a parameter, a register name can't be use. For example, the ppcasm assembler allows the following:
  lwz r1,r2(r3) ; ppcasm assembler
  For Mac OS X, this must be coded as:
  lwz r1,2(r3) ; Mac OS X assembler
  The Mac OS X assembler generates a warning if branch prediction is coded with an unconditional branch.
  The Mac OS X assembler checks all fields for range errors and generates error messages if an expression is out of range. The ppcasm assembler simply uses the low N bits of the expression (where N is the field width) if the value is greater than zero. For example the simplified mnemonic:
  inslwi rA,rS,n,b
  is equivalent to
  rlwimi rA,rS,32-b,b,(b+n)-1
  The following code:
  inslwi r17,r18,19,20 ; equivalent to rlwimi r17,r18,32-20,20,(20+19)-1
  assembles to
  rlwimi r17,r18,12,20,6 ; where the low 5 bits (20+19)-1 is 6
  with ppcasm. This generates an out-of-range error with the Mac OS X assembler.
  For fields less than zero, the ppcasm assembler uses the value of zero. For example, the simplified mnemonic:
  clrlslwi rA,rS,b,n
  is equivalent to
  rlwinm rA,rB,n,b-n,31-b
  Thus the following code:
  clrlslwi r5,r6,7,8 ; equivalent to rlwinm r5,r6,8,7-8,31-7
  assembles to:
  rlwinm r5,r6,7,0,24 ; where 7-8 gets turned into 0
  with ppcasm. This generates an out-of-range error with the Mac OS X assembler.
  All integer expressions in the Mac OS X assembler are signed 32-bit values. Parameters that are 16-bit signed or unsigned immediate values must agree in their upper 16 bits or the assembler generates an out-of-range error message.
  For example:
  addi r1,r2,0xffff ; out of range for a 16-bit signed immediate
  generates the message "Parameter error: expression out of range (parameter 3)".
  The
  addi instruction takes a signed immediate value
  so it will sign extend its parameter to 32 bits before performing the
  operation. If the value 0xffffffff is intended, it would be coded
  as:
  addi r1,r2,0xffffffff
  If this is half of a two-instruction 32-bit add it should be coded as:
  addis r1,0,ha16(expression) addi r1,r2,lo16(expression):
  extldi rA,rS,n,b
  is equivalent to
  rldicr rA,rS,b,n-1
  Thus the following code:
  extldi r1,r2,0,2
  generates the error message "Parameter error: expression out of range (parameter 4)," which refers to "n-1" or "0-1", or parameter 4 of the expanded macro.
  The instruction
  tlbiex, which has been removed from
  the PowerPC architecture, is not supported by the Mac OS X assembler.
  This instruction is assembled by ppcasm.