minor changes due to documentation review
authorTom Henderson <tomh@tomh.org>
Fri, 18 May 2007 10:27:42 -0700
changeset 657be551a3b07c6
parent 656 01ccd5f47ed4
child 658 32307a281d86
minor changes due to documentation review
INSTALL
README
RELEASE_NOTES
VERSION
doc/build-waf.txt
doc/build.txt
doc/codingstd.txt
doc/contributing.txt
doc/mercurial.txt
     1.1 --- a/INSTALL	Fri May 18 18:06:00 2007 +0200
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,35 +0,0 @@
     1.4 -ns-3.0.1 snapshot release, March 2007
     1.5 -
     1.6 -1.  Tested platforms:
     1.7 -
     1.8 -- Windows XP 32-bit Cygwin
     1.9 -
    1.10 -- Linux Fedora Core 5 x86
    1.11 -
    1.12 -- OS X 10.4.7 or later with XCode 2.4 or later 
    1.13 -
    1.14 -2.  Prerequisites:
    1.15 -
    1.16 -- The SCons build system (http://www.scons.org) version 0.96.1 or later
    1.17 -
    1.18 -- gcc (version 3.4 or later)
    1.19 -
    1.20 -3.  Installing into your current directory:
    1.21 -
    1.22 -tar xvfz ns-3.0.1.tar.gz
    1.23 -cd ns-3.0.1
    1.24 -scons
    1.25 -cd build-dir/dbg-shared/bin/
    1.26 -./simple-p2p
    1.27 -
    1.28 -The above steps will run a simple program whose source is found in
    1.29 -ns-3.0.1/examples/simple-p2p.cc
    1.30 -Some minimal trace output is found in simple-p2p.tr.
    1.31 -
    1.32 -Note:  OS X users may need to set the following env. variable from
    1.33 -the bin/ directory above:
    1.34 -setenv DYLD_LIBRARY_PATH `pwd`/../lib
    1.35 -
    1.36 -4.  For more information, read
    1.37 -ns-3.0.1-documentation.pdf
    1.38 - 
     2.1 --- a/README	Fri May 18 18:06:00 2007 +0200
     2.2 +++ b/README	Fri May 18 10:27:42 2007 -0700
     2.3 @@ -1,9 +1,9 @@
     2.4  
     2.5 -    The Network Simulator Version 3
     2.6 -    -------------------------------
     2.7 +    The Network Simulator, Version 3
     2.8 +    --------------------------------
     2.9  
    2.10 -Table of Content:
    2.11 ------------------
    2.12 +Table of Contents:
    2.13 +------------------
    2.14  
    2.15  1) An Open Source project
    2.16  2) An overview of the ns-3 project
    2.17 @@ -16,7 +16,7 @@
    2.18  1) An Open Source project
    2.19  -------------------------
    2.20  
    2.21 -ns-3 is an Open Source project and we intend to make this
    2.22 +ns-3 is an Open Source project.   We intend to make this
    2.23  project a successful collaborative project: we hope that 
    2.24  the missing pieces of the models we have not yet implemented
    2.25  will be contributed by the community in an open collaboration
    2.26 @@ -25,11 +25,11 @@
    2.27  Contributing to the ns-3 project is still a very informal
    2.28  process because that process depends heavily on the personality
    2.29  of the people involved, the amount of time they can invest
    2.30 -and the type of model they want to work on.
    2.31 +and the type of model they want to work on.  
    2.32  
    2.33  Despite this lack of a formal process, there are a number of 
    2.34  steps which naturally stem from the open-source roots of the
    2.35 -project. These steps are described in doc/contributing.txt
    2.36 +project.  These steps are described in doc/contributing.txt
    2.37  
    2.38  2) An overview of the ns-3 project
    2.39  ----------------------------------
    2.40 @@ -42,8 +42,9 @@
    2.41    - point-to-point physical-layer links
    2.42    - OnOff traffic generator
    2.43  
    2.44 -However, the framework is there to make adding new models as 
    2.45 -simple as possible:
    2.46 +Our focus to date has been on getting an overall software
    2.47 +framework in place.  The framework is there to make adding 
    2.48 +new models as simple as possible:
    2.49    - an extensive tracing system can be used to connect
    2.50      any number of arbitrary trace sources to any number
    2.51      of trace sinks. This tracing system is decoupled
    2.52 @@ -65,7 +66,7 @@
    2.53  
    2.54  The code for the framework and the default models provided
    2.55  by ns-3 is built as a set of libraries. User simulations
    2.56 -are expected to be written as simple programs which make
    2.57 +are expected to be written as simple programs that make
    2.58  use of these ns-3 libraries.
    2.59  
    2.60  To build the set of default libraries and the example
    2.61 @@ -92,14 +93,14 @@
    2.62    - gcc 3.3 and earlier
    2.63    - optimized builds on linux x86 gcc 4.0 
    2.64  
    2.65 -Other platforms might or might not work: we welcome 
    2.66 +Other platforms may or may not work: we welcome 
    2.67  patches to improve the portability of the code to these
    2.68  other platforms.
    2.69  
    2.70  4) Running ns-3
    2.71  ---------------
    2.72  
    2.73 -On Recent Linux systems, once you have built ns-3, it 
    2.74 +On recent Linux systems, once you have built ns-3, it 
    2.75  should be easy to run the sample programs with the
    2.76  following command:
    2.77  
    2.78 @@ -112,7 +113,7 @@
    2.79  
    2.80  That program should generate a simple-p2p.tr text 
    2.81  trace file and a set of simple-p2p-xx-xx.pcap binary
    2.82 -pcap trace files.
    2.83 +pcap trace files, which can be read by tcpdump.
    2.84  
    2.85  5) Getting access to the ns-3 documentation
    2.86  -------------------------------------------
    2.87 @@ -166,4 +167,4 @@
    2.88  If you have successfully installed mercurial, you can get
    2.89  a copy of the development version with the following
    2.90  command:
    2.91 -"hg clone http://code.nsnam.org/ns-3-dev"
    2.92 \ No newline at end of file
    2.93 +"hg clone http://code.nsnam.org/ns-3-dev"
     3.1 --- a/RELEASE_NOTES	Fri May 18 18:06:00 2007 +0200
     3.2 +++ b/RELEASE_NOTES	Fri May 18 10:27:42 2007 -0700
     3.3 @@ -1,9 +1,9 @@
     3.4  
     3.5  		ns-3 RELEASE NOTES
     3.6  
     3.7 -This file contains ns-3  release notes (most recent releases first).
     3.8 +This file contains ns-3 release notes (most recent releases first).
     3.9  
    3.10 -Release 0.2 (2007/05/XX)
    3.11 +Release 3.0.2 (2007/05/18)
    3.12  ========================
    3.13  
    3.14    - Implement a new memory management infrastructure based
    3.15 @@ -15,7 +15,7 @@
    3.16  
    3.17    - Add support for a BSD-style socket API for user applications
    3.18  
    3.19 -Release 0.1 (2007/03/31)
    3.20 +Release 3.0.1 (2007/03/31)
    3.21  ========================
    3.22  
    3.23    - First public release; not yet pre-alpha.
     4.1 --- a/VERSION	Fri May 18 18:06:00 2007 +0200
     4.2 +++ b/VERSION	Fri May 18 10:27:42 2007 -0700
     4.3 @@ -1,1 +1,1 @@
     4.4 -3.0.1
     4.5 +3.0.2
     5.1 --- a/doc/build-waf.txt	Fri May 18 18:06:00 2007 +0200
     5.2 +++ b/doc/build-waf.txt	Fri May 18 10:27:42 2007 -0700
     5.3 @@ -1,12 +1,17 @@
     5.4 -WAF is an alternative build system, similar to SCons.  NS-3 now is
     5.5 -able to build with WAF, in parallel to SCons.
     5.6 +The main ns-3 build system is SCons.  Read the file build.txt
     5.7 +for SCons instructions.
     5.8  
     5.9 -Note: the WAF build scripts are experimental at this stage.
    5.10 +Waf is an alternative build system, similar to SCons.  ns-3 now is
    5.11 +able to build with Waf, in parallel to SCons.
    5.12  
    5.13 +(http://www.freehackers.org/~tnagy/waf.html)
    5.14  
    5.15 -=== Building with WAF ===
    5.16 +Note: the Waf build scripts are experimental at this stage.
    5.17 +Gustavo Carneiro (gjcarneiro@gmail.com) is the maintainer.
    5.18  
    5.19 -To build NS-3 with waf type the commands:
    5.20 +=== Building with Waf ===
    5.21 +
    5.22 +To build ns-3 with waf type the commands:
    5.23   1. ./waf configure [options]
    5.24   2. ./waf
    5.25  
    5.26 @@ -30,7 +35,7 @@
    5.27      Run code coverage analysis (assuming the project was configured
    5.28  with --enable-gcov)
    5.29  
    5.30 -=== Extending NS-3 ===
    5.31 +=== Extending ns-3 ===
    5.32  
    5.33  To add new modules:
    5.34    1. Create the module directory under src (or src/devices, or whatever);
    5.35 @@ -38,7 +43,7 @@
    5.36    3. Add a 'wscript' describing it;
    5.37    4. Add the module subdirectory name to the all_modules list in src/wscript.
    5.38  
    5.39 -A module's wscript file is basically a regular WAF script.  A NS-3
    5.40 +A module's wscript file is basically a regular Waf script.  A ns-3
    5.41  module is created as a cpp/shlib object, like this:
    5.42  
    5.43  def build(bld):
    5.44 @@ -65,7 +70,7 @@
    5.45  
    5.46  === Note for developers ===
    5.47  
    5.48 -The NS-3 code repository does not contain the waf script.  Instead,
    5.49 +The ns-3 code repository does not contain the waf script.  Instead,
    5.50  developers should check it out from a subversion repository:
    5.51  
    5.52    svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
    5.53 @@ -77,8 +82,8 @@
    5.54  Then it can be installed system-wide with 'sudo ./waf-light install'.
    5.55  When preparing a distribution, the resulting 'waf' script, which is
    5.56  self contained (no external files needed), can be easily included in
    5.57 -the tarball so that users downloading NS-3 can easily build it without
    5.58 -having WAF installed (although Python >= 2.3 is still needed).
    5.59 +the tarball so that users downloading ns-3 can easily build it without
    5.60 +having Waf installed (although Python >= 2.3 is still needed).
    5.61  
    5.62  The command 'waf dist' can be used to create a distribution tarball.
    5.63  It includes all files in the source directory, except some particular
     6.1 --- a/doc/build.txt	Fri May 18 18:06:00 2007 +0200
     6.2 +++ b/doc/build.txt	Fri May 18 10:27:42 2007 -0700
     6.3 @@ -16,6 +16,9 @@
     6.4  the right libraries. This saves you the pain of having to
     6.5  setup environment variables to point to the right libraries.
     6.6  
     6.7 +(Note:  An experimental, alternative build system is described
     6.8 +in build-waf.txt)
     6.9 +
    6.10  1) Options
    6.11  ----------
    6.12  
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/doc/codingstd.txt	Fri May 18 10:27:42 2007 -0700
     7.3 @@ -0,0 +1,210 @@
     7.4 +       The Ns-3 Coding Style
     7.5 +
     7.6 +/*
     7.7 + * Note:  This file is incomplete and will be converted to non-text (html,pdf)
     7.8 + * formats at a future date
     7.9 + */
    7.10 +
    7.11 +1) Code layout
    7.12 +     -----------
    7.13 +
    7.14 +The code layout follows the GNU coding standard layout for C and extends
    7.15 +it to C++. Do not use tabs for indentation. Indentation spacing is 2
    7.16 +spaces as outlined below:
    7.17 +
    7.18 +void 
    7.19 +Foo (void)
    7.20 +{
    7.21 +  if (test)
    7.22 +    {
    7.23 +      // do stuff here
    7.24 +    }
    7.25 +  else
    7.26 +    {
    7.27 +      // do other stuff here
    7.28 +    }
    7.29 +
    7.30 +  for (int i = 0; i < 100; i++)
    7.31 +    {
    7.32 +      // do loop
    7.33 +    }
    7.34 +
    7.35 +  while (test)
    7.36 +    {
    7.37 +      // do while
    7.38 +    }
    7.39 +
    7.40 +  do
    7.41 +    {
    7.42 +      // do stuff
    7.43 +    } while ();
    7.44 +}
    7.45 +
    7.46 +The following is not recommended:
    7.47 +
    7.48 +if (test) statement
    7.49 +
    7.50 +if (test)
    7.51 +  statement
    7.52 +
    7.53 +for (...) statement
    7.54 +
    7.55 +Each statement should be put on a separate line to increase readability.
    7.56 +Short one-line comments can use the C++ comment style, that is, '//'
    7.57 +but longer comments should use C-style comments:
    7.58 +/*
    7.59 + *
    7.60 + *
    7.61 + */
    7.62 +
    7.63 +
    7.64 +2) Naming Patterns
    7.65 +   ---------------
    7.66 +
    7.67 +2.1) Name encoding
    7.68 +     -------------
    7.69 +Function, Method, and Type names should follow the CamelCase convention:
    7.70 +words are joined without spaces and are capitalized. For example,
    7.71 +"my computer" is transformed into MyComputer. Do not use all capital 
    7.72 +letters such as MAC or, PHY, but choose instead Mac or Phy. Do not use
    7.73 +all capital letters, even for acronyms such as EDCA: use Edca instead.
    7.74 +The goal of the CamelCase convention is to ensure that the words which
    7.75 +make up a name can be separated by the eye: the initial Caps fills
    7.76 +that role.
    7.77 +
    7.78 +Variable names should follow a slight variation on the base CamelCase
    7.79 +convention: camelBack. For example, the variable "user name" would be
    7.80 +named "userName". This variation on the basic naming pattern is used to
    7.81 +allow a reader to distinguish a variable name from its type. For example,
    7.82 +"UserName userName;" would be used to declare a variable named userName
    7.83 +of type UserName.
    7.84 +
    7.85 +Global variables should be prefixed with a "g_" and member variables
    7.86 +(including static member variables) should be prefixed with a "m_". The
    7.87 +goal of that prefix is to give a reader a sense of where a variable of
    7.88 +a given name is declared to allow the reader to locate the variable 
    7.89 +declaration and infer the variable type from that declaration. For example
    7.90 +you could declare in your class header my-class.h:
    7.91 +
    7.92 +class MyClass
    7.93 +{
    7.94 +  void MyMethod (int aVar);
    7.95 +  int m_aVar;
    7.96 +  static int m_anotherVar;
    7.97 +};
    7.98 +
    7.99 +and implement in your class file my-class.cc:
   7.100 +
   7.101 +int MyClass::m_anotherVar = 10;
   7.102 +static int g_aStaticVar = 100;
   7.103 +int g_aGlobalVar = 1000;
   7.104 +
   7.105 +void
   7.106 +MyClass::MyMethod (int aVar)
   7.107 +{
   7.108 +  m_aVar = aVar;
   7.109 +}
   7.110 +
   7.111 +2.2) Choosing names
   7.112 +
   7.113 +Variable, function, method, and type names should be based on the
   7.114 +english language. Furthermore, always try to choose descriptive
   7.115 +names for them. Types are often english names such as: Packet, 
   7.116 +Buffer, Mac, or Phy. Functions and Methods are often named
   7.117 +based on verbs and adjectives: GetX, DoDispose, ClearArray, etc.
   7.118 +
   7.119 +A long descriptive name which requires a lot of typing is always
   7.120 +better than a short name which is hard to decipher. Do not use
   7.121 +abbreviations in names unless the abbreviation is really unambiguous
   7.122 +and obvious to everyone. Do not use short inapropriate names such
   7.123 +as foo, bar, or baz. The name of an item should always match its 
   7.124 +purpose. As such, names such as tmp to identify a temporary
   7.125 +variable or such as 'i' to identify a loop index are ok.
   7.126 +
   7.127 +3) File layout and code organization
   7.128 +   ---------------------------------
   7.129 +
   7.130 +A class named MyClass should be declared in a header named my-class.h
   7.131 +and implemented in a source file named my-class.cc. The goal of this
   7.132 +naming pattern is to allow a reader to quickly navigate through
   7.133 +the ns-3 codebase to locate the source file relevant to a specific
   7.134 +type.
   7.135 +
   7.136 +Each my-class.h header should start with the following comments: the
   7.137 +first line ensures that developers who use the emacs editor will be 
   7.138 +able to indent your code correctly. The following lines ensure that
   7.139 +your code is licensed under the GPL, that the copyright holders
   7.140 +are properly identified (typically, you or your employer), and
   7.141 +that the actual author of the code is identified. The latter is
   7.142 +purely informational and we use it to try to track the most
   7.143 +appropriate person to review a patch or fix a bug.
   7.144 +
   7.145 +/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
   7.146 +/*
   7.147 + * Copyright (c) YEAR COPYRIGHTHOLDER
   7.148 + * 
   7.149 + * 3-paragran GPL blurb
   7.150 + *
   7.151 + * Author: MyName <myemail@foo.com>
   7.152 + */
   7.153 +
   7.154 +Below these C-style comments, always include the following which
   7.155 +defines a set of header guards (MY_CLASS_H) used to avoid multiple
   7.156 +header includes, which ensures that your code is included
   7.157 +in the "ns3" namespace and which provides a set of doxygen comments
   7.158 +for the public part of your class API. Detailed information
   7.159 +on the set of tags available for doxygen documentation is described
   7.160 +in the doxygen website: http://www.doxygen.org.
   7.161 +
   7.162 +#ifndef MY_CLASS_H
   7.163 +#define MY_CLASS_H
   7.164 +
   7.165 +namespace n3 {
   7.166 +
   7.167 +/**
   7.168 + * \brief short one-line description of the purpose of your class
   7.169 + *
   7.170 + * A longer description of the purpose of your class after a blank
   7.171 + * empty line.
   7.172 + */
   7.173 +class MyClass
   7.174 +{
   7.175 +public:
   7.176 + MyClass ();
   7.177 + /**
   7.178 +  * \param firstParam a short description of the purpose of this parameter
   7.179 +  * \returns a short description of what is returned from this function.
   7.180 +  *
   7.181 +  * A detailed description of the purpose of the method.
   7.182 +  */
   7.183 + int DoFoo (int firstParam);
   7.184 +private:
   7.185 + void MyPrivateMethod (void);
   7.186 + int m_myPrivateMemberVariable;
   7.187 +};
   7.188 +
   7.189 +} // namespace ns3
   7.190 +
   7.191 +#endif /* MY_CLASS_H */
   7.192 +
   7.193 +The my-class.cc file is structured similarly:
   7.194 +
   7.195 +/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
   7.196 +/*
   7.197 + * Copyright (c) YEAR COPYRIGHTHOLDER
   7.198 + * 
   7.199 + * 3-paragran GPL blurb
   7.200 + *
   7.201 + * Author: MyName <myemail@foo.com>
   7.202 + */
   7.203 +#include "my-class.h"
   7.204 +
   7.205 +namespace ns3 {
   7.206 +
   7.207 +MyClass::MyClass ()
   7.208 +{}
   7.209 +
   7.210 +...
   7.211 +
   7.212 +} // namespace ns3
   7.213 +
     8.1 --- a/doc/contributing.txt	Fri May 18 18:06:00 2007 +0200
     8.2 +++ b/doc/contributing.txt	Fri May 18 10:27:42 2007 -0700
     8.3 @@ -1,7 +1,13 @@
     8.4 -
     8.5  Contributing to the ns-3 project
     8.6  --------------------------------
     8.7  
     8.8 +ns-3 is an open source project backed by an NSF CISE CRI grant. 
     8.9 +Although the NSF PIs have specific aims to fulfill, we want others to 
    8.10 +contribute, and we'd like to have a broad community of users and 
    8.11 +developers, with the goal of a self-sustaining project downstream. 
    8.12 +The project is currently in a bootstrapping phase, but we welcome 
    8.13 +ambitious developers who might want to help shape the early design.
    8.14 +
    8.15  Despite the lack of a formal contribution process to the ns-3
    8.16  project, there are a number of steps which we expect every
    8.17  potential contributor to follow. These naturally stem from 
    8.18 @@ -46,8 +52,12 @@
    8.19      also expect model authors to act as responsible maintainers
    8.20      and be reactive to bug reports concerning their models.
    8.21  
    8.22 -  - you should make sure that you understand that contributed
    8.23 -    models should be licensed under the GPLv2. You do not have
    8.24 -    to assign your copyright to the ns-3 project but you must
    8.25 -    accept the terms of the GPLv2. See the following link:
    8.26 +  - The project has decided upon GNU GPLv2 as the licensing structure. 
    8.27 +    All simulation software in the ns-3 repositories will be GNU GPLv2 
    8.28 +    or GNU GPLv2-compatible (with non-GPLv2 licensing reserved for
    8.29 +    ports of pre-existing code under a different license, such as BSD).
    8.30 +    You do not have to assign your copyright to the ns-3 project but
    8.31 +    you must accept the terms of the GPLv2 and attest that your 
    8.32 +    contributions can be licensed under those terms.  See the 
    8.33 +    following link:
    8.34      http://www.fsf.org/licensing/licenses/info/GPLv2.html
     9.1 --- a/doc/mercurial.txt	Fri May 18 18:06:00 2007 +0200
     9.2 +++ b/doc/mercurial.txt	Fri May 18 10:27:42 2007 -0700
     9.3 @@ -3,7 +3,7 @@
     9.4  
     9.5  ns-3 uses the Mercurial software revision control system which
     9.6  is a replacement for tools liks cvs or subversion. Thus, to get
     9.7 -access to the developement versions of ns-3, you need to install
     9.8 +access to the development versions of ns-3, you need to install
     9.9  mercurial first. See http://www.selenic.com/mercurial/wiki/
    9.10  
    9.11  Mercurial cheat sheet
    9.12 @@ -38,6 +38,7 @@
    9.13  --------------------------------------
    9.14  To the main repository:
    9.15  hg push ssh://code@code.nsnam.org/repos/ns-3-dev
    9.16 +
    9.17  To your private repository:
    9.18  hg push ssh://username@code.nsnam.org//home/username/repositories/username/repository
    9.19