5. macOS

This chapter describes installation steps specific to Apple macOS. macOS installation of ns-3 requires either the installation of the full Xcode IDE or a more minimal install of Xcode Command Line Tools).

The full Xcode IDE requires 40 GB of disk space. If you are just interested in getting ns-3 to run, the full Xcode is not necessary; we recommend Command Line Tools instead.

In addition to Command Line Tools, some ns-3 extensions require third-party libraries; we recommend either Homebrew or MacPorts. 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 application; see ns-3 MR 1247 for discussion about this.

Finally, regarding Python, some ns-3 maintainers prefer to use a virtualenv to guard against incompatibilities that might arise from the native macOS Python and versions that may be installed by Homebrew or Anaconda. Some ns-3 users never use Python bindings or visualizer, but if your ns-3 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.

Due to an upstream limitation with Cppyy, Python bindings do not work on macOS machines with Apple silicon (M1 and M2 processors).

5.1. Requirements

macOS uses the Clang/LLVM compiler toolchain. It is possible to install gcc/g++ from Homebrew and MacPorts, but macOS will not provide it due to licensing issues. ns-3 works on recent versions of both clang++ and g++, so for macOS, there is no need to install g++.

ns-3 Version	Homebrew packages	MacPorts packages
3.36 and later	cmake ninja	cmake ninja
3.35 and earlier	None	None

5.2. Recommended

Feature	Homebrew packages	MacPorts packages
Compiler cache optimization	ccache	ccache
Code linting	clang-format llvm	clang-format included with clang, need to select clang-XX llvm-XX versions
Debugging	None	gdb ddd (ddd requires gdb)

Note

The llvm Homebrew package provides clang-tidy, but please note that the binary is placed at /opt/homebrew/opt/llvm/bin/clang-tidy so you may 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 ``16), 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).

5.3. 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 simulation	open-mpi	openmpi
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, CircularApertureAntennaModel	boost	boost

5.4. Caveats and troubleshooting