1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
.. include:: replace.txt
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
.. _macOS:
macOS
-----
This chapter describes installation steps specific to Apple macOS. macOS installation of |ns3|
requires either the installation of the full
`Xcode IDE <https://developer.apple.com/xcode/features/>`_ or a more minimal install of
`Xcode Command Line Tools <https://www.freecodecamp.org/news/install-xcode-command-line-tools/>`_).
The full Xcode IDE requires 40 GB of disk space. If you are just interested in getting |ns3|
to run, the full Xcode is not necessary; we recommend Command Line Tools instead.
In addition to Command Line Tools, some |ns3| extensions require third-party libraries;
we recommend either `Homebrew <https://brew.sh/>`_ or `MacPorts <https://www.macports.org/>`_.
If you prefer, you can probably avoid installing Command Line Tools and install the compiler
of your choice and any other tools you may need using Homebrew or MacPorts.
In general, documentation on the web suggests to use either, but not both, Homebrew or MacPorts
on a particular system. It has been noted that Homebrew tends to install the GUI version of certain
applications without easily supporting the command-line equivalent, such as for the
`dia <https://gitlab.gnome.org/GNOME/dia/>`_ application; see ns-3
`MR 1247 <https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/1247>`_ for discussion about this.
Finally, regarding Python, some |ns3| maintainers prefer to use a
`virtualenv <https://docs.python.org/3/library/venv.html>`_ to guard against incompatibilities
that might arise from the native macOS Python and versions that may be installed by Homebrew
or `Anaconda <https://docs.anaconda.com/anaconda/install/mac-os/>`_. Some |ns3| users never
use Python bindings or visualizer, but if your |ns3| workflow requires more heavy use
of Python, please keep the possibility of a virtualenv in mind if you run into Python difficulties.
For a short guide on virtual environments, please see
`this link <https://www.dataquest.io/blog/a-complete-guide-to-python-virtual-environments/>`_.
Due to an `upstream limitation with Cppyy <https://github.com/wlav/cppyy/issues/150>`_, Python bindings do not work on macOS machines with Apple silicon (M1 and M2 processors).
Requirements
************
Installing ns-3 on macOS requires two fundamental things: 1) C++/Python development tools, and 2) CMake build system with at least one underlying build tool. These can either be installed via binary package installation from the macOS App Store (Xcode development tools) or the web (`CMake binary package <https://cmake.org/download/>`_), or from Homebrew or MacPorts.
macOS Xcode uses the Clang/LLVM compiler toolchain. It is possible to install the GNU compiler gcc/g++ from
Homebrew and MacPorts, but macOS will not provide it due to licensing issues. If you do not install Xcode you will have to install build tools via Homebrew or MacPorts. |ns3|
works on recent versions of both ``clang++`` and ``g++``, so for macOS, there is no need
to install ``g++``.
The following table provides package names for installing CMake and Ninja build system from Homebrew or MacPorts.
+--------------------+-------------------------------+-------------------------------------+
| **ns-3 Version** | **Homebrew packages** | **MacPorts packages** |
+====================+===============================+=====================================+
| 3.36 and later | ``cmake ninja`` | ``cmake ninja`` |
+--------------------+-------------------------------+-------------------------------------+
| 3.35 and earlier | None | None |
+--------------------+-------------------------------+-------------------------------------+
You will know you are done when you can successfully type `clang++ -v` at the command line, and when you type `cmake --help` and it identifies that you have at least one installed generator (in the below example, Unix Makefiles):
::
Generators
The following generators are available on this platform (* marks default):
* Unix Makefiles = Generates standard UNIX makefiles.
Ninja = Generates build.ninja files.
Ninja Multi-Config = Generates build-<Config>.ninja files.
Watcom WMake = Generates Watcom WMake makefiles.
Xcode = Generate Xcode project files.
Recommended
***********
+-----------------------------+----------------------------+-----------------------------------+
| **Feature** | **Homebrew packages** | **MacPorts packages** |
+=============================+============================+===================================+
| Compiler cache optimization | ``ccache`` | ``ccache`` |
+-----------------------------+----------------------------+-----------------------------------+
| Code linting | clang-format included with | clang-format included with |
| | ``llvm``, need to select | ``clang``, need to select |
| | ``llvm@XX`` version | ``clang-XX llvm-XX`` versions |
+-----------------------------+----------------------------+-----------------------------------+
.. note::
macOS development tools are based on clang, so installing llvm and clang using Homebrew or
MacPorts is typically unnecessary. However, ``clang-tidy`` might be missing, and the
``clang-format`` version might be not the expected one. In these cases it is suggested to
install the ``llvm`` package either though Homebrew or MacPorts.
.. note::
Homebrew provides a ``clang-format`` package, but its version might be incompatible with
the one used by |ns3|.
The ``llvm`` Homebrew package provides ``clang-tidy`` and ``clang-format``, but the binary
is placed at ``/opt/homebrew/opt/llvm@XX/bin/clang-tidy`` (where ``XX`` is the installed
version number such as ``18``), so you will need to add this path to your ``$PATH`` variable.
.. note::
Likewise, when using MacPorts, the ``clang-tidy`` and ``clang-format`` binaries will be
placed in ``/opt/local/libexec/llvm-XX/bin`` (where ``XX`` is the installed version number
such as ``18``), so you will need to add this to your ``$PATH`` variable.
.. note::
For debugging, ``lldb`` is the default debugger for llvm. Memory checkers such as
Memory Graph exist for macOS, but the ns-3 team doesn't have experience with it as a
substitution for ``valgrind`` (which is reported to not work on M1 Macs).
Optional
********
Please see below subsections for Python-related package requirements.
For MacPorts packages we show the most recent package version available as of early 2023.
+-----------------------------+----------------------------------+--------------------------+
| **Feature** | **Homebrew packages** | **MacPort packages** |
+=============================+==================================+==========================+
| Reading pcap traces | ``wireshark`` | ``wireshark4`` |
+-----------------------------+----------------------------------+--------------------------+
| Database support | ``sqlite`` | ``sqlite3`` |
+-----------------------------+----------------------------------+--------------------------+
| NetAnim animator | ``qt@5`` | ``qt513`` |
+-----------------------------+----------------------------------+--------------------------+
| MPI-based distributed | | ``openmpi`` |
| simulation | ``open-mpi`` | |
+-----------------------------+----------------------------------+--------------------------+
| Building Doxygen | ``doxygen graphviz imagemagick`` | ``doxygen graphviz`` |
| | | ``ImageMagick`` |
+-----------------------------+----------------------------------+--------------------------+
| Sphinx documentation | ``sphinx-doc texlive`` | ``dia texlive`` |
| | | ``texlive-fonts-extra`` |
| | | ``texlive-latex-extra`` |
| | | ``py3XX-sphinx``, with |
| | | `XX`` the Python minor |
| | | version such as `12` |
+-----------------------------+----------------------------------+--------------------------+
| Eigen3 | ``eigen`` | ``eigen3`` |
+-----------------------------+----------------------------------+--------------------------+
| GNU Scientific Library | ``gsl`` | ``gsl`` |
+-----------------------------+----------------------------------+--------------------------+
| XML config store | ``libxml2`` | ``libxml2`` |
+-----------------------------+----------------------------------+--------------------------+
| GTK-based config store | ``gtk+3`` | ``gtk3`` or ``gtk4`` |
+-----------------------------+----------------------------------+--------------------------+
| Emulation with virtual | | |
| machines | Not available for macOS | Not available for macOS |
+-----------------------------+----------------------------------+--------------------------+
| Support for openflow, | ``boost`` | ``boost`` |
| CircularApertureAntennaModel| | |
+-----------------------------+----------------------------------+--------------------------+
Caveats and troubleshooting
***************************
|
