doc: Update and improve README.md
Eduardo Almeida
parent
3de3a27f25
commit
6c81a8fccb
127
README.md
127
README.md
|
|
@ -1,36 +1,33 @@
|
|||
# The Network Simulator, Version 3
|
||||
|
||||
|
||||
[](https://codecov.io/gh/nsnam/ns-3-dev-git/branch/master/)
|
||||
[](https://gitlab.com/nsnam/ns-3-dev/-/pipelines)
|
||||
[](https://github.com/nsnam/ns-3-dev-git/actions)
|
||||
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1) [An overview](#an-open-source-project)
|
||||
2) [Building ns-3](#building-ns-3)
|
||||
3) [Running ns-3](#running-ns-3)
|
||||
4) [Getting access to the ns-3 documentation](#getting-access-to-the-ns-3-documentation)
|
||||
5) [Working with the development version of ns-3](#working-with-the-development-version-of-ns-3)
|
||||
* [Overview](#overview-an-open-source-project)
|
||||
* [Building ns-3](#building-ns-3)
|
||||
* [Testing ns-3](#testing-ns-3)
|
||||
* [Running ns-3](#running-ns-3)
|
||||
* [ns-3 Documentation](#ns-3-documentation)
|
||||
* [Working with the Development Version of ns-3](#working-with-the-development-version-of-ns-3)
|
||||
* [Contributing to ns-3](#contributing-to-ns-3)
|
||||
* [Reporting Issues](#reporting-issues)
|
||||
* [ns-3 App Store](#ns-3-app-store)
|
||||
|
||||
> **NOTE**: Much more substantial information about ns-3 can be found at
|
||||
<https://www.nsnam.org>
|
||||
|
||||
## An Open Source project
|
||||
## Overview: An Open Source Project
|
||||
|
||||
ns-3 is a free open source project aiming to build a discrete-event
|
||||
network simulator targeted for simulation research and education.
|
||||
This is a collaborative project; we hope that
|
||||
the missing pieces of the models we have not yet implemented
|
||||
will be contributed by the community in an open collaboration
|
||||
process.
|
||||
|
||||
The process of contributing to the ns-3 project varies with
|
||||
the people involved, the amount of time they can invest
|
||||
and the type of model they want to work on, but the current
|
||||
process that the project tries to follow is described here:
|
||||
<https://www.nsnam.org/developers/contributing-code/>
|
||||
process. If you would like to contribute to ns-3, please check
|
||||
the [Contributing to ns-3](#contributing-to-ns-3) section below.
|
||||
|
||||
This README excerpts some details from a more extensive
|
||||
tutorial that is maintained at:
|
||||
|
|
@ -45,24 +42,31 @@ use of these ns-3 libraries.
|
|||
|
||||
To build the set of default libraries and the example
|
||||
programs included in this package, you need to use the
|
||||
tool 'ns3'. Detailed information on how to use ns3 is
|
||||
included in the file doc/build.txt
|
||||
`ns3` tool. This tool provides a Waf-like API to the
|
||||
underlying CMake build manager.
|
||||
Detailed information on how to use `ns3` is included in the
|
||||
[quick start guide](doc/installation/source/quick-start.rst).
|
||||
|
||||
However, the real quick and dirty way to get started is to
|
||||
type the command
|
||||
Before building ns-3, you must configure it.
|
||||
This step allows the configuration of the build options,
|
||||
such as whether to enable the examples, tests and more.
|
||||
|
||||
To configure ns-3 with examples and tests enabled,
|
||||
run the following command on the ns-3 main directory:
|
||||
|
||||
```shell
|
||||
./ns3 configure --enable-examples
|
||||
./ns3 configure --enable-examples --enable-tests
|
||||
```
|
||||
|
||||
followed by
|
||||
Then, build ns-3 by running the following command:
|
||||
|
||||
```shell
|
||||
./ns3
|
||||
./ns3 build
|
||||
```
|
||||
|
||||
in the directory which contains this README file. The files
|
||||
built will be copied in the build/ directory.
|
||||
By default, the build artifacts will be stored in the `build/` directory.
|
||||
|
||||
### Supported Platforms
|
||||
|
||||
The current codebase is expected to build and run on the
|
||||
set of platforms listed in the [release notes](RELEASE_NOTES.md)
|
||||
|
|
@ -71,6 +75,18 @@ file.
|
|||
Other platforms may or may not work: we welcome patches to
|
||||
improve the portability of the code to these other platforms.
|
||||
|
||||
## Testing ns-3
|
||||
|
||||
ns-3 contains test suites to validate the models and detect regressions.
|
||||
To run the test suite, run the following command on the ns-3 main directory:
|
||||
|
||||
```shell
|
||||
./test.py
|
||||
```
|
||||
|
||||
More information about ns-3 tests is available in the
|
||||
[test framework](doc/manual/source/test-framework.rst) section of the manual.
|
||||
|
||||
## Running ns-3
|
||||
|
||||
On recent Linux systems, once you have built ns-3 (with examples
|
||||
|
|
@ -83,11 +99,10 @@ following command, such as:
|
|||
|
||||
That program should generate a `simple-global-routing.tr` text
|
||||
trace file and a set of `simple-global-routing-xx-xx.pcap` binary
|
||||
pcap trace files, which can be read by `tcpdump -tt -r filename.pcap`
|
||||
The program source can be found in the examples/routing directory.
|
||||
PCAP trace files, which can be read by `tcpdump -n -tt -r filename.pcap`.
|
||||
The program source can be found in the `examples/routing` directory.
|
||||
|
||||
|
||||
## Running ns-3 from python
|
||||
## Running ns-3 from Python
|
||||
|
||||
If you do not plan to modify ns-3 upstream modules, you can get
|
||||
a pre-built version of the ns-3 python bindings.
|
||||
|
|
@ -117,26 +132,26 @@ The script above will print the logging messages for the called commands.
|
|||
|
||||
Use `help(ns)` to check the prototypes for all functions defined in the
|
||||
ns3 namespace. To get more useful results, query specific classes of
|
||||
interest and their functions e.g. `help(ns.Simulator)`.
|
||||
interest and their functions e.g., `help(ns.Simulator)`.
|
||||
|
||||
Smart pointers `Ptr<>` can be differentiated from objects by checking if
|
||||
`__deref__` is listed in `dir(variable)`. To dereference the pointer,
|
||||
use `variable.__deref__()`.
|
||||
|
||||
Most ns-3 simulations are written in C++ and the documentation is
|
||||
oriented towards C++ users. The ns-3 tutorial programs (first.cc,
|
||||
second.cc, etc.) have Python equivalents, if you are looking for
|
||||
oriented towards C++ users. The ns-3 tutorial programs (`first.cc`,
|
||||
`second.cc`, etc.) have Python equivalents, if you are looking for
|
||||
some initial guidance on how to use the Python API. The Python
|
||||
API may not be as full-featured as the C++ API, and an API guide
|
||||
for what C++ APIs are supported or not from Python do not currently exist.
|
||||
The project is looking for additional Python maintainers to improve
|
||||
the support for future Python users.
|
||||
|
||||
## Getting access to the ns-3 documentation
|
||||
## ns-3 Documentation
|
||||
|
||||
Once you have verified that your build of ns-3 works by running
|
||||
the simple-point-to-point example as outlined in 3) above, it is
|
||||
quite likely that you will want to get started on reading
|
||||
the `simple-global-routing` example as outlined in the [running ns-3](#running-ns-3)
|
||||
section, it is quite likely that you will want to get started on reading
|
||||
some ns-3 documentation.
|
||||
|
||||
All of that documentation should always be available from
|
||||
|
|
@ -144,31 +159,55 @@ the ns-3 website: <https://www.nsnam.org/documentation/>.
|
|||
|
||||
This documentation includes:
|
||||
|
||||
- a tutorial
|
||||
- a reference manual
|
||||
- models in the ns-3 model library
|
||||
- a wiki for user-contributed tips: <https://www.nsnam.org/wiki/>
|
||||
- API documentation generated using doxygen: this is
|
||||
* a tutorial
|
||||
* a reference manual
|
||||
* models in the ns-3 model library
|
||||
* a wiki for user-contributed tips: <https://www.nsnam.org/wiki/>
|
||||
* API documentation generated using doxygen: this is
|
||||
a reference manual, most likely not very well suited
|
||||
as introductory text:
|
||||
<https://www.nsnam.org/doxygen/index.html>
|
||||
|
||||
## Working with the development version of ns-3
|
||||
## Working with the Development Version of ns-3
|
||||
|
||||
If you want to download and use the development version of ns-3, you
|
||||
need to use the tool `git`. A quick and dirty cheat sheet is included
|
||||
in the manual, but reading through the git
|
||||
in the manual, but reading through the Git
|
||||
tutorials found in the Internet is usually a good idea if you are not
|
||||
familiar with it.
|
||||
|
||||
If you have successfully installed git, you can get
|
||||
If you have successfully installed Git, you can get
|
||||
a copy of the development version with the following command:
|
||||
|
||||
```shell
|
||||
git clone https://gitlab.com/nsnam/ns-3-dev.git
|
||||
```
|
||||
|
||||
However, we recommend to follow the Gitlab guidelines for starters,
|
||||
that includes creating a Gitlab account, forking the ns-3-dev project
|
||||
However, we recommend to follow the GitLab guidelines for starters,
|
||||
that includes creating a GitLab account, forking the ns-3-dev project
|
||||
under the new account's name, and then cloning the forked repository.
|
||||
You can find more information in the [manual](https://www.nsnam.org/docs/manual/html/working-with-git.html).
|
||||
|
||||
## Contributing to ns-3
|
||||
|
||||
The process of contributing to the ns-3 project varies with
|
||||
the people involved, the amount of time they can invest
|
||||
and the type of model they want to work on, but the current
|
||||
process that the project tries to follow is described in the
|
||||
[contributing code](https://www.nsnam.org/developers/contributing-code/)
|
||||
website and in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
If you would like to report an issue, you can open a new issue in the
|
||||
[GitLab issue tracker](https://gitlab.com/nsnam/ns-3-dev/-/issues).
|
||||
Before creating a new issue, please check if the problem that you are facing
|
||||
was already reported and contribute to the discussion, if necessary.
|
||||
|
||||
## ns-3 App Store
|
||||
|
||||
The official [ns-3 App Store](https://apps.nsnam.org/) is a centralized directory
|
||||
listing third-party modules for ns-3 available on the Internet.
|
||||
|
||||
More information on how to submit an ns-3 module to the ns-3 App Store is available
|
||||
in the [ns-3 App Store documentation](https://www.nsnam.org/docs/contributing/html/external.html).
|
||||
|
|
|
|||
Loading…
Reference in New Issue