README.macos

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