From Nsnam
Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

What is a sprint?

A sprint is a scheduled time for ns-3 contributors to gather and focus their undivided attention on improving the code, documentation, or tests.

Sprints are open to anyone, and are conducted on IRC, and if needed, other virtual meeting technologies.

  • IRC channel is #ns-3 at irc.freenode.net

The Django project has a good reference and links to some presentations all about coding sprints.

A summary of the results of sprints will be shared with other developers on the ns-developers mailing list.

Results of recent sprints

In the March 2015 sprint, we were able to commit about half of the SetGroupName() methods across the codebase. Following the sprint, the remainder of the codebase was handled, so by the ns-3.23 release, this item was completed.

In the December 2014 sprint, we were able to get to zero warnings on the LTE helper directory, and also the mobility model and helper directories. December sprint warnings fixed (Peter, Piotr, Tom):

  • 176 src/mobility/model (all eliminated)
  • 39 src/mobility/helper (all eliminated)
  • 146 src/lte/helper (all eliminated)
  • reduced src/core warnings to below 500 count

In the October 2014 sprint, the following warnings were fixed (Budi, Tiago, Tommaso, Natale, Peter):

  • src/lte warnings count reduced by ~1500
  • src/mobility warnings count reduced by 20
  • all 160 propagation warnings eliminated
  • all 47 point-to-point warnings eliminated
  • all 55 internet warnings eliminated

Future sprints

None are scheduled at this time.

Past sprints

We had several past sprints; details from the last few are listed below. Details from older ones can be found in this wiki page history.

Friday March 27, 2015, 13h00-19h00 UTC

 ./waf --run "third --PrintHelp"
  Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
  Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (3.209s)
  ns3-dev-third-debug [Program Arguments] [General Arguments]

  Program Arguments:
    --nCsma:    Number of "extra" CSMA nodes/devices [3]
    --nWifi:    Number of wifi STA devices [3]
    --verbose:  Tell echo applications to log if true [true]

  General Arguments:
    --PrintGlobals:              Print the list of globals.
    --PrintGroups:               Print the list of groups.
    --PrintGroup=[group]:        Print all TypeIds of group.
    --PrintTypeIds:              Print all TypeIds.
    --PrintAttributes=[typeid]:  Print all attributes of typeid.
    --PrintHelp:                 Print this help message.

This command should also work;

 ./waf --run "third --PrintGroups"
  Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
  Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (3.231s)
  Registered TypeId groups:

We then want to be able to list all of the relevant TypeIds:

./waf --run "third --PrintGroup=Mobility"
Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
'build' finished successfully (3.202s)
TypeIds in group Mobility:

Then the attributes of a given class; this type of capability will be enabled across the codebase if we set the Group names consistently:

 ./waf --run "third --PrintAttributes=ns3::RandomWalk2dMobilityModel"
Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
'build' finished successfully (3.187s)
Attributes for TypeId ns3::RandomWalk2dMobilityModel
        Bounds of the area to cruise.
        A random variable used to pick the direction (radians).
        Change current direction and speed after moving for this distance.
        The mode indicates the condition used to change the current speed and direction
        A random variable used to pick the speed (m/s).
        Change current direction and speed after moving for this delay.
  • Tasks: We will organize to group as many TypeIds as possible, across module lines. For instance, someone will be assigned the src/applications module, someone will be assigned the src/propagation model, and so on. When finished or having taken it as far as you can, submit a patch for the module.
  • Patches: We would like code to be sent in unified diff format. An easy way to do this is to use the 'hg diff' command, and redirect the output into a file (and submit the file). For instance, here is the output of 'hg diff' if one line of text is added:
hg diff
diff -r 6ea11eb86c17 src/applications/model/application-packet-probe.cc
--- a/src/applications/model/application-packet-probe.cc	Thu Mar 19 21:13:16 2015 +0100
+++ b/src/applications/model/application-packet-probe.cc	Mon Mar 23 15:44:33 2015 -0700
@@ -39,6 +39,7 @@
   static TypeId tid = TypeId ("ns3::ApplicationPacketProbe")
     .SetParent<Probe> ()
