README
author Tom Henderson <tomh@tomh.org>
Fri, 18 May 2007 10:27:42 -0700
changeset 657 be551a3b07c6
parent 655 f2ee52034178
child 663 48c05ee9fb6a
permissions -rw-r--r--
minor changes due to documentation review
tomh@421
     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
mathieu@635
     8
1) An Open Source project
mathieu@635
     9
2) An overview of the ns-3 project
mathieu@635
    10
3) Building ns-3
mathieu@635
    11
4) Running ns-3
mathieu@641
    12
5) Getting access to the ns-3 documentation
mathieu@641
    13
6) Working with the development version of ns-3
raj@217
    14
tomh@263
    15
mathieu@635
    16
1) An Open Source project
mathieu@635
    17
-------------------------
tomh@263
    18
tomh@657
    19
ns-3 is an Open Source project.   We intend to make this
mathieu@635
    20
project a successful collaborative project: we hope that 
mathieu@635
    21
the missing pieces of the models we have not yet implemented
mathieu@635
    22
will be contributed by the community in an open collaboration
mathieu@635
    23
process.
tomh@263
    24
mathieu@635
    25
Contributing to the ns-3 project is still a very informal
mathieu@635
    26
process because that process depends heavily on the personality
mathieu@635
    27
of the people involved, the amount of time they can invest
tomh@657
    28
and the type of model they want to work on.  
tomh@314
    29
mathieu@635
    30
Despite this lack of a formal process, there are a number of 
mathieu@635
    31
steps which naturally stem from the open-source roots of the
tomh@657
    32
project.  These steps are described in doc/contributing.txt
mathieu@635
    33
mathieu@635
    34
2) An overview of the ns-3 project
mathieu@635
    35
----------------------------------
mathieu@635
    36
mathieu@635
    37
This package contains the latest version of ns-3 which is aims 
mathieu@635
    38
at being a replacement for ns-2. Currently, ns-3 provides a 
mathieu@635
    39
number of very simple network simulation models:
mathieu@635
    40
  - an ipv4 and udp stack
mathieu@635
    41
  - arp support at the bottom of the stack
mathieu@635
    42
  - point-to-point physical-layer links
mathieu@635
    43
  - OnOff traffic generator
mathieu@635
    44
tomh@657
    45
Our focus to date has been on getting an overall software
tomh@657
    46
framework in place.  The framework is there to make adding 
tomh@657
    47
new models as simple as possible:
mathieu@635
    48
  - an extensive tracing system can be used to connect
mathieu@635
    49
    any number of arbitrary trace sources to any number
mathieu@635
    50
    of trace sinks. This tracing system is decoupled
mathieu@635
    51
    from the act of serializing the trace events to a 
mathieu@635
    52
    file: users can and should provide their own
mathieu@635
    53
    trace handling routines.
mathieu@635
    54
mathieu@635
    55
  - simple file trace serialization support is included
mathieu@635
    56
    to both text and pcap files.
mathieu@635
    57
mathieu@635
    58
  - adding new MAC-level models simply requires subclassing
mathieu@635
    59
    the pair of classes NetDevice and Channel.
mathieu@635
    60
mathieu@635
    61
  - adding new traffic generation algorithms is also very 
mathieu@635
    62
    simple through the Application and the Socket classes.
mathieu@635
    63
mathieu@635
    64
3) Building ns-3
mathieu@635
    65
----------------
mathieu@635
    66
mathieu@635
    67
The code for the framework and the default models provided
mathieu@635
    68
by ns-3 is built as a set of libraries. User simulations
tomh@657
    69
are expected to be written as simple programs that make
mathieu@635
    70
use of these ns-3 libraries.
mathieu@635
    71
mathieu@635
    72
To build the set of default libraries and the example
mathieu@635
    73
programs included in this package, you need to use the
mathieu@635
    74
tool 'scons'. Detailed information on how to install
mathieu@635
    75
and use scons is included in the file doc/build.txt
mathieu@635
    76
mathieu@635
    77
However, the real quick and dirty way to get started is to
mathieu@635
    78
type the command "scons" the the directory which contains
mathieu@635
    79
this README file. The files built will be copied in the
mathieu@635
    80
build-dir/dbg-shared/bin and build-dir/dbg-shared/lib
mathieu@635
    81
directories. build-dir/dbg-shared/bin will contain
mathieu@635
    82
one binary for each of the sample code in the 'samples'
mathieu@635
    83
directory and one binary for each of the detailed examples
mathieu@635
    84
found in the 'examples' directory.
mathieu@635
    85
mathieu@635
    86
