From ab476ddcde8815f8847f912af8e3adb63490613b Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Wed, 22 Sep 2021 13:42:10 -0700
Subject: [PATCH] documentation: Add quick start section to ns-3 tutorial

---
 doc/release_steps.txt                       |   2 +-
 doc/tutorial/source/conceptual-overview.rst |   2 +
 doc/tutorial/source/getting-started.rst     |   2 +
 doc/tutorial/source/index.rst               |   1 +
 doc/tutorial/source/introduction.rst        |   6 +
 doc/tutorial/source/quick-start.rst         | 145 ++++++++++++++++++++
 6 files changed, 157 insertions(+), 1 deletion(-)
 create mode 100644 doc/tutorial/source/quick-start.rst

diff --git a/doc/release_steps.txt b/doc/release_steps.txt
index 27953016f..e90ac33b8 100644
--- a/doc/release_steps.txt
+++ b/doc/release_steps.txt
@@ -39,7 +39,7 @@ and/or the buildbots have been testing
    - confirm that the new bake configurations for the release work correctly
    - confirm all documents build:  './waf docs' and check outputs
 
-2.1)  Update the tutorial "Getting Started" page to use the new release number.
+2.1)  Update the tutorial "Getting Started" and "Quick Start" pages to use the new release number.
 
 An example commit (July 14, 2021) to review is 9df8ef4b2.
 
diff --git a/doc/tutorial/source/conceptual-overview.rst b/doc/tutorial/source/conceptual-overview.rst
index 3be0750b6..934c29d17 100644
--- a/doc/tutorial/source/conceptual-overview.rst
+++ b/doc/tutorial/source/conceptual-overview.rst
@@ -1,6 +1,8 @@
 .. include:: replace.txt
 .. highlight:: cpp
 
+.. _Conceptual Overview:
+
 Conceptual Overview
 -------------------
 
diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst
index dd1b4eca8..81a49afb7 100644
--- a/doc/tutorial/source/getting-started.rst
+++ b/doc/tutorial/source/getting-started.rst
@@ -1,6 +1,8 @@
 .. include:: replace.txt
 .. highlight:: bash
 
+.. _Getting Started:
+
 Getting Started
 ---------------
 
