Friday, 24 August 2012

Extending NS3 with your module and extra libraries

I have been working on custom module in ns3 for some time now. Due to many changes in NS3, like bug fixes, extensions, improvements, I decided to move to latest version.

This decision consumed couple of days and several gray hair, due to lack of documentation. The biggest difference for custom module developer is the new waf build system and thus how build works.

Reading it seems very simple to add additional libraries, however the tutorial is not valid for module. Because the suggested build steps will only link the individual files with external libraries and NOT the module. The flags are only passed when compiling indivirual object, the bug (?) is reported.

So here is how I managed to solve it

First, add configuration in your wafscript script
def configure(conf):
     conf.env['xercersc'] = conf.check(mandatory=True, lib='xerces-c', uselib_store='XERCES')
     conf.env['ldl'] = conf.check(mandatory=True, lib='dl', uselib_store='LDL')
make sure you change naming to your libs, note also the name of library, you have to omit "lib", "l" and only go by the name. Having mandatory=True will abort the compilation if waf can not find the library.

Second and last

def build(bld):
    #...... code omited
    #...... the rest of build code
Delete build directory run
./waf configure && ./waf build
If you still having problems with linking it is very useful to run
./waf --no-task-lines -v
In that case after each build step waf will output runner were the compiler and all passed flags are visible. From there you can continue bug hunt :)



  1. I need help with my work. I'm trying to create a scenario to analyze the effect of mobility on data delivery. Now I'm working on Mac OSX 10.8 (Mountain Lion) and using g++ 4.8 but I keep getting this error about referencing.

    Undefined symbols for architecture x86_64:
    "ns3::pimdm::MulticastRoutingProtocol::registerMember(ns3::Ipv4Address, ns3::Ipv4Address, unsigned int)", referenced from:
    ns3::igmpx::IGMPXRoutingProtocol::RecvIgmpReport(ns3::igmpx::IGMPXHeader::IgmpReportMessage&, ns3::Ipv4Address, ns3::Ipv4Address, unsigned int, double) in
    "ns3::pimdm::MulticastRoutingProtocol::unregisterMember(ns3::Ipv4Address, ns3::Ipv4Address, unsigned int)", referenced from:
    ns3::igmpx::IGMPXRoutingProtocol::RemoveClients(ns3::igmpx::SourceGroupPair, unsigned int) in
    "typeinfo for ns3::pimdm::MulticastRoutingProtocol", referenced from:
    ns3::Ptr ns3::DynamicCast(ns3::Ptr const&) in
    ld: symbol(s) not found for architecture x86_64
    collect2: error: ld returned 1 exit status

    I can't seem to figure out the problem and how to solve it though I have a feeling it's a linking problem. The thing is pimdm and video-push are all new modules introduced in the simulator. Do you have any idea what I can do? I must warn you that I'm really new to all this and if you can please be very clear. Thank you in advance.

  2. from the error it looks like linking problem. Have you defined all the modules needed? Have never used Mac so I have no clue how to solve it :) run ns-3 in the cloud ;) more convenient.

  3. Hi,
    First of all, thank you... but
    When you suffered a lot for a solution, at least explain a bit more.
    For example, you should explain a bit more what each line means. and be careful what code you are omitting. For instance, in build function, I(a newbie) didn't know what variable 'module' is.
    you had to mention:
    module = bld.create_ns3_module('antenna', ['core'])

    It cost a couple of my hair(black or gray) to make sense of your explanation.

    Now I know your solution isn't necessarily good for modules, but also for other cases like the examples in ./example subfolder. There, the script is like:
    obj = bld.create_ns3_program('energy-model-example', ['core', 'blah blah'])
    and then we can ask to link the library like this:
    obj.use.append("BOOST_SYSTEM") (...or any other library that you have registered in the configure function in the main wscript file)

    even now that I am writing these lines, I feel stupid as it seems soooo trivial. But,...sometime missing such simple hints cost you days.

    Thank you for your help.

    1. Hi,

      This solution was a temporarily work around after I reported bug. Will not necessary even be need in latest version of ns-3.

  4. Hi,
    Thanks for the great post. 
I am new to ns3 and I have checked and implemented the examples present in ns3.
    I have to implement a project for which i have created a QT dynamic library using IDE netbeans.I have read the help present in this forum and the ns3 nsnam website. What i figured out is that I need to create a I created the module by executing the which create some templates and wscript file.Now in order to link the library i need to modify file.
    To link the library i made following changes in the file

    bld.env.append_value(“LINKFLAGS”, ["-L/home/a/NetBeansProjects/QDynLib/dist/Debug/GNU-Linux-x86"])
bld.env.append_value(“LIB”, ["libQDynLib"])

    but still building is not successful and i am getting some errors

    can anybody help me please?
    location of the dynamic library:

    name of library file:libQDynLib

  5. This comment has been removed by the author.

    1. without knowing what errors you get its impossible to help. One common mistake that your LD_* variable does not contain the path to library, so when you execute program the lib is not found.

  6. I need to install a RoHC compression Library in NS-3. Can you help me how to install it?

  7. I need to install a RoHC compression Library in NS-3. Can you help me how to install it?

    1. hi did you find a way because I have a same problem.

  8. I have created a bridge module which is just renamed the existing bridge . My intention is to remove the source code of the bridge module and use the header files and the binary of the source module to run the topology used by the bridge module how to link this to NS3