README
author Tom Henderson <tomh@tomh.org>
Thu, 30 Aug 2018 13:39:08 -0700
changeset 13764 ee1b8a17f63a
parent 13055 60e423e20a9d
permissions -rw-r--r--
tcp: Update status of NSC TCP in manual
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3760
cfc585a0ea16 Undo change
Raj Bhattacharjea <raj.b@gatech.edu>
parents: 3759
diff changeset
     1
657
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
     2
    The Network Simulator, Version 3
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
     3
    --------------------------------
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
     4
657
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
     5
Table of Contents:
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
     6
------------------
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
     7
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
     8
1) An overview
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
     9
2) Building ns-3
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    10
3) Running ns-3
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    11
4) Getting access to the ns-3 documentation
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    12
5) Working with the development version of ns-3
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    13
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    14
Note:  Much more substantial information about ns-3 can be found at
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    15
http://www.nsnam.org
421
56928998e05c Final pre-release files
Tom Henderson <tomh@tomh.org>
parents: 314
diff changeset
    16
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    17
1) An Open Source project
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    18
-------------------------
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    19
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    20
ns-3 is a free open source project aiming to build a discrete-event
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    21
network simulator targeted for simulation research and education.   
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    22
This is a collaborative project; we hope that
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    23
the missing pieces of the models we have not yet implemented
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    24
will be contributed by the community in an open collaboration
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    25
process.
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    26
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    27
The process of contributing to the ns-3 project varies with
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    28
the people involved, the amount of time they can invest
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    29
and the type of model they want to work on, but the current
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    30
process that the project tries to follow is described here:
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    31
http://www.nsnam.org/developers/contributing-code/
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    32
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    33
This README excerpts some details from a more extensive
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    34
tutorial that is maintained at:
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    35
http://www.nsnam.org/documentation/latest/
263
618a886c7130 Test of commit access with Mercurial cheat sheet
Tom Henderson <tomh@tomh.org>
parents: 217
diff changeset
    36
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    37
2) Building ns-3
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    38
----------------
7
e53ac3c458e9 test of commit
tomh@powerbook.local
parents: 3
diff changeset
    39
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    40
The code for the framework and the default models provided
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    41
by ns-3 is built as a set of libraries. User simulations
657
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
    42
are expected to be written as simple programs that make
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    43
use of these ns-3 libraries.
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    44
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    45
To build the set of default libraries and the example
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    46
programs included in this package, you need to use the
12472
e23933168fdc README fix
Alexander Krotov <krotov@iitp.ru>
parents: 7621
diff changeset
    47
tool 'waf'. Detailed information on how to use waf is
3653
b6724ca12da9 update build matrix
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 2891
diff changeset
    48
included in the file doc/build.txt
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    49
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    50
However, the real quick and dirty way to get started is to
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    51
type the command
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    52
  ./waf configure --enable-examples
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    53
followed by
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    54
  ./waf 
13055
60e423e20a9d Documentation spelling fixes
Alexander Krotov <krotov@iitp.ru>
parents: 12479
diff changeset
    55
in the directory which contains
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    56
this README file. The files built will be copied in the
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    57
build/ directory.
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    58
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    59
The current codebase is expected to build and run on the
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    60
set of platforms listed in the RELEASE_NOTES file.
3653
b6724ca12da9 update build matrix
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 2891
diff changeset
    61
b6724ca12da9 update build matrix
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 2891
diff changeset
    62
Other platforms may or may not work: we welcome patches to 
b6724ca12da9 update build matrix
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 2891
diff changeset
    63
improve the portability of the code to these other platforms. 
217
1df7792bdc0c Raj test commit
raj@igloo.ece.gatech.edu
parents: 7
diff changeset
    64
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    65
3) Running ns-3
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    66
---------------
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    67
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    68
On recent Linux systems, once you have built ns-3 (with examples
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    69
enabled), it should be easy to run the sample programs with the
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    70
following command, such as:
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    71
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    72
  ./waf --run simple-global-routing
263
618a886c7130 Test of commit access with Mercurial cheat sheet
Tom Henderson <tomh@tomh.org>
parents: 217
diff changeset
    73
2841
eed8d933cdf0 update platform build matrix and example program.
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1786
diff changeset
    74
That program should generate a simple-global-routing.tr text 
eed8d933cdf0 update platform build matrix and example program.
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1786
diff changeset
    75
trace file and a set of simple-global-routing-xx-xx.pcap binary
eed8d933cdf0 update platform build matrix and example program.
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1786
diff changeset
    76
pcap trace files, which can be read by tcpdump -tt -r filename.pcap
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    77
The program source can be found in the examples/routing directory.
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    78
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    79
4) Getting access to the ns-3 documentation
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    80
-------------------------------------------
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    81
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    82
Once you have verified that your build of ns-3 works by running
12479
4f650ff67065 Another README typo fix
Alexander Krotov <krotov@iitp.ru>
parents: 12472
diff changeset
    83
the simple-point-to-point example as outlined in 3) above, it is
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    84
quite likely that you will want to get started on reading
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    85
some ns-3 documentation. 
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    86
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    87
All of that documentation should always be available from
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    88
the ns-3 website: http:://www.nsnam.org/documentation/.
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    89
655
f2ee52034178 update the documentation section
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 643
diff changeset
    90
This documentation includes:
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    91
2891
aeca90b95bf5 nits for 3.0.12 release
Tom Henderson <tomh@tomh.org>
parents: 2841
diff changeset
    92
  - a tutorial
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    93
 
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    94
  - a reference manual
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    95
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
    96
  - models in the ns-3 model library
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    97
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    98
  - a wiki for user-contributed tips: http://www.nsnam.org/wiki/
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    99
7621
b0120c820a67 Fix outdated README information
Tom Henderson <tomh@tomh.org>
parents: 3982
diff changeset
   100
  - API documentation generated using doxygen: this is
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
   101
    a reference manual, most likely not very well suited 
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
   102
    as introductory text:
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
   103
    http://www.nsnam.org/doxygen/index.html
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
   104
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
   105
5) Working with the development version of ns-3
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   106
-----------------------------------------------
263
618a886c7130 Test of commit access with Mercurial cheat sheet
Tom Henderson <tomh@tomh.org>
parents: 217
diff changeset
   107
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   108
If you want to download and use the development version 
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   109
of ns-3, you need to use the tool 'mercurial'. A quick and
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   110
dirty cheat sheet is included in doc/mercurial.txt but
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   111
reading through the mercurial tutorials included on the
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   112
mercurial website is usually a good idea if you are not
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   113
familiar with it.
314
2a105293177d touch a file
tomh@ubuntu
parents: 263
diff changeset
   114
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   115
If you have successfully installed mercurial, you can get
697
8019689fb08c Touch file for test checkin
Tom Henderson <tomh@tomh.org>
parents: 663
diff changeset
   116
a copy of the development version with the following command:
657
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
   117
"hg clone http://code.nsnam.org/ns-3-dev"