CompilerTools.html   [plain text]


<HTML>
<!--This file created 3/21/05 5:22 PM by Claris Home Page version 3.0-->
<HEAD>
   <TITLE>Mac OS X Compiler Tools Release Notes</TITLE>
   <META NAME=GENERATOR CONTENT="Claris Home Page 3.0">
   <X-CLARIS-WINDOW TOP=185 BOTTOM=987 LEFT=190 RIGHT=874>
   <X-CLARIS-TAGVIEW MODE=minimal>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H1>Mac OS X Xcode 2.1 Release Notes:<BR>
Compiler Tools</H1>

<P><!-- start of path --> <TABLE BORDER=0 CELLSPACING=0 WIDTH=600 valign=left>
   <TR>
      <TD>
         <P><FONT SIZE="-2" FACE="Geneva,Helvetica,Arial"><B>PATH<SPACER TYPE=horizontal SIZE=5>&nbsp;</B></FONT><A HREF="help:goto_helpcenter=developer" TARGET="_top"><FONT SIZE="-2" FACE="Geneva,Helvetica,Arial">Documentation</FONT></A><FONT SIZE="-2" FACE="Geneva,Helvetica,Arial">
         <B>&gt;</B> Release Notes</FONT></P>
      </TD>
   </TR>
</TABLE>
<BR>
<!-- end of path --> <A HREF="index.html"><IMG SRC="Images/up.gif" WIDTH=36 HEIGHT=16 BORDER=0 ALIGN=bottom></A></P>

<P>These notes are for the MacOS X Xcode 2.1 Release of the compiler
tools. They contain information about the following topics:</P>

<UL>
   <LI>The Mac OS X Mach-O GNU-based assemblers</LI>
   
   <LI>The Mac OS X 32-bit Mach-O static link editor</LI>
   
   <LI>Mach-O object file tools (<B>nm</B>, <B>otool</B>, and so
   on)</LI>
</UL>

<H2>Notes Specific to Mac OS X Xcode 2.1 Release</H2>

<H2>New Features</H2>

<P>The tools now have support for the handful of x86 sse3
instructions.</P>

<H2>Notes Specific to Mac OS X Xcode 2.0 Release</H2>

<H2>New Features</H2>

<P>The tools now support development of 64-bit Mach-O binaries for
the PowerPC with the -arch ppc64 flag. The one tool that has not been
seamlessly ported for this release is otool(1). And there is an
otool64(1) for 64-bit Mach-O binaries.</P>

<H2>Notes Specific to Mac OS X Xcode 1.5 Release</H2>

<H2>New Features</H2>

<H3><FONT SIZE="+1">The static linker has an option to do dead code
stripping</FONT></H3>

<P>The static link editor now can do dead code stripping. The new
<I>ld</I>(1) option to do this is <B>-dead_strip</B>. There is also
an additional option <B>-no_dead_strip_inits_and_terms</B> that can
be used when <B>-dead_strip</B> is specified to cause all
constructors and destructors to never be dead code stripped. The load
map printed with the <I>ld</I>(1) option <B>-M</B> notes what was
dead stripped from the input files.</P>

<P>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.</P>

<P>For testing, the environment variable LD_DEAD_STRIP can be set.
which causes <B>-dead_strip</B> to specified for all <I>ld</I>(1)
commands that don't specify the <B>-r</B> option. The environment
variable LD_NO_DEAD_STRIP_INITS_AND_TERMS likewise causes
<B>-no_dead_strip_inits_and_terms</B> to specified for all
<I>ld</I>(1) commands that don't specify the <B>-r</B> option. And
the environment variable LD_DEAD_STRIP_DYLIB causes
<B>-dead_strip</B> to specified for all <I>ld</I>(1) commands that
have the <B>-dylib</B> option specified.</P>

<P>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 <B>-exported_symbols_list</B> option or a list of
symbols not to be exported is specified with the
<B>-unexported_symbols_list </B>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 <B>-init</B> <I>symbol_name</I> option then
that <I>symbol_name</I> 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 <B>-e</B> <I>symbol_name</I> is an initial
live symbol. Other symbols can be marked by the programmer as an
initial live symbols with the GNU compiler's __attribute__((used)).
For Objective-C code, the compiler will also mark the blocks of
Objective-C runtime data it produces so they are part of the initial
live blocks. For symbols marked referenced dynamically (via the
REFERENCED_DYNAMICALLY bit in &lt;mach-o/nlist.h&gt;), such as the
symbol <B>_environ</B> from /usr/lib/crt1.o, they are also part of
the initial live symbols.</P>

<P>Before turning on the <B>-dead_strip</B> option your project will
first have to be "ported" to work with dead code stripping. This will
include changing from -gused (the default for -g) to -gfull and
re-compiling all of the objects files being linked into your program
with the new compiler from the Mac OS X June 2004 release. Also if
your building an executable that loads plugins, which uses symbols
from the executable, you will have to make sure the symbols the
plugins use are not stripped (by using __attribute__((used)) or the
<B>-exported_symbols_list</B> option). If you are using an export
list and building a shared library, or an executable that will be
used with ld(1)'s -bundle_loader flag, you need to include the
symbols for exception frame information in the export list for your
exported C++ symbols. These symbols end with .eh and can be seen with
the nm(1) tool.</P>

