From 12ed9958e57734511d83e7ec23c960312a921e3d Mon Sep 17 00:00:00 2001 From: Mathieu Lacage Date: Thu, 17 May 2007 11:32:22 +0200 Subject: [PATCH] write README, contributing.txt, reorganize the other documentation files --- README | 145 +++++++++++++++++++++++++++------ RELEASE_NOTES | 12 +++ BUILD.WAF => doc/build-waf.txt | 0 BUILD => doc/build.txt | 0 doc/contributing.txt | 53 ++++++++++++ doc/mercurial.txt | 44 ++++++++++ 6 files changed, 230 insertions(+), 24 deletions(-) rename BUILD.WAF => doc/build-waf.txt (100%) rename BUILD => doc/build.txt (100%) create mode 100644 doc/contributing.txt create mode 100644 doc/mercurial.txt diff --git a/README b/README index 28f63b163..75a51d801 100644 --- a/README +++ b/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 -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 +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" \ No newline at end of file diff --git a/RELEASE_NOTES b/RELEASE_NOTES index 089923f16..5e0c28ee7 100644 --- a/RELEASE_NOTES +++ b/RELEASE_NOTES @@ -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) ======================== diff --git a/BUILD.WAF b/doc/build-waf.txt similarity index 100% rename from BUILD.WAF rename to doc/build-waf.txt diff --git a/BUILD b/doc/build.txt similarity index 100% rename from BUILD rename to doc/build.txt diff --git a/doc/contributing.txt b/doc/contributing.txt new file mode 100644 index 000000000..f0a8b7b83 --- /dev/null +++ b/doc/contributing.txt @@ -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 diff --git a/doc/mercurial.txt b/doc/mercurial.txt new file mode 100644 index 000000000..5e6f8cb4a --- /dev/null +++ b/doc/mercurial.txt @@ -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 +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 + +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 + +