diff --git a/doc/tutorial/source/index.rst b/doc/tutorial/source/index.rst
index 1691e96b8..17c21221e 100644
--- a/doc/tutorial/source/index.rst
+++ b/doc/tutorial/source/index.rst
@@ -16,6 +16,7 @@ This document is written in `reStructuredText <http://docutils.sourceforge.net/r
 .. toctree::
    :maxdepth: 2
 
+   quick-start
    introduction
    resources
    getting-started
diff --git a/doc/tutorial/source/introduction.rst b/doc/tutorial/source/introduction.rst
index fd160b223..ca42a0c17 100644
--- a/doc/tutorial/source/introduction.rst
+++ b/doc/tutorial/source/introduction.rst
@@ -1,5 +1,7 @@
 .. include:: replace.txt
 
+.. _Introduction:
+
 Introduction
 ------------
 
@@ -20,6 +22,9 @@ As the tutorial unfolds, we will introduce the full |ns3| documentation
 and provide pointers to source code for those interested in delving deeper
 into the workings of the system.
 
+We also provide a quick start guide for those who are comfortable
+diving right in without too much documentation.
+
 A few key points are worth noting at the onset:
 
 * |ns3| is open-source, and the project strives to maintain an 
@@ -29,6 +34,7 @@ A few key points are worth noting at the onset:
   it is a new simulator.  The two simulators are both written in C++ but 
   |ns3| is a new simulator that does not support the |ns2| APIs.
 
+
 About ns-3
 **********
 
diff --git a/doc/tutorial/source/quick-start.rst b/doc/tutorial/source/quick-start.rst
new file mode 100644
index 000000000..bb7a49c87
--- /dev/null
+++ b/doc/tutorial/source/quick-start.rst
@@ -0,0 +1,145 @@
+.. include:: replace.txt
+.. highlight:: bash
+
+.. _Quick Start:
+
+Quick Start
+-----------
+
+This section is optional, for readers who want to get |ns3| up and running
+as quickly as possible.  Readers may skip forward to the :ref:`Introduction`
+chapter, followed by the :ref:`Getting Started` chapter, for a lengthier
+coverage of all of this material.
+
+Brief Summary
+*************
+|ns3| is a discrete-event simulator typically run from the command line.
+It is written directly in C++, not in a high-level modeling language;
+simulation events are simply C++ function calls, organized by a scheduler.
+
+An |ns3| user will obtain the |ns3| source code (see below), 
+compile it into shared (or static) libraries, and link the libraries to 
+`main()` programs that he or she authors.  The `main()` program is where
+the specific simulation scenario configuration is performed and where the 
+simulator is run and stopped.  Several example programs are provided, which
+can be modified or copied to create new simulation scenarios.  Users also
+often edit the |ns3| library code (and rebuild the libraries) to change
+its behavior.
+
+|ns3| has optional Python bindings for authoring scenario configuration
+programs in Python (and using a Python-based workflow); this quick start
+does not cover those aspects.
+
+Prerequisites
+*************
+|ns3| has various optional extensions, but the main features just require
+a C++ compiler (g++ or clang++) and Python (version 3.6 or above); the
+Python is needed for the build system.  We focus in this chapter only on
+getting |ns3| up and running on a system supported by a recent C++ compiler
+and Python runtime support.
+
+For Linux, use either g++ or clang++ compilers.  For macOS, use clang++ 
+(available in Xcode or Xcode Command Line Tools).  For Windows, we recommend
+to either use a Linux virtual machine, or the Windows Subsystem for Linux. 
+
+Downloading ns-3
+****************
+
+|ns3| is distributed in source code only (some binary packages exist but
+they are not maintained by the open source project).  There are two
+main ways to obtain the source code:  1) downloading the latest release
+as a source code archive from the main |ns3| web site, or 2) cloning
+the Git repository from GitLab.com.  These two options are described next;
+either one or the other download option (but not both) should be followed.
+
+Downloading the Latest Release
+++++++++++++++++++++++++++++++
+
+1) Download the latest release from https://www.nsnam.org/releases/latest
+
+2) Unpack it in a working directory of your choice.
+
+   ::
+
+    $ tar xjf ns-allinone-3.34.tar.bz2
+
+3) Change into the |ns3| directory directly; e.g.
+
+   ::
+
+    $ cd ns-allinone-3.34/ns-3.34
+
+The ns-allinone directory has some additional components but we are skipping
+over them here; one can work directly from the |ns3| source code directory.
+
+Cloning ns-3 from GitLab.com
+++++++++++++++++++++++++++++
+
+You can perform a Git clone in the usual way:
+
+::
+
+  $ git clone https://gitlab.com/nsnam/ns-3-dev.git
+
+If you are content to work with the tip of the development tree; you need
+only to `cd` into ns-3-dev; the `master` branch is checked out by default.
+
+::
+
+  $ cd ns-3-dev
+
+If instead you want to try the most recent release (version 3.34 as of this
+writing), you can checkout a branch corresponding to that git tag:
+
+::
+
+  $ git checkout -b ns-3.34-branch ns-3.34
+
+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 *Waf* build system that comes with |ns3|.  There
+are several options to control the build, but enabling the example programs
+and the tests, for a default debug build profile (with debugging symbols
+and support for |ns3| logging) is what is usually done at first:
+
+::
+
+  $ ./waf configure --enable-examples --enable-tests
+
+Then, use Waf to build |ns3|:
+
+::
+
+  $ ./waf build
+
+Once complete, you can run the unit tests to check your build:
+
+::
+
+  $ ./test.py
+
+All tests should either PASS or be SKIPped.  At this point, you have a
+working |ns3| simulator.  From here, you can start to
+run programs (look in the examples directory).  To run the first tutorial
+program, whose source code is located at `examples/tutorial/first.cc`, 
+use Waf to run it (by doing so, the |ns3| shared libraries are found
+automatically):
+
+::
+
+  $ ./waf --run first
+
+To view possible command-line options, specify the `--PrintHelp` argument:
+
+::
+
+  $ ./waf --run 'first --PrintHelp'
+
+To continue reading about the conceptual model and architecture of |ns3|,
+the tutorial chapter :ref:`Conceptual Overview` would be the next natural place
+to skip to, or you can learn more about the project and the
+various build options by continuing directly with the :ref:`Introduction`
+and :ref:`Getting Started` chapters.