<P>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 <B>-dead_strip</B> 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 <B>the -dead_strip</B> option on.</P>

<P>Recompiling with a new compiler is required to get effective dead
code stripping. As it marks the object files it creates as OK to
divide up the section contents into individual blocks by the symbols
that are in the object files. Objects not marked are assumed to be
generated from assembly code, older compilers, or from compilers that
are not know to be safe to divide up their section contents by their
symbols. For non-marked objects if any symbol is used from a section
the entire section is kept and not dead stripped.</P>

<H3>Work around for objects incorrectly marked object files as OK to
divide up</H3>

<P>The new compiler unconditionally marks the object files it creates
as OK to divide up. There may be cases, especially with <B>asm()</B>
statements, that it should not mark the object it creates as OK to
divide up. In these cases turning on the <B>-dead_strip</B> option
may fail to produce a working program because it can incorrectly
strip a live block. The reason for this is that the heuristic of
dividing up the section contents by their symbols is incorrect if any
individual block has more than one symbol. This makes the heuristic
fragile.</P>

<P>The reason that the current dead code stripping inplementation is
fragile is because the static linker is guessing at the structure of
the program. Namely it is guess at which bytes of a section make up a
individual block of code or data. It makes its guess based on the
symbols that are in the object files being linked. In the same way it
guesses for the blocks it uses for the <B>-sectorder</B> option. With
the difference being that all sections are broken up into individual
blocks with the goal to eliminate the unreachable (dead) blocks in
the linked output. The reason this is fragile is that all the symbols
in an object file may not be the start of an individual block.</P>

<P>As a workaround to the problem of incorrectly strip a live block
you can produce a <B>-sectorder</B> 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
<I>.section_all</I>. 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:</P>

<BLOCKQUOTE>/usr/lib/crt1.o:.section_all<BR>
   /usr/lib/libgcc.a:darwin-tramp.o:section_all</BLOCKQUOTE>

<P>to your <I>order_file</I> for the __TEXT __text section. Then use
the ld(1) option <B>-sectorder</B> __TEXT __text <I>order_file</I>
when linking.</P>

<H3>Current design limitations</H3>

<P>There is a limitation in the current design for individual blocks
that have no symbols visible in the object file. Symbols that are
temporary labels that start with a 'L', or symbols that have been
stripped. An individual block that starts with these symbols will
appear to be part of the previous block that has a symbol in the
object file. This can result in a linked image that does not have all
of its dead code stripped. When what would have been a dead
individual block becomes part of the previous block which is live.
Causing the dead individual block and all of its references to be
live.</P>

<P>By default when there are multiply defined symbols in the linked
objects this is treated as an error. Even when the <B>-dead_strip</B>
option is specified. Unused multiply defined symbols can be stripped
if the strongly discouraged <B>-m</B> 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.</P>

<P>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
&lt;mach-o/nlist.h&gt; which causes them to be live.</P>

<P>There is no support in the current design to dead strip branch
islands created with the compiler option <B>-mlongcall</B>.</P>

<H2>Assembly level and object file support for dead code
stripping</H2>

<H3>Marking of objects that can have their section contents divided
up</H3>

<P>The marking of object files which are OK to divide their section
contents into individual blocks is done with the new assembler
directive <B>.subsections_via_symbols</B>. 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 &lt;mach-o/loader.h&gt;:</P>

<BLOCKQUOTE>#define MH_SUBSECTIONS_VIA_SYMBOLS 0x2000 /* safe to
   divide up the sections into<BR>
   sub-sections via symbols for dead<BR>
   code stripping */</BLOCKQUOTE>

<P>This can be see with <I>otool</I>(1)'s <B>-hv</B> options and
shows up as <B>SUBSECTIONS_VIA_SYMBOLS </B>in the following
output:</P>

<BLOCKQUOTE>% otool.NEW -hv a.out<BR>
   a.out:<BR>
   Mach header<BR>
   magic cputype cpusubtype filetype ncmds sizeofcmds flags<BR>
   MH_MAGIC PPC ALL OBJECT 3 228 <B>SUBSECTIONS_VIA_SYMBOLS</B></BLOCKQUOTE>

<P>The new assembler directive <B>.subsections_via_symbols</B> can be
added to hand written assembly files provided the symbols are at the
start of individual blocks. Since this applies to the entire file,
when multiple object files are combined by the static link ediror,
ld(1), to produce a relocable object, using the -r flag, if any of
the objects do not have this flag set the output file will not have
this flag set.</P>

<P>For example this assembly code contains only two individual blocks
but four symbols:</P>

<BLOCKQUOTE>.text<BR>
   .globl _plus_three<BR>
   _plus_three:<BR>
   addi r3, r3, 1<BR>
   .globl _plus_two<BR>
   _plus_two:<BR>
   addi r3, r3, 1<BR>
   .globl _plus_one<BR>
   _plus_one:<BR>
   addi r3, r3, 1<BR>
   blr<BR>
   <BR>
   .globl _some_other_routine<BR>
   _some_other_routine:<BR>
   blr</BLOCKQUOTE>

<P>And if the new assembler directive <B>.subsections_via_symbols</B>
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
<B>-dead_strip</B> 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.</P>

<H3>The .no_dead_strip assembler directive</H3>

<P>The new assembler directive <B>.no_dead_strip</B>
<I>symbol_name</I> can be used to specify that a symbol is not to be
dead stripped. For example:</P>

