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