[darwinbuild-changes] [93] trunk/www

Wed Oct 4 01:44:49 PDT 2006

Revision: 93
          http://trac.macosforge.org/projects/darwinbuild/changeset/93
Author:   kevin
Date:     2006-10-04 01:44:49 -0700 (Wed, 04 Oct 2006)

Log Message:
-----------
- added some docs about using darwinbuild

Modified Paths:
--------------
    trunk/www/doc/tools/index.html
    trunk/www/sidebar.html

Modified: trunk/www/doc/tools/index.html
===================================================================

--- trunk/www/doc/tools/index.html	2005-07-25 23:47:49 UTC (rev 92)
+++ trunk/www/doc/tools/index.html	2006-10-04 08:44:49 UTC (rev 93)
@@ -19,12 +19,213 @@
 <h3>Overview</h3>
 <div class="articlebody">
 <p>
-This document describes how to use DarwinBuild to build Darwin projects.  More to come...
+This document describes how to use DarwinBuild to build Darwin projects.
+It gives a simple example of how to rebuild the apache_mod_php sources to
+configure with --with-ldap-sasl.  More advanced topics, like how to alter
+build settings, or create your own build, will be covered later.
 </p>
 </div>
 </div>
 
+
+<div class="article">
+<a name="install"></a><h3>Installation</h3>
+<div class="articlebody">
+<p>
+This section describes how to install DarwinBuild 0.6 or later.  DarwinBuild 0.6 can
+be downloaded from the <a href="../../releases/index.html">Releases</a> page.
+Alternatively, you can obtain the sources via <a href="../../sources.html">CVS</a>.
+</p>
+<p>
+By default, DarwinBuild will install into /usr/local, and you will need to make sure
+that /usr/local/bin is in your shell's PATH variable.  If you want to change the
+installation location, edit the <tt>common.mk</tt> file in the darwinbuild directory.
+</p>
+<p>
+DarwinBuild has been tested on Mac OS X 10.3 (Panther), Mac OS X 10.4 (Tiger).
+The following is an example of downloading the 0.6 release and installing it on Mac OS X:
+</p>
+<pre>
+$ curl -O http://opendarwin.org/projs/darwinbuild/releases/darwinbuild-0.6.tar.gz
+$ tar xzf darwinbuild-0.6.tar.gz
+$ cd darwinbuild-0.6
+$ make
+$ sudo make install
+</pre>
 </div>
+</div>
 
