README.macos

   1 MacOS Quick Start (Using Homebrew)
   2 -----------------------------------
   3
   4 > Note that this method is particularly recommended for M1 and later Macs.
   5
   6 1. Install the latest Xcode from the MacOS app store.
   7    See https://guide.macports.org/#installing.xcode for details.
   8
   9 2. Install Homebrew (https://brew.sh/)
  10
  11 3. From the top-level source directory, run tools/macos-setup-brew.sh and wait
  12    for it to complete.
  13
  14    Note: You may set the environment variable HOMEBREW_NO_AUTO_UPDATE=1 if you
  15          do not want the script to update homebrew.
  16
  17 4. Create a build directory and enter it:
  18     mkdir build && cd build
  19
  20 5. Configure the build:
  21     cmake ..
  22
  23 6. Build wireshark!
  24     make -j
  25
  26 The wireshark binary will be found at run/wireshark under your build directory.
  27
  28 Note that for subsequent builds, you will only need to enter the build
  29 directory and run "make -j".
  30
  31 Note that if you cannot use homebrew, or otherwise need to manually install
  32 prerequisites, you cannot use this method; continue reading for more detailed
  33 instructions.
  34
  35
  36 Non-Homebrew Setup and Build of Wireshark for macOS
  37 ----------------------------------------------------
  38 This file tries to help building Wireshark for macOS (The Operating
  39 System Formerly Known As Mac OS X And Then OS X) (Wireshark does not
  40 work on the classic Mac OS).
  41
  42 You must have the developer tools (called Xcode) installed.  For
  43 versions of macOS up to and including Snow Leopard, Xcode 3 should be
  44 available on the install DVD; Xcode 4 is available for download from
  45 developer.apple.com and, for Lion and later releases, from the Mac App
  46 Store.  See
  47
  48         https://guide.macports.org/#installing.xcode
  49
  50 for details.  For Xcode 4, you will need to install the command-line
  51 tools; select Preferences from the Xcode menu, select Downloads in the
  52 Preferences window, and install Command Line Tools.
  53
  54
  55 You must also have GLib and, if you want to build Wireshark as well as
  56 TShark, you must have also Qt installed.  You can download precompiled
  57 Qt packages and source code from
  58
  59         https://www.qt.io/download
  60
  61 or use the tools/macos-setup.sh script described below.
  62
  63 You should have CMake installed; you can download binary distributions
  64 for macOS from
  65
  66         https://cmake.org/download/
  67
  68 The tools/macos-setup.sh script can be used to download, patch as
  69 necessary, build as necessary, and install those libraries and the
  70 libraries on which they depend, along with tools such as CMake; it will,
  71 by default, also install other libraries that can be used by Wireshark
  72 and TShark.  The versions of libraries and tools to download are
  73 specified by variables set early in the script; you can comment out the
  74 settings of optional libraries if you don't want them downloaded and
  75 installed.  Before running the tools/macos-setup.sh script, and before
  76 attempting to build Wireshark, make sure your PKG_CONFIG_PATH
  77 environment variable's setting includes /usr/local/lib/pkgconfig.
  78
  79 The tools/macos-setup.sh script must be run from the top-level source
  80 directory.
  81
  82 After you have installed those libraries:
  83
  84  1. It is generally recommended to install Qt with the online installer
  85     provided by Qt - see https://www.qt.io/download
  86
  87         If you are building on an Apple Silicon machine, it is highly recommended
  88         to use at least Qt 6.2.4, as this architecture is not fully supported
  89         with Qt 5.15
  90
  91  2. Make a directory in which Wireshark is to be built, separate
  92         from the top-level source directory for Wireshark - it can be a
  93         subdirectory of that top-level source directory;
  94
  95  3. cd to that directory, and run CMake, with an argument that is a
  96         path to the top-level source directory;
  97
  98  4. When CMake finishes, run make to build Wireshark.
  99
 100 For example, to build Wireshark in a subdirectory of the top-level
 101 source directory, named "build", do, from the top-level source
 102 directory;
 103
 104         mkdir build
 105         cd build
 106         cmake ..
 107         make
 108
 109 It is also possible to use the Xcode IDE to build and debug Wireshark
 110 using cmake's Xcode generator. Create a separate build directory, as
 111 described above and run cmake with the "-G Xcode" argument to create
 112 a Xcode project file in the current directory.
 113
 114         cmake -G Xcode ..
 115
 116  1. Double click Wireshark.xcodeproj
 117
 118  2. Choose to create schemes manually
 119
 120  3. Create a scheme for the ALL_BUILD target
 121
 122  4. Edit the scheme, go to the run configuration and select Wireshark.app
 123   as executable
 124
 125 If you upgrade the major release of macOS on which you are building
 126 Wireshark, we advise that, before you do any builds after the upgrade,
 127 you remove the build directory and all its subdirectories, and repeat the
 128 above process, re-running CMake and rebuilding from scratch.
 129
 130 On Snow Leopard (10.6) and later releases, if you are building on a
 131 machine with a 64-bit processor (with the exception of the early Intel
 132 Core Duo and Intel Core Solo machines, all Apple machines with Intel
 133 processors have 64-bit processors), the C/C++/Objective-C compiler will
 134 build 64-bit by default.
 135
 136 This means that you will, by default, get a 64-bit version of Wireshark.
 137
 138 One consequence of this is that, if you built and installed any required
 139 or optional libraries for Wireshark on an earlier release of macOS, those
 140 are probably 32-bit versions of the libraries, and you will need to
 141 un-install them and rebuild them on your current version of macOS, to get
 142 64-bit versions.
 143
 144 Some required and optional libraries require special attention if you
 145 install them by building from source code on Snow Leopard and later
 146 releases; the tools/macos-setup.sh script will handle that for you.
 147
 148 GLib - the GLib configuration script determines whether the system's
 149 libiconv is GNU iconv or not by checking whether it has libiconv_open(),
 150 and the compile will fail if that test doesn't correctly indicate
 151 whether libiconv is GNU iconv.  In macOS, libiconv is GNU iconv, but the
 152 64-bit version doesn't have libiconv_open(); a workaround for this is to
 153 replace all occurrences of "libiconv_open" with "iconv_open" in the
 154 configure script before running the script.  The tools/macos-setup.sh
 155 setup script will patch GLib to work around this.
 156
 157 libgcrypt - the libgcrypt configuration script attempts to determine
 158 which flavor of assembler-language routines to use based on the platform
 159 type determined by standard autoconf code.  That code uses uname to
 160 determine the processor type; however, in macOS, uname always reports
 161 "i386" as the processor type on Intel machines, even Intel machines with
 162 64-bit processors, so it will attempt to assemble the 32-bit x86
 163 assembler-language routines, which will fail.  The workaround for this
 164 is to run the configure script with the --disable-asm argument, so that
 165 the assembler-language routines are not used.  The tools/macos-setup.sh
 166 will configure libgcrypt with that option.