TODO SMB2 NegotiateContext....
[metze/wireshark/wip.git] / 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 tools/macos-setup.sh script can be used to download, patch as
31 necessary, build as necessary, and install those libraries and the
32 libraries on which they depend, along with tools such as CMake; it will,
33 by default, also install other libraries that can be used by Wireshark
34 and TShark.  The versions of libraries and tools to download are
35 specified by variables set early in the script; you can comment out the
36 settings of optional libraries if you don't want them downloaded and
37 installed.  Before running the tools/macos-setup.sh script, and before
38 attempting to build Wireshark, make sure your PKG_CONFIG_PATH
39 environment variable's setting includes /usr/local/lib/pkgconfig.
40
41 The tools/macos-setup.sh script must be run from the top-level source
42 directory.
43
44 After you have installed those libraries:
45
46  1. If you have installed Qt into some non-standard place, as is
47         distinctly possible with the build included with
48         macos-setup.sh, you must inform cmake by either including its
49         "bin" directory as part of the PATH environment variable or
50         setting CMAKE_PREFIX_PATH to the directory above Qt's "lib"
51         directory.  For Qt 5.8 installed into one's home directory,
52         for instance:
53
54         % export CMAKE_PREFIX_PATH=~/Qt5.8.0/5.8/clang_64
55
56         This step is unnecessary if you've used a recent version of
57         Homebrew, as the CMake build scripts will find Qt.
58
59  2. Make a directory in which Wireshark is to be built, separate
60         from the top-level source directory for Wireshark - it can be a
61         subdirectory of that top-level source directory;
62
63  3. cd to that directory, and run CMake, with an argument that is a
64         path to the top-level source directory;
65
66  4. When CMake finishes, run make to build Wireshark.
67
68 For example, to build Wireshark in a subdirectory of the top-level
69 source directory, named "build", do, from the top-level source
70 directory;
71
72         mkdir build
73         cd build
74         cmake ..
75         make
76
77 It is also possible to use the Xcode IDE to build and debug Wireshark
78 using cmake's Xcode generator. Create a separate build directory, as 
79 described above and run cmake with the "-G Xcode" argument to create 
80 a Xcode project file in the current directory.
81
82         cmake -G Xcode ..
83
84  1. Double click Wireshark.xcodeproj 
85
86  2. Choose to create schemes manually
87
88  3. Create a scheme for the ALL_BUILD target
89
90  4. Edit the scheme, go to the run configuration and select Wireshark.app 
91   as executable
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 libgcrypt - the libgcrypt configuration script attempts to determine
126 which flavor of assembler-language routines to use based on the platform
127 type determined by standard autoconf code.  That code uses uname to
128 determine the processor type; however, in macOS, uname always reports
129 "i386" as the processor type on Intel machines, even Intel machines with
130 64-bit processors, so it will attempt to assemble the 32-bit x86
131 assembler-language routines, which will fail.  The workaround for this
132 is to run the configure script with the --disable-asm argument, so that
133 the assembler-language routines are not used.  The tools/macos-setup.sh
134 will configure libgcrypt with that option.
135
136 If you want to build Wireshark installer packages on a system that
137 doesn't include Xcode 3.x or earlier, you will need to install some
138 additional tools.  From the Xcode menu, select the Open Developer Tool
139 menu, and then select More Developer Tools... from that menu.  That will
140 open up a page on the Apple Developer Connection Web site; you may need
141 a developer account to download the additional tools.  Download the
142 Auxiliary Tools for Xcode package; when the dmg opens, drag all its
143 contents to the Contents/Applications subdirectory of the Xcode.app
144 directory (normally /Applications/Xcode.app/Contents/Applications); then
145 copy .../Contents/Applications/PackageMaker.app/Contents/MacOS/PackageMaker
146 to /usr/bin/packagemaker (the PackageMaker app, when run from the
147 command line rather than as a double-clicked app, is the packagemaker
148 command).