The current codebase is expected to build and run on the
mathieu@635
    87
following set of platforms:
mathieu@643
    88
  - linux x86 gcc 4.2, 4.1, and, 3.4.
mathieu@635
    89
  - MacOS X ppc and x86
mathieu@635
    90
mathieu@635
    91
The current codebase is expected to fail to build on
mathieu@635
    92
the following platforms:
mathieu@635
    93
  - gcc 3.3 and earlier
mathieu@635
    94
  - optimized builds on linux x86 gcc 4.0 
mathieu@635
    95
tomh@657
    96
Other platforms may or may not work: we welcome 
mathieu@635
    97
patches to improve the portability of the code to these
mathieu@635
    98
other platforms.
mathieu@635
    99
mathieu@635
   100
4) Running ns-3
mathieu@635
   101
---------------
mathieu@635
   102
tomh@657
   103
On recent Linux systems, once you have built ns-3, it 
mathieu@635
   104
should be easy to run the sample programs with the
mathieu@635
   105
following command:
mathieu@635
   106
mathieu@635
   107
./build-dir/dbg-shared/bin/simple-p2p
mathieu@635
   108
mathieu@635
   109
or:
mathieu@635
   110
mathieu@635
   111
cd build-dir/dbg-shared/bin
mathieu@635
   112
./simple-p2p
mathieu@635
   113
mathieu@635
   114
That program should generate a simple-p2p.tr text 
mathieu@635
   115
trace file and a set of simple-p2p-xx-xx.pcap binary
tomh@657
   116
pcap trace files, which can be read by tcpdump.
mathieu@635
   117
mathieu@641
   118
5) Getting access to the ns-3 documentation
mathieu@641
   119
-------------------------------------------
mathieu@641
   120
mathieu@641
   121
Once you have verified that your build of ns-3 works by running
mathieu@641
   122
the simple-p2p example as outlined in 4) above, it is
mathieu@641
   123
quite likely that you will want to get started on reading
mathieu@641
   124
some ns-3 documentation. 
mathieu@641
   125
mathieu@641
   126
All of that documentation should always be available from
mathieu@655
   127
the ns-3 website: http:://www.nsnam.org/ but we
mathieu@655
   128
include some of it in this release for ease of use.
mathieu@641
   129
mathieu@655
   130
This documentation includes:
mathieu@641
   131
mathieu@641
   132
  - an architecture document which describes a very 
mathieu@641
   133
    high-level view of ns-3: it tries to explain the
mathieu@641
   134
    use-cases the ns-3 developers really focused on when
mathieu@641
   135
    doing the initial design and then goes on to explain
mathieu@641
   136
    the structure of the resulting framework.
mathieu@655
   137
    See the file doc/architecture.pdf
mathieu@641
   138
mathieu@641
   139
  - a wiki for user-contributed tips: http://www.nsnam.org/wiki/
mathieu@641
   140
mathieu@641
   141
  - an API documentation generated using doxygen: this is
mathieu@641
   142
    a reference manual, most likely not very well suited 
mathieu@641
   143
    as introductory text:
mathieu@641
   144
    http://www.nsnam.org/doxygen/index.html
mathieu@641
   145
mathieu@655
   146
If you want to re-generate this documentation, you can 
mathieu@655
   147
easily do so:
mathieu@655
   148
mathieu@655
   149
  - doc/architecture.pdf is generated from the architecture.tex
mathieu@655
   150
    file in http://code.nsnam.org/docs
mathieu@655
   151
mathieu@655
   152
  - the doxygen documentation is generated from the doc/doxygen.conf
mathieu@655
   153
    configuration file. The command "scons doc" will generate it
mathieu@655
   154
    as doc/html/index.html if you have installed the doxygen tools 
mathieu@655
   155
    (see http://www.doxygen.org)
mathieu@655
   156
mathieu@641
   157
6) Working with the development version of ns-3
mathieu@635
   158
-----------------------------------------------
mathieu@635
   159
mathieu@635
   160
If you want to download and use the development version 
mathieu@635
   161
of ns-3, you need to use the tool 'mercurial'. A quick and
mathieu@635
   162
dirty cheat sheet is included in doc/mercurial.txt but
mathieu@635
   163
reading through the mercurial tutorials included on the
mathieu@635
   164
mercurial website is usually a good idea if you are not
mathieu@635
   165
familiar with it.
mathieu@635
   166
mathieu@635
   167
If you have successfully installed mercurial, you can get
mathieu@635
   168
a copy of the development version with the following
mathieu@635
   169
command:
tomh@657
   170
"hg clone http://code.nsnam.org/ns-3-dev"