Update of /cvsroot/fink/web/doc/porting
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv23803/web/doc/porting
Modified Files:
basics.en.php index.en.php libtool.en.php porting.en.html
preparing-10.2.en.php preparing-10.3.en.php shared.en.php
Log Message:
Improved shared-library descritions and added missing xml tags
Index: preparing-10.2.en.php
===================================================================
RCS file: /cvsroot/fink/web/doc/porting/preparing-10.2.en.php,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- preparing-10.2.en.php 16 Mar 2005 18:13:58 -0000 1.1
+++ preparing-10.2.en.php 16 Mar 2005 18:35:31 -0000 1.2
@@ -1,7 +1,7 @@
<?
$title = "Porting - Preparing for 10.2";
$cvs_author = 'Author: dmacks';
-$cvs_date = 'Date: 2005/03/16 18:01:32';
+$cvs_date = 'Date: 2005/03/16 18:33:31';
$metatags = '<link rel="contents" href="index.php?phpLang=en" title="Porting
Contents"><link rel="next" href="preparing-10.3.php?phpLang=en"
title="Preparing for 10.3"><link rel="prev" href="libtool.php?phpLang=en"
title="GNU libtool">';
@@ -103,7 +103,7 @@
libtool fail with an install_name error, because libtool passes
the -install_name flag even along with the -bundle flag (when it is not
strictly needed). This behavior was accepted by the gcc2 compiler but is
-not being accepted by the gcc3 compiler. The fix can be found<a
href="http://www.mail-archive.com/fink-devel@lists.sourceforge.net/msg02025.html";>here.</a>
+not being accepted by the gcc3 compiler. The fix can be found <a
href="http://www.mail-archive.com/fink-devel@lists.sourceforge.net/msg02025.html";>here.</a>
Note that you do not need the patch if your package uses libtool-1.3.5
(for example, if you are using <code>UpdateLibtool: True</code>)
since it has already been incorporated into a revised version of fink's
Index: shared.en.php
===================================================================
RCS file: /cvsroot/fink/web/doc/porting/shared.en.php,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- shared.en.php 16 Mar 2005 18:13:59 -0000 1.6
+++ shared.en.php 16 Mar 2005 18:35:31 -0000 1.7
@@ -1,7 +1,7 @@
<?
$title = "Porting - Shared Code";
$cvs_author = 'Author: dmacks';
-$cvs_date = 'Date: 2005/03/16 18:01:32';
+$cvs_date = 'Date: 2005/03/16 18:33:31';
$metatags = '<link rel="contents" href="index.php?phpLang=en" title="Porting
Contents"><link rel="next" href="libtool.php?phpLang=en" title="GNU
libtool"><link rel="prev" href="basics.php?phpLang=en" title="Basics">';
@@ -15,9 +15,9 @@
- <p>One Mach-O feature that hits many people by surprise
is the strict distinction between shared libraries and dynamically loadable
modules. On ELF systems both are the same; any piece of shared code can be used
as a library and for dynamic loading.</p>
+ <p>One Mach-O feature that hits many people by surprise
is the strict distinction between shared libraries and dynamically loadable
modules. On ELF systems both are the same; any piece of shared code can be used
as a library and for dynamic loading. Use <code>otool -hv
<b>some_file</b></code> to see the filetype of <code>some_file</code>.</p>
- <p>Mach-O shared libraries have the file type MH_DYLIB
and carry the extension <code>.dylib</code>. They can be linked against with
the usual static linker flags, e.g. <code>-lfoo</code> for libfoo.dylib.
However, they can not be loaded as a module. (Side note: Shared libraries can
be loaded dynamically through an API. However, that API is different from the
API for bundles and the semantics make it useless for an dlopen() emulation.
Most notably, shared libraries can not be unloaded.)</p>
+ <p>Mach-O shared libraries have the file type MH_DYLIB
and carry the extension <code>.dylib</code>. They can be linked against with
the usual static linker flags, e.g. <code>-lfoo</code> for libfoo.dylib.
However, they can not be loaded as a module. (Side note: Shared libraries can
be loaded dynamically through an API. However, that API is different from the
API for bundles and the semantics make it useless for an <code>dlopen()</code>
emulation. Most notably, shared libraries can not be unloaded.)</p>
<p>Loadable modules are called "bundles" in Mach-O
speak. They have the file type MH_BUNDLE. Since no component involved cares
about it, they can carry any extension. The extension <code>.bundle</code> is
recommended by Apple, but most ported software uses <code>.so</code> for the
sake of compatibility. Bundles can be dynamically loaded and unloaded via dyld
APIs, and there is a wrapper that emulates <code>dlopen()</code> on top of that
API. It is not possible to link against bundles as if they were shared
libraries. However, it is possible that a bundle is linked against real shared
libraries; those will be loaded automatically when the bundle is loaded.</p>
@@ -26,27 +26,27 @@
<h2><a name="version">2.2 Version Numbering</a></h2>
- <p>On an ELF system, version numbers are usually
appended to the file name of the shared library, e.g.
<code>libqt.so.2.3.0</code>. On Darwin, the version numbers are placed between
the library name and the extension, e.g. <code>libqt.2.3.0.dylib</code>. Note
that this allows you to request a specific version of the library when linking,
using <code>-lqt.2.3.0</code> for the example above.</p>
+ <p>On an ELF system, version numbers are usually
appended to the file name of the shared library after the extension, e.g.
<code>libqt.so.2.3.0</code>. On Darwin, the version numbers are placed between
the library name and the extension, e.g. <code>libqt.2.3.0.dylib</code>. Note
that this allows you to request a specific version of the library when linking,
using <code>-lqt.2.3.0</code> for the example above.</p>
<p>When creating a shared library, you can specify a
name to be used when searching for the library at run time. This is usual
practice and allows several major versions of a library to be installed at the
same time. On ELF systems this is called the <code>soname</code>. What's
different on Darwin is that you can (and should) specify a full path along with
the file name. This eliminates the need for "rpath" options and the
ldconfig/ld.so.cache system. To use a library that is not yet installed, you
can set the DYLD_LIBRARY_PATH environment variable; see the dyld man page for
details.</p>
<p>The Mach-O format also offers real minor version
checking, unknown on ELF systems. Every Mach-O library carries two version
numbers: a "current" version and a "compatibility" version. Both version
numbers are written as three numbers separated by dots, e.g. 1.4.2. The first
number must be non-zero. The second and third number can be omitted and default
to zero. When no version is specified, it will default to 0.0.0, which is some
kind of wildcard value.</p>
- <p>The "current" version is for informational purposes
only. The "compatibility" version is used for checking as follows. When an
executable is linked, the version information from the library is copied into
the executable. When the executable is run, that version information is checked
against the used library. dyld generates a run time error and terminates the
program unless the used library version is equal to or newer than the one used
during linking.</p>
+ <p>The "current" version is for informational purposes
only. The "compatibility" version is used for checking as follows. When an
executable is linked, the version information from the library is copied into
the executable. When that executable is run, the stored version information is
checked against the version information in the library that is loaded. dyld
generates a run-time error and terminates the program unless the loaded library
version is equal to or newer than the one used during linking.</p>
<h2><a name="cflags">2.3 Compiler Flags</a></h2>
- <p>The generation of position-independent code (PIC) is
the default is the default on Darwin. Actually, PowerPC code is
position-independent by design, so there is no performance or space penalty
involved. So, you don't need to specify a PIC option when compiling code for a
shared library or module. However, the linker doesn't allow "common" symbols in
shared libraries, so you must use the <code>-fno-common</code> compiler
option.</p>
+ <p>The generation of position-independent code (PIC) is
the default on Darwin. Actually, PowerPC code is position-independent by
design, so there is no performance or space penalty involved. So, you don't
need to specify a PIC option when compiling code for a shared library or
module. However, the linker doesn't allow "common" symbols in shared libraries,
so you must use the <code>-fno-common</code> compiler option.</p>
<h2><a name="build-lib">2.4 Building a Shared Library</a></h2>
- <p>To build a shared library, you invoke the compiler
driver with the <code>-dynamiclib</code> option. This is best demonstrated by a
comprehensive example. We'll build a library called libfoo, composed of the
source files source.c and code.c. The version number is 2.4.5, where 2 is the
major revision (incompatible API change), 4 is the minor revision
(backwards-compatible API change) and 5 is the bugfix revision count (some
people call this the "teeny" revision, it denotes fully compatible changes).
The library depends on no other shared libraries and will be installed in
/usr/local/lib.</p>
+ <p>To build a shared library, you invoke the compiler
driver with the <code>-dynamiclib</code> option. This is best demonstrated by a
comprehensive example. We'll build a library called libfoo, composed of the
source files <code>source.c</code> and <code>code.c</code>. The version number
is 2.4.5, where 2 is the major revision (incompatible API change), 4 is the
minor revision (backwards-compatible API change) and 5 is the bugfix revision
count (some people call this the "teeny" revision, it denotes fully compatible
changes). The library depends on no other shared libraries and will be
installed in <code>/usr/local/lib</code>.</p>
<pre>cc -fno-common -c source.c
cc -fno-common -c code.c
@@ -58,10 +58,7 @@
ln -s libfoo.2.4.5.dylib libfoo.dylib</pre>
<p>
Note which parts of the version are used where.
-Also note that the static linker will use the libfoo.dylib symlink,
-while the dynamic linker will use the libfoo.2.dylib symlink.
-It is possible to point these symlinks at different minor revisions of
-the library.
+When linking against this library, one would normally use the
<code>-lfoo</code> flag, which accesses the <code>libfoo.dylib</code> symlink.
Regardless of which symlink or file is specified, though, it is the
<code>install_name</code> that is written into one's program. That means one
can delete the "higher" (less version-specific) symlink
<code>libfoo.dylib</code> after compiling. During a minor-revision library
upgrade, one just changes the target of the <code>libfoo.2.dylib</code> symlink
that is used by the runtime dynamic linker.
</p>
@@ -84,8 +81,8 @@
Note that no version numbering is used.
It is possible to use it in theory, but in practice it's pointless.
Also note that there are no naming restrictions for bundles.
-Some packages prefer to prepend a "lib" anyway because some other
-systems require it; this is harmless.
+Some packages prefer to prepend "lib" anyway because some other
+systems require it; this is harmless, since a program would use the full
filename when loading a module.
</p>
Index: index.en.php
===================================================================
RCS file: /cvsroot/fink/web/doc/porting/index.en.php,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- index.en.php 16 Mar 2005 18:13:58 -0000 1.6
+++ index.en.php 16 Mar 2005 18:35:30 -0000 1.7
@@ -1,17 +1,17 @@
<?
$title = "Porting";
$cvs_author = 'Author: dmacks';
-$cvs_date = 'Date: 2005/03/16 18:01:32';
+$cvs_date = 'Date: 2005/03/16 18:33:31';
$metatags = '<link rel="contents" href="index.php?phpLang=en" title="Porting
Contents"><link rel="next" href="basics.php?phpLang=en" title="Basics">';
include_once "header.en.inc";
?>
<h1>Porting Unix software to Darwin and Mac OS X</h1>
- <p>This document contains hints for porting Unix applications
to Darwin and Mac OS X. The information here applies to Mac OS X version 10.0.x
and Darwin 1.3.x. Both systems will be referred to as Darwin, since Mac OS X is
actually a superset of Darwin.</p>
+ <p>This document contains hints for porting Unix applications
to Darwin and Mac OS X. Much of the information here applies to both Mac OS X
version 10.x.x and "pure" Darwin systems. Both systems will be referred to as
Darwin, since Mac OS X is actually a superset of Darwin.</p>
<h2><? echo FINK_CONTENTS ; ?></h2><ul>
<li><a href="basics.php?phpLang=en"><b>1 Basics</b></a><ul><li><a
href="basics.php?phpLang=en#heritage">1.1 Where Darwin came from</a></li><li><a
href="basics.php?phpLang=en#compiler">1.2 The Compiler and Tools</a></li><li><a
href="basics.php?phpLang=en#host-type">1.3 Host type</a></li><li><a
href="basics.php?phpLang=en#libraries">1.4 Libraries</a></li><li><a
href="basics.php?phpLang=en#other-sources">1.5 Other sources of
information</a></li></ul></li><li><a href="shared.php?phpLang=en"><b>2 Shared
Code</b></a><ul><li><a href="shared.php?phpLang=en#lib-and-mod">2.1 Shared
Libraries vs. Loadable Modules</a></li><li><a
href="shared.php?phpLang=en#version">2.2 Version Numbering</a></li><li><a
href="shared.php?phpLang=en#cflags">2.3 Compiler Flags</a></li><li><a
href="shared.php?phpLang=en#build-lib">2.4 Building a Shared
Library</a></li><li><a href="shared.php?phpLang=en#build-mod">2.5 Building a
Module</a></li></ul></li><li><a href="libtool.php?phpLang=en"><b>3 GNU
libtool</b
></a><ul><li><a href="libtool.php?phpLang=en#situation">3.1 The
>Situation</a></li><li><a href="libtool.php?phpLang=en#patch-135">3.2 The
>1.3.5 Patch</a></li><li><a href="libtool.php?phpLang=en#fixing-14x">3.3
>Fixing 1.4.x</a></li><li><a href="libtool.php?phpLang=en#notes">3.4 Further
>Notes</a></li></ul></li><li><a href="preparing-10.2.php?phpLang=en"><b>4
>Preparing for 10.2</b></a><ul><li><a
>href="preparing-10.2.php?phpLang=en#bash">4.1 The bash shell</a></li><li><a
>href="preparing-10.2.php?phpLang=en#gcc3">4.2 The gcc3
>compiler</a></li></ul></li><li><a href="preparing-10.3.php?phpLang=en"><b>5
>Preparing for 10.3</b></a><ul><li><a
>href="preparing-10.3.php?phpLang=en#perl">5.1 Perl</a></li></ul></li></ul>
-<!--Generated from $Fink: porting.en.xml,v 1.4 2005/03/16 18:01:32 dmacks Exp
$-->
+<!--Generated from $Fink: porting.en.xml,v 1.5 2005/03/16 18:33:31 dmacks Exp
$-->
<? include_once "../../footer.inc"; ?>
Index: basics.en.php
===================================================================
RCS file: /cvsroot/fink/web/doc/porting/basics.en.php,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- basics.en.php 16 Mar 2005 18:13:58 -0000 1.6
+++ basics.en.php 16 Mar 2005 18:35:30 -0000 1.7
@@ -1,7 +1,7 @@
<?
$title = "Porting - Basics";
$cvs_author = 'Author: dmacks';
-$cvs_date = 'Date: 2005/03/16 18:01:32';
+$cvs_date = 'Date: 2005/03/16 18:33:31';
$metatags = '<link rel="contents" href="index.php?phpLang=en" title="Porting
Contents"><link rel="next" href="shared.php?phpLang=en" title="Shared
Code"><link rel="prev" href="index.php?phpLang=en" title="Porting Contents">';
@@ -37,12 +37,14 @@
<p>Short story: If configure fails with 'Can't
determine host type', copy config.guess and config.sub from /usr/share/libtool
(/usr/libexec for OS versions prior to 10.2) into the current directory.</p>
- <p>Long story: The GNU world uses a canonical format to
specify system types. It has three parts: cpu type, manufacturer and operating
system. Sometimes a fourth part is added - then the third part denotes the
kernel, while the fourth denotes the operating system. All parts are lower case
and concatenated using dashes. Some examples: <code>i586-pc-linux-gnu</code>,
<code>hppa1.1-hp-hpux10.20</code>, <code>sparc-sun-solaris2.6</code>. The host
type for Mac OS X 10.0 is <code>powerpc-apple-darwin1.3</code>.</p>
+ <p>Long story: The GNU world uses a canonical format to
specify system types. It has three parts: cpu type, manufacturer and operating
system. Sometimes a fourth part is added - then the third part denotes the
kernel, while the fourth denotes the operating system. All parts are lower case
and concatenated using dashes. Some examples: <code>i586-pc-linux-gnu</code>,
<code>hppa1.1-hp-hpux10.20</code>, <code>sparc-sun-solaris2.6</code>. The host
type for Mac OS X 10.0 is <code>powerpc-apple-darwin1.3</code>. Versions of Mac
OS X 10.2 bring various <code>powerpc-apple-darwin6.x.0</code>, where "x"
depends on the exact OS revision.</p>
<p>Many packages that use autoconf want to know the
host type of the system they are compiled on. (Side note: to support
cross-compiling and porting, there are actually three types - the host type,
the build type and the target type. Usually, they're all the same.) You can
either pass the host type to the configure script as a parameter or you can let
it guess.</p>
<p>The configure script uses two companion scripts to
determine host types. <code>config.guess</code> tries to guess the host type,
<code>config.sub</code> is used to validate and canonicalize the host type.
These scripts are maintained as separate entities, but they are included in
every package that uses them. Until very recently, these scripts didn't know
about Darwin or Mac OS X. If you have a package that doesn't recognize Darwin,
you must replace the config.guess and config.sub included in the package.
Luckily, Apple put working versions in /usr/share/libtool (/usr/libexec for
pre-10.2 OS), so you can just copy them from there.</p>
+ <p>If you are constructing a Fink package, you can use
the <code>UpdateConfigGuess</code> and/or <code>UpdateConfigGuessInDirs</code>
fields in your <code>.info</code> package description file to do this update
automatically.</p>
+
<h2><a name="libraries">1.4 Libraries</a></h2>
Index: libtool.en.php
===================================================================
RCS file: /cvsroot/fink/web/doc/porting/libtool.en.php,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- libtool.en.php 16 Mar 2005 18:13:58 -0000 1.6
+++ libtool.en.php 16 Mar 2005 18:35:31 -0000 1.7
@@ -1,7 +1,7 @@
<?
$title = "Porting - libtool";
$cvs_author = 'Author: dmacks';
-$cvs_date = 'Date: 2005/03/16 18:01:32';
+$cvs_date = 'Date: 2005/03/16 18:33:31';
$metatags = '<link rel="contents" href="index.php?phpLang=en" title="Porting
Contents"><link rel="next" href="preparing-10.2.php?phpLang=en"
title="Preparing for 10.2"><link rel="prev" href="shared.php?phpLang=en"
title="Shared Code">';
@@ -99,7 +99,7 @@
configure and make.) This is done automatically, by the way, in the
current Fink package for libtool 1.3.5.</p><p>
But that's only half the work - every package using libtool comes with
-its own copies of ltconfig and ltmain.sh.
+its own copies of <code>ltconfig</code> and <code>ltmain.sh</code>.
So you must replace these in every package that you want to build as a
shared library.
Note that you must do this before running the configure script.
@@ -113,9 +113,9 @@
<p>
There are at least three different versions of libtool 1.4.x now in wide use
(1.4.1, 1.4.2, and later development snapshots). They all have some issues on
-Darwin, though the exact changes required to fix them differ. The libtool14
+Darwin, though the exact changes required to fix them differ. The "libtool14"
package shipped via Fink has all required patches already applied to it.
-However, you still have to manually fix the ltmain.sh/configure files of
+However, you still have to manually fix the <code>ltmain.sh</code> and
<code>configure</code> files of
affected packages in order to get them working.
</p>
@@ -144,7 +144,7 @@
<li>
<b>The loadable module bug</b>:
This bug is caused by the non-standard behaviour of zsh (which is the default
-shell in 10.0 and 10.1; in 10.2 it is supposed to be replaced by bash).
+shell in 10.0 and 10.1; starting in 10.2 bash is the default).
Zsh's non-standard quoting behaviours prevents loadable module from being built
correctly, they end up as shared libraries instead (unlike Linux, these are
reall different things on Darwin). A typical fix for this (cut off, so you
can't
Index: preparing-10.3.en.php
===================================================================
RCS file: /cvsroot/fink/web/doc/porting/preparing-10.3.en.php,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- preparing-10.3.en.php 16 Mar 2005 18:13:59 -0000 1.1
+++ preparing-10.3.en.php 16 Mar 2005 18:35:31 -0000 1.2
@@ -1,7 +1,7 @@
<?
$title = "Porting - Preparing for 10.3";
$cvs_author = 'Author: dmacks';
-$cvs_date = 'Date: 2005/03/16 18:01:32';
+$cvs_date = 'Date: 2005/03/16 18:33:31';
$metatags = '<link rel="contents" href="index.php?phpLang=en" title="Porting
Contents"><link rel="prev" href="preparing-10.2.php?phpLang=en"
title="Preparing for 10.2">';
Index: porting.en.html
===================================================================
RCS file: /cvsroot/fink/web/doc/porting/porting.en.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- porting.en.html 16 Mar 2005 18:13:58 -0000 1.7
+++ porting.en.html 16 Mar 2005 18:35:31 -0000 1.8
@@ -11,7 +11,7 @@
</tr>
</table>
<h1 style="text-align: center;">Porting Unix software to Darwin and Mac OS
X</h1>
- <p>This document contains hints for porting Unix applications
to Darwin and Mac OS X. The information here applies to Mac OS X version 10.0.x
and Darwin 1.3.x. Both systems will be referred to as Darwin, since Mac OS X is
actually a superset of Darwin.</p>
+ <p>This document contains hints for porting Unix applications
to Darwin and Mac OS X. Much of the information here applies to both Mac OS X
version 10.x.x and "pure" Darwin systems. Both systems will be referred to as
Darwin, since Mac OS X is actually a superset of Darwin.</p>
<h2>Contents</h2><ul><li><a href="#basics"><b>1
Basics</b></a><ul><li><a href="#basics.heritage">1.1 Where Darwin came
from</a></li><li><a href="#basics.compiler">1.2 The Compiler and
Tools</a></li><li><a href="#basics.host-type">1.3 Host type</a></li><li><a
href="#basics.libraries">1.4 Libraries</a></li><li><a
href="#basics.other-sources">1.5 Other sources of
information</a></li></ul></li><li><a href="#shared"><b>2 Shared
Code</b></a><ul><li><a href="#shared.lib-and-mod">2.1 Shared Libraries vs.
Loadable Modules</a></li><li><a href="#shared.version">2.2 Version
Numbering</a></li><li><a href="#shared.cflags">2.3 Compiler
Flags</a></li><li><a href="#shared.build-lib">2.4 Building a Shared
Library</a></li><li><a href="#shared.build-mod">2.5 Building a
Module</a></li></ul></li><li><a href="#libtool"><b>3 GNU
libtool</b></a><ul><li><a href="#libtool.situation">3.1 The
Situation</a></li><li><a href="#libtool.patch-135">3.2 The 1.3.5
Patch</a></li><li><a href="#libtool.fixing-14x
">3.3 Fixing 1.4.x</a></li><li><a href="#libtool.notes">3.4 Further
Notes</a></li></ul></li><li><a href="#preparing-10.2"><b>4 Preparing for
10.2</b></a><ul><li><a href="#preparing-10.2.bash">4.1 The bash
shell</a></li><li><a href="#preparing-10.2.gcc3">4.2 The gcc3
compiler</a></li></ul></li><li><a href="#preparing-10.3"><b>5 Preparing for
10.3</b></a><ul><li><a href="#preparing-10.3.perl">5.1
Perl</a></li></ul></li></ul><h2><a name="basics">1 Basics</a></h2>
@@ -42,12 +42,14 @@
<p>Short story: If configure fails with 'Can't
determine host type', copy config.guess and config.sub from /usr/share/libtool
(/usr/libexec for OS versions prior to 10.2) into the current directory.</p>
- <p>Long story: The GNU world uses a canonical format to
specify system types. It has three parts: cpu type, manufacturer and operating
system. Sometimes a fourth part is added - then the third part denotes the
kernel, while the fourth denotes the operating system. All parts are lower case
and concatenated using dashes. Some examples: <tt style="white-space:
nowrap;">i586-pc-linux-gnu</tt>, <tt style="white-space:
nowrap;">hppa1.1-hp-hpux10.20</tt>, <tt style="white-space:
nowrap;">sparc-sun-solaris2.6</tt>. The host type for Mac OS X 10.0 is <tt
style="white-space: nowrap;">powerpc-apple-darwin1.3</tt>.</p>
+ <p>Long story: The GNU world uses a canonical format to
specify system types. It has three parts: cpu type, manufacturer and operating
system. Sometimes a fourth part is added - then the third part denotes the
kernel, while the fourth denotes the operating system. All parts are lower case
and concatenated using dashes. Some examples: <tt style="white-space:
nowrap;">i586-pc-linux-gnu</tt>, <tt style="white-space:
nowrap;">hppa1.1-hp-hpux10.20</tt>, <tt style="white-space:
nowrap;">sparc-sun-solaris2.6</tt>. The host type for Mac OS X 10.0 is <tt
style="white-space: nowrap;">powerpc-apple-darwin1.3</tt>. Versions of Mac OS X
10.2 bring various <tt style="white-space:
nowrap;">powerpc-apple-darwin6.x.0</tt>, where "x" depends on the exact OS
revision.</p>
<p>Many packages that use autoconf want to know the
host type of the system they are compiled on. (Side note: to support
cross-compiling and porting, there are actually three types - the host type,
the build type and the target type. Usually, they're all the same.) You can
either pass the host type to the configure script as a parameter or you can let
it guess.</p>
<p>The configure script uses two companion scripts to
determine host types. <tt style="white-space: nowrap;">config.guess</tt> tries
to guess the host type, <tt style="white-space: nowrap;">config.sub</tt> is
used to validate and canonicalize the host type. These scripts are maintained
as separate entities, but they are included in every package that uses them.
Until very recently, these scripts didn't know about Darwin or Mac OS X. If you
have a package that doesn't recognize Darwin, you must replace the config.guess
and config.sub included in the package. Luckily, Apple put working versions in
/usr/share/libtool (/usr/libexec for pre-10.2 OS), so you can just copy them
from there.</p>
+ <p>If you are constructing a Fink package, you can use
the <tt style="white-space: nowrap;">UpdateConfigGuess</tt> and/or <tt
style="white-space: nowrap;">UpdateConfigGuessInDirs</tt> fields in your <tt
style="white-space: nowrap;">.info</tt> package description file to do this
update automatically.</p>
+
<h3><a name="basics.libraries">1.4 Libraries</a></h3>
@@ -76,9 +78,9 @@
- <p>One Mach-O feature that hits many people by surprise
is the strict distinction between shared libraries and dynamically loadable
modules. On ELF systems both are the same; any piece of shared code can be used
as a library and for dynamic loading.</p>
+ <p>One Mach-O feature that hits many people by surprise
is the strict distinction between shared libraries and dynamically loadable
modules. On ELF systems both are the same; any piece of shared code can be used
as a library and for dynamic loading. Use <tt style="white-space:
nowrap;">otool -hv <b>some_file</b></tt> to see the filetype of <tt
style="white-space: nowrap;">some_file</tt>.</p>
- <p>Mach-O shared libraries have the file type MH_DYLIB
and carry the extension <tt style="white-space: nowrap;">.dylib</tt>. They can
be linked against with the usual static linker flags, e.g. <tt
style="white-space: nowrap;">-lfoo</tt> for libfoo.dylib. However, they can not
be loaded as a module. (Side note: Shared libraries can be loaded dynamically
through an API. However, that API is different from the API for bundles and the
semantics make it useless for an dlopen() emulation. Most notably, shared
libraries can not be unloaded.)</p>
+ <p>Mach-O shared libraries have the file type MH_DYLIB
and carry the extension <tt style="white-space: nowrap;">.dylib</tt>. They can
be linked against with the usual static linker flags, e.g. <tt
style="white-space: nowrap;">-lfoo</tt> for libfoo.dylib. However, they can not
be loaded as a module. (Side note: Shared libraries can be loaded dynamically
through an API. However, that API is different from the API for bundles and the
semantics make it useless for an <tt style="white-space: nowrap;">dlopen()</tt>
emulation. Most notably, shared libraries can not be unloaded.)</p>
<p>Loadable modules are called "bundles" in Mach-O
speak. They have the file type MH_BUNDLE. Since no component involved cares
about it, they can carry any extension. The extension <tt style="white-space:
nowrap;">.bundle</tt> is recommended by Apple, but most ported software uses
<tt style="white-space: nowrap;">.so</tt> for the sake of compatibility.
Bundles can be dynamically loaded and unloaded via dyld APIs, and there is a
wrapper that emulates <tt style="white-space: nowrap;">dlopen()</tt> on top of
that API. It is not possible to link against bundles as if they were shared
libraries. However, it is possible that a bundle is linked against real shared
libraries; those will be loaded automatically when the bundle is loaded.</p>
@@ -87,27 +89,27 @@
<h3><a name="shared.version">2.2 Version Numbering</a></h3>
- <p>On an ELF system, version numbers are usually
appended to the file name of the shared library, e.g. <tt style="white-space:
nowrap;">libqt.so.2.3.0</tt>. On Darwin, the version numbers are placed between
the library name and the extension, e.g. <tt style="white-space:
nowrap;">libqt.2.3.0.dylib</tt>. Note that this allows you to request a
specific version of the library when linking, using <tt style="white-space:
nowrap;">-lqt.2.3.0</tt> for the example above.</p>
+ <p>On an ELF system, version numbers are usually
appended to the file name of the shared library after the extension, e.g. <tt
style="white-space: nowrap;">libqt.so.2.3.0</tt>. On Darwin, the version
numbers are placed between the library name and the extension, e.g. <tt
style="white-space: nowrap;">libqt.2.3.0.dylib</tt>. Note that this allows you
to request a specific version of the library when linking, using <tt
style="white-space: nowrap;">-lqt.2.3.0</tt> for the example above.</p>
<p>When creating a shared library, you can specify a
name to be used when searching for the library at run time. This is usual
practice and allows several major versions of a library to be installed at the
same time. On ELF systems this is called the <tt style="white-space:
nowrap;">soname</tt>. What's different on Darwin is that you can (and should)
specify a full path along with the file name. This eliminates the need for
"rpath" options and the ldconfig/ld.so.cache system. To use a library that is
not yet installed, you can set the DYLD_LIBRARY_PATH environment variable; see
the dyld man page for details.</p>
<p>The Mach-O format also offers real minor version
checking, unknown on ELF systems. Every Mach-O library carries two version
numbers: a "current" version and a "compatibility" version. Both version
numbers are written as three numbers separated by dots, e.g. 1.4.2. The first
number must be non-zero. The second and third number can be omitted and default
to zero. When no version is specified, it will default to 0.0.0, which is some
kind of wildcard value.</p>
- <p>The "current" version is for informational purposes
only. The "compatibility" version is used for checking as follows. When an
executable is linked, the version information from the library is copied into
the executable. When the executable is run, that version information is checked
against the used library. dyld generates a run time error and terminates the
program unless the used library version is equal to or newer than the one used
during linking.</p>
+ <p>The "current" version is for informational purposes
only. The "compatibility" version is used for checking as follows. When an
executable is linked, the version information from the library is copied into
the executable. When that executable is run, the stored version information is
checked against the version information in the library that is loaded. dyld
generates a run-time error and terminates the program unless the loaded library
version is equal to or newer than the one used during linking.</p>
<h3><a name="shared.cflags">2.3 Compiler Flags</a></h3>
- <p>The generation of position-independent code (PIC) is
the default is the default on Darwin. Actually, PowerPC code is
position-independent by design, so there is no performance or space penalty
involved. So, you don't need to specify a PIC option when compiling code for a
shared library or module. However, the linker doesn't allow "common" symbols in
shared libraries, so you must use the <tt style="white-space:
nowrap;">-fno-common</tt> compiler option.</p>
+ <p>The generation of position-independent code (PIC) is
the default on Darwin. Actually, PowerPC code is position-independent by
design, so there is no performance or space penalty involved. So, you don't
need to specify a PIC option when compiling code for a shared library or
module. However, the linker doesn't allow "common" symbols in shared libraries,
so you must use the <tt style="white-space: nowrap;">-fno-common</tt> compiler
option.</p>
<h3><a name="shared.build-lib">2.4 Building a Shared
Library</a></h3>
- <p>To build a shared library, you invoke the compiler
driver with the <tt style="white-space: nowrap;">-dynamiclib</tt> option. This
is best demonstrated by a comprehensive example. We'll build a library called
libfoo, composed of the source files source.c and code.c. The version number is
2.4.5, where 2 is the major revision (incompatible API change), 4 is the minor
revision (backwards-compatible API change) and 5 is the bugfix revision count
(some people call this the "teeny" revision, it denotes fully compatible
changes). The library depends on no other shared libraries and will be
installed in /usr/local/lib.</p>
+ <p>To build a shared library, you invoke the compiler
driver with the <tt style="white-space: nowrap;">-dynamiclib</tt> option. This
is best demonstrated by a comprehensive example. We'll build a library called
libfoo, composed of the source files <tt style="white-space:
nowrap;">source.c</tt> and <tt style="white-space: nowrap;">code.c</tt>. The
version number is 2.4.5, where 2 is the major revision (incompatible API
change), 4 is the minor revision (backwards-compatible API change) and 5 is the
bugfix revision count (some people call this the "teeny" revision, it denotes
fully compatible changes). The library depends on no other shared libraries and
will be installed in <tt style="white-space: nowrap;">/usr/local/lib</tt>.</p>
<pre>cc -fno-common -c source.c
cc -fno-common -c code.c
@@ -119,10 +121,7 @@
ln -s libfoo.2.4.5.dylib libfoo.dylib</pre>
<p>
Note which parts of the version are used where.
-Also note that the static linker will use the libfoo.dylib symlink,
-while the dynamic linker will use the libfoo.2.dylib symlink.
-It is possible to point these symlinks at different minor revisions of
-the library.
+When linking against this library, one would normally use the <tt
style="white-space: nowrap;">-lfoo</tt> flag, which accesses the <tt
style="white-space: nowrap;">libfoo.dylib</tt> symlink. Regardless of which
symlink or file is specified, though, it is the <tt style="white-space:
nowrap;">install_name</tt> that is written into one's program. That means one
can delete the "higher" (less version-specific) symlink <tt style="white-space:
nowrap;">libfoo.dylib</tt> after compiling. During a minor-revision library
upgrade, one just changes the target of the <tt style="white-space:
nowrap;">libfoo.2.dylib</tt> symlink that is used by the runtime dynamic linker.
</p>
@@ -145,8 +144,8 @@
Note that no version numbering is used.
It is possible to use it in theory, but in practice it's pointless.
Also note that there are no naming restrictions for bundles.
-Some packages prefer to prepend a "lib" anyway because some other
-systems require it; this is harmless.
+Some packages prefer to prepend "lib" anyway because some other
+systems require it; this is harmless, since a program would use the full
filename when loading a module.
</p>
@@ -243,7 +242,7 @@
configure and make.) This is done automatically, by the way, in the
current Fink package for libtool 1.3.5.</p><p>
But that's only half the work - every package using libtool comes with
-its own copies of ltconfig and ltmain.sh.
+its own copies of <tt style="white-space: nowrap;">ltconfig</tt> and <tt
style="white-space: nowrap;">ltmain.sh</tt>.
So you must replace these in every package that you want to build as a
shared library.
Note that you must do this before running the configure script.
@@ -257,9 +256,9 @@
<p>
There are at least three different versions of libtool 1.4.x now in wide use
(1.4.1, 1.4.2, and later development snapshots). They all have some issues on
-Darwin, though the exact changes required to fix them differ. The libtool14
+Darwin, though the exact changes required to fix them differ. The "libtool14"
package shipped via Fink has all required patches already applied to it.
-However, you still have to manually fix the ltmain.sh/configure files of
+However, you still have to manually fix the <tt style="white-space:
nowrap;">ltmain.sh</tt> and <tt style="white-space: nowrap;">configure</tt>
files of
affected packages in order to get them working.
</p>
@@ -288,7 +287,7 @@
<li>
<b>The loadable module bug</b>:
This bug is caused by the non-standard behaviour of zsh (which is the default
-shell in 10.0 and 10.1; in 10.2 it is supposed to be replaced by bash).
+shell in 10.0 and 10.1; starting in 10.2 bash is the default).
Zsh's non-standard quoting behaviours prevents loadable module from being built
correctly, they end up as shared libraries instead (unlike Linux, these are
reall different things on Darwin). A typical fix for this (cut off, so you
can't
@@ -469,7 +468,7 @@
libtool fail with an install_name error, because libtool passes
the -install_name flag even along with the -bundle flag (when it is not
strictly needed). This behavior was accepted by the gcc2 compiler but is
-not being accepted by the gcc3 compiler. The fix can be found<a
href="http://www.mail-archive.com/fink-devel@lists.sourceforge.net/msg02025.html";>here.</a>
+not being accepted by the gcc3 compiler. The fix can be found <a
href="http://www.mail-archive.com/fink-devel@lists.sourceforge.net/msg02025.html";>here.</a>
Note that you do not need the patch if your package uses libtool-1.3.5
(for example, if you are using <tt style="white-space: nowrap;">UpdateLibtool:
True</tt>)
since it has already been incorporated into a revised version of fink's
@@ -494,4 +493,4 @@
provided the document and this copyright notice remain complete and
unmodified. Any commercial reproduction and any online publication
requires the explicit consent of the author.</p><hr>
-<p>Generated from <i>$Fink: porting.en.xml,v 1.4 2005/03/16 18:01:32 dmacks
Exp $</i></p></body></html>
+<p>Generated from <i>$Fink: porting.en.xml,v 1.5 2005/03/16 18:33:31 dmacks
Exp $</i></p></body></html>
-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click
_______________________________________________
Fink-commits mailing list
Fink-commits@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/fink-commits
