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