# HG changeset patch # User Tom Henderson # Date 1179509262 25200 # Node ID be551a3b07c622f26dda6da2cec640870f4fd305 # Parent 01ccd5f47ed4286eab34aa1588b789a991132b66 minor changes due to documentation review diff -r 01ccd5f47ed4 -r be551a3b07c6 INSTALL --- a/INSTALL Fri May 18 18:06:00 2007 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,35 +0,0 @@ -ns-3.0.1 snapshot release, March 2007 - -1. Tested platforms: - -- Windows XP 32-bit Cygwin - -- Linux Fedora Core 5 x86 - -- OS X 10.4.7 or later with XCode 2.4 or later - -2. Prerequisites: - -- The SCons build system (http://www.scons.org) version 0.96.1 or later - -- gcc (version 3.4 or later) - -3. Installing into your current directory: - -tar xvfz ns-3.0.1.tar.gz -cd ns-3.0.1 -scons -cd build-dir/dbg-shared/bin/ -./simple-p2p - -The above steps will run a simple program whose source is found in -ns-3.0.1/examples/simple-p2p.cc -Some minimal trace output is found in simple-p2p.tr. - -Note: OS X users may need to set the following env. variable from -the bin/ directory above: -setenv DYLD_LIBRARY_PATH `pwd`/../lib - -4. For more information, read -ns-3.0.1-documentation.pdf - diff -r 01ccd5f47ed4 -r be551a3b07c6 README --- a/README Fri May 18 18:06:00 2007 +0200 +++ b/README Fri May 18 10:27:42 2007 -0700 @@ -1,9 +1,9 @@ - The Network Simulator Version 3 - ------------------------------- + The Network Simulator, Version 3 + -------------------------------- -Table of Content: ------------------ +Table of Contents: +------------------ 1) An Open Source project 2) An overview of the ns-3 project @@ -16,7 +16,7 @@ 1) An Open Source project ------------------------- -ns-3 is an Open Source project and we intend to make this +ns-3 is an Open Source project. 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 @@ -25,11 +25,11 @@ 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. +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 +project. These steps are described in doc/contributing.txt 2) An overview of the ns-3 project ---------------------------------- @@ -42,8 +42,9 @@ - point-to-point physical-layer links - OnOff traffic generator -However, the framework is there to make adding new models as -simple as possible: +Our focus to date has been on getting an overall software +framework in place. 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 @@ -65,7 +66,7 @@ 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 +are expected to be written as simple programs that make use of these ns-3 libraries. To build the set of default libraries and the example @@ -92,14 +93,14 @@ - gcc 3.3 and earlier - optimized builds on linux x86 gcc 4.0 -Other platforms might or might not work: we welcome +Other platforms may or may 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 +On recent Linux systems, once you have built ns-3, it should be easy to run the sample programs with the following command: @@ -112,7 +113,7 @@ That program should generate a simple-p2p.tr text trace file and a set of simple-p2p-xx-xx.pcap binary -pcap trace files. +pcap trace files, which can be read by tcpdump. 5) Getting access to the ns-3 documentation ------------------------------------------- @@ -166,4 +167,4 @@ 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 +"hg clone http://code.nsnam.org/ns-3-dev" diff -r 01ccd5f47ed4 -r be551a3b07c6 RELEASE_NOTES --- a/RELEASE_NOTES Fri May 18 18:06:00 2007 +0200 +++ b/RELEASE_NOTES Fri May 18 10:27:42 2007 -0700 @@ -1,9 +1,9 @@ ns-3 RELEASE NOTES -This file contains ns-3 release notes (most recent releases first). +This file contains ns-3 release notes (most recent releases first). -Release 0.2 (2007/05/XX) +Release 3.0.2 (2007/05/18) ======================== - Implement a new memory management infrastructure based @@ -15,7 +15,7 @@ - Add support for a BSD-style socket API for user applications -Release 0.1 (2007/03/31) +Release 3.0.1 (2007/03/31) ======================== - First public release; not yet pre-alpha. diff -r 01ccd5f47ed4 -r be551a3b07c6 VERSION --- a/VERSION Fri May 18 18:06:00 2007 +0200 +++ b/VERSION Fri May 18 10:27:42 2007 -0700 @@ -1,1 +1,1 @@ -3.0.1 +3.0.2 diff -r 01ccd5f47ed4 -r be551a3b07c6 doc/build-waf.txt --- a/doc/build-waf.txt Fri May 18 18:06:00 2007 +0200 +++ b/doc/build-waf.txt Fri May 18 10:27:42 2007 -0700 @@ -1,12 +1,17 @@ -WAF is an alternative build system, similar to SCons. NS-3 now is -able to build with WAF, in parallel to SCons. +The main ns-3 build system is SCons. Read the file build.txt +for SCons instructions. -Note: the WAF build scripts are experimental at this stage. +Waf is an alternative build system, similar to SCons. ns-3 now is +able to build with Waf, in parallel to SCons. +(http://www.freehackers.org/~tnagy/waf.html) -=== Building with WAF === +Note: the Waf build scripts are experimental at this stage. +Gustavo Carneiro (gjcarneiro@gmail.com) is the maintainer. -To build NS-3 with waf type the commands: +=== Building with Waf === + +To build ns-3 with waf type the commands: 1. ./waf configure [options] 2. ./waf @@ -30,7 +35,7 @@ Run code coverage analysis (assuming the project was configured with --enable-gcov) -=== Extending NS-3 === +=== Extending ns-3 === To add new modules: 1. Create the module directory under src (or src/devices, or whatever); @@ -38,7 +43,7 @@ 3. Add a 'wscript' describing it; 4. Add the module subdirectory name to the all_modules list in src/wscript. -A module's wscript file is basically a regular WAF script. A NS-3 +A module's wscript file is basically a regular Waf script. A ns-3 module is created as a cpp/shlib object, like this: def build(bld): @@ -65,7 +70,7 @@ === Note for developers === -The NS-3 code repository does not contain the waf script. Instead, +The ns-3 code repository does not contain the waf script. Instead, developers should check it out from a subversion repository: svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf @@ -77,8 +82,8 @@ Then it can be installed system-wide with 'sudo ./waf-light install'. When preparing a distribution, the resulting 'waf' script, which is self contained (no external files needed), can be easily included in -the tarball so that users downloading NS-3 can easily build it without -having WAF installed (although Python >= 2.3 is still needed). +the tarball so that users downloading ns-3 can easily build it without +having Waf installed (although Python >= 2.3 is still needed). The command 'waf dist' can be used to create a distribution tarball. It includes all files in the source directory, except some particular diff -r 01ccd5f47ed4 -r be551a3b07c6 doc/build.txt --- a/doc/build.txt Fri May 18 18:06:00 2007 +0200 +++ b/doc/build.txt Fri May 18 10:27:42 2007 -0700 @@ -16,6 +16,9 @@ the right libraries. This saves you the pain of having to setup environment variables to point to the right libraries. +(Note: An experimental, alternative build system is described +in build-waf.txt) + 1) Options ---------- diff -r 01ccd5f47ed4 -r be551a3b07c6 doc/codingstd.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/codingstd.txt Fri May 18 10:27:42 2007 -0700 @@ -0,0 +1,210 @@ + The Ns-3 Coding Style + +/* + * Note: This file is incomplete and will be converted to non-text (html,pdf) + * formats at a future date + */ + +1) Code layout + ----------- + +The code layout follows the GNU coding standard layout for C and extends +it to C++. Do not use tabs for indentation. Indentation spacing is 2 +spaces as outlined below: + +void +Foo (void) +{ + if (test) + { + // do stuff here + } + else + { + // do other stuff here + } + + for (int i = 0; i < 100; i++) + { + // do loop + } + + while (test) + { + // do while + } + + do + { + // do stuff + } while (); +} + +The following is not recommended: + +if (test) statement + +if (test) + statement + +for (...) statement + +Each statement should be put on a separate line to increase readability. +Short one-line comments can use the C++ comment style, that is, '//' +but longer comments should use C-style comments: +/* + * + * + */ + + +2) Naming Patterns + --------------- + +2.1) Name encoding + ------------- +Function, Method, and Type names should follow the CamelCase convention: +words are joined without spaces and are capitalized. For example, +"my computer" is transformed into MyComputer. Do not use all capital +letters such as MAC or, PHY, but choose instead Mac or Phy. Do not use +all capital letters, even for acronyms such as EDCA: use Edca instead. +The goal of the CamelCase convention is to ensure that the words which +make up a name can be separated by the eye: the initial Caps fills +that role. + +Variable names should follow a slight variation on the base CamelCase +convention: camelBack. For example, the variable "user name" would be +named "userName". This variation on the basic naming pattern is used to +allow a reader to distinguish a variable name from its type. For example, +"UserName userName;" would be used to declare a variable named userName +of type UserName. + +Global variables should be prefixed with a "g_" and member variables +(including static member variables) should be prefixed with a "m_". The +goal of that prefix is to give a reader a sense of where a variable of +a given name is declared to allow the reader to locate the variable +declaration and infer the variable type from that declaration. For example +you could declare in your class header my-class.h: + +class MyClass +{ + void MyMethod (int aVar); + int m_aVar; + static int m_anotherVar; +}; + +and implement in your class file my-class.cc: + +int MyClass::m_anotherVar = 10; +static int g_aStaticVar = 100; +int g_aGlobalVar = 1000; + +void +MyClass::MyMethod (int aVar) +{ + m_aVar = aVar; +} + +2.2) Choosing names + +Variable, function, method, and type names should be based on the +english language. Furthermore, always try to choose descriptive +names for them. Types are often english names such as: Packet, +Buffer, Mac, or Phy. Functions and Methods are often named +based on verbs and adjectives: GetX, DoDispose, ClearArray, etc. + +A long descriptive name which requires a lot of typing is always +better than a short name which is hard to decipher. Do not use +abbreviations in names unless the abbreviation is really unambiguous +and obvious to everyone. Do not use short inapropriate names such +as foo, bar, or baz. The name of an item should always match its +purpose. As such, names such as tmp to identify a temporary +variable or such as 'i' to identify a loop index are ok. + +3) File layout and code organization + --------------------------------- + +A class named MyClass should be declared in a header named my-class.h +and implemented in a source file named my-class.cc. The goal of this +naming pattern is to allow a reader to quickly navigate through +the ns-3 codebase to locate the source file relevant to a specific +type. + +Each my-class.h header should start with the following comments: the +first line ensures that developers who use the emacs editor will be +able to indent your code correctly. The following lines ensure that +your code is licensed under the GPL, that the copyright holders +are properly identified (typically, you or your employer), and +that the actual author of the code is identified. The latter is +purely informational and we use it to try to track the most +appropriate person to review a patch or fix a bug. + +/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ +/* + * Copyright (c) YEAR COPYRIGHTHOLDER + * + * 3-paragran GPL blurb + * + * Author: MyName + */ + +Below these C-style comments, always include the following which +defines a set of header guards (MY_CLASS_H) used to avoid multiple +header includes, which ensures that your code is included +in the "ns3" namespace and which provides a set of doxygen comments +for the public part of your class API. Detailed information +on the set of tags available for doxygen documentation is described +in the doxygen website: http://www.doxygen.org. + +#ifndef MY_CLASS_H +#define MY_CLASS_H + +namespace n3 { + +/** + * \brief short one-line description of the purpose of your class + * + * A longer description of the purpose of your class after a blank + * empty line. + */ +class MyClass +{ +public: + MyClass (); + /** + * \param firstParam a short description of the purpose of this parameter + * \returns a short description of what is returned from this function. + * + * A detailed description of the purpose of the method. + */ + int DoFoo (int firstParam); +private: + void MyPrivateMethod (void); + int m_myPrivateMemberVariable; +}; + +} // namespace ns3 + +#endif /* MY_CLASS_H */ + +The my-class.cc file is structured similarly: + +/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ +/* + * Copyright (c) YEAR COPYRIGHTHOLDER + * + * 3-paragran GPL blurb + * + * Author: MyName + */ +#include "my-class.h" + +namespace ns3 { + +MyClass::MyClass () +{} + +... + +} // namespace ns3 + diff -r 01ccd5f47ed4 -r be551a3b07c6 doc/contributing.txt --- a/doc/contributing.txt Fri May 18 18:06:00 2007 +0200 +++ b/doc/contributing.txt Fri May 18 10:27:42 2007 -0700 @@ -1,7 +1,13 @@ - Contributing to the ns-3 project -------------------------------- +ns-3 is an open source project backed by an NSF CISE CRI grant. +Although the NSF PIs have specific aims to fulfill, we want others to +contribute, and we'd like to have a broad community of users and +developers, with the goal of a self-sustaining project downstream. +The project is currently in a bootstrapping phase, but we welcome +ambitious developers who might want to help shape the early design. + 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 @@ -46,8 +52,12 @@ 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: + - The project has decided upon GNU GPLv2 as the licensing structure. + All simulation software in the ns-3 repositories will be GNU GPLv2 + or GNU GPLv2-compatible (with non-GPLv2 licensing reserved for + ports of pre-existing code under a different license, such as BSD). + You do not have to assign your copyright to the ns-3 project but + you must accept the terms of the GPLv2 and attest that your + contributions can be licensed under those terms. See the + following link: http://www.fsf.org/licensing/licenses/info/GPLv2.html diff -r 01ccd5f47ed4 -r be551a3b07c6 doc/mercurial.txt --- a/doc/mercurial.txt Fri May 18 18:06:00 2007 +0200 +++ b/doc/mercurial.txt Fri May 18 10:27:42 2007 -0700 @@ -3,7 +3,7 @@ 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 +access to the development versions of ns-3, you need to install mercurial first. See http://www.selenic.com/mercurial/wiki/ Mercurial cheat sheet @@ -38,6 +38,7 @@ -------------------------------------- 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