<BLOCKQUOTE>.no_dead_strip _my_version_string<BR>
   .cstring<BR>
   _my_version_string:<BR>
   .ascii "cctools-501"</BLOCKQUOTE>

<P>This can be seen (in object files only) with <I>nm</I>(1)'s
<B>-m</B> option and shows up as <B>&#91;no dead strip&#93;</B> in
the following output:</P>

<BLOCKQUOTE>% nm -m x.o<BR>
   00000000 (__TEXT,__cstring) non-external <B>&#91;no dead
   strip&#93;</B> _my_version_string</BLOCKQUOTE>

<P>The <B>.no_dead_strip</B> directive is generated by the new
compiler when the __attribute__((used)) is specified on a symbol.</P>

<P>In object files, this bit is N_NO_DEAD_STRIP as defined in
&lt;mach-o/nlist.h&gt;. And is set in relocatable .o files (MH_OBJECT
filetype) only in the n_desc field of an nlist struct.</P>

<H3>The section attribute no_dead_strip</H3>

<P>The new section attribute <B>no_dead_strip</B> 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:</P>

<BLOCKQUOTE>.section __OBJC, __image_info, regular,
   <B>no_dead_strip</B></BLOCKQUOTE>

<P>In object files, this bit is S_ATTR_NO_DEAD_STRIP as defined in
&lt;mach-o/loader.h&gt;. And is set in the flags field of a section
struct.</P>

<H3>The section attribute live_support</H3>

<P>The new section attribute <B>live_support</B> 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:</P>

<BLOCKQUOTE>.section __TEXT, __eh_frame, coalesced,
   no_toc+strip_static_syms+<B>live_support</B></BLOCKQUOTE>

<P>In object files, this bit is S_ATTR_LIVE_SUPPORT as defined in
&lt;mach-o/loader.h&gt;. And is set in the flags field of a section
struct.</P>

<H3><FONT SIZE="+1">The assembler has a new .machine
directive</FONT></H3>

<P>The assembler now takes a new <B>.machine</B> directive as an
alternate to using the command line <B>-arch</B> <I>arch_name</I>
option. It is specified as for example as:</P>

<BLOCKQUOTE>.machine ppc970</BLOCKQUOTE>

<P>Where <I>ppc970</I> can be any <I>arch_name</I> that would appear
in the <B>-arch</B> <I>arch_name</I> option as listed on the
<I>arch</I>(3) man page for the assembler's architecture family.</P>

<H2>Notes Specific to Mac OS X 10.3.4 Release</H2>

<H2>New Features</H2>

<H2>Improved launch times of applications</H2>

<P>The dynamic linker has been changed that improve launch times of
applications.</P>

<H3><FONT SIZE="+1">The redo_prebinding command supports
unprebinding</FONT></H3>

<P>The <I>redo_prebinding</I>(1) command has a new option, <B>-u</B>,
that does a unprebind operation. The unprebind operation produces a
canonical form of a Mach-O file that can be used for binary diffing
and patching. Bundles and non-prebound executables and dylibs can
also be canonicalized with the unprebind operation.</P>

<H2>Notes Specific to Mac OS X December 2003 Release</H2>

<UL>
   <LI>There are no notes specific to the Mac OS X December 2003
   release of the compiler tools.</LI>
</UL>

<H2>Notes Specific to Mac OS X 10.3 Release</H2>

<H2>New Features</H2>

<H3><FONT SIZE="+1">The static linker has an option to find
@executable_path dynamic libraries</FONT></H3>

<P>Added the <B>-executable_path </B><I>path_name</I> option to
<I>ld</I>(1) where <I>path_name</I> is is used to replace
@executable_path for dependent libraries.</P>

<H2>Notes Specific to Mac OS X June 2003 Developer Release</H2>

<H2>New Features</H2>

<H3><FONT SIZE="+1">The compiler tools now support the PowerPC 970
processor</FONT></H3>

<P>The compiler tools now support the PowerPC 970 processor. The
architecture specific flag <B>-arch ppc970</B> 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
<B>-arch ppc970 </B>or <B>-force_cpusubtype_ALL</B> is specified.</P>

<P>To specify branch predictions which use the AT bit encodings for
<I>The branch is very likely to be taken</I> and <I>The branch is
very likely not to be taken</I> the two character suffixes ++ and --
are used. For example:</P>

<BLOCKQUOTE>bge-- foo</BLOCKQUOTE>

<P>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
<B>-static_branch_prediction_AT_bits</B> (see the <I>as</I>(1) man
page for more details).</P>

<H3><FONT SIZE="+1">The compiler tools now support stub
libraries</FONT></H3>

<P>The compiler tools now support stub libraries created from dynamic
libraries which are used in the SDKs. Stub libraries are created via
<I>strip</I>(1) and the new <B>-c</B> option. And can be linked
against in place of the actual dynamic library.</P>

<H3><FONT SIZE="+1">The static linker now can search for libraries
first in the library paths</FONT></H3>

<P>By default when the <B>-dynamic</B> flag is in effect, the
<B>-l</B><I>x</I> and <B>-weak-l</B><I>x</I> options first search for
a file of the form lib<I>x</I>.dylib in each directory in the library
search path, then a file of the form lib<I>x</I>.a is searched for in
the library search paths. The new option <B>-search_paths_first</B>
changes it so that in each path lib<I>x</I>.dylib is searched for
then lib<I>x</I>.a before the next path in the library search path is
searched.</P>

