README.macos

   1 $Id$
   2
   3 This file tries to help building Wireshark for (Mac) OS X (Wireshark
   4 does not work on earlier versions of Mac OS).
   5
   6 You must have the developer tools (called Xcode) installed.  For
   7 versions of OS X up to and including Snow Leopard, Xcode 3 should be
   8 available on the install DVD; Xcode 4 is available for download from
   9 developer.apple.com and, for Lion and later releases, from the Mac App
  10 Store.  See
  11
  12         http://guide.macports.org/chunked/installing.xcode.html
  13
  14 for details.  For Xcode 4, you will need to install the command-line
  15 tools; select Preferences from the Xcode menu, select Downloads in the
  16 Preferences window, and install Command Line Tools.
  17
  18 You must have X11 and the X11 developer headers and libraries installed;
  19 otherwise, you will not be able to build or install GTK+, and will only
  20 be able to build TShark.  The X11 and X11 SDK that come with Mac OS X
  21 releases for releases from Panther to Lion can be used to build and run
  22 Wireshark.  Mountain Lion does not include X11; you should install X11
  23 from elsewhere, such as
  24
  25         http://xquartz.macosforge.org/
  26
  27 You must also have GLib and, if you want to build Wireshark as well as
  28 TShark, GTK+.  The macosx-setup.sh script can be used to download, patch
  29 as necessary, build, and install those libraries and the libraries on
  30 which they depend; it will, by default, also install other libraries
  31 that can be used by Wireshark and TShark.  The versions of libraries to
  32 download are specified by variables set early in the script; you can
  33 comment out the settings of optional libraries if you don't want them
  34 downloaded and installed.  Before running the macosx-setup.sh script,
  35 and before attempting to build Wireshark, make sure your PKG_CONFIG_PATH
  36 environment variable's setting includes both /usr/X11/lib/pkgconfig
  37 and /usr/local/lib/pkgconfig.
  38
  39 After you have installed those libraries:
  40
  41 If you are building from a Subversion tree, rather than from a source
  42 distribution tarball, run the autogen.sh script.  This should not be
  43 necessary if you're building from a source distribution tarball, unless
  44 you've added new source files to the Wireshark source.
  45
  46 Then run the configure script, and run make to build Wireshark.
  47
  48 If you upgrade the major release of OS X on which you are building
  49 Wireshark, we advise that, before you do any builds after the upgrade,
  50 you do, in the build directory:
  51
  52     If you are building from a release tarball:
  53         make distclean
  54
  55     If you are building from SVN:
  56         make maintainer-clean
  57         ./autogen.sh
  58
  59 Then re-run the configure script and rebuild from scratch.
  60
  61 On Snow Leopard (10.6) and later releases, if you are building on a
  62 machine with a 64-bit processor (with the exception of the early Intel
  63 Core Duo and Intel Core Solo machines, all Apple machines with Intel
  64 processors have 64-bit processors), the C/C++/Objective-C compiler will
  65 build 64-bit by default.
  66
  67 This means that you will, by default, get a 64-bit version of Wireshark.
  68
  69 One consequence of this is that, if you built and installed any required
  70 or optional libraries for Wireshark on an earlier release of OS X, those
  71 are probably 32-bit versions of the libraries, and you will need to
  72 un-install them and rebuild them on your current version of OS X, to get
  73 64-bit versions.
  74
  75 Some required and optional libraries require special attention if you
  76 install them by building from source code on Snow Leopard and later
  77 releases; the macosx-setup.sh script will handle that for you.
  78
  79 GLib - the GLib configuration script determines whether the system's
  80 libiconv is GNU iconv or not by checking whether it has libiconv_open(),
  81 and the compile will fail if that test doesn't correctly indicate
  82 whether libiconv is GNU iconv.  In OS X, libiconv is GNU iconv, but the
  83 64-bit version doesn't have libiconv_open(); a workaround for this is to
  84 replace all occurrences of "libiconv_open" with "iconv_open" in the
  85 configure script before running the script.  The macosx-setup.sh setup
  86 script will patch GLib to work around this.
  87
  88 GTK+ - GTK+ 2.24.10, at least, doesn't build on Mountain Lion with the
  89 CUPS printing backend - either the CUPS API changed incompatibly or the
  90 backend was depending on non-API implementation details.  The
  91 macosx-setup.sh setup script will, on Mountain Lion and later, configure
  92 GTK+ with the CUPS printing backend disabled.
  93
  94 libgcrypt - the libgcrypt configuration script attempts to determine
  95 which flavor of assembler-language routines to use based on the platform
  96 type determined by standard autoconf code.  That code uses uname to
  97 determine the processor type; however, in Mac OS X, uname always reports
  98 "i386" as the processor type on Intel machines, even Intel machines with
  99 64-bit processors, so it will attempt to assemble the 32-bit x86
 100 assembler-language routines, which will fail.  The workaround for this
 101 is to run the configure script with the --disable-asm argument, so that
 102 the assembler-language routines are not used.  The macosx-setup.sh will
 103 configure libgcrypt with that option.
 104
 105 PortAudio - when compiling on OS X, the configure script for the
 106 pa_stable_v19_20071207 version of PortAudio will cause certain
 107 platform-dependent build environment #defines to be set in the Makefile
 108 rules, and to cause a universal build to be done; those #defines will be
 109 incorrect for all but one of the architectures for which the build is
 110 being done, and that will cause a compile-time error on Snow Leopard.
 111 Newer versions don't have this problem, but still fail to build on Lion
 112 if a universal build is attempted.  The macosx-setup.sh script downloads
 113 a newer version, and also suppresses the universal build.
 114
 115 GeoIP - Their man pages "helpfully" have an ISO 8859-1 copyright symbol
 116 in the copyright notice, but OS X's default character encoding is UTF-8.
 117 sed on Mountain Lion barfs at the "illegal character sequence"
 118 represented by an ISO 8859-1 copyright symbol, as it's not a valid UTF-8
 119 sequence.  The macosx-setup.sh script uses iconv to convert the man page
 120 files from ISO 8859-1 to UTF-8.
 121
 122 If you want to build Wireshark installer packages on a system that
 123 doesn't include Xcode 3.x or earlier, you will need to install some
 124 additional tools.  From the Xcode menu, select the Open Developer Tool
 125 menu, and then select More Developer Tools... from that menu.  That will
 126 open up a page on the Apple Developer Connection Web site; you may need
 127 a developer account to download the additional tools.  Download the
 128 Auxiliary Tools for Xcode package; when the dmg opens, drag all its
 129 contents to the Contents/Applications subdirectory of the Xcode.app
 130 directory (normally /Applications/Xcode.app/Contents/Applications); then
 131 copy .../Contents/Applications/PackageMaker.app/Contents/MacOS/PackageMaker
 132 to /usr/bin/packagemaker (the PackageMaker app, when run from the
 133 command line rather than as a double-clicked app, is the packagemaker
 134 command).