87 lines
5.0 KiB
ReStructuredText
87 lines
5.0 KiB
ReStructuredText
.. include:: replace.txt
|
|
.. heading hierarchy:
|
|
------------- Chapter
|
|
************* Section (#.#)
|
|
============= Subsection (#.#.#)
|
|
############# Paragraph (no number)
|
|
|
|
Overview
|
|
--------
|
|
|
|
This guide documents the different ways that users can download, build, and install |ns3| from source code. All of these actions (download, build, install) have variations
|
|
or options, and can be customized or extended by users; this document attempts to inform readers
|
|
about different possibilities.
|
|
|
|
Please note a few important details:
|
|
|
|
* |ns3| is supported for Linux, macOS, and Windows systems. Linux is the primary system
|
|
supported, and (almost) all |ns3| features are supported on Linux. However, most features can
|
|
also be used on macOS and Windows. Windows is probably the least used and least supported
|
|
system.
|
|
* |ns3| has minimal prerequisites for its most basic installation; namely, a **C++** compiler,
|
|
**Python3** support, the **CMake** build system, and at least one of **make**, **ninja**, or
|
|
**Xcode** build systems. However, some users will want to install optional packages
|
|
to make use of the many optional extensions.
|
|
* |ns3| installation requirements vary from release to release, and also as underlying operating
|
|
systems evolve. This document is version controlled, so if you are using the *ns-3.X* release,
|
|
try to read the *ns-3.X* version of this document. Even with this guidance, you may encounter
|
|
issues if you are trying to use an old version of |ns3| on a much newer system. For instance,
|
|
|ns3| versions until around 2020 relied on Python2, which is now end-of-life and not installed
|
|
by default on many Linux distributions. Compilers also become more pedantic and issue more
|
|
warnings as they evolve. Solutions to some of these forward compatibility problems exist and
|
|
are discussed herein or might be found in the ns-3-users mailing list archives.
|
|
|
|
If you find any stale or inaccurate information in this document, please report it to maintainers,
|
|
on our `Zulip chat <https://ns-3.zulipchat.com>`_, in the GitLab.com
|
|
`Issue tracker <https://gitlab.com/nsnam/ns-3-dev/-/issues/>`_, (or better yet, a patch to fix
|
|
in the `Merge Request tracker <https://gitlab.com/nsnam/ns-3-dev/-/merge_requests>`_), or on our
|
|
developers mailing list.
|
|
|
|
We also will accept patches to this document to provide installation guidance for the
|
|
FreeBSD operating system and other operating systems being used in practice.
|
|
|
|
Software organization
|
|
*********************
|
|
|
|
|ns3| is a set of C++ libraries (usually compiled as shared libraries) that can be used by C++
|
|
or Python programs to construct simulation scenarios and execute simulations. Users can also
|
|
write programs that link other C++ shared libraries (or import other Python modules). Users can
|
|
choose to use a subset of the available libraries; only the ``core`` library is strictly required.
|
|
|
|
|ns3| uses the CMake build system (until release 3.36, the Waf build system was used). It can be
|
|
built from command-line or via a code editor program.
|
|
|
|
Most users write C++ ns-3 programs; Python support is less frequently used and is not officially
|
|
maintained as of this writing. As of *ns-3.37*, |ns3| uses `cppyy` to generate runtime Python
|
|
bindings. Officially, Python3 support is only lightly maintained, and the `cppyy` support was
|
|
contributed by Gabriel Ferreira as a proof-of-concept (hint: the project is seeking a full-time
|
|
maintainer to develop this further).
|
|
|
|
Many users may be familiar with how software is packaged and installed on Linux and other systems
|
|
using package managers. For example, to install a given Linux development library such as
|
|
OpenSSL, a package manager is typically used (e.g., ``apt install openssl libssl-dev``), which leads
|
|
to shared libraries being installed under ``/usr/lib/``, development headers being installed
|
|
under ``/usr/include/``, etc. Programs that wish to use these libraries must link the system
|
|
libraries and include the development headers. |ns3| is capabile of being installed in exactly
|
|
the same way, and some downstream package maintainers have packaged |ns3| for some systems
|
|
such as Ubuntu. However, as of this writing, the |ns3| project has not prioritized or
|
|
standardized such package distribution, favoring instead to recommend a *source download* without
|
|
a system-level install. This is mainly because most |ns3| users prefer to slightly or extensively
|
|
edit or extend the |ns3| libraries, or to build them in specific ways (for debugging, or optimized
|
|
for large-scale simulation campaign). Our build system provides an ``install`` command that can
|
|
be used to install libraries and headers to system locations (usually requiring administrator
|
|
privileges), but usually the libraries are just built and used from within the |ns3| ``build``
|
|
directory.
|
|
|
|
Document organization
|
|
*********************
|
|
|
|
The rest of this document is organized as follows:
|
|
|
|
* :ref:`Quick start` (for any operating system)
|
|
* :ref:`General list` of requirements, recommendations, and optional prerequisites
|
|
* :ref:`Linux` installation
|
|
* :ref:`macOS` installation
|
|
* :ref:`Windows` installation
|
|
* :ref:`Bake` installation
|