<H3><FONT SIZE="+1">The static linker now supports forcing a dynamic
library to be weak</FONT></H3>

<P>Added the <B>-weak_framework</B>, <B>-weak_library</B> and
<B>-weak-l</B> options to <I>ld</I>(1) to force the dynamic library
and the symbols referenced from it to be marked as weak imports. See
the <I>ld</I>(1) man page for more details.</P>

<H3><FONT SIZE="+1">The static linker now has a work around for not
having dead code stripping</FONT></H3>

<P>Added the <B>-undefined define_a_way</B> option to <I>ld</I>(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
<I>ld</I>(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.</P>

<H2>Notes Specific to Mac OS X November 2002 Developer Release</H2>

<H2>New Features</H2>

<H3><FONT SIZE="+1">Exports lists can now be specified to the static
linker</FONT></H3>

<P>The static link editor, <I>ld</I>(1), now has two new options,
<B>-exported_symbols_list </B><I>filename </I>and<I>
</I><B>-unexported_symbols_list </B><I>filename </I>to limit the
global symbols in the linked output file. This was previously done by
with an <I>nmedit</I>(1). By using the new options to <I>ld</I>(1)
the use of <I>nmedit</I>(1) can be eliminated resulting in faster
build times.</P>

<H3><FONT SIZE="+1">The static linker now can build single module
dynamic libraries</FONT></H3>

<P>The static link editor, <I>ld</I>(1), now has a new option,
<B>-single_module</B>, to build a dynamic library containing only one
module. This was previously done by first creating a master.o file
with an <I>ld</I>(1) <B>-r</B> step and then using the master.o to
created the dynamic library. By using the new <B>-single_module</B>
option to <I>ld</I>(1) this first step can be eliminated resulting in
faster build times.</P>

<P>The default in the static link editor remains the same and dynamic
libraries are built with multiple modules. The new flag
<B>-multi_module</B> has also been added to allow this to be
explicitly specified.</P>

<H3><FONT SIZE="+1">The static linker's -s option now works like
strip on dynamic executables</FONT></H3>

<P>The static link editor's <B>-s</B> option can now be used to strip
an executable that use the dynamic link editor. This will produce the
same result as running <I>strip</I>(1) with no options on the
executable. By using the <B>-s</B> option when building an executable
the <I>strip</I>(1) step can be eliminated resulting in faster build
times.</P>

<H2>Notes Specific to Mac OS X 10.2 Release</H2>

<P>The compiler tools for the MacOS X 10.2 Release must be used with
prebound images (executables, and shared libraries) from the MacOS X
10.2 User Release. The compiler tools in MacOS 10.1 will not work
with prebound images from with the MacOS X 10.2 User Release. If the
10.1 compiler tools are used on prebound images from the MacOS X 10.2
User Release the compiler tools will generate error messages
indicating that the image is a malformed file.</P>

<H2>New Features</H2>

<H3><FONT SIZE="+1">The dynamic linker now supports weak references
and weak dylibs</FONT></H3>

<P>The dynamic linker now supports weak symbol references and weak
dymamic libraries. When creating a binary with the static link editor
if all the symbols referenced from a given dependent dynamic library
are weak references then the library is marked weak. When the binary
is used at execution time and a weak library is missing the dynamic
linker will not cause an error. For all weak symbols that are missing
execution time the dynamic linker uses zero as their address. This
allows a weak symbol's address to be tested for zero at runtime
allowing the code to avoid using the weak symbol when it is missing.
Binaries that use weak references require a dynamic linker from Mac
OS X 10.2 or later.</P>

<P>To indicate a symbol is to be a weak reference the
__attribute((weak_import)) is used on the prototype of the symbol.
When a binary is created by the static link editor normally the all
the undefined symbol references of the object files being linked
should be consistent for each undefined symbol. That is all undefined
symbols should either be weak or non-weak references. If they are not
by default this is treated as an error and can be changed with the
ld(1) <B>-weak_reference_mismatches</B> <I>treatment</I> flag (see
the ld(1) man page for more details).</P>

<P>Weak referenced symbols and weak libraries are only created in the
output by the static link editor, <I>ld</I>(1), when the
MACOSX_DEPLOYMENT_TARGET environment variable is set to 10.2. If not
a warning is generated when a weak reference would be in the output
and it is not marked weak. Note the default for the
MACOSX_DEPLOYMENT_TARGET environment variable 10.1 so weak referenced
symbols and weak libraries are not created by default. See the
<I>ld</I>(1) man page for more information on the
MACOSX_DEPLOYMENT_TARGET environment variable.</P>

<H3><FONT SIZE="+1">redo_prebinding can now slide dylibs</FONT></H3>

<P>The redo_prebinding(1) command now can slide dymamic libraries to
new prefered addresses (see the man page for more details).</P>

<H2>Notes Specific to Mac OS X 10.1 Release</H2>

<P>You must use the 10.1 compiler tools with images (executables,
plugins and shared libraries) created with the 10.1 tools. The
compiler tools in MacOS 10.0 will not work with images created with
the 10.1 compiler tools. If you attempt to use the 10.0 compiler
tools on images created with the 10.1 compiler tools, error messages
may result indicating that the image is a malformed file.</P>

<P>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 <A HREF="#namespacenote">(see below
for more information)</A>.</P>

<H2>New Features</H2>

<P>The following new features have been added to the Compiler Tools
for the Mac OS X 10.1 system release.</P>

<UL>
   <LI><A NAME=namespacenote id=namespacenote></A>The compiler tools
   now support two-level namespaces for binding undefined references
   from shared libraries. In flat namespace images, all symbols are
   referenced globally using a single name table. In two-level
   namespace images, symbols are referenced by library name and
   symbol name. This prevents multiple-defined-symbol errors when one
   image exports the same symbol as another image in the same
   program. You must rebuild your applications and plugins to take
   advantage of this feature, and there are compatibility
   restrictions with Mac OS X 10.0 that you should understand. For
   more information see the <I>ld</I>(1) man page and the <A HREF="TwoLevelNamespaces.html">two-level
   namespace release note.</A></LI>
   
   <LI>The dynamic linker now has API's for doing two-levelnamespace
   lookups. They are NSAddImage(), NSLookupSymbolInImage() and
   NSIsSymbolNameDefinedInImage(). For more information see the
   NSModule(3) man page. &#91;This fixes Apple bug number
   2689833.&#93;</LI>
   
   <LI><A HREF="Prebinding.html">Prebinding is now documented in a
   release note.</A> &#91;This fixes Apple bug number
   2611234.&#93;</LI>
</UL>

<H2>Notes Specific to Mac OS X 10.0 Release</H2>

<UL>
   <LI>There are no notes specific to the Mac OS X 10.0 release of
   the compiler tools.</LI>
</UL>

<H2>Notes Specific to Mac OS X Public Beta Release</H2>

<H3>New Features</H3>

<P>The following new features have been added to the Compiler Tools
since the Mac OS X Developer Release 4.</P>

<UL>
   <LI>The dynamic linker now calls shared library initialization
   routines in their dependent order (reference number 2441683).</LI>
   
   <LI>The new function __initialize_Cplusplus() now can be called
   from a shared library initialization routine to cause the static
   C++ objects in the library to be initialized. This allows shared
   library initialization routines to make use of statically
   initialized C++ objects (reference number 2441683).</LI>
   
   <LI>The dynamic linker now supports module termination functions
   for all types of images (executables, plugins that are not
   unloaded and shared libraries). See the decription below as part
   of the notes specific to Mac OS X Developer preview of module
   termination functions (reference number 2469527).</LI>
   
   <LI>The compiler tools support the new directory layout for MacOS
   X Public Beta. The new location for Frameworks local to the
   machine is /MacOSX/Library/Framework (in DP4 and previous releases
   this was /Local/Library/Frameworks).</LI>
</UL>

<H2>Notes Specific to Mac OS X Developer Release 4</H2>

<UL>
   <LI>There are no notes specific to the compiler tools for
   Developer Release 4.</LI>
</UL>

<H2>Notes Specific to Mac OS X Developer Release 3</H2>

<H3><FONT SIZE="+1">New Features</FONT></H3>

<P>The following new features have been added to the Compiler Tools
since the Mac OS X Developer Release 2.</P>

<UL>
   <LI>The static linker supports removing duplicate debugging
   information from header files when this information appears in
   multiple linked object files. This is done with the -Si option to
   the static link editor and is now the default. To have no symbols
   stripped when linking use the new -Sn option.</LI>
</UL>

<H2>Notes Specific to Mac OS X Developer Release 2</H2>

<H3><FONT SIZE="+1">New Features</FONT></H3>

<P>The following new features have been added to the Compiler Tools
since the Mac OS X Developer Preview Release.</P>

<UL>
   <LI>Dynamic shared libraries now can have a dynamic shared library
   initialization routine (reference number 2367584). This routine is
   specified to libtool(1) with the new "-init <I>symbol_name</I>"
   argument. The library initialization routine is called before any
   symbol is used from the library including C++ static initializers
   (and #pragma CALL_ON_MODULE_BIND routines). So the code in a
   library initialization routine or code called by it can not depend
   on C++ static initializers. Also code in a library initialization
   routine or code called by it can not call any of the dynamic
   linker API, &lt;mach-o/dyld.h&gt;, otherwise that could result in
   more than one library initialization routine being partially
   executed on the stack.</LI>
   
   <LI>The dynamic linker now supports shared library install names
   that start with "@executable_path/" and substitutes the directory
   path of the executable for "@executable_path/"when locating the
   library. This requires a kernel from Mac OS X Developer Release 2
   or later. Without that kernel, this feature can only be used if
   argv&#91;0&#93; is in fact the name of the executable and it is an
   absolute path or relative to the current directory (contains at a
   '/' in the argv&#91;0&#93; string).</LI>
   
   <LI>The NSLinkModule() API now has an option to cause it to return
   when there is an error loading the module and a new API
   NSLinkEditError() to get the error information. To use this the
   constant NSLINKMODULE_OPTION_RETURN_ON_ERROR needs to be or'ed
   into the options parameter to NSLinkModule(). Then if
   NSLinkModule() returns NULL the error information can be retrieved
   with NSLinkEditError().
   
   <P>The NSLINKMODULE_OPTION_RETURN_ON_ERROR option is an
   alternative method to the existing dyld error handling which fits
   better with a plugin model. With the
   NSLINKMODULE_OPTION_RETURN_ON_ERROR option, the model for handling
   errors is to simply return without any changes to the program. To
   support this model of error handling a new API has been added to
   allow the programmer to get the error information that the dyld
   error handlers would normally have gotten. The API is similar to
   the dyld linkEdit error handler except that all the parameters are
   passed as pointers to be filled in.</P>
   
   <UL>
      <LI>extern void NSLinkEditError(<BR>
      NSLinkEditErrors *c,<BR>
      int *errorNumber,<BR>
      const char **fileName,<BR>
      const char **errorString);</LI>
   </UL>
   
   <P>The last two parameters return pointers to static buffers
   allocated in the dynamic linker which get reused on subsequent
   calls to NSLinkEditError(). The NSLinkEditErrors enum has been
   extended to include NSLinkEditUndefinedError and
   NSLinkEditMultiplyDefinedError.</P></LI>
</UL>

<H2>Notes Specific to Mac OS X Developer Preview Release</H2>

<H3><FONT SIZE="+1">New Features</FONT></H3>

<P>The following new features have been added to the Compiler Tools
since the Mac OS X Server Release.</P>

<UL>
   <LI>The NSLinkModule() API now can create private modules and the
   new API NSLookupSymbolInModule() allows symbols to be looked up in
   a private module. To do this the interface to NSLinkModule() has
   changed in a compatible way from:
   
   <UL>
      <LI>extern NSModule NSLinkModule(<BR>
      NSObjectFileImage objectFileImage,<BR>
      const char *moduleName,<BR>
      enum bool bindNow);</LI>
   </UL>
   
   <P>to:</P>
   
   <UL>
      <LI>extern NSModule NSLinkModule(<BR>
      NSObjectFileImage objectFileImage,<BR>
      const char *moduleName,<BR>
      unsigned long options);</LI>
   </UL>
   
   <P>with the options as follows:</P>
   
   <UL>
      <LI>#define NSLINKMODULE_OPTION_NONE 0x0<BR>
      #define NSLINKMODULE_OPTION_BINDNOW 0x1<BR>
      #define NSLINKMODULE_OPTION_PRIVATE 0x2</LI>
   </UL>
   
   <P>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:</P>
   
   <UL>
      <LI>extern NSSymbol NSLookupSymbolInModule(<BR>
      NSModule module,<BR>
      const char *symbolName);</LI>
   </UL>
   
   <P>Then to get the address of the returned NSSymbol, the existing
   NSAddressOfSymbol() API can be used.</P>
   
   <P>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):</P>
   
   <UL>
      <LI>only works for plugins (can only be called on modules that
      were returned by NSLinkModule).</LI>
      
      <LI>C++ plugins that have a static destructor can't be
      unloaded. The program will crash in atexit(3) when the unlinked
      destructor is attempted to be called.</LI>
      
      <LI>Objective-C plugins should not be unloaded. The Objective-C
      runtime has not been updated to know about unloading and the
      result is very likely to crash the program.</LI>
      
      <LI>The debugger has not been updated to know about unloading
      and trying to debug a program that unloads its plugins may
      confuse or crash the debugger.</LI>
   </UL>
   
   <P>The interface to NSUnLinkModule has changed in a compatible way
   from:</P>
   
   <UL>
      <LI>extern enum bool NSUnLinkModule(<BR>
      NSModule module,<BR>
      enum bool keepMemoryMapped);</LI>
   </UL>
   
   <P>to:</P>
   
   <UL>
      <LI>extern enum bool NSUnLinkModule(<BR>
      NSModule module,<BR>
      int options);</LI>
   </UL>
   
   <P>where the options are:</P>
   
   <UL>
      <LI>#define NSUNLINKMODULE_OPTION_NONE 0x0<BR>
      #define NSUNLINKMODULE_OPTION_KEEP_MEMORY_MAPPED 0x1<BR>
      #define NSUNLINKMODULE_OPTION_RESET_LAZY_REFERENCES 0x2</LI>
   </UL>
   
   <P>The first two are the same as keepMemoryMapped with a value of
   FALSE and TRUE. The reset lazy references option allows unloading
   modules with only call sites to undefined functions (direct calls,
   not calls through pointers) to not cause an undefined symbol
   error. Then if a subsequent module is loaded that defines symbols
   that were previously undefined, the call sites will use the new
   definitions. This is currently only implemented for PowerPC.</P>
   
   <P>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:</P>
   
   <UL>
      <LI>void my_term(void)<BR>
      {<BR>
      /* do module termination */<BR>
      }<BR>
      /* #pragma CALL_ON_UNLOAD my_term */<BR>
      #pragma SECTION data ".section __DATA, __mod_term_func,
      mod_init_funcs"<BR>
      static void (*dummy)(void) = my_term;<BR>
      #pragma SECTION data</LI>
   </UL>
   </LI>
</UL>

<H2>Notes Specific to Mac OS X Server Release</H2>

<H3><FONT SIZE="+1">New Features</FONT></H3>

<P>The following new features have been added to the Compiler Tools
since the Rhapsody Developer Release 2.</P>

<UL>
   <LI>The 4.4bsd ar extended format #1 is now supported by the
   compiler tools. The default is to use 4.4bsd ar extended format #1
   when creating static archives whose member names are longer than
   16 characters or have spaces in the name. The tools that create
   static archives, ar(1), libtool(1) and ranlib(1), all take the
   options -T (to truncate member names) and -L (to used long member
   names, the default) (reference 1670513).</LI>
   
   <LI>The AltiVec opcodes have been added to the Mac OS X PowerPC
   assembler. To assemble files with these instructions it requires
   the option -force_cpusubtype_ALL and then it is the code's
   responsibility to only use these instructions when the CPU
   supports them. (references 2237908, 2227999, 2213821,
   2004760).</LI>
   
   <LI>The header file &lt;mach-o/getsect.h&gt; has been added to the
   system as the proper place to get the prototypes of the Mach-O
   routines. (reference 2227839).</LI>
</UL>

<P>&nbsp;</P>

<H2>There are no Notes Specific to Rhapsody Developer Release 2</H2>

<P>&nbsp;</P>

<H2>Notes Specific to Rhapsody Developer Release</H2>

<H3>New Features</H3>

<P>The following new features have been added to the compiler tools
since OPENSTEP 4.2 (NeXT).</P>

<UL>
   <LI>The PowerPC architecture is now supported via the <CODE>-arch
   ppc</CODE> switch.<BR>
   <BR>
   </LI>
</UL>

<H3>Known Problems</H3>

<P>These bugs are known to exist in the compiler tools:</P>

<P>

<HR>

<TABLE BORDER=0 CELLSPACING=4>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Reference</FONT></P>
      </TD>
      <TD>
         <P>1670513</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Problem</FONT></P>
      </TD>
      <TD>
         <P>4.4BSD <B>ar</B> extended format #1 not compatible with
         compiler tools.</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Description</FONT></P>
      </TD>
      <TD>
         <P>The 4.4 <B>ar</B> command can create an archive with the
         base name of an object file that is longer than 16
         characters. With the <B>-L</B> option, it produces a format
         that makes the object file in the archive invisible to
         various tools, including the static link editor. This can
         lead to undefined symbols when this archive is linked
         against. Other tools like <B>nm</B> and <B>ranlib</B> also
         don't see the long-name object files in the archive. To
         avoid this problem, <B>ar</B> makes the <B>-T </B>option,
         which truncates names, a default option. The compiler tools
         will understand the extended format in future releases.</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Workaround</FONT></P>
      </TD>
      <TD>
         <P>Do not use the <B>-L</B> option with <B>ar</B> when
         creating archive libraries. Use the <B>-T</B> option (the
         default for the Premier release) to tuncate file names or
         use <B>libtool</B> <B>-static</B> to create archive
         libraries.</P>
      </TD>
   </TR>
</TABLE>

<HR>

<TABLE BORDER=0 CELLSPACING=4>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Reference</FONT></P>
      </TD>
      <TD>
         <P>1666993</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Problem</FONT></P>
      </TD>
      <TD>
         <P>The Mac OS X assembler is different from
         <B>ppcasm</B>.</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Description</FONT></P>
      </TD>
      <TD>
         <P>The major difference is that the Mac OS X assembler is
         not TOC-based and uses two instructions to load a global or
         static item. The directives and the syntax of labels and
         directives of the two assemblers are very different. Also,
         the Mac OS X assembler is stricter in the parameter types
         and ranges for instructions. For more on this last topic,
         see "Instruction Parameter Differences," below.</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Workaround</FONT></P>
      </TD>
      <TD>
         <P>The difference between the Mac OS X assembler and the
         TOC-based model, plus the differences in directives and
         syntax, may necessitate significant rewriting of assembly
         code for the Developer Release. The strict parameter
         requirements might require rewriting of assembly code for
         the Developer Release but the resulting code should work
         with <B>ppcasm</B>.</P>
      </TD>
   </TR>
</TABLE>

<HR>

<TABLE BORDER=0 CELLSPACING=4>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Reference</FONT></P>
      </TD>
      <TD>
         <P>1670513</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Problem</FONT></P>
      </TD>
      <TD>
         <P>BSD 4.4 <B>ar</B> format is not compatible with compiler
         tools</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Description</FONT></P>
      </TD>
      <TD>
         <P>The BSD 4.4 <B>ar</B> command, which creates an archive
         with object file names longer than 16 characters, produces a
         format that makes the object file invisible to various
         tools, including the static link editor. This can lead to
         undefined symbols when a program links against this archive.
         Other tools like <B>nm</B> and <B>ranlib</B> also don't see
         the object files with longer names in the archive.</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Workaround</FONT></P>
      </TD>
      <TD>
         <P>Use the <B>-T</B> option with <B>ar</B> to tuncate file
         names or use <B>libtool -static</B> to create archive
         libraries.</P>
      </TD>
   </TR>
</TABLE>

<HR>

</P>

<H3>Bugs Fixed</H3>

<P>The following bug has been fixed:</P>

<P><TABLE BORDER=0 CELLSPACING=4>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Reference</FONT></P>
      </TD>
      <TD>
         <P>none</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Problem</FONT></P>
      </TD>
      <TD>
         <P>Profiling does not work</P>
      </TD>
   </TR>
   <TR>
      <TD VALIGN=top WIDTH=60>
         <P ALIGN=right><FONT SIZE="-1">Description</FONT></P>
      </TD>
      <TD>
         <P>Bugs were reported when developers tried to compile, run
         and produce the profiling information for a program. Among
         these bigs were kernel panics, <B>gprof</B>(1) not
         understanding the <B>gmon.out</B> format produced,
         <B>add_profil</B>(2) system call not working, and other
         problems.</P>
      </TD>
   </TR>
</TABLE>
</P>

<P>

<HR>

</P>

<H3>PowerPC Assembly Instruction Parameter Differences</H3>

<P>Register names can't be designated with just a number. You must
refer to them with their register name. This restriction includes
general registers (<CODE>r</CODE><I>N</I>), floating point registers,
(<CODE>f</CODE><I>N</I>), condition registers
(<CODE>cr</CODE><I>N</I>), and segment registers
(<CODE>sr</CODE><I>N</I>). 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,
<CODE>mq</CODE>, <CODE>xer</CODE>, <CODE>lr</CODE>, <CODE>ctr</CODE>,
and <CODE>dsisr</CODE>).</P>

<P>For instance, for the <B>ppcasm</B> assember you could code a move
from segment register instruction as:</P>

<PRE>mfsr r24,9 ; ppcasm assembler</PRE>

<P>But, for the Mac OS X assembler, this same move would be coded
as:</P>

<PRE>mfsr r24,sr9 ; Mac OS X assembler</PRE>

<P>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.</P>

<P>Where a numeric value is expected as a parameter, a register name
can't be use. For example, the <B>ppcasm</B> assembler allows the
following:</P>

<PRE>lwz r1,r2(r3) ; ppcasm assembler</PRE>

<P>For Mac OS X, this must be coded as:</P>

<PRE>lwz r1,2(r3) ; Mac OS X assembler</PRE>

<P>The Mac OS X assembler generates a warning if branch prediction is
coded with an unconditional branch.</P>

<P>The Mac OS X assembler checks all fields for range errors and
generates error messages if an expression is out of range. The
<B>ppcasm</B> assembler simply uses the low <I>N</I> bits of the
expression (where <I>N</I> is the field width) if the value is
greater than zero. For example the simplified mnemonic:</P>

<PRE>inslwi r<I>A</I>,r<I>S</I>,<I>n</I>,<I>b</I></PRE>

<P>is equivalent to</P>

<PRE>rlwimi r<I>A</I>,r<I>S</I>,32-<I>b</I>,<I>b</I>,(<I>b</I>+<I>n</I>)-1</PRE>

<P>The following code:</P>

<PRE>inslwi r17,r18,19,20 ; equivalent to rlwimi r17,r18,32-20,20,(20+19)-1</PRE>

<P>assembles to</P>

<PRE>rlwimi r17,r18,12,20,6 ; where the low 5 bits (20+19)-1 is 6</PRE>

<P>with <B>ppcasm</B>. This generates an out-of-range error with the
Mac OS X assembler.</P>

<P>For fields less than zero, the <B>ppcasm</B> assembler uses the
value of zero. For example, the simplified mnemonic:</P>

<PRE>clrlslwi r<I>A</I>,r<I>S</I>,<I>b</I>,<I>n</I></PRE>

<P>is equivalent to</P>

<PRE>rlwinm r<I>A</I>,r<I>B</I>,<I>n</I>,<I>b</I>-<I>n,</I>31-<I>b</I></PRE>

<P>Thus the following code:</P>

<PRE>clrlslwi r5,r6,7,8 ; equivalent to rlwinm r5,r6,8,7-8,31-7</PRE>

<P>assembles to:</P>

<PRE>rlwinm r5,r6,7,0,24 ; where 7-8 gets turned into 0</PRE>

<P>with <B>ppcasm</B>. This generates an out-of-range error with the
Mac OS X assembler.</P>

<P>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.</P>

<P>For example:</P>

<PRE>addi r1,r2,0xffff ; out of range for a 16-bit signed immediate</PRE>

<P>generates the message "Parameter error: expression out of range
(parameter 3)".</P>

<P>The <CODE>addi</CODE> 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:</P>

<PRE>addi r1,r2,0xffffffff</PRE>

<P>If this is half of a two-instruction 32-bit add it should be coded
as:</P>

<PRE>addis r1,0,ha16(<I>expression</I>)
addi r1,r2,lo16(<I>expression</I>)</PRE>

<P>Many of the simplified mnemonics are implemented as Mac OS X
assembler macros (as noted in the listing of PowerPC assembler
instructions in the assember manual). Like all macros, the macro is
expanded and assembled. This expansion can result in errors that can
seem confusing when you look at the coded macro. For example, the
simplified mnemonic:</P>

<PRE>extldi r<I>A</I>,r<I>S</I>,<I>n</I>,<I>b</I></PRE>

<P>is equivalent to</P>

<PRE>rldicr r<I>A</I>,r<I>S</I>,<I>b</I>,<I>n</I>-1 </PRE>

<P>Thus the following code:</P>

<PRE>extldi r1,r2,0,2</PRE>

<P>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.</P>

<P>The instruction <CODE>tlbiex</CODE>, which has been removed from
the PowerPC architecture, is not supported by the Mac OS X assembler.
This instruction is assembled by <B>ppcasm</B>.</P>

<P><FONT SIZE="-2" FACE="Geneva,Helvetica,Arial">Copyright &copy;
2003 Apple Computer, Inc.</FONT></P>
</BODY>
</HTML>