README
author Josh Pelkey <jpelkey@gatech.edu>
Wed, 11 Aug 2010 11:37:37 -0400
changeset 6553 fb5ad9c7755a
parent 3760 cfc585a0ea16
permissions -rw-r--r--
update release notes and fix doxygen warnings
raj@3760
     1
tomh@657
     2
    The Network Simulator, Version 3
tomh@657
     3
    --------------------------------
mathieu@3
     4
tomh@657
     5
Table of Contents:
tomh@657
     6
------------------
tomh@7
     7
tomh@3982
     8
1) An overview
tomh@3982
     9
2) Building ns-3
tomh@3982
    10
3) Running ns-3
tomh@3982
    11
4) Getting access to the ns-3 documentation
tomh@3982
    12
5) Working with the development version of ns-3
raj@217
    13
tomh@3982
    14
Note:  Much more substantial information about ns-3 can be found at
tomh@3982
    15
http://www.nsnam.org
tomh@263
    16
mathieu@635
    17
1) An Open Source project
mathieu@635
    18
-------------------------
tomh@263
    19
tomh@3982
    20
ns-3 is a free open source project aiming to build a discrete-event
tomh@3982
    21
network simulator targeted for simulation research and education.   
tomh@3982
    22
This is a collaborative project; we hope that
mathieu@635
    23
the missing pieces of the models we have not yet implemented
mathieu@635
    24
will be contributed by the community in an open collaboration
mathieu@635
    25
process.
tomh@263
    26
mathieu@635
    27
Contributing to the ns-3 project is still a very informal
mathieu@783
    28
process because that process depends heavily on the background
mathieu@635
    29
of the people involved, the amount of time they can invest
tomh@657
    30
and the type of model they want to work on.  
tomh@314
    31
mathieu@635
    32
Despite this lack of a formal process, there are a number of 
mathieu@635
    33
steps which naturally stem from the open-source roots of the
tomh@657
    34
project.  These steps are described in doc/contributing.txt
mathieu@635
    35
tomh@3982
    36
2) Building ns-3
mathieu@635
    37
----------------
mathieu@635
    38
mathieu@635
    39
The code for the framework and the default models provided
mathieu@635
    40
by ns-3 is built as a set of libraries. User simulations
tomh@657
    41
are expected to be written as simple programs that make
mathieu@635
    42
use of these ns-3 libraries.
mathieu@635
    43
mathieu@635
    44
To build the set of default libraries and the example
mathieu@635
    45
programs included in this package, you need to use the
mathieu@3653
    46
tool 'waf'. Detailed information on how use waf is 
mathieu@3653
    47
included in the file doc/build.txt
mathieu@635
    48
mathieu@635
    49
However, the real quick and dirty way to get started is to
tomh@3982
    50
type the command "./waf configure; ./waf" the the directory which contains
mathieu@635
    51
this README file. The files built will be copied in the
gjc@956
    52
build/debug or build/optimized.
mathieu@635
    53
mathieu@635
    54
The current codebase is expected to build and run on the
tomh@3982
    55
set of platforms listed in the RELEASE_NOTES file.
mathieu@3653
    56
mathieu@3653
    57
Other platforms may or may not work: we welcome patches to 
mathieu@3653
    58
improve the portability of the code to these other platforms. 
mathieu@635
    59
tomh@3982
    60
3) Running ns-3
mathieu@635
    61
---------------
mathieu@635
    62
tomh@657
    63
On recent Linux systems, once you have built ns-3, it 
mathieu@635
    64
should be easy to run the sample programs with the
mathieu@635
    65
following command:
mathieu@635
    66
mathieu@2841
    67
./waf --run simple-global-routing
mathieu@635
    68
mathieu@2841
    69
That program should generate a simple-global-routing.tr text 
mathieu@2841
    70
trace file and a set of simple-global-routing-xx-xx.pcap binary
mathieu@2841
    71
pcap trace files, which can be read by tcpdump -tt -r filename.pcap
mathieu@635
    72
tomh@3982
    73
4) Getting access to the ns-3 documentation
mathieu@641
    74
-------------------------------------------
mathieu@641
    75
mathieu@641
    76
Once you have verified that your build of ns-3 works by running
tomh@1786
    77
the simple-point-to-point example as outlined in 4) above, it is
mathieu@641
    78
quite likely that you will want to get started on reading
mathieu@641
    79
some ns-3 documentation. 
mathieu@641
    80
mathieu@641
    81
All of that documentation should always be available from
mathieu@655
    82
the ns-3 website: http:://www.nsnam.org/ but we
mathieu@655
    83
include some of it in this release for ease of use.
mathieu@641
    84
mathieu@655
    85
This documentation includes:
mathieu@641
    86
tomh@2891
    87
  - a tutorial
tomh@3982
    88
 
tomh@3982
    89
  - a manual
mathieu@641
    90
mathieu@641
    91
  - a wiki for user-contributed tips: http://www.nsnam.org/wiki/
mathieu@641
    92
mathieu@641
    93
  - an API documentation generated using doxygen: this is
mathieu@641
    94
    a reference manual, most likely not very well suited 
mathieu@641
    95
    as introductory text:
mathieu@641
    96
    http://www.nsnam.org/doxygen/index.html
mathieu@641
    97
tomh@3982
    98
5) Working with the development version of ns-3
mathieu@635
    99
-----------------------------------------------
mathieu@635
   100
mathieu@635
   101
If you want to download and use the development version 
mathieu@635
   102
of ns-3, you need to use the tool 'mercurial'. A quick and
mathieu@635
   103
dirty cheat sheet is included in doc/mercurial.txt but
mathieu@635
   104
reading through the mercurial tutorials included on the
mathieu@635
   105
mercurial website is usually a good idea if you are not
mathieu@635
   106
familiar with it.
mathieu@635
   107
mathieu@635
   108
If you have successfully installed mercurial, you can get
tomh@697
   109
a copy of the development version with the following command:
tomh@657
   110
"hg clone http://code.nsnam.org/ns-3-dev"