diff --git a/doc/installation/.gitignore b/doc/installation/.gitignore new file mode 100644 index 000000000..567609b12 --- /dev/null +++ b/doc/installation/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/doc/installation/Makefile b/doc/installation/Makefile new file mode 100644 index 000000000..ea2ecc46f --- /dev/null +++ b/doc/installation/Makefile @@ -0,0 +1,165 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +# Additional variables for figures, not sphinx default: +DIA = dia +EPSTOPDF = epstopdf +FIGURES = source/figures +IMAGES_EPS = \ + +IMAGES_PNG = ${IMAGES_EPS:.eps=.png} +IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf} + +IMAGES = $(IMAGES_EPS) $(IMAGES_PNG) $(IMAGES_PDF) + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +.NOTPARALLEL: + +%.eps : %.dia + @echo dia $(notdir $<) + @$(DIA) -t eps $< -e $@ >/dev/null + +%.png : %.dia + @echo dia $(notdir $<) + @$(DIA) -t png $< -e $@ >/dev/null + +%.png : %.eps + @echo convert $(notdir $<) + @$(CONVERT) $< $@ >/dev/null + +%.pdf : %.eps + @echo epstopdf $(notdir $<) + @$(EPSTOPDF) $< -o=$@ >/dev/null + @if test x$($@_width) != x; then $(RESCALE) $($@_width) $@ ; fi + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +frag: pickle + @if test ! -d $(BUILDDIR)/frag; then mkdir $(BUILDDIR)/frag; fi + pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle > navigation.xml && popd + cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag + +html: $(IMAGES) + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: $(IMAGES) + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: $(IMAGES) + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: $(IMAGES) + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: $(IMAGES) + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: $(IMAGES) + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: $(IMAGES) + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ns-3.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ns-3.qhc" + +devhelp: $(IMAGES) + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/ns-3" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ns-3" + @echo "# devhelp" + +epub: $(IMAGES) + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: $(IMAGES) + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: $(IMAGES) + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: $(IMAGES) + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: $(IMAGES) + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: $(IMAGES) + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: $(IMAGEs) + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: $(IMAGES) + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/installation/source/_static/.hidden b/doc/installation/source/_static/.hidden new file mode 100644 index 000000000..e69de29bb diff --git a/doc/installation/source/_static/custom.css b/doc/installation/source/_static/custom.css new file mode 100644 index 000000000..8a5f414db --- /dev/null +++ b/doc/installation/source/_static/custom.css @@ -0,0 +1,4 @@ +table.align-left { + margin-left: auto; + margin-right: auto; +} diff --git a/doc/installation/source/bake.rst b/doc/installation/source/bake.rst new file mode 100644 index 000000000..db2120852 --- /dev/null +++ b/doc/installation/source/bake.rst @@ -0,0 +1,23 @@ +.. include:: replace.txt +.. heading hierarchy: + ------------- Chapter + ************* Section (#.#) + ============= Subsection (#.#.#) + ############# Paragraph (no number) + +.. _Bake: + +Installing Bake +--------------- + +Bake is a build system orchestration tool that was primarily designed for installing ns-3 +`Direct Code Execution `_ but +can be used more generally to install ns-3 third-party libraries and apps. + +Bake is a Python 3 program that requires the ``distro`` and ``requests`` packages; to start +using Bake, it is generally sufficient to add those packages to your Python 3 installation +using ``pip``. + +Bake is further documented elsewhere, including +`here `_ and in the +`Getting Started `_ chapter of the |ns3| tutorial. diff --git a/doc/installation/source/conf.py b/doc/installation/source/conf.py new file mode 100644 index 000000000..9afab90d9 --- /dev/null +++ b/doc/installation/source/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# ns-3 documentation build configuration file, created by +# sphinx-quickstart on Tue Dec 14 09:00:39 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.imgmath'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'ns-3' +copyright = u'2018, ns-3 project' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = 'ns-3-dev' +# The full version, including alpha/beta/rc tags. +release = 'ns-3-dev' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'ns3_html_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ['../..'] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = 'Installation guide' + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y %H:%M' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ns-3doc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'ns-3-installation.tex', u'ns-3 Installation Guide', + u'ns-3 project', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +latex_logo = '../../ns3_html_theme/static/ns-3.png' + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +latex_preamble = '\\usepackage{amssymb}' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'ns-3-installation', u'ns-3 Installation', + [u'ns-3 project'], 1) +] diff --git a/doc/installation/source/figures/README.txt b/doc/installation/source/figures/README.txt new file mode 100644 index 000000000..ceb61d4d4 --- /dev/null +++ b/doc/installation/source/figures/README.txt @@ -0,0 +1,18 @@ +Please write image files in a vector graphics format, when possible, and +generate the .png and .pdf versions on the fly (see ../Makefile). + +The currently supported tool is dia. xfig could be added similarly +if someone wants to add it. The main requirement for adding another format +is that the tool to edit it is freely available and that a cron script can +autogenerate the pdf and png from the figure source. Tgif (.obj) files +were once used but the file conversions require a valid X display to +be running, and are therefore to be avoided since our code server +does not run such a server. Tgif pdf conversions were also cumbersome. + +Store the .dia versions in this directory, but not the .png or .pdfs. +If the figure is not available in a vector graphics format, store both +a .png and a .pdf version in this directory. + +If you add a source (.dia) file here, remember to add it to +the list of figure sources in the Makefile in the directory above + diff --git a/doc/installation/source/index.rst b/doc/installation/source/index.rst new file mode 100644 index 000000000..25bf96928 --- /dev/null +++ b/doc/installation/source/index.rst @@ -0,0 +1,35 @@ +.. only:: html or latex + +ns-3 Installation Guide +======================= + +This is the *ns-3 Installation Guide*. Primary documentation for the ns-3 project is organized as +follows: + +* Several guides that are version controlled for each release (the + `latest release `_) and + `development tree `_: + + * Installation Guide (this document) + * Tutorial + * Manual + * Model Library + * Contributing +* `ns-3 Doxygen `_: Documentation of the public APIs of + the simulator +* `ns-3 wiki `_ + +This document is written in `reStructuredText `_ +for `Sphinx `_ and is maintained in Tom Henderson's 'installation-guide' branch +until it is ready to publish. Source file column width is 100 columns. + +.. toctree:: + :maxdepth: 2 + + overview + quick-start + system + linux + macos + windows + bake diff --git a/doc/installation/source/linux.rst b/doc/installation/source/linux.rst new file mode 100644 index 000000000..27ad5088a --- /dev/null +++ b/doc/installation/source/linux.rst @@ -0,0 +1,165 @@ +.. include:: replace.txt +.. heading hierarchy: + ------------- Chapter + ************* Section (#.#) + ============= Subsection (#.#.#) + ############# Paragraph (no number) + +.. _Linux: + +Linux +----- + +This chapter describes Linux-specific installation commands to install the options described +in the previous chapter. The chapter is written initially with Ubuntu (Debian-based) Linux +examples (Ubuntu is the most frequently used Linux distribution by |ns3| users) but should +translate fairly well to derivatives (e.g. Linux Mint). + +The list of packages depends on which version of ns-3 you are trying to build, and on which +extensions you need; please review the previous chapter if you need more information. + +Requirements +************ + +The minimum supported version of Ubuntu is Ubuntu 16.04 LTS (as long as a modern compiler +version such as g++ version 8 or later is added). + + +--------------------+---------------------------------------------------------------------+ + | **ns-3 Version** | **apt Packages** | + +====================+==================+==================================================+ + | 3.36 and later | ``g++ python3 cmake ninja-build git`` | + +--------------------+---------------------------------------------------------------------+ + | 3.30-3.35 | ``g++ python3 git`` | + +--------------------+---------------------------------------------------------------------+ + | 3.29 and earlier | ``g++ python2`` | + +--------------------+---------------------------------------------------------------------+ + +.. note:: + As of January 2022 (ns-3.36 release and later), the minimum g++ version is g++-8. + Older Ubuntu releases (18.04, 16.04) come with an older default g++. On Ubuntu 18.04, this + `StackOverflow answer `_ can be followed to install and + prefer g++-8. On older Ubuntu such as 16.04, to use the most recent |ns3|, you must install + g++-8 or g++-9 from the `Ubuntu toolchain `_. + +Recommended +*********** + + +-----------------------------+------------------------------------------------------------+ + | **Feature** | **apt Packages** | + +=============================+============================================================+ + | Compiler cache optimization | ``ccache`` | + +-----------------------------+------------------------------------------------------------+ + | Code linting | ``clang-format clang-tidy`` | + +-----------------------------+------------------------------------------------------------+ + | Debugging | ``gdb valgrind`` | + +-----------------------------+------------------------------------------------------------+ + +.. note:: + For Ubuntu 20.04 release and earlier, the version of ccache provided by apt + (3.7.7 or earlier) may not provide performance benefits, and users are recommended to install + version 4 or later, possibly as a source install. For Ubuntu 22.04 and later, ccache can be + installed using apt. + +.. note:: + clang-format-14 through clang-format-16 version is required. + +Optional +******** + +Please see below subsections for Python-related package requirements. + + +-----------------------------+------------------------------------------------------------+ + | **Feature** | **apt Packages** | + +=============================+============================================================+ + | Reading pcap traces | ``tcpdump wireshark`` | + +-----------------------------+------------------------------------------------------------+ + | Database support | ``sqlite sqlite3 libsqlite3-dev`` | + +-----------------------------+------------------------------------------------------------+ + | NetAnim animator | ``qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools`` | + +-----------------------------+------------------------------------------------------------+ + | MPI-based distributed | | + | simulation | ``openmpi-bin openmpi-common openmpi-doc libopenmpi-dev`` | + +-----------------------------+------------------------------------------------------------+ + | Building Doxygen | ``doxygen graphviz imagemagick`` | + +-----------------------------+------------------------------------------------------------+ + | Sphinx documentation | ``python3-sphinx dia imagemagick texlive dvipng latexmk`` | + | | ``texlive-extra-utils texlive-latex-extra`` | + | | ``texlive-font-utils`` | + +-----------------------------+------------------------------------------------------------+ + | GNU Scientific Library | ``gsl-bin libgsl-dev libgslcblas0`` | + +-----------------------------+------------------------------------------------------------+ + | XML config store | ``libxml2 libxml2-dev`` | + +-----------------------------+------------------------------------------------------------+ + | GTK-based config store | ``libgtk-3-dev`` | + +-----------------------------+------------------------------------------------------------+ + | Emulation with virtual | ``lxc-utils lxc-templates`` | + | machines and tap bridge | ``vtun uml-utilities ebtables bridge-utils`` | + +-----------------------------+------------------------------------------------------------+ + | Support for openflow | ``libxml2 libxml2-dev libboost-all-dev`` | + +-----------------------------+------------------------------------------------------------+ + +.. note:: + For Ubuntu 20.10 and earlier, the single 'qt5-default' package suffices for NetAnim (``apt install qt5-default``) + +Python bindings +=============== + +ns-3.37 and newer:: + + python3 -m pip install --user cppyy + +ns-3.30-3.36 (also requires pybindgen, found in the ``allinone`` directory):: + + apt install python3-dev pkg-config python3-setuptools + +PyViz visualizer +================ + +The PyViz visualizer uses a variety of Python packages supporting GraphViz.:: + + apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 + +For Ubuntu 18.04 and later, python-pygoocanvas is no longer provided. The ns-3.29 release and later upgrades the support to GTK+ version 3, and requires these packages: + +For ns-3.28 and earlier releases, PyViz is based on Python2, GTK+ 2, GooCanvas, and GraphViz:: + + apt install python-pygraphviz python-kiwi python-pygoocanvas libgoocanvas-dev ipython + +Generating modified python bindings (ns-3.36 and earlier) +========================================================= + +To modify the Python bindings found in release 3.36 and earlier (not needed for modern releases, +or if you do not use Python).:: + + apt install cmake libc6-dev libc6-dev-i386 libclang-dev llvm-dev automake python3-pip + python3 -m pip install --user cxxfilt + +and you will want to install castxml and pygccxml as per the instructions for python bindings (or +through the bake build tool as described in the tutorial). The 'castxml' and 'pygccxml' packages +provided by Ubuntu 18.04 and earlier are not recommended; a source build (coordinated via bake) +is recommended. If you plan to work with bindings or rescan them for any ns-3 C++ changes you +might make, please read the chapter in the manual on this topic. + +Caveats and troubleshooting +*************************** + +When building documentation, if you get an error such as +``convert ... not authorized source-temp/figures/lena-dual-stripe.eps``, see +`this post `_ about editing +ImageMagick's security policy configuration. In brief, you will want to make this kind of +change to ImageMagick security policy:: + + --- ImageMagick-6/policy.xml.bak 2020-04-28 21:10:08.564613444 -0700 + +++ ImageMagick-6/policy.xml 2020-04-28 21:10:29.413438798 -0700 + @@ -87,10 +87,10 @@ + + - + + + + + + - + + + + + diff --git a/doc/installation/source/macos.rst b/doc/installation/source/macos.rst new file mode 100644 index 000000000..aadf5fc17 --- /dev/null +++ b/doc/installation/source/macos.rst @@ -0,0 +1,122 @@ +.. 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 `_ 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 |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 `_ 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 |ns3| 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 |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 `_. + +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. |ns3| +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 | + +--------------------+---------------------------------------------------------------------+ + +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:: + 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`` | ``texlive`` | + | | | ``pyXX-sphinx``, with | + | | | `XX`` the Python version | + +-----------------------------+----------------------------------+--------------------------+ + | 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`` | + +-----------------------------+----------------------------------+--------------------------+ + +Caveats and troubleshooting +*************************** + diff --git a/doc/installation/source/overview.rst b/doc/installation/source/overview.rst new file mode 100644 index 000000000..02c01f5ce --- /dev/null +++ b/doc/installation/source/overview.rst @@ -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 `_, in the GitLab.com +`Issue tracker `_, (or better yet, a patch to fix +in the `Merge Request tracker `_), 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 diff --git a/doc/installation/source/quick-start.rst b/doc/installation/source/quick-start.rst new file mode 100644 index 000000000..9713c84cd --- /dev/null +++ b/doc/installation/source/quick-start.rst @@ -0,0 +1,179 @@ +.. include:: replace.txt +.. highlight:: bash +.. heading hierarchy: + ------------- Chapter + ************* Section (#.#) + ============= Subsection (#.#.#) + ############# Paragraph (no number) + +.. _Quick start: + +Quick Start +----------- + +This chapter summarizes the |ns3| installation process for C++ users interested in trying a +generic install of the main simulator. Python bindings installation is not covered. + +Some of this chapter is redundant with the +|ns3| `tutorial `_, which also covers similar steps. + +The steps are: + +1. Download a source archive, or make a git clone, of |ns3| to a location on your file + system (usually somewhere under your home directory). + +2. Use a C++ compiler to compile the software into a set of shared libraries, executable example + programs, and tests + +|ns3| uses the CMake build system to manage the C++ compilation, and CMake itself calls on +a lower-level build system such as ``make`` to perform the actual compilation. + +Prerequisites +************* + +Make sure that your system has these prerequisites. Download can be via either ``git`` or via +source archive download (via a web browser, ``wget``, or ``curl``). + + +--------------------+--------------------------------------+------------------------------+ + | **Purpose** | **Tool** | **Minimum Version** | + +====================+==================+===================+==============================+ + | **Download** | ``git`` (for Git download) | No minimum version | + + + + + + | | or ``tar`` and ``bunzip2`` | No minimum version | + | | (for Web download) | | + +--------------------+--------------------------------------+------------------------------+ + | **Compiler** | ``g++`` | >= 8 | + + + + + + | | or ``clang++`` | >= 10 | + +--------------------+--------------------------------------+------------------------------+ + | **Configuration** | ``python3`` | >= 3.5 | + +--------------------+--------------------------------------+------------------------------+ + | **Build system** | ``cmake``, | >= 3.10 | + + + + + + | | and at least one of: | No minimum version | + | | ``make``, ``ninja``, or ``Xcode`` | | + +--------------------+--------------------------------------+------------------------------+ + +.. note:: + + If you are using an older version of ns-3, other tools may be needed (such as + ``python2`` instead of ``python3`` and ``Waf`` instead of ``cmake``). Check the file + ``RELEASE_NOTES`` in the top-level directory for requirements for older releases. + +From the command line, you can check the version of each of the above tools with version +requirements as follows: + + +--------------------------------------+------------------------------------+ + | **Tool** | **Version check command** | + +======================================+====================================+ + | ``g++`` | ``$ g++ --version`` | + +--------------------------------------+------------------------------------+ + | ``clang++`` | ``$ clang++ --version`` | + +--------------------------------------+------------------------------------+ + | ``python3`` | ``$ python3 -V`` | + +--------------------------------------+------------------------------------+ + | ``cmake`` | ``$ cmake --version`` | + +--------------------------------------+------------------------------------+ + +Download +******** + +There are two main options: + +1. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.37`` +containing |ns3| and some other programs. Below is a command-line download using ``wget``, +but a browser download will also work:: + + $ wget https://www.nsnam.org/releases/ns-allinone-3.37.tar.bz2 + $ tar xfj ns-allinone-3.37.tar.bz2 + $ cd ns-allinone-3.37/ns-3.37 + +2. Clone |ns3| from the Git repository. The ``ns-3-allinone`` can be cloned, as well as +``ns-3-dev`` by itself. Below, we illustrate the latter:: + + $ git clone https://gitlab.com/nsnam/ns-3-dev.git + $ cd ns-3-dev + +Note that if you select option 1), your directory name will contain the release number. If +you clone |ns3|, your directory will be named ``ns-3-dev``. By default, Git will check out +the |ns3| ``master`` branch, which is a development branch. All |ns3| releases are tagged +in Git, so if you would then like to check out a past release, you can do so as follows:: + + $ git checkout -b ns-3.37-release ns-3.37 + +In this quick-start, we are omitting download and build instructions for optional |ns3| modules, +the ``NetAnim`` animator, Python bindings, and ``NetSimulyzer``. The +`ns-3 Tutorial `_ has some +instructions on optional components, or else the documentation associated with the extension +should be consulted. + +Moreover, in this guide we will assume that you are using ns-3.36 or later. Earlier +versions had different configuration, build, and run command and options. + +Building and testing ns-3 +************************* + +Once you have obtained the source either by downloading a release or by cloning a Git repository, +the next step is to configure the build using the *CMake* build system. The below commands +make use of a Python wrapper around CMake, called ``ns3``, that simplifies the command-line +syntax, resembling *Waf* syntax. There are several options to control the build, but enabling +the example programs and the tests, for a default build profile (with asserts enabled and +and support for |ns3| logging) is what is usually done at first:: + + $ ./ns3 configure --enable-examples --enable-tests + +Depending on how fast your CPU is, the configuration command can take anywhere from a few +seconds to a minute. + +Then, use the ``ns3`` program to build the |ns3| module libraries and executables:: + + $ ./ns3 build + +Build times vary based on the number of CPU cores, the speed of the CPU and memory, and the mode +of the build (whether debug mode, which is faster, or the default or optimized modes, which are +slower). Additional configuration (not covered here) can be used to limit the scope of the +build, and the ``ccache``, if installed, can speed things up. In general, plan on the build +taking a few minutes on faster workstations. + +You should see some output such as below, if successful:: + + 'build' finished successfully (44.159s) + + Modules built: + antenna aodv applications + bridge buildings config-store + core csma csma-layout + dsdv dsr energy + fd-net-device flow-monitor internet + internet-apps lr-wpan lte + mesh mobility mpi + netanim (no Python) network nix-vector-routing + olsr point-to-point point-to-point-layout + propagation sixlowpan spectrum + stats tap-bridge test (no Python) + topology-read traffic-control uan + virtual-net-device visualizer wave + wifi wimax + + Modules not built (see ns-3 tutorial for explanation): + brite click openflow + + +Once complete, you can run the unit tests to check your build:: + + $ ./test.py + +This command should run several hundred unit tests. If they pass, you have made a successful +initial build of |ns3|. Read further in this manual for instructions about building +optional components, or else consult the |ns3| Tutorial or other documentation to get started +with the base |ns3|. + +If you prefer to code with an code editor, consult the documentation in the |ns3| Manual +on `Working with CMake `_, +since CMake enables |ns3| integration with a variety of code editors, including: + +* JetBrains's CLion +* Microsoft Visual Studio and Visual Studio Code +* Apple's XCode +* CodeBlocks +* Eclipse CDT4 diff --git a/doc/installation/source/replace.txt b/doc/installation/source/replace.txt new file mode 100644 index 000000000..d3c0a4273 --- /dev/null +++ b/doc/installation/source/replace.txt @@ -0,0 +1,5 @@ +.. |ns3| replace:: *ns-3* + +.. |ns2| replace:: *ns-2* + +.. |check| replace:: :math:`\checkmark` diff --git a/doc/installation/source/system.rst b/doc/installation/source/system.rst new file mode 100644 index 000000000..def660b16 --- /dev/null +++ b/doc/installation/source/system.rst @@ -0,0 +1,226 @@ +.. include:: replace.txt +.. heading hierarchy: + ------------- Chapter + ************* Section (#.#) + ============= Subsection (#.#.#) + ############# Paragraph (no number) + +.. _General list: + +System Prerequisites +-------------------- + +This chapter describes the various required, recommended, and optional system prerequisites +for installing and using |ns3|. Optional prerequisites depend on whether an optional feature of +|ns3| is desired by the user. The chapter is written to be generally applicable to all operating +systems, and subsequent chapters describe the specific packages for different operating systems. + +The list of requirements depends on which version of ns-3 you are trying to build, and on which +extensions you need. + +.. note:: + **"Do I need to install all of these packages?"** Some users want to install everything so + that their configuration output shows that every feature is enabled. However, there is + no real need to install prerequisites related to features you are not yet using; you can always + come back later and install more prerequisites as needed. The build system should warn + you if you are missing a prerequisite. + +In the following, we have classified the prerequisites as either being required, recommended +for all users, or optional depending on use cases. + +.. note:: + **"Is there a maintained list of all prerequisites?"** We use GitLab.com's continuous + integration system for testing; the configuration YAML files for these jobs can be found + in the directory ``utils/tests/``. So, for instance, if you want to look at what packages + the CI is installing for Alpine Linux, look at ``utils/tests/gitlab-ci-alpine.yml``. The + default CI (Arch Linux) ``pacman`` commands are in ``utils/tests/gitlab-ci.yml``. + +Requirements +************ + +Minimal requirements for release 3.36 and later +=============================================== + +A C++ compiler (``g++`` or ``clang++``), Python 3, the `CMake `_ build +system, and a separate C++ building tool such as ``make``, ``ninja-build``, or ``Xcode`` are +the minimal requirements for compiling the software. + +The ``tar`` and ``bunzip2`` utilities are needed to unpack source file archives. +If you want to instead use `Git `_ to fetch code, rather than downloading +a source archive, then ``git`` is required instead. + +Minimal requirements for release 3.30-3.35 +========================================== + +If you are not using Python bindings, since the Waf build system is provided as part of |ns3|, +there are only two build requirements (a C++ compiler, and Python3) for a minimal install of these +older |ns3| releases. + +The ``tar`` and ``bunzip2`` utilities are needed to unpack source file archives. +If you want to instead use `Git `_ to fetch code, rather than downloading +a source archive, then ``git`` is required instead. + +Minimal requirements for release 3.29 and earlier +================================================= + +Similarly, only a C++ compiler and Python2 were strictly required for building the |ns3| +releases 3.29 and earlier. + +The ``tar`` and ``bunzip2`` utilities are needed to unpack source file archives. +If you want to instead use `Git `_ to fetch code, rather than downloading +a source archive, then ``git`` is required instead. + +Recommended +*********** + +The following are recommended for most users of |ns3|. + +compiler cache optimization (for ns-3.37 and later) +=================================================== + +`Ccache `_ is a compiler cache optimization that will speed up builds across +multiple |ns3| directories, at the cost of up to an extra 5 GB of disk space used in the cache. + +Code linting +============ + +Since ns-3.37 release, `Clang-Format `_ and +`Clang-Tidy `_ are used to enforce the coding-style +adopted by |ns3|. + +Users can invoke these tools directly from the command-line or through the +(``utils/check-style-clang-format.py``) check program. +Moreover, clang-tidy is integrated with CMake, enabling code scanning during the build phase. + +.. note:: + clang-format-14 through clang-format-16 version is required. + +clang-format is strongly recommended to write code that follows the ns-3 code conventions, but +might be skipped for simpler tasks (e.g., writing a simple simulation script for yourself). + +clang-tidy is recommended when writing a module, to both follow code conventions and to provide +hints on possible bugs in code. + +Both are used in the CI system, and a merge request will likely fail if you did not use them. + +Debugging +========= + +`GDB `_ and `Valgrind `_ are useful +for debugging and recommended if you are doing C++ development of new models or scenarios. +Both of the above tools are available for Linux and BSD systems; for macOS, +`LLDB `_ is similar to GDB, but Valgrind doesn't appear to be available +for M1 machines. + +Optional +******** + +The remaining prerequisites listed below are only needed for optional ns-3 components. + +.. note:: + As of ns-3.30 release (August 2019), ns-3 uses Python 3 by default, but earlier + releases depend on Python 2 packages, and at least a Python 2 interpreter is recommended. + If installing the below prerequisites for an earlier release, one may in general substitute + 'python' where 'python3' is found in the below (e.g., install 'python-dev' instead of + 'python3-dev'). + +To read pcap packet traces +========================== + +Many |ns3| examples generate pcap files that can be viewed by pcap analyzers such as Tcpdump +and `Wireshark `_. + +Database support +================ + +`SQLite `_ is recommended if you are using the statistics framework or +if you are running LTE or NR simulations (which make use of SQLite databases): + + +Python bindings (ns-3.37 and newer) +=================================== + +|ns3| Python support now uses `cppyy `_. + +Using Python bindings (release 3.30 to ns-3.36) +=============================================== + +This pertains to the use of existing Python bindings shipped with ns-3; for updating or +generating new bindings, see further below. + +Python bindings used `pybindgen `_ in the past, which +can usually be found in the ``ns-3-allinone`` directory. Python3 development packages, and +setup tools, are typically needed. + +NetAnim animator +================ + +The `Qt `_ qt5 development tools are needed for NetAnim animator; +qt4 will also work but we have migrated to qt5. qt6 compatibility is not tested. + +PyViz visualizer +================ + +The PyViz visualizer uses a variety of Python packages supporting GraphViz. +In general, to enable Python support in ns-3, `cppyy `_ is required. + +MPI-based distributed simulation +================================ + +`Open MPI `_ support is needed if you intend to run large, parallel +|ns3| simulations. + +Doxygen +======= + +`Doxygen `_ is only needed if you intend to write new Doxygen +documentation for header files. + +Sphinx documentation +==================== + +The ns-3 manual (``doc/manual``), tutorial (``doc/tutorial``) and others are written in +reStructuredText for Sphinx, and figures are typically in dia. To build PDF versions, +`texlive `_ packages are needed. + +GNU Scientific Library (GSL) +============================ + +GNU Scientific Library (GSL) is is only used for more accurate 802.11b (legacy) WiFi error models (not needed for more modern OFDM-based Wi-Fi). + +XML-based version of the config store +===================================== + +`Libxml2 `_ is needed for the XML-based Config Store feature. + +A GTK-based configuration system +================================ + +`GTK development libraries `_ are also related to the (optional) config store, +for graphical desktop support. + +Generating modified python bindings (ns-3.36 and earlier) +========================================================= + +To modify the Python bindings found in release 3.36 and earlier (not needed for modern releases, +or if you do not use Python, the `LLVM toolchain `_ and +`cxxfilt `_ are needed. + +You will also need to install +`castxml `_ and +`pygccxml `_ as per the instructions for Python bindings (or +through the bake build tool as described in the |ns3| tutorial). +If you plan to work with bindings or rescan them for any ns-3 C++ changes you +might make, please read the chapter in the manual (corresponding to the release) on this topic. + +To experiment with virtual machines and ns-3 +============================================ + +Linux systems can use `LXC `_ and +`TUN/TAP device drivers `_ for emulation support. + +Support for openflow module +=========================== + +`OpenFlow switch support `_ requires +XML and `Boost `_ development libraries. diff --git a/doc/manual/source/windows.rst b/doc/installation/source/windows.rst similarity index 92% rename from doc/manual/source/windows.rst rename to doc/installation/source/windows.rst index aebdeffe2..0bb0db686 100644 --- a/doc/manual/source/windows.rst +++ b/doc/installation/source/windows.rst @@ -1,21 +1,46 @@ .. include:: replace.txt -.. highlight:: console +.. heading hierarchy: + ------------- Chapter + ************* Section (#.#) + ============= Subsection (#.#.#) + ############# Paragraph (no number) -.. Section Separators: - ---- - **** - ++++ - ==== - ~~~~ +.. _Windows: -.. _Windows 10: +Windows +------- -Windows 10 ----------- - -This chapter describes installation steps specific to Windows 10 and its +This chapter describes installation steps specific to Microsoft Windows (version 10) and its derivatives (e.g. Home, Pro, Enterprise) using the Msys2/MinGW64 toolchain. +There are two documented ways to use |ns3| on Windows: the Windows Subsystem for Linux (WSL) or +via the Msys2/MinGW64 toolchain. Both options are listed below; users may choose to install +either WSL or the Msys2/MinGW64 toolchain (installing both is not required). + +.. note:: + |ns3| is not fully compatible with Visual Studio IDE / MSVC compiler; only Visual Studio Code +editor, the Msys2/MinGW64 toolchain, and WSL, as explained below. + +.. _WSL2: + +Windows Subsystem for Linux +*************************** + +Windows Subsystem for Linux (WSL), particularly WSL2, can be used on Windows for |ns3|. WSL2 +runs a real Linux kernel on Windows's Hyper-V hypervisor, providing 100% code compatibility with +Linux and seamless integration with Windows. VS Code has excellent support and integration with +WSL, enabling Windows users to develop for ns-3 in a native environment. It is recommended to +install the WSL extension in VS Code for this purpose. + +Users starting with WSL2 can follow the Linux installation instructions to fill out other +package prerequisites. Note that |ns3| emulation features using WSL2 are not tested/supported. + +For more information: + +* `WSL `_ +* `Developing in WSL with VS Code `_ +* `WSL tutorial `_ + .. _Windows 10 package prerequisites: Windows 10 package prerequisites @@ -31,7 +56,9 @@ Installation of the Msys2 environment The `Msys2`_ includes ports of Unix tools for Windows built with multiple toolchains, including: MinGW32, MinGW64, Clang64, UCRT. -The MinGW64 (GCC) toolchain is the one ns-3 was tested. +|ns3| has been tested with the MinGW64 (GCC) toolchain. MinGW32 is 32-bit, which |ns3| does +not support. The project's Windows maintainer has tested Clang64 unsuccessfully, and has +not tested the UCRT toolchain (which may work). The `Msys2`_ installer can be found on their site. Msys2 will be installed by default in the ``C:\msys64`` directory. @@ -46,7 +73,7 @@ or via the following command (assuming it was installed to the default directory Note: if the MinGW64 binary directory doesn't precede the Windows/System32 directory (already in ``%PATH%``), the documentation build will fail since Windows has a conflicting ``convert`` command (FAT-to-NTFS). Similarly, -the Msys64 binary directory doesn't precede the Windows/System2 directory, running the ``bash`` command will +if the Msys64 binary directory doesn't precede the Windows/System2 directory, running the ``bash`` command will result in Windows trying to run the Windows Subsystem for Linux (WSL) bash shell. Accessing the MinGW64 shell @@ -74,8 +101,13 @@ This is the minimal set of packages needed to run ns-3 C++ programs from a relea .. sourcecode:: console - /c/ns-3-dev/ MINGW64$ pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake \ - mingw-w64-x86_64-ninja mingw-w64-x86_64-grep mingw-w64-x86_64-sed mingw-w64-x86_64-python + /c/ns-3-dev/ MINGW64$ pacman -S \ + mingw-w64-x86_64-toolchain \ + mingw-w64-x86_64-cmake \ + mingw-w64-x86_64-ninja \ + mingw-w64-x86_64-grep \ + mingw-w64-x86_64-sed \ + mingw-w64-x86_64-python Netanim animator @@ -121,14 +153,6 @@ Debugging GDB is installed along with the mingw-w64-x86_64-toolchain package. -Support for utils/check-style.py code style check program -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. sourcecode:: console - - /c/ns-3-dev/ MINGW64$ pacman -S mingw-w64-x86_64-uncrustify - - Doxygen and related inline documentation ++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 8e501e8f5..3fb0b88e5 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -45,7 +45,6 @@ SOURCES = \ source/tracing.rst \ source/troubleshoot.rst \ source/utilities.rst \ - source/windows.rst \ source/working-with-cmake.rst \ source/working-with-git.rst \ source/working-with-gitlab-ci-local.rst \ diff --git a/doc/manual/source/develop.rst b/doc/manual/source/develop.rst index 79b2e5534..b5ead5678 100644 --- a/doc/manual/source/develop.rst +++ b/doc/manual/source/develop.rst @@ -17,4 +17,3 @@ This chapter describes the development ecosystem generally used to create new mo documentation profiling working-with-gitlab-ci-local - windows