From 234aafe368b71316eb021a7be47d920d7150ccf3 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Fri, 18 May 2007 10:27:42 -0700 Subject: [PATCH] minor changes due to documentation review --- INSTALL | 35 -------- README | 29 +++--- RELEASE_NOTES | 6 +- VERSION | 2 +- doc/build-waf.txt | 25 +++--- doc/build.txt | 3 + doc/codingstd.txt | 210 +++++++++++++++++++++++++++++++++++++++++++ doc/contributing.txt | 20 +++-- doc/mercurial.txt | 3 +- 9 files changed, 264 insertions(+), 69 deletions(-) delete mode 100644 INSTALL create mode 100644 doc/codingstd.txt diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 36b34f92d..000000000 --- a/INSTALL +++ /dev/null @@ -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 --git a/README b/README index 91ac01939..1443c2df7 100644 --- a/README +++ b/README @@ -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 @@ Table of Content: 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 @@ process. 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 @@ number of very simple network simulation models: - 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 @@ simple as possible: 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 @@ 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 +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 @@ cd build-dir/dbg-shared/bin 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 @@ 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 +"hg clone http://code.nsnam.org/ns-3-dev" diff --git a/RELEASE_NOTES b/RELEASE_NOTES index 5e0c28ee7..8e02e3ee2 100644 --- a/RELEASE_NOTES +++ b/RELEASE_NOTES @@ -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 @@ Release 0.2 (2007/05/XX) - 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 --git a/VERSION b/VERSION index cb2b00e4f..b50214693 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -3.0.1 +3.0.2 diff --git a/doc/build-waf.txt b/doc/build-waf.txt index a560b3bff..0327f41db 100644 --- a/doc/build-waf.txt +++ b/doc/build-waf.txt @@ -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 @@ Other waf usages include: 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 @@ To add new modules: 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 @@ def build(bld): === 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 @@ tested to work correctly with ns3, although 'trunk' will likely work 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 --git a/doc/build.txt b/doc/build.txt index 4cf112c0e..b23be1e5d 100644 --- a/doc/build.txt +++ b/doc/build.txt @@ -16,6 +16,9 @@ the executable binaries generated link explicitely against 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 --git a/doc/codingstd.txt b/doc/codingstd.txt new file mode 100644 index 000000000..6369035e9 --- /dev/null +++ b/doc/codingstd.txt @@ -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 --git a/doc/contributing.txt b/doc/contributing.txt index f0a8b7b83..13da6989d 100644 --- a/doc/contributing.txt +++ b/doc/contributing.txt @@ -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 @@ the open-source roots of the project: 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 --git a/doc/mercurial.txt b/doc/mercurial.txt index 5e6f8cb4a..fefc88f39 100644 --- a/doc/mercurial.txt +++ b/doc/mercurial.txt @@ -3,7 +3,7 @@ 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 +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 @@ 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