write README, contributing.txt, reorganize the other documentation files
Mathieu Lacage
parent
58f1af736e
commit
12ed9958e5
145
README
145
README
|
|
@ -1,32 +1,129 @@
|
|||
ns-3 uses the Mercurial software revision control system
|
||||
|
||||
Mercurial cheat sheet
|
||||
The Network Simulator Version 3
|
||||
-------------------------------
|
||||
|
||||
clone this repository:
|
||||
----------------------
|
||||
hg clone http://code.nsnam.org/ns-3-dev
|
||||
Table of Content:
|
||||
-----------------
|
||||
|
||||
pull development tree changes to your local repository:
|
||||
------------------------------------------------------
|
||||
hg pull http://code.nsnam.org/ns-3-dev
|
||||
hg update (apply the changes) OR
|
||||
hg merge (if you've made local changes)
|
||||
1) An Open Source project
|
||||
2) An overview of the ns-3 project
|
||||
3) Building ns-3
|
||||
4) Running ns-3
|
||||
5) Working with the development version of ns-3
|
||||
|
||||
commit locally:
|
||||
--------------
|
||||
hg status
|
||||
hg add <new files, if any>
|
||||
hg ci -m "message"
|
||||
|
||||
push upwards (developers access only):
|
||||
--------------------------------------
|
||||
hg push ssh://code@code.nsnam.org//home/code/repos/ns-3-dev
|
||||
1) An Open Source project
|
||||
-------------------------
|
||||
|
||||
view the change log:
|
||||
--------------
|
||||
hg log <file>
|
||||
ns-3 is an Open Source project and we intend to make this
|
||||
project a successful 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.
|
||||
|
||||
doing a scons make clean:
|
||||
------------------------
|
||||
scons -c
|
||||
Contributing to the ns-3 project is still a very informal
|
||||
process because that process depends heavily on the personality
|
||||
of the people involved, the amount of time they can invest
|
||||
and the type of model they want to work on.
|
||||
|
||||
Despite this lack of a formal process, there are a number of
|
||||
steps which naturally stem from the open-source roots of the
|
||||
project. These steps are described in doc/contributing.txt
|
||||
|
||||
2) An overview of the ns-3 project
|
||||
----------------------------------
|
||||
|
||||
This package contains the latest version of ns-3 which is aims
|
||||
at being a replacement for ns-2. Currently, ns-3 provides a
|
||||
number of very simple network simulation models:
|
||||
- an ipv4 and udp stack
|
||||
- arp support at the bottom of the stack
|
||||
- point-to-point physical-layer links
|
||||
- OnOff traffic generator
|
||||
|
||||
However, the framework is there to make adding new models as
|
||||
simple as possible:
|
||||
- an extensive tracing system can be used to connect
|
||||
any number of arbitrary trace sources to any number
|
||||
of trace sinks. This tracing system is decoupled
|
||||
from the act of serializing the trace events to a
|
||||
file: users can and should provide their own
|
||||
trace handling routines.
|
||||
|
||||
- simple file trace serialization support is included
|
||||
to both text and pcap files.
|
||||
|
||||
- adding new MAC-level models simply requires subclassing
|
||||
the pair of classes NetDevice and Channel.
|
||||
|
||||
- adding new traffic generation algorithms is also very
|
||||
simple through the Application and the Socket classes.
|
||||
|
||||
3) Building ns-3
|
||||
----------------
|
||||
|
||||
The code for the framework and the default models provided
|
||||
by ns-3 is built as a set of libraries. User simulations
|
||||
are expected to be written as simple programs which make
|
||||
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 'scons'. Detailed information on how to install
|
||||
and use scons is included in the file doc/build.txt
|
||||
|
||||
However, the real quick and dirty way to get started is to
|
||||
type the command "scons" the the directory which contains
|
||||
this README file. The files built will be copied in the
|
||||
build-dir/dbg-shared/bin and build-dir/dbg-shared/lib
|
||||
directories. build-dir/dbg-shared/bin will contain
|
||||
one binary for each of the sample code in the 'samples'
|
||||
directory and one binary for each of the detailed examples
|
||||
found in the 'examples' directory.
|
||||
|
||||
The current codebase is expected to build and run on the
|
||||
following set of platforms:
|
||||
- linux x86 gcc 4.1, gcc 3.4.
|
||||
- MacOS X ppc and x86
|
||||
|
||||
The current codebase is expected to fail to build on
|
||||
the following platforms:
|
||||
- gcc 3.3 and earlier
|
||||
- optimized builds on linux x86 gcc 4.0
|
||||
|
||||
Other platforms might or might not work: we welcome
|
||||
patches to improve the portability of the code to these
|
||||
other platforms.
|
||||
|
||||
4) Running ns-3
|
||||
---------------
|
||||
|
||||
On Recent Linux systems, once you have built ns-3, it
|
||||
should be easy to run the sample programs with the
|
||||
following command:
|
||||
|
||||
./build-dir/dbg-shared/bin/simple-p2p
|
||||
|
||||
or:
|
||||
|
||||
cd build-dir/dbg-shared/bin
|
||||
./simple-p2p
|
||||
|
||||
That program should generate a simple-p2p.tr text
|
||||
trace file and a set of simple-p2p-xx-xx.pcap binary
|
||||
pcap trace files.
|
||||
|
||||
5) 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 'mercurial'. A quick and
|
||||
dirty cheat sheet is included in doc/mercurial.txt but
|
||||
reading through the mercurial tutorials included on the
|
||||
mercurial website is usually a good idea if you are not
|
||||
familiar with it.
|
||||
|
||||
If you have successfully installed mercurial, you can get
|
||||
a copy of the development version with the following
|
||||
command:
|
||||
"hg clone http://code.nsnam.org/ns-3-dev"
|
||||
|
|
@ -3,6 +3,18 @@
|
|||
|
||||
This file contains ns-3 release notes (most recent releases first).
|
||||
|
||||
Release 0.2 (2007/05/XX)
|
||||
========================
|
||||
|
||||
- Implement a new memory management infrastructure based
|
||||
on reference counting and smart pointers (the latter being
|
||||
optional)
|
||||
|
||||
- Implement a COM-like framework with support for QueryInterface
|
||||
to provide object extensibility
|
||||
|
||||
- Add support for a BSD-style socket API for user applications
|
||||
|
||||
Release 0.1 (2007/03/31)
|
||||
========================
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,53 @@
|
|||
|
||||
Contributing to the ns-3 project
|
||||
--------------------------------
|
||||
|
||||
Despite the lack of a formal contribution process to the ns-3
|
||||
project, there are a number of steps which we expect every
|
||||
potential contributor to follow. These naturally stem from
|
||||
the open-source roots of the project:
|
||||
|
||||
- first, you should subscribe to the ns-developers
|
||||
mailing-list (see http://www.nsnam.org/mailing_lists.html)
|
||||
|
||||
- then, you should send an email there stating your interest
|
||||
in working on a specific part of the models and trying
|
||||
to explain how you would like to implement it, what
|
||||
resources you have, etc.
|
||||
|
||||
- you should be prepared to work together with the other
|
||||
potential contributors who want to work on the same models.
|
||||
|
||||
- you should be prepared to go through code reviews with the
|
||||
ns-3 development team prior to integration. The goal of these
|
||||
code reviews is to:
|
||||
- ensure adherence to the coding style of the project
|
||||
(see doc/codingstyle.html)
|
||||
- ensure that the structure of your code has a certain
|
||||
coherence with regard to the rest of the ns-3 codebase
|
||||
- improve the quality of the code: we strongly believe in
|
||||
the old saying: "many eyes make all bugs shallow".
|
||||
- increase code reuse by trying to generalize certain
|
||||
useful pieces of your code to make them available to
|
||||
other models.
|
||||
|
||||
- you should be prepared to try to integrate as many tests
|
||||
in the codebase as possible: we understand that writing
|
||||
tests is not sexy and that not everyone is convinced that
|
||||
they improve the code-writing poductivity which is why
|
||||
we do not enforce strict rules about testing. However,
|
||||
we expect model authors to answer basic questions about
|
||||
how they plan to test and validate their models.
|
||||
|
||||
- you should be prepared to maintain your model once it is
|
||||
integrated: while we consider every bug filed against the
|
||||
simulator as being a bug we must deal with and while we
|
||||
will try to fix as many bugs as humanly possible, we
|
||||
also expect model authors to act as responsible maintainers
|
||||
and be reactive to bug reports concerning their models.
|
||||
|
||||
- you should make sure that you understand that contributed
|
||||
models should be licensed under the GPLv2. You do not have
|
||||
to assign your copyright to the ns-3 project but you must
|
||||
accept the terms of the GPLv2. See the following link:
|
||||
http://www.fsf.org/licensing/licenses/info/GPLv2.html
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
Introduction
|
||||
------------
|
||||
|
||||
ns-3 uses the Mercurial software revision control system which
|
||||
is a replacement for tools liks cvs or subversion. Thus, to get
|
||||
access to the developement versions of ns-3, you need to install
|
||||
mercurial first. See http://www.selenic.com/mercurial/wiki/
|
||||
|
||||
Mercurial cheat sheet
|
||||
---------------------
|
||||
|
||||
Look at our project history and source code:
|
||||
-------------------------------------------
|
||||
http://code.nsnam.org/ns-3-dev
|
||||
|
||||
clone this repository:
|
||||
---------------------
|
||||
hg clone http://code.nsnam.org/ns-3-dev
|
||||
|
||||
commit locally:
|
||||
--------------
|
||||
hg status
|
||||
hg add <new files, if any>
|
||||
hg ci -m "message"
|
||||
|
||||
pull development tree changes to your local repository:
|
||||
------------------------------------------------------
|
||||
hg ci -m "my local changes are recorded"
|
||||
hg pull http://code.nsnam.org/ns-3-dev
|
||||
hg update (apply the changes) OR
|
||||
hg merge (if you've made local changes)
|
||||
|
||||
view the change log:
|
||||
-------------------
|
||||
hg log <file>
|
||||
|
||||
push upwards (developers access only):
|
||||
--------------------------------------
|
||||
To the main repository:
|
||||
hg push ssh://code@code.nsnam.org/repos/ns-3-dev
|
||||
To your private repository:
|
||||
hg push ssh://username@code.nsnam.org//home/username/repositories/username/repository
|
||||
|
||||
|
||||
Loading…
Reference in New Issue