+    .SetGroupName ("Application")
     .AddConstructor<ApplicationPacketProbe> ()
     .AddTraceSource ( "Output",
                       "The packet plus its socket address that serve "

If you type

 hg diff > application.patch

you will store the above in a patch file, which can be submitted.

Please remember that an implementation file (.cc) may contain multiple TypeId declarations, so please search through each file.

  • Outcome: If successful, the PrintGroups command will have many groups defined (one for each module, perhaps more). The tutorial and manual will also be extended to describe how to use this feature.
  • Coordination: We will use IRC and Etherpad to coordinate the work (make sure multiple people do not work on the same file).

Friday December 12, 2014, 14h00-20h00 UTC

Fix as many of the doxygen warnings as we can. A current count of warnings (by module) can be seen here: http://mailman.isi.edu/pipermail/ns-commits/2014-November/015994.html. There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor. How this is planned to work is that contributors who show up will choose a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
We may also work on reducing includes in ns-3.
  • Coordination: We will use IRC and Etherpad to coordinate the work (make sure multiple people do not work on the same file).

How to build Doxygen for ns-3 and find the errors

  • Use mercurial to check out the current copy of ns-3 (see the tutorial if you don't know how to do this):
  • You must also have Doxygen installed on your machine.

Once you have an ns-3-dev/ directory, take these steps:

   $ ./waf configure --enable-examples --enable-tests
   $ ./waf build

Then, run the script doc/doxygen.warnings.report.sh from the ns-3-dev directory:

 $ ./doc/doxygen.warnings.report.sh -t -e

(Note: this excludes tests and examples; to include warnings for those files, rerun without the -t and -e options). This will produce lots of summary statistics like:

  Warnings by module/directory:
  Count Directory
  ----- ----------------------------------
  3390 src/lte/model
  1532 src/wimax/model
   575 src/core/model
   570 src/wifi/model
   488 src/mesh/model
   338 src/visualizer/visualizer
   229 src/netanim/model
   213 src/dsr/model

Do not worry if the output scrolls beyond the buffer in your terminal window; the full warnings log is written to doc/doxygen.warnings.log.

Once this is complete, you can use the doxygen.warnings.report.sh script to focus on one module or file. To see just the errors from one module, for example wifi:

 $ ./doc/doxygen.warnings.report.sh -t -e -s -m wifi

The -s option skips the doxygen run, and just reports results from the existing warnings log. Obviously, if you want to see the results of your edits, you would omit the -s option so you could regenerate the warnings log. The -m <module> option only shows results from the ./src/<module> module; after printing the warnings counts by file, it shows the actual errors from each file:

 Filtered Warnings
 src/wifi/helper/athstats-helper.h:49: warning: Member EnableAthstats(std::string filename, uint32_t nodeid, 
 uint32_t deviceid) (function) of class ns3::AthstatsHelper is not documented.

This means the method AthstatsHelper::EnableAthstats has no documentation, and it's declared in src/wifi/helper/athstats-helper.h around line 49.

To see just the warnings from a single file (or a set of files matching a regular expression) use the -F <file-name-or-regex> option:

 $ ./doc/doxygen.warnings.report.sh -s -F "block-ack.*"

How to add documentation during the sprint

Once you find the list of files and look at the possible errors to fix, feel free to join the chat and request to take a module or file and fix it, and we will list it on the Etherpad as being taken. While all docs are valuable, we should probably focus on code in the model/ directories, then helpers/, examples/, and finally test/.

To add doxygen documentation, please follow the ns-3 Specifics guidelines.

Don't be surprised if you fix one warning and more appear! If a struct, class or function has no documentation, doxygen reports a single "is not documented" error. Once that object has documentation, then doxygen will examine it in detail and report additional warnings. For example, a function with no documentation will generate one warning. Adding documentation about the function itself will fix that warning, but then generate warnings for each of the function parameters and return value, until those are also documented.

Unfortunately, it's not enough just write documentation; you also have to test it. (Documentation has bugs too!) Just rerun the doxygen.warnings.report.sh script without the -s option:

 $ ./doc/doxygen.warnings.report.sh -m <module> # or -F <file-name-or-regex>

(BTW, without -s the script will always build all the doxygen; the -m and -F options only affect what it displays from the resulting doxygen.warnings.log)

Once the script completes, load up the docs in your browser and check that it looks as you intended/you didn't mistype some doxygen syntax:

 $ firefox doc/html/index.html &

As in all code development: wash, rinse, repeat, or, in this case:

 $ ./doc/doxygen.warnings.report.sh -m <module>
 [edit, edit, edit]
 $ firefox doc/html/index.html &

How to contribute your docs

Once you have fixed a file, you may create a patch such as follows:

 $ hg diff file-you-have-fixed.h > file-you-have-fixed.h.patch

and upload it to bug 938 or email it to one of the maintainers participating in the sprint (you can ask on IRC about it).

General preparation

  • Make sure that you can join the IRC channel in advance
  • Make sure you can checkout the development version of ns-3 (we will use ns-3-dev)
  • Familiarize yourself with how to generate a patch against ns-3-dev. Patches you write can be uploaded to Bugzilla or sent to one of the maintainers.

Once you're there

  • Check in on IRC by letting others know that you've joined and are ready to contribute, and a maintainer will go from there