Getting Started

Opening Notes

The walkthrough below uses then normal NS3 directory names. However, these have the version number baked in to both the parent directory (ns-allinone-3.25) and the interior directory (ns-allinone-3.25/ns-3.25). This means if you make an Eclipse project around those names, upgrading NS3 will require major updates to your development environment.

One option is to link symbolic names. For example ln -s ns-allinone-3.25 simulator and ln -s ns-3.25 ns. This means your Eclipse configuration could use the paths simulator/ and simulator/ns.

Getting Started with ccns3Sim

N.B.: This walkthrough uses NS-3.25. The same steps work for NS-3.24.1. Just change the version number below.

This section describes how to download and build the CCNx 1.0 module for NS3. The module will be called ccns3Sim inside the NS3 system.

• Complete Walkthrough
• Running examples and unit tests
• Integrating with the Eclipse IDE

Complete Walkthrough

Here is a complete walk through of starting with nothing and building the whole ns3 simulator with our code

# *NOTE*: environment variables are used throughout to make the example easier. They are not essential.
#export NS3_RELEASE="3.24.1"
export NS3_RELEASE="3.25"

# STEP 1
export NS3_ROOT=~/ns3

mkdir $NS3_ROOT
cd $NS3_ROOT
wget https://www.nsnam.org/release/ns-allinone-${NS3_RELEASE}.tar.bz2
tar -xjf ns-allinone-${NS3_RELEASE}.tar.bz2

# STEP 2
export NSDIR=${NS3_ROOT}/ns-allinone-${NS3_RELEASE}/ns-${NS3_RELEASE}

cd $NSDIR/src
# It is recommended that you fork the project in to your own workspace so you
# can generate pull requests for modifications.
git clone [email protected]:PARC/ccns3Sim.git

# The examples are not required, but provide extended examples of using the simulator
git clone [email protected]:PARC/ccns3Examples.git

# STEP 3
cd $NSDIR
patch -p 2 < $NSDIR/src/ccns3Sim/patch-files/ns-${NS3_RELEASE}-patch

# On OS.X apply this patch to be able to use the gcov build
if [ "$(uname -s)" == "Darwin" ]; then
    patch -p 2 < $NSDIR/src/ccns3Sim/patch-files/ns-${NS3_RELEASE}.osx-gcov.patch
fi

# STEP 4
# We provide some scripts to make it easier to configure, run examples, and debug.
# Use of these scripts is not required, you can still use `waf configure` and `waf build`.

cd $NSDIR
ln -s $NSDIR/src/ccns3Sim/bin/ccnx.sh .
ln -s $NSDIR/src/ccns3Sim/bin/run_ccnx_test_suites.sh .

./ccnx.sh configure
./ccnx.sh build

# STEP 5
# Run the CCNx unit tests
# To list all the tests use `run_ccnx_test_suites.sh list`
# To run a specific test use `run_ccnx_test_suites.sh suite TestSuiteName`
# To debug a specific test use `run_ccnx_test_suites.sh debug TestSuiteName`
# To run all CCNx related unit tests:
./run_ccnx_test_suites.sh ccnx

Integrating with ns3

If you already have an NS3 setup, you can use the above walkthrough and skip to STEP 2 with the appropriate definition of $NSDIR for your installation.

The patch only updates two files in the PointToPoint module to account for our EtherType (0x0801) and our PPP ProtocolNumber (0x25).

We include a set of launch configurations in src/ccns3Sim/eclipse-launch that have some path dependencies. See the Integrating with the Eclipse IDE section for information about that if you use Eclipse and want to use our launch configurations for running unit tests and examples in the IDE.

Running the code

Running examples

Running unit tests

Integrating with Eclipse

You should be able to follow the normal NS3 method for setting up eclipse. We provide Eclipse run configurations for our unit tests and examples in src/ccns3Sim/eclipse-launch, but they assume your Eclipse project is name 'ns-allinone-3.25'. If your eclipse project has a different name you will need to update all those files. You can use File | Import and select 'Run/Debug' launch configurations.

You should also exclude ns-3.25/doc from the build. If you happen to "./waf doxygen" it will cause problem in Eclipse as it tries to refresh that very large directory structure.