{"id":305,"date":"2010-08-27T15:25:57","date_gmt":"2010-08-27T19:25:57","guid":{"rendered":"http:\/\/www.eg.bucknell.edu\/~perrone\/?p=305"},"modified":"2010-08-27T17:26:56","modified_gmt":"2010-08-27T21:26:56","slug":"creating-a-new-module-in-ns-3","status":"publish","type":"post","link":"https:\/\/www.eg.bucknell.edu\/~perrone\/2010\/08\/27\/creating-a-new-module-in-ns-3\/","title":{"rendered":"Creating a new module in ns-3"},"content":{"rendered":"

At times people create new functionality for ns-3 that takes the shape of module, that is, multiple files that implement various classes. If you’re looking for information on how to put together a new ns-3 module, you’ve come to the right place. I’ll walk you through a sequence of steps toward\u00a0setting up your installation to build and recognize your module.<\/p>\n

Step 1 – Create a directory for your new module<\/h3>\n

I’ll start the assumption that you are working with a tarball distribution – if you’re working with a mercurial repo, you’ll will know how to change the path names in this discussion. Say you want to create a new module for ns-3 and that you will want it to live in the contrib directory. This means your code will be in a path such as:<\/p>\n

~\/tarballs\/ns-allinone-3.9\/ns-3.9\/src\/contrib<\/code><\/p>\n

For the sake of discussion, say your module is called “awesome”. Let’s further assume that it will live in a directory called:<\/p>\n

~\/tarballs\/ns-allinone-3.9\/ns-3.9\/src\/contrib\/awesome<\/code><\/p>\n

This is not just an assumption for the sake of discussion: it’s a requirement. The directory must have the same name as the module.<\/p>\n

Step 2 – Tweak the build system<\/h3>\n

Before you write any actual code, let’s tweak the waf build scripts to take care of your new module. In a text editor, open file:<\/p>\n

~tarballs\/ns-allinone-3.9\/ns-3.9\/src\/wscript<\/code><\/p>\n

In this file, you will see a list of all the modules that the build system is already aware of. It’s appropriately called “all_modules”, and it will look like this:<\/p>\n

\n
all_modules = (\r\n    'core',\r\n    'common',\r\n    'simulator',\r\n    'contrib',\r\n    'node',\r\n    'internet-stack',\r\n    'devices\/point-to-point',\r\n    ...\r\n    'mpi',\r\n    'contrib\/topology-read',\r\n    'contrib\/energy',\r\n    )<\/pre>\n<\/blockquote>\n
Add your new module to the list (perhaps at the end), so that it reads:<\/p>\n
\n
all_modules = (\r\n    'core',\r\n    'common',\r\n    'simulator',\r\n    'contrib',\r\n    'node',\r\n    'internet-stack',\r\n    'devices\/point-to-point',\r\n    ...\r\n    'mpi',\r\n    'contrib\/topology-read',\r\n    'contrib\/energy',\r\n    'contrib\/awesome',\r\n    )<\/pre>\n<\/blockquote>\n
Next, change to the directory where your module lives. Following the pattern in this example, that would be:<\/p>\n
~\/tarballs\/ns-allinone-3.9\/ns-3.9\/src\/contrib\/awesome<\/code><\/p>\n
Now, create a new file called wscript<\/code> in this directory. This file will state for the build system a complete list of your implementation (.cc<\/code>) and header files (.h<\/code>).<\/p>\n
\n
## -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-\r\n\r\ndef build(bld):\r\n    obj = bld.create_ns3_module('dcf', ['node'])\r\n    obj.source = [\r\n          'one_of_your.cc',\r\n          'another_of_your.cc',\r\n          ...\r\n          ]\r\n    headers = bld.new_task_gen('ns3header')\r\n    headers.module = 'dcf'\r\n    headers.source = [\r\n         'one_of_your.h',\r\n         'another_of_your.h',\r\n         ...\r\n    ]<\/pre>\n<\/blockquote>\n
Step 3 – Implement your module<\/h3>\n
By now, you have set everything up for the build system to create code for your new module. You might already have started on the development of\u00a0the .cc and .h files for your module, but otherwise, you ready to start working on them. There’s more about creating a new module that I’ll address in a different post (I’ll come back to drop a hyperlink here when that is ready). For now, suffice to say that you’ll fall into the classic iterative pattern of software development: design, code, compile, run, and debug, repeating each of these steps as needed.<\/p>\n
Remember that to compile, you will change to the directory at the root of your ns-3 distribution, which in our example has been:<\/p>\n
~\/tarballs\/ns-allinone-3.9\/ns-3.9\/<\/code><\/p>\n
To build in your new module, you do:<\/p>\n
.\/waf build<\/code><\/p>\n
If all goes well and your code compiled flawlessly, you can check out the fruits of your labor. Take a look at:<\/p>\n
~tarballs\/ns-allinone-3.9\/ns-3.9\/build\/debug\/ns3<\/code><\/p>\n
You will discover that this directory contains a file called awesome-module.h<\/code>, which corresponds directly to your new module. This is an aggregator<\/em> header file, that is, a single header file which end-user C++ programs must include to use all the features implemented in your module. (The aggregator stands in for possibly multiple header files in your module.) These end-user scripts will be able to use your module after one single #include<\/code>, such as:<\/p>\n
\n#include “ns3\/awesome-module.h”\n<\/p><\/blockquote>\n
Note that the ns3\/<\/code> part in the path to your include refers to the directory under:<\/p>\n
~tarballs\/ns-allinone-3.9\/ns-3.9\/build\/<\/code><\/p>\n
which contains all the headers for all the modules in your installation. Depending on your particular configuration, this directory may be<\/p>\n
~tarballs\/ns-allinone-3.9\/ns-3.9\/build\/debug\/ns3<\/code>
\nor
\n~tarballs\/ns-allinone-3.9\/ns-3.9\/build\/optimized\/ns3<\/code><\/p>\n
Step 4 – Create examples using your module<\/h3>\n
Finally, once you’ve tested and debugged your module, remember to be kind to the community and to leave some working code that demonstrates how one can use your work. Consider creating a directory such as:<\/p>\n
~tarballs\/ns-allinone-3.9\/ns-3.9\/examples\/awesome\/<\/code><\/p>\n
which should contain one or more examples of how to use your module.<\/p>\n","protected":false},"excerpt":{"rendered":"
At times people create new functionality for ns-3 that takes the shape of module, that is, multiple files that implement various classes. If you’re looking for information on how to put together a new ns-3 module, you’ve come to the right place. I’ll walk you through a sequence of steps toward\u00a0setting up your installation to…<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[15,12],"class_list":["post-305","post","type-post","status-publish","format-standard","hentry","category-uncategorized","tag-ns-3","tag-simulation"],"_links":{"self":[{"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/posts\/305"}],"collection":[{"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/comments?post=305"}],"version-history":[{"count":38,"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/posts\/305\/revisions"}],"predecessor-version":[{"id":343,"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/posts\/305\/revisions\/343"}],"wp:attachment":[{"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/media?parent=305"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/categories?post=305"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.eg.bucknell.edu\/~perrone\/wp-json\/wp\/v2\/tags?post=305"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}