F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Add installation guide

Browse Source
This commit is contained in:
Tom Henderson
2023-01-08 09:53:50 -08:00
parent 7da2f08a97
commit 9e6ee90989
17 changed files with 1293 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
doc/installation/source/overview.rst Normal file
View File

@@ -0,0 +1,86 @@
.. 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