+<div class="article">
+<a name="init"></a><h3>Creating a Build Directory</h3>
+<div class="articlebody">
+<p>
+The build directory contains a hierarchy of directories that DarwinBuild uses
+while building Darwin projects.  Since some sources require a case sensitive
+filesystem to build successfully (e.g. cvs), it's recommended to create your
+build directory on a case-sensitive HFSX or UFS volume.
+</p>
+<p>If you  do not already have a partition that you can use for this purpose,
+you can create a disk image with the following command (for Mac OS X only):
+</p>
+<pre>
+$ hdiutil create -size 4g -type UDIF -fs HFSX -volname Builds \
+        -uid 0 -gid 0 -attach Builds.dmg
+</pre>
+<p>
+<b>Important:</b> if you use a disk image, be sure to uncheck the "Ignore
+ownership on this volume" setting in the Finder's Get Info panel for the volume.
+Otherwise, the results of your builds will not have any meaningful ownerships
+and will likely fail to work.
+</p>
+<p>
+For the remainder of this section, we will assume the build directory is to
+be located inside /Volumes/Builds, the mount point of the Builds disk image.
+</p>
+<p>
+Once you've chosen a location for your build directory, create and initialize
+it with the following commands.  The darwinbuild -init command requires a build
+number to be specified.  This indicates which version of the Darwin sources you
+want to use as a base while building.  Use the 
+<a href="http://developer.apple.com/documentation/Darwin/Reference/ManPages/man1/sw_vers.1.html">sw_vers</a>
+tool to determine which
+build of Mac OS X you are currently running (see the
+<a href="#builds">Currently Supported Builds</a> section for more information).
+The build number used during initialization is stored in the build directory,
+and will be used as the default value for future darwinbuild operations.
+</p>
+<pre>
+$ sudo -s
+Password:
+# cd /Volumes/Builds
+# mkdir Build8C46
+# cd Build8C46
+# darwinbuild -init 8C46
+Attempting to download http://darwinsource.opendarwin.org/plists//8C46.plist ...
+Download complete
+Attempting to download http://darwinsource.opendarwin.org/plists//8B15.plist ...
+Download complete
+Attempting to download http://darwinsource.opendarwin.org/plists//8A428.plist ...
+Download complete
+# ls
+.build  Headers Logs    Roots   Sources Symbols
+</pre>
+</p>
+<p>
+The .build directory contains private data for the DarwinBuild system and shouldn't
+need to be inspected directly.
+The Logs directory will contain the build log for each attempt to build a Darwin project.
+The Roots directory will contain the results of successful builds of Darwin projects.
+The Headers directory will contain the results of any installhdrs builds (See the
+<a href="http://opendarwin.org/projects/darwinbuild/doc/build/index.html#installhdrs">installhdrs</a>
+section of Building Darwin Projects for more information).
+The Symbols directory will contain the debug-symboled versions of successful builds
+of Darwin projects.
+The Sources directory contains the cached source code of Darwin projects.
+</p>
+</div>
+</div>
+
+
+<div class="article">
+<a name="fetch"></a><h3>Downloading and Modifying Sources</h3>
+<div class="articlebody">
+<p>
+DarwinBuild provides a -fetch argument which will download the correct set of source code
+for the current build number (as determined by the current build directory).  The sources
+will be downloaded into the Sources directory as a .tar.gz archive.  DarwinBuild will use
+these sources when building the project, but if a directory of the same name (without the
+.tar.gz suffix) is present inside Sources, then that directory will take precedent.
+In this way, you can extract the sources and modify them before building with DarwinBuild.
+</p>
+<p>
+The following example shows how to fetch and modify the apache_mod_php sources prior to
+building.
+</p>
+<pre>
+# darwinbuild -fetch apache_mod_php
+*** Fetching Sources ...
+Attempting to download http://darwinsource.opendarwin.org/tarballs/other//apache_mod_php-18.tar.gz ...
+Download complete
+# cd Sources
+# tar xzf apache_mod_php-18.tar.gz
+# vi apache_mod_php-18/Makefile
+(... add --with-ldap-sasl to Extra_Configure_Flags)
+# cd ..
+</pre>
+</div>
+</div>
+
+
+<div class="article">
+<a name="build"></a><h3>Building Darwin Projects</h3>
+<div class="articlebody">
+<p>
+From within the build directory, a simple command to darwinbuild will start the build process.
+In order to ensure accurate, successful builds, DarwinBuild performs all build operations in
+a special environment, separate from the base system.  First, DarwinBuild determines which
+tools will be needed to build the software, downloads them from the OpenDarwin servers, and
+loads them into the BuildRoot directory.  Then, using the
+<a href="http://developer.apple.com/documentation/Darwin/Reference/ManPages/man8/chroot.8.html">chroot</a>
+command, DarwinBuild changes the root directory to BuildRoot.  This allows DarwinBuild to use
+private headers and tools without polluting the base system (see the
+<a href="http://opendarwin.org/projects/darwinbuild/doc/build/index.html#dependencies">dependencies</a>
+section of Building Darwin Projects for more information).
+</p>
+<p>
+All output sent to the terminal during the build will also be logged in a file in the Logs
+directory.  The Log file will have the same name as the project-version currently being built.
+In addition, a build number is appended to the filename (separated by a ~).  The build number
+is incremented with each attempt to build the project, so that you can compare the results of
+various attempts.
+</p>
+<p>If the build is successful, the results are copied into the Roots directory.  If any debug-
+symboled versions are available, they will be copied into the Symbols directory.  Both the
+Roots and Symbols directories are named with the same convention as the log file.
+</p>
+<p>The following example shows how to build the apache_mod_php sources</p>
+<pre>
+# darwinbuild apache_mod_php
+*** Fetching Sources ...
+Found apache_mod_php-18 in /Volumes/Builds/Build8C46/Sources
+*** Installing Roots ...
+Copying files ...
+Attempting to download http://darwinsource.opendarwin.org/Roots//8C46/curl.root.tar.gz ...
+...
+(removed for brevity)
+*** Copying Sources ...
+*** Mounting special filesystems ...
+Mounting devfs ...
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+BUILDING apache_mod_php-18~1 on Mon Jul 25 15:39:44 PDT 2005
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+(removed for brevity)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+make install  "SRCROOT=/SourceCache/apache_mod_php/apache_mod_php-18" "OBJROOT=/private/var/tmp/apache_mod_php/apache_mod_php-18.obj" "SYMROOT=/private/var/tmp/apache_mod_php/apache_mod_php-18.sym" "DSTROOT=/private/var/tmp/apache_mod_php/apache_mod_php-18.root" "RC_ProjectName=apache_mod_php" "RC_ProjectSourceVersion=18" "RC_ProjectNameAndSourceVersion=apache_mod_php-18" "RC_ProjectBuildVersion=4" "INSTALLED_PRODUCT_ASIDES=YES" "MACOSX_DEPLOYMENT_TARGET=10.4" "NEXT_ROOT=" "RC_ARCHS=ppc i386" "RC_CFLAGS=-pipe -no-cpp-precomp -arch ppc -arch i386" "RC_JASPER=YES" "RC_NONARCH_CFLAGS=-pipe -no-cpp-precomp" "RC_OS=macos" "RC_RELEASE=Tiger" "RC_XBS=YES" "RC_i386=YES" "RC_ppc=YES" "SEPARATE_STRIP=YES" "UNAME_RELEASE=8.0" "UNAME_SYSNAME=Darwin"
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Build log begins here:
+
+if [ ! -f "/SourceCache/apache_mod_php/apache_mod_php-18/Makefile" ]; then make install_source; fi
+Configuring php...
+/bin/mkdir -p -m 0755 /private/var/tmp/apache_mod_php/apache_mod_php-18.obj
+cd /private/var/tmp/apache_mod_php/apache_mod_php-18.obj &amp;&amp; CFLAGS="-arch ppc -arch i386 -g -Os -pipe -no-cpp-precomp -pipe -no-cpp-precomp -arch ppc -arch i386" CCFLAGS="-arch ppc -arch i386 -g -Os -pipe " CXXFLAGS="-arch ppc -arch i386 -g -Os -pipe " LDFLAGS="-arch ppc -arch i386            -lresolv"  TEXI2HTML="/usr/bin/texi2html -subdir ." /SourceCache/apache_mod_php/apache_mod_php-18/php/configure --prefix="/usr" --mandir="/usr/share/man" --infodir="/usr/share/info" --with-apxs --with-ldap=/usr --with-kerberos=/usr --enable-cli --with-zlib-dir=/usr --enable-trans-sid --with-xml --enable-exif --enable-ftp --enable-mbstring --enable-mbregex --enable-dbx --enable-sockets --with-iodbc=/usr --with-curl=/usr --with-config-file-path=/etc --sysconfdir=/private/etc --with-ldap-sasl
+creating cache ./config.cache
+checking host system type... powerpc-apple-darwin8.0
+checking for gcc... gcc
+checking whether the C compiler (gcc -arch ppc -arch i386 -g -Os -pipe -no-cpp-precomp -pipe -no-cpp-precomp -arch ppc -arch i386 -arch ppc -arch i386            -lresolv) works... yes
+(removed for brevity)
+</pre>
+</div>
+</div>
+
+<div class="article">
+<h3>Advanced topics...</h3>
+<div class="articlebody">
+<p>More to come ...</p>
+</div>
+</div>
+
+</div>
+
 </body>
 </html>

Modified: trunk/www/sidebar.html
===================================================================
--- trunk/www/sidebar.html	2005-07-25 23:47:49 UTC (rev 92)
+++ trunk/www/sidebar.html	2006-10-04 08:44:49 UTC (rev 93)
@@ -60,7 +60,9 @@
 <a href="doc/tools/index.html">Using DarwinBuild</a><br>
 <div class="groupsublinks">
 <a href="doc/tools/index.html#install">Installation</a><br>
-<a href="doc/tools/index.html#build">Build a Project</a><br>
+<a href="doc/tools/index.html#init">Creating a Build Directory</a><br>
+<a href="doc/tools/index.html#fetch">Downloading and Modifying Sources</a><br>
+<a href="doc/tools/index.html#build">Building Darwin Projects</a><br>
 </div>
 </div>
 </div>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/darwinbuild-changes/attachments/20061004/0358ab3e/attachment.html
