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.
Overview
Installation
This section describes how to install DarwinBuild 0.7.1 or later. DarwinBuild 0.7.1 can be downloaded from the Releases page. Alternatively, you can obtain the sources via CVS.
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 common.mk file in the darwinbuild directory.
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.7.1 release and installing it on Mac OS X:
$ curl -O http://www.opendarwin.org/projects/darwinbuild/releases/darwinbuild-0.7.1.tar.gz $ tar xzf darwinbuild-0.7.1.tar.gz $ cd darwinbuild-0.7.1 $ make $ sudo make install
Creating a Build Directory
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.
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):
$ hdiutil create -size 4g -type UDIF -fs HFSX -volname Builds \ -uid 0 -gid 0 -attach Builds.dmg
Important: 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.
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.
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 sw_vers tool to determine which build of Mac OS X you are currently running (see the Property Lists page for a list of currently supported builds). The build number used during initialization is stored in the build directory, and will be used as the default value for future darwinbuild operations.
$ 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
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 installhdrs 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.
Downloading and Modifying Sources
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.
The following example shows how to fetch and modify the apache_mod_php sources prior to building.
# 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 ..
Building Darwin Projects
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 chroot command, DarwinBuild changes the root directory to BuildRoot. This allows DarwinBuild to use private headers and tools without polluting the base system (see the dependencies section of Building Darwin Projects for more information).
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.
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.
The following example shows how to build the apache_mod_php sources
# 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 && 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)
Advanced topics...
More to come ...