README
author Raj Bhattacharjea <raj.b@gatech.edu>
Wed, 01 Apr 2009 19:09:12 -0400
changeset 4306 5396ecd09060
parent 3982 4f370a1b637c
permissions -rw-r--r--
Update AUTHORS for ns-3.4
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
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    27
Contributing to the ns-3 project is still a very informal
783
abde897006fd fix small typos
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 697
diff changeset
    28
process because that process depends heavily on the background
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    29
of the people involved, the amount of time they can invest
657
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
    30
and the type of model they want to work on.  
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    31
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    32
Despite this lack of a formal process, there are a number of 
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    33
steps which naturally stem from the open-source roots of the
657
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
    34
project.  These steps are described in doc/contributing.txt
263
618a886c7130 Test of commit access with Mercurial cheat sheet
Tom Henderson <tomh@tomh.org>
parents: 217
diff changeset
    35
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    36
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
    37
----------------
7
e53ac3c458e9 test of commit
tomh@powerbook.local
parents: 3
diff changeset
    38
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    39
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
    40
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
    41
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
    42
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
    43
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    44
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
    45
programs included in this package, you need to use the
3653
b6724ca12da9 update build matrix
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 2891
diff changeset
    46
tool 'waf'. Detailed information on how use waf is 
b6724ca12da9 update build matrix
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 2891
diff changeset
    47
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
    48
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    49
However, the real quick and dirty way to get started is to
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    50
type the command "./waf configure; ./waf" the 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
    51
this README file. The files built will be copied in the
956
cf63e1cc64be Update README to mention WAF instead of SCons.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 783
diff changeset
    52
build/debug or build/optimized.
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    53
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    54
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
    55
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
    56
b6724ca12da9 update build matrix
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 2891
diff changeset
    57
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
    58
improve the portability of the code to these other platforms. 
217
1df7792bdc0c Raj test commit
raj@igloo.ece.gatech.edu
parents: 7
diff changeset
    59
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    60
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
    61
---------------
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    62
657
be551a3b07c6 minor changes due to documentation review
Tom Henderson <tomh@tomh.org>
parents: 655
diff changeset
    63
On recent Linux systems, once you have built ns-3, it 
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    64
should be easy to run the sample programs with the
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    65
following command:
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    66
2841
eed8d933cdf0 update platform build matrix and example program.
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1786
diff changeset
    67
./waf --run simple-global-routing
263
618a886c7130 Test of commit access with Mercurial cheat sheet
Tom Henderson <tomh@tomh.org>
parents: 217
diff changeset
    68
2841
eed8d933cdf0 update platform build matrix and example program.
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 1786
diff changeset
    69
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
    70
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
    71
pcap trace files, which can be read by tcpdump -tt -r filename.pcap
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
    72
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    73
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
    74
-------------------------------------------
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    75
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    76
Once you have verified that your build of ns-3 works by running
1786
c88914465031 updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 956
diff changeset
    77
the simple-point-to-point example as outlined in 4) above, it is
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    78
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
    79
some ns-3 documentation. 
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
All of that documentation should always be available from
655
f2ee52034178 update the documentation section
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 643
diff changeset
    82
the ns-3 website: http:://www.nsnam.org/ but we
f2ee52034178 update the documentation section
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 643
diff changeset
    83
include some of it in this release for ease of use.
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    84
655
f2ee52034178 update the documentation section
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 643
diff changeset
    85
This documentation includes:
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    86
2891
aeca90b95bf5 nits for 3.0.12 release
Tom Henderson <tomh@tomh.org>
parents: 2841
diff changeset
    87
  - a tutorial
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    88
 
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    89
  - a manual
641
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    90
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    91
  - 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
    92
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    93
  - an API documentation generated using doxygen: this is
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    94
    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
    95
    as introductory text:
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    96
    http://www.nsnam.org/doxygen/index.html
c55da3a2f496 add reference to architecture document
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 635
diff changeset
    97
3982
4f370a1b637c add some things to release notes and changes.html; revise README
Tom Henderson <tomh@tomh.org>
parents: 3760
diff changeset
    98
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
    99
-----------------------------------------------
263
618a886c7130 Test of commit access with Mercurial cheat sheet
Tom Henderson <tomh@tomh.org>
parents: 217
diff changeset
   100
635
71b92dfe5f55 write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 421
diff changeset
   101
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
   102
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
   103
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
   104
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
   105
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
   106
familiar with it.
314
2a105293177d touch a file
tomh@ubuntu
parents: 263
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 have successfully installed mercurial, you can get
697
8019689fb08c Touch file for test checkin
Tom Henderson <tomh@tomh.org>
parents: 663
diff changeset
   109
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
   110
"hg clone http://code.nsnam.org/ns-3-dev"