Nsnam - User contributions [en]

Local Clocks

2019-02-01T18:58:55Z

Pdbarnes: Created page with "''This is a continuation of the local clocks/per-node clock discussion from GSOC2015MpTcpImplementation#On_the_per_node_clock''' == Developer List Discussion 2019-01 ==..."

''This is a continuation of the local clocks/per-node clock discussion from [[GSOC2015MpTcpImplementation#On_the_per_node_clock']]''

== Developer List Discussion 2019-01 ==

On 24/01/19 at 09:15, Tommaso Pecorella wrote:
<blockquote>Hi all,

there's an unused and yet potentially very interesting feature in ns-3: Node::GetLocalTime.
</blockquote>

On 25 Jan 2019, at 02:55, Natale Patriciello
<blockquote>Matt was working on that as part of his GSoC 4 years ago.
[[GSOC2015MpTcpImplementation#On_the_per_node_clock]]
</blockquote>

On Feb 1, 2019, at 9:15 AM, Barnes, Peter D. <barnes26@llnl.gov> wrote:
<blockquote>I worked with Matt on this GSoC (gosh was it 4 years ago already?). This turned out to be more complex than we expected:

1. (should have been the easy part) Finding code to simulate noisy clocks. The simple thing would be to just sum samples from a Gaussian (or Poisson) for the actual tick size, but this would give an unrealistic Allen variance (just the noise portion, not the drift, which is typically more significant.)

2. Each Node has to support it’s own Scheduler, in local time. (This is so you don’t have to predict accumulated variation over long times, which makes #1 harder.[1])

3.a For every Now() call you have to decide if it should be GetLocalTime()
3.b For every Schedule() call you have to decide if it should be in local time or absolute time.

Happy to talk more,
Peter

[1] Longer explanation:

Suppose we’re at time 100 (absolute: 100_a), and want to schedule an event A for +100 (local: +100_l), which will end up at ~200_a. We could look up the Allan deviation for tau=100 (or equivalently the time deviation), and sample from that to determine the absolute delay to schedule the event.

Now the simulation proceeds and at time 110_a needs to schedule an event B for +80_l, which will end up ~190_a, so we follow the same process. The difficulty is that each event inserted before A subdivides the original interval, but the shorter intervals will no longer result in the intended Allan deviation. In this example we sampled at tau = 100_l, then tau = 80_l, leaving a gap of 10_l *which we didn’t sample from the full Allan deviation*

I think (but since I don’t understand#1 above it’s more like conjecture) that the right way is to store the events in a local-time schedule, then as we prepare to execute the next event E @ t_E,l, sample the noisy clock for t_E,l - t’_l (where t’_l is the local time of the previous event), in order to compute t_E,a, the absolute time of event E.
</blockquote>

== Possibly Relevant Literature ==

=== Series on the Dynamic Allan Variance ===
* "The Dynamic Allan Variance," L. Galleani, 2009. ([https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=4816055 pdf])
* "The Dynamic Allan Variance II: A Fast Computational Algorithm," L. Galleani, 2019. ([https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=5361540 pdf])
* "The Dynamic Allan Variance III: Confidence and Detection Surfaces," L. Galleani, 2019. ([https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=5995212 pdf])
* "The Dynamic Allan VarianceIV: Characterization of Atomic Clock Anomalies," L. Galleani, 2009. ([https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7103519 pdf])
* "The Dynamic Allan VarianceV: Recent Advances in Dynamic Stability Analysis," L. Galleani, 2009. ([https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7339453 pdf])

=== Simulation of Noisy Clocks ===
* "Discrete Simulation Of Power Law Noise," N.Jeremy Kasdin and Todd Walter, 1992. ([http://www.crya.unam.mx/radiolab/recursos/Allan/Kasdin-Walter.pdf pdf]) Includes C source code.
* "Discrete Simulation of Power Law Noise," Neil Ashby, 2011. ([https://arxiv.org/pdf/1103.5062.pdf pdf])
* colorednoise," Julia Leute, 2018. ([https://github.com/jleute/colorednoise colorednoise Github Python repo], now merged into next reference)
* "allantools," Anders Wallin, 2018. ([https://github.com/aewallin/allantools allantools Github Python repo])

GSOC2015MpTcpImplementation

2019-02-01T18:37:30Z

Pdbarnes: /* On the per node clock */ Link to Local Clocks page

{{TOC}}

Return to [[GSOC2015AcceptedProjects | GSoC 2015 Accepted Projects]] page.
== Project overview ==
* '''Project:''' Implementation of MPTCP (Multipath TCP) + Implementation of per-node clocks
* '''Student:''' Matthieu Coudron
* '''Mentors:''' [mailto:tomh@tomh.org Tom Henderson], Vedran Miletic, Tommaso Pecarolla, Peter Barnes
* '''Code:''' https://github.com/teto/ns-3-dev-git/tree/master (check out the different branches)
* '''About me:''' I am a PhD student working on multipath communications. I have a background in network and system security.

== On the MPTCP subject ==

Thanks to last year TCP option gsoc, it is possible to implement multipath TCP - an extension to TCP that is more and more popular (used in Apple voice recognition system "SIRI", embedded in yosemite, some Citrix products, soon to be embedded in Proximus products) - in a clean way.
MPTCP is available in some (possibly out of branch) kernels - Linux, Mac OS, FreeBSD - and work even with adversary middleboxes (Contrary to SCTP), which was an important challenge.
The 2nd challenge is still pending, ie, how to make the best usage of the path diversity ? How to be better than TCP without being more aggressive than TCP at bottlenecks ? I hope that being able to run MPTCP in a simulator could foster research on that peculiar subject since doing it with kernel code or creating a multihomed (3G/wired) setup can be complex (MPTCP kernel code is being refactored, and implementation is quite time consuming). There is no solution in the literature that answers this in a robust way.

Hi,

Here is a diff file of the beginning of one mptcp incomplete implementation based on ns3.19: http://downloads.tuxfamily.org/bluecosmos/ns3/final.patch. It was generated through this kind of
command (I just discovered the filterdiff utility, pretty cool):
diff -ENwbur ~/ns3off/src/internet src/internet > test.patch
cat test.patch | filterdiff -p0 -X toexclude.txt > final.patch

To help reviewers focus on the architecture, I removed some unnecessary files (but this is still a huge diff) and I add some comments in the following about MPTCP and the code.
To sum up, the main files to check are mptcp-socket-base.* and mptcp-subflow.* and the modifications made to tcp-socket-base.* .

1/ First of all, MPTCP doesn't require modifications to be modified, so does this implementation, it just appears as another TCP variant so the MPTCP socket works with all the code that can work with a TcpSocket.
2/ MPTCP is a TCP extension, all the signaling is done through TCP options
3/ The application sees a *fake* TCP socket usually called the "meta socket". This socket then dispatches the data to send among the different TCP connections of the MPTCP connection (usually called subflows)

TcpSocketBase
|-MpTcpSocketBase (this is the "meta socket", a logical socket that dispatches the send buffer between the different MpTcpSubflows, and reorder the segments received on the different subflows for the application to see)
|
|-MpTcpSubflow (This is a copy/paste of TcpNewReno except that it handles MPTCP logic, add/pop options when necessary)

4/ the standard demands that MPTCP should not be more greedy than TCP so there are congestion control algorithms specific to MPTCP. In the diff you just mptcp-cc-uncoupled. the way it's implemented, you subclass both MpTcpSocketBase and MpTcpSubflow into MpTcpSocketBaseUncoupled and MpTcpSubflowUncoupled.

5/ the path management files/classes are not used in the implementation and they don't have the same meaning as in the linux kernel, these classes are meant to attribute the unique IDs for each possible subflow (as required by the standard). In the linux kernel, path management modules implement policies as to yes or no should the meta establishes a new subflow.

6/ MPTCP has a global sequence number (to reassemble packets in order at the receiver) that is conveyed through a TCP option. Every TCP sequence number should be mapped to an "MPTCP sequence number". There are strict rules concerning these mappings: once a mapping is sent, it can't be changed, the data has to be sent, resent even if it was received on another subflow etc... the mapping is responsible for much complexity of the code. It means a mapping can't be removed as long as the whole data has not been received, and the data can not be passed to the upper layer because there may be a checksum covering the whole mapping.

Features required from ns3:
- Need to decorralate Tcp sender unacknowledged head (SND.UNA) from TcpTxBuffer
- MPTCP demultiplexing is not done on the 5 tuple but on the key
embedded in the MPTCP capable option
- it should be possible to set a memory size for the Meta buffer and
to share this space with subflows, ie it should be possible for TCP
buffers

One critical aspect of multipath protocols is the reordering problem that usually require larger buffer to get the same performance as single path protocols. The main challenge to simulate correctly MPTCP is to mimic linux buffer mechanisms (in my opinion).

Nb: MPTCP has many mechanisms to deal with middleboxes and such but I don't believe they are interesting to have in ns3 which should be used to analyze the algorithmic part, thus none of the failure mechanims are implemented (e.g. fallback to TCP in case the server is not MPTCP compliant etc...).

== On the per node clock ==
I would like to start implementing per node clock to be able to simulate time distribution protocols. Right now nodes are all perfectly synchronized ins ns3 (they share the simulator clocks). My goal is to be able to run NTPD in ns3-dce over ns3 nodes with drifting clocks. Time distribution experimentations are hard to do in practice (do you control 2 or more stratum 1 NTP servers ? and the traffic between these), I believe it makes sens and I know of no simulator that does it. This proposition is a follow up of my email to the dev ml: http://network-simulator-ns-2.7690.n7.nabble.com/Addition-of-per-node-clocks-in-ns3-td29301.html

More discussion of this topic is on the [[Local Clocks]] page.

= Expected deliverables =
While working on the previous projects I also intend to send patches to improve some parts of the ns3 code (such as the waf upgrade I sent last week).
I plan to work during the first half on the MPTCP code and then on the per-node clock integration. The MPTCP code has the priority though since this is the most awaited feature I believe.

== Validation ==
I intend to validate MPTCP against DCE. This may require some synergy with the TCP validation project.

== Week 1 - Step 1 ==
* Modify tcp-option.h to support MPTCP
* (de)Serialization of the numerous MPTCP options

== Week 2 - Deliverable for Step 1; start of Step 2 ==
* Add MPTCP crypto
The following was the initial plan but it may be postponed:
* Adapt TcpSocketBase to be more flexible (making all function virtual, overload some functions with TcpHeaders parameters instead of flags etc...)
* Same for TcpXxBuffer

== Week 3 - Step 2 ==
* Addition of test scripts, to trace buffers

== Week 4 - Step 2 ==
* put DCE infrastructure into place

== Week 5 - Deliverable for Step2 and Step 3 ==
* Implement linux MPTCP schedulers to be able to compare
* Implement OLIA/LIA congestion controls

== Week 6 - Step 3 ==
* MPTCP may still need some polishing at this point

== Week 7 - Deliverable for Step 3; start of Step 4 ==
* Addition of a Clock m_clock member in each Node.
** (Peter) Consider adding the clock by aggregation instead. I haven't thought this through, but I think aggregation will make it easier to manipulate the clock through the Config system, for example.
* Addition of a perfect clock (default behavior won't change)
* Addition of a drifting clock with initial offset

== Week 8 - Step 4 ==
* making ntpd work in DCE

== Week 9 - Step 4 ==
* making ntpd work in DCE (indeed: that looks complex)

== Week 10 - Step 4 and Deliverables for Step 3 and 4 ==
* test the whole thing
* Add some tests/documentation

= Weekly progress =

== Week 1 - Step 1 ==

Sticking the plan In summary, this week has delivered the following:

- (de)Serialization of the 7/8 mptcp options with their documentation
- Associated testsuite

The implementation of these message can found on the repository[1].For more
details check wiki[2].
During next week, while waiting for a clearer schedule over the mptcp
work I plan to:

- Add the pending mptcp crypto testsuite (depends on the discussion)
- Continue the work I've started in background over netlink export
from DCE. This is something I've started long ago but it proves quite
difficult, since wireshark can't dissect raw netlink, it expects it to
be contained within a "cooked linux" header that libpcap generates but
not DCE (yet). Current DCE netlink implementation does not work with
NTPd, that's why I look into it. (Netlink is the linux communication
protocol between kernel and userspace).
- Send some patches to DCE to support ntpd

[1] https://github.com/teto/ns-3-dev-git/tree/mptcp_options
[2] https://www.nsnam.org/wiki/GSOC2015MpTcpImplementation#Expected_deliverables

== Week 2 - Step 2 ==
This week has delivered the following:

- Generation of MPTCP token/initial sequence data number based on libgcrypt when available or an ns3 implementation not compliant with the standard). waf configure seems to detect correctly libgcrypt but it does not seem to pass on the -DENABLE_CRYPTO flag. This is something I have to look into
- Associated testsuite
- Generated a diff of the MPTCP implementation against ns3.19 to help reviewers get a feeling of the architecture.
- I also got more understanding of a DCE bug [0] .

The implementation of these message can found on the repository[1]. For more details check wiki[2]. This week end got surprisingly hectic for me so I did not have the time to clean my DCE tree, for next week:

- I have good hope to find & fix my DCE bug. Once this is done, I will have a respectable amount of code to clean and push.
- Fix the ENABLE_CRYPTO flag detection
- Review and maybe merge nat's code
- Try to generate mptcp graphs with DCE + linux kernel

[0] https://github.com/direct-code-execution/ns-3-dce/issues/2 
[1] https://github.com/teto/ns-3-dev-git/tree/libcrypto 
[2] https://www.nsnam.org/wiki/GSOC2015MpTcpImplementation#Expected_deliverables 

== Week 3 - Step 3 ==

This week has delivered the following:
- fixed the netlink bug described in [1] (to help me in that task, I
extended wireshark's netlink dissector[0])
- About the libgcrypt problem, it doesn't provide pkg-config so I
found a waf alternative that can check for its presence without it.
Test nearly finished.
- Rather than sending patches dependant on one another, I've pushed
the clock support code for dce [2] and ns3 [3]. This seems to launch
ntpd but I've no idea if it works
I've not had the time to look at mptcp dce as I had (ambitiously xD) proposed

For the upcoming week:
- prepare the mptcp crypto code for the 20 of june review
- understand if clock synchronization happens or not and fix what
needs to be fixed.

Matt

[0] https://code.wireshark.org/review/#/c/8916/1/epan/dissectors/packet-netlink.c
[1] https://github.com/direct-code-execution/ns-3-dce/issues/2
[2] https://github.com/teto/ns-3-dce/commits/clock_support
[3] https://github.com/teto/ns-3-dev-git/commits/clock_support

== Week 4 - Step 4 ==

This week has delivered the following:
- I have modified my testing script so that it can run with different
ntp programs : ntimed-client, ntpd, chronyd. Ntpd has a huge codebase
so I prefer to work for now with simpler programs ie chronyd & ntimed.
- Openntpd portable now can compile for DCE [1] but I have not tested it yet
- I wrote a script that evaluates the number of unimplemented DCE
syscalls compared to what a binary calls. It got merged in DCE [2]. It
can be interesting to evaluate the complexity of running a program
within DCE. It is worth mentioning so that all the missing syscalls do
not need to be implemented to run the program within DCE. For instance
the ntpd binary calls 80 syscalls missing from DCE but the part of the
program I use doesn't call these 80 syscalls so ntpd works fine.
- got some fixes on the mptcp crypto part [3]

I have not been able yet to draw plots about offsets of the clocks.
This is what I plan for the next week.
So far, programs can't steer the clock (adjtimex/settimeofday not
implemented) and this is something I also hope to accomplish for next
week but I have little idea about how complex it can be.

Matt

[0] https://code.wireshark.org/review/#/c/8916/1/epan/dissectors/packet-netlink.c
[1] https://github.com/openntpd-portable/openntpd-portable/issues/13
[2] https://github.com/direct-code-execution/ns-3-dce/pull/4
[3] https://github.com/teto/ns-3-dev-git/commits/libcrypto

== Midterm Report ==

The initial schedule of my gsoc got reversed due to the presence of the other TCP Gsoc. I preferred to wait for these changes to come first before rebasing my previous work on MPTCP. I am also eager to read comments about the architecture of the MPTCP implementation (link at the top of this page https://www.nsnam.org/wiki/GSOC2015MpTcpImplementation#On_the_MPTCP_subject).

Here is a list of repositories with the work done so far:
- https://github.com/teto/ns-3-dev-git/commits/libcrypto : this branch contains the code to a cleaned version of the mptcp options (de)serialization code. I've added some files about cryptographic processes used in MPTCP. I did not test this part extensively enough.
- https://github.com/teto/ns-3-dev-git/commits/clock_support WIP: This branch implements an aggregatable virtual clock that can be set on a per node basis. This can be used to modelize how node synchronization can play a role in different protocols. It can also be used with the following DCE version.
- https://github.com/teto/ns-3-dce/commits/clock_support . This DCE fork can't work without the specific ns3 branch previously mentioned. This branch fixes an important bug about the netlink implementation of DCE as well as adds documentation.

== Week 5 ==

This week hasn't delivered much in sound code as I was trying to
understand how to simulate the clock.
I've discovered the simulator [0] and proposed a similar way to
simulate time. It was rightfully objected by my mentors that it would
change ns3 into a timestep simulator. I had to come up with an
alternate design which still needs some feedback. My proposal is to
add Node::Schedule members that would convert node's time to
simulation time. Whenever the node's clock frequency is changed or
stepped, it should cancel the registered events and reregister them
with an updated simulator time.

Now the translation between node and simulator time is not that easy
even in the simple case to which I limit myself (I only plan to
support adjtime and not adjtimex). The clock's frequency has 3
potentially components: the background frequency + the ntp correction
+ a singleshot ntp correction that is removed as soon as the
singleshot offset is compensated for.

So for instance when translating from node's time to sim time, you
potentially have to distinguish between 2 phases, the one with the
singleshot frequency and the one without.

I've started some experimental implementation adding C++11 flags to
quickly relay Node::Schedule calls to Simulator::Schedule (replaced
with legacy templates if the branch proves successful). This doesn't
compile yet. My plan is to have a test for the clock conversion
covering different frequencies.

I've updated the wiki with the midterm report with mainly a patch for
mptcp options. I've added to it some crypto code so I would not advise
it for immediate inclusion (as I had previosuly done) since I am not
sure about how stable the crypto API will be.

[0] https://github.com/mlichvar/clknetsim
[1] https://www.nsnam.org/wiki/GSOC2015MpTcpImplementation#Midterm_Report
[2] https://github.com/teto/ns-3-dev-git/commits/clock_support

== Week 6 ==

This week thanks to the help of Peter, Steve & David, I've started the
API to allow scheduling events based on a node's clock. Instead of
using Simulator::Schedule, one would use Node::Schedule that would
relay these calls to Simulator::Schedule with a corrected timestep
depending on the node's clock. Compared to last week's design, we only
schedule the first node event in the node queue and as soon as that
event is finished, the next event of the node is pushed to the
simulator's queue. This way, if the frequency of the clock changes,
you only have one event (already pushed to the Simulator) that you
have to cancel & repush with a new timestep.

The idea was to write tests along the implementation. So I've started
writing 2 tests:
1/ One test is for the clock ("clock-test.cc"). It sets a frequency
and checks that the
clock time matches the tested skew against simulator time.
It is possible to change the frequency during the test to check that it
calls the test callback. It should also be possible to test against
timesteps but this is not implemented yet.
2/ The 2nd test is in "node-schedule-test" and is equivalent to
simulator-test-suite but with calls like m_node->Schedule( Time(3),
...).
It also checks that events trigger according to node's clock.
There are no Node::*Destroy functions as they don't seem fundamental yet.

The tests don't pass yet so for next week, the plan would be:
- to pass the simple cases
- as Nat finished the bulk changes on the TCP stack, to start working
on a rebase for MPTCP.

== Week 7 ==

As proposed in week 6:
- I fixed the clock tests so that they now pass [0].
- I submitted a patch to change a few things
in pcap handling to unblock some [1]
- started rebasing mptcp implementation on nat's branch [2]

My planning for next week is:
- to upstream most of the DCE changes I wrote during the first Gsoc
part (netlink fix, some syscalls, doc...)
- keep working on mptcp rebasing

Cheers
Matt

[0] https://github.com/teto/ns-3-dev-git/tree/clock_support
[1] https://github.com/teto/ns-3-dev-git/commits/netlink_ok
[2] https://github.com/teto/ns-3-dev-git/commit/f6cd305de0378b028d1ca9275a8f5d8b7835b437

== Week 8 ==
Hi,

I've not been able to complete the tasks partly because I had less time to work due to personal issues and the tasks I had in mind required someinteractions. I spent time to investigate how to improve the MPTCP codebase.
While the initial codebase copies a lot of code to minimize changes it makes it hard to maintain. Also the TCP changes made by Nat though interesting break how the initial MPTCP aware socket was created. Somehow this is a chance since it motivated me to look into MPTCP fallback. So far the user had to create an MPTCP socket and it would fail it the peer was not MPTCP compliant. I hope to minimize the
changes needed by the user to ease the use of MPTCP. This was not in the initial proposal and I've had a hard time defining an API but I believe we should do it as in the (linux) kernel:
-the client sends the MPTCP options during the SYN but does not
instantiate any MPTCP related structure
-upon SYN/ACK, it generates MPTCP structures, copies the current
socket (the copy becomes the "master" socket) and uses the socket seen
by the application as the metasocket

In the case of ns3, this approach is more problematic because of the Ptr<Socket> indirection. Thus I've used "placement new" to replace a TcpSocketBase instance with an MpTcpSocketBase. This is a bit tricky and this as far as I went.

So for next week to sum up, I have to:
-address comments on time simulation
-keep working on MPTCP

Cheers

Matt

[0] https://github.com/teto/ns-3-dev-git/tree/merge_nat

== Week 9 ==
Hi,

This week has been really tough in the sense I had to deal with 2
problems in domains I was not very confident with. First I had to
change the link order so that libgcrypt got linked first, which is not
that simple if you are not familiar with waf. Many thanks to Alex
Afanasyev who really saved me there. libgcrypt license is compatible
with ns3. As discussed on the mailing list, it is an optional
dependancy and it felt more natural than duplicating sha1 in ns3. This
should allow to read mptcp pcap in wireshark, which relies on the
token to identify subflows of a same connection.
The second problem I had was dealing with the placement new. It seemed
to create bugs in libc ("double linked list corrupted") and as I was
unsure it was valid C++ I looked at the libc code just to realize that
in fact I had left in the code a "CopyObject<TcpSocketBase>" that was
not allocating enough memory to convert this TcpSocketBase to a
MpTcpSocketBase.

As for the TCP design, what I've done is to remove the
TcpSocketBase::ReadOptions that was reading options even when the
packet was discarded later on. I contextualize option reading as in
linux with functions such as "ProcessTcpOptionsSynSent".
I've also introduced a function
"TcpSocketBase::IsTcpOptionEnabled(TcpOption::Kind)" which is easier
to remember than the boolean for each option.

As for next week, development should be a lot smoother:
- Vedranm pushed the patch that was preventing me to propose DCE PRs.
- I should be able to have a single subflow scenario running

Cheers
Matt

[0] https://github.com/teto/ns-3-dev-git/tree/merge_nat

== Week 10 ==
Hi,

This past week, I had planned to upstream some DCE code and I had to
hook HookDefaultSink with the (header,packet) version. Instead of
adding a new function in the PcapHelper, I thought ns3 could bind the
correct callback depending on the signature, something like if you
can't bind to X, try Y etc...

By the way, I don't know why this function is a template since it is
equivalent to "void PcapHelper::HookDefaultSink (Ptr<Object> object,
std::string tracename, Ptr<PcapFileWrapper> file)".

So I dived into TraceConnectWithoutContext details and the callback
mechanism. I looked into Callback::DoCheckType which is supposed to
compare callbacks but apparently it accepts any callback (if none is
set, it accepts and otherwise there is a dynamic_cast which I suspect
to always succeed even though callbacks are not compatible). All of
the compile time information disappear at runtime.
So my idea was to retain the difference in types within CallbackBase
since due to object slicing (during the upcast, the most derived
members disappear) usin virtual functions is "prohibited". My idea is
to set a member in CallbackBase that register std::type_info of
callback. I've made a first approach in a specifc branch that allows
to compare callbacks a lot better than the current ns3 [0]. The
drawback of the current approach is that it is not possible to run
typeid(*this) in Callback constructor since the object is being
constructed. Thus I run it afterwards but the problem is that if
MakeNullCallback was not called, then the type checks don't work
If we had C++11, we could use an std::tuple and it would always work
(I think). I understand the previous explanations may not make sense
at all but to sum up, the added callback compareasons in [1] would not
work without my changes. I don't think I will have the time to work
more on this so I put it on hold (since MPTCP takes precedence).

I've sent a patch [2] to flush pcap writing so that packets get
recorded even in case of a crash.

As for the MPTCP stack, I've kept on improving the design. IMO the
design is much better than the original one but doing so I broke many
features and I am slowly putting things in order again.
There used to be a mix between the meta socket and subflows while the
separation is now clearer with the meta socket really becoming a shim
layer, without any actual packet.
As such single path communications start sending data but the closing
phase it not working yet [3].

For the following week, I plan to fix the MPTCP closing phase so that
1 path communications work flawlessly and then move forward to the
multiple subflow case.

Matt

[0] https://github.com/teto/ns-3-dev-git/blob/add_sink_with_header
[1] https://github.com/teto/ns-3-dev-git/blob/add_sink_with_header/src/core/test/callback-test-suite.cc#L744
[2] https://github.com/nsnam/ns-3-dev-git/pull/3
[3] https://github.com/teto/ns-3-dev-git/tree/merge_nat

== Final review ==

This is my final report for the Gsoc 2015 on Clock support & MpTcp
Implementation on Linux.

I will sum up the work done and some propositions for the after Gsoc.
- During the first half of my Gsoc, I have been working on allowing
each node to run its own clock [0]. This way each node can have its
own time. It makes sense to test the difference in behavior of
protocols that depend on node synchronization. The clock takes some
parameters such as the raw frequency which can change over time. In
the end every event must be queued into the main simulator class. To
prevent the addition/update (when clock parameters change)/removal of
events, we only queue the next node event in the global Simulator.
Thus if the node clock change, it's enough to reschedule the event.
Once the event is fired, we schedule the next node event.
During this process, I also was able to run an unmodified ntpd (the
Nework Time Protocol daemon) in DCE with specific DCE patches [1].

- As for the Mptcp implementation, I got a much cleaner version then
the initial one. There is now a clear difference between the "meta
socket" (seen by the applications) and the TCP subflows (traditional
TCP connections). The old meta was sending packets etc... while now it
focuses on the logic between subflows. Also it used to be a modified
copy/paste of TcpSocketBase while now subflows and meta integrate with
it, resulting in less code duplication. I've also improved the
TCP/MPTCP compatiblity, i.e., MPTCP is now a TCP option like any other
while you used to create a specific MPTCP socket. For instance when
you had one MPTCP socket connecting to a legacy TCP one, it was
impossible before the Gsoc and now it is. [1] I managed to exchange a
file between 2 nodes with 1 subflow. The multiple subflow case is
trickier and while a second subflow can be established, I have to do
more testing before assessing anything else.

I've also sent a few patches to:
- upgrade waf to 1.8 (with vedran's help mostly)
- provided a script to allow YouCompleteMe (a vim completion engine)
to work with ns3

I don't think any of these 2 are ready for reviewing yet. Don't get me
wrong, I have working tests in each case but each project is
intertwined with other ns3 components (the TCP stack, DCE, event
handling) and thus require specific attention to the API. I don't
think I am quite there yet. Once I am I will clean/document the code
and send official reviews. You can already have a look at it but the
documentation may not be quite there yet.

Ns-3.29

2018-08-08T00:22:30Z

Pdbarnes: Add waf update

{{TOC}}

This page summarizes the release planning for ns-3.29. The ns-3 release process is listed [http://www.nsnam.org/developers/release-process/ here] and [[Release Process | here]].

= Release status =

ns-3.29 is rescheduled for August 2018.

= Current open issues =

The following is considered a blocker:

* (Bug 2930) Ubuntu 18.04 missing pygoocanvas package
** Tracked here: https://www.nsnam.org/bugzilla/show_bug.cgi?id=2930 Ankit is looking into remaining issue.

The following would be nice to have but probably not blockers:

* (Bug 2470) Block ack agreement handshake
** Pending issue with InactivityTimeout identified with Alexander
* (Bug 2960) Improve bindings toolchain installation via bake
** Tracked here: https://www.nsnam.org/bugzilla/show_bug.cgi?id=2960

* Steve would like to update waf to current (v2.0.9), patch coming. This will enable him to fix another issue: lack of MD5 in FIPS-compliant systems. Patch coming. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Ns-3 on Visual Studio

2018-05-11T21:57:52Z

Pdbarnes: /* Alternative Proposals */ comment

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code is an example of a header file that is not used and does not exist on Windows systems:

<nowiki>#ifndef _WIN32
#include <unistd.h>
#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

These questions need to be addressed.

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach will not work because gcc and Visual Studio do not use identical rules for name mangling of C++ objects. The --export-all output would be specfic to gcc and would not work for Visual Studio.

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#* ''As noted in the alternative proposal what the symbol resolves to depends on if the header file is being included in the module where the implementation resides or if it is used by another module to reference the module where the implementation resides.
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the<code>ATTRIBUTE_HELPER_*</code> macros have been extended. The <code>ATTRIBUTE_*</code> macros declare a three classes for each underlying type <code>X</code>: <code>XValue</code>, <code>XAccessor</code> and <code>XChecker</code>. These are impacted by the import/export tag discussed above. As a result, the tag for the module ''invoking'' the macro has to be passed through to the macro, so they now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the <code>ATTRIBUTE_HELPER_*</code> macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the <code>ATTRIBUTE_HELPER_*</code> macros locally within a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposals ====
Desirable attributes of any solution are:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

Could a refinement of the primary proposal be made to work?

* Auto-generate <code>ns3-modules.h</code> file (see below for a sketch)
** Which defines a unique numeric symbol for each module present in the build.

This file would be added to the hgignore file, so it never gets added to the repo.
By dynamically (at build time) assigning module numbers, we avoid numbering conflict from statically assigned module symbols, yet still facilitate simple (integer) comparisons between module tags and the current compilation unit tag.

This would enable a variation of an earlier (unworkable) proposal:

''build/ns3/ns3-modules.h:''
<nowiki>
/* This file autogenerated-do not edit. */

/* Make sure NS3_MODULE is undefined.
It will be defined by the file including this file. */
#ifdef NS3_MODULE
# undef NS3_MODULE
#endif

/* Define the module ids */
#ifndef NS3_MODULES_DEFINED
#define NS3_MODULES_DEFINED

#define NS3_ANTENNA_MODULE 1
#define NS3_AODV_MODULE 2
/* ... */

#endif /* NS3_MODULES_DEFINED */</nowiki>

''src/core/model/ns3-export.h:''
<nowiki>
/* No include guard. This is meant to appear many times
in a single compilation unit
*/

/* Usage:
Start each header with this three line block, after the last header inclusion (assuming this is the core module):
#include "ns3-modules.h"
#define NS3_MODULE NS3_CORE_MODULE
#include "ns3/ns3-export.h"

Label each class with

class NS3_EXPORT ...

The build system defines NS3_COMPILATION_MODULE to be
the current module being built.
*/

#ifdef NS3_EXPORT
# undef NS3_EXPORT
#endif

#if NS3_MODULE == NS3_COMPILATION_MODULE
# define NS3_EXPORT __declspec(dllexport)
#else
# define NS3_EXPORT __declspec(dllimport)
#endif </nowiki>

and an example source file:

''src/.../example.cc:''
<nowiki>
#include <iostream>
#include <iomanip>

// The build system:
#ifndef NS3_COMPILATION_MODULE
# define NS3_COMPILATION_MODULE NS3_AODV_MODULE
#endif

// A module header file:
#include "ns3-modules.h"
#define NS3_MODULE NS3_ANTENNA_MODULE
#include "ns3-export.h"

// Helpers for this demo
#define stringify_it( name ) # name
#define stringify(name) stringify_it(name)
#define doc(name) std::left << std::setw (20) << # name << "\t" << stringify (name) << "\n"

int
main (int argc, char** argv)
{

std::cout << doc (NS3_MODULE)
<< doc (NS3_COMPILATION_MODULE)
<< doc (NS3_EXPORT);

return 0;
} </nowiki>

Two example builds and runs:

<nowiki>
g++ example.cc -o example && ./example
NS3_MODULE 1
NS3_COMPILATION_MODULE 2
NS3_EXPORT __declspec(dllimport)

g++ example.cc -o example -DNS3_COMPILATION_MODULE=NS3_ANTENNA_MODULE && ./example
NS3_MODULE 1
NS3_COMPILATION_MODULE 1
NS3_EXPORT __declspec(dllexport) </nowiki>

This appears to address the requirements above, in a more direct way than the original proposal:

* All exported headers have the same three line block defining their module identity, between two ns-3 includes
* No core file listing all modules; it's auto-generated and only exists in the build tree.
* Works equally well with contrib modules, since <code>ns3-modules.h</code> is auto-generated at build time, when the modules are known.
* Works transparently through macros, including the <code>ATTRIBUTE_</code> macros.
**''This approach will work and the patch has been updated to use this approach with one exception. Autogenerating the file at build time wont work because that would cause every source file in the whole project to be recompiled every time any modification is made to any file because Visual Studio uses the file modification time to determine which files need to be compiled. Visual Studio doesn't provide an analog to ./waf configure to configure the project before build time.
** The file build/ns3/ns3-modules.h only needs to be created when the list of modules changes, not every build. How to achieve this in VS is up to you. If we can't solve this, we're stuck, because the original proposal to create src/core/ns3dll.h has the same issues (as well as other show-stoppers IMO).

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-05-01T16:20:37Z

Pdbarnes: /* Alternative Proposals */ add missing include line

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code is an example of a header file that is not used and does not exist on Windows systems:

<nowiki>#ifndef _WIN32
#include <unistd.h>
#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

These questions need to be addressed.

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach was not evaluated for two reasons, first the goal of the project was to set up a Visual Studio development environment that did not require any other tools or software beyond Visual Studio. Second, using an approach like this would eliminate developer control of what was exported. While this may not be an issue for core ns-3 modules, with a contributor model, contributor may not want to make all of the implementation visible or external.
** ''Exporting all symbols is the current behavior (with two possible exceptions, see below). What's wrong with keeping this as the default?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Is there room to modify the overall goals for the project? For example, instead of "pure VS environment" we could set the lower bar of "can be built and developed from VS", which leaves room for hybrid solutions, such as continuing to use waf, or other non-VS build tools/steps. In particular, this might enable us to do something like --export-all and leverage the list of exported headers already present in wscript to indicate what should be exported. This would provide the same granularity as presently available.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the<code>ATTRIBUTE_HELPER_*</code> macros have been extended. The <code>ATTRIBUTE_*</code> macros declare a three classes for each underlying type <code>X</code>: <code>XValue</code>, <code>XAccessor</code> and <code>XChecker</code>. These are impacted by the import/export tag discussed above. As a result, the tag for the module ''invoking'' the macro has to be passed through to the macro, so they now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the <code>ATTRIBUTE_HELPER_*</code> macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the <code>ATTRIBUTE_HELPER_*</code> macros locally within a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposals ====
Desirable attributes of any solution are:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

Could a refinement of the primary proposal be made to work?

* Auto-generate <code>ns3-modules.h</code> file (see below for a sketch)
** Which defines a unique numeric symbol for each module present in the build.

This file would be added to the hgignore file, so it never gets added to the repo.
By dynamically (at build time) assigning module numbers, we avoid numbering conflict from statically assigned module symbols, yet still facilitate simple (integer) comparisons between module tags and the current compilation unit tag.

This would enable a variation of an earlier (unworkable) proposal:

''build/ns3/ns3-modules.h:''
<nowiki>
/* This file autogenerated-do not edit. */

/* Make sure NS3_MODULE is undefined.
It will be defined by the file including this file. */
#ifdef NS3_MODULE
# undef NS3_MODULE
#endif

/* Define the module ids */
#ifndef NS3_MODULES_DEFINED
#define NS3_MODULES_DEFINED

#define NS3_ANTENNA_MODULE 1
#define NS3_AODV_MODULE 2
/* ... */

#endif /* NS3_MODULES_DEFINED */</nowiki>

''src/core/model/ns3-export.h:''
<nowiki>
/* No include guard. This is meant to appear many times
in a single compilation unit
*/

/* Usage:
Start each header with this three line block, after the last header inclusion (assuming this is the core module):
#include "ns3-modules.h"
#define NS3_MODULE NS3_CORE_MODULE
#include "ns3/ns3-export.h"

Label each class with

class NS3_EXPORT ...

The build system defines NS3_COMPILATION_MODULE to be
the current module being built.
*/

#ifdef NS3_EXPORT
# undef NS3_EXPORT
#endif

#if NS3_MODULE == NS3_COMPILATION_MODULE
# define NS3_EXPORT __declspec(dllexport)
#else
# define NS3_EXPORT __declspec(dllimport)
#endif </nowiki>

and an example source file:

''src/.../example.cc:''
<nowiki>
#include <iostream>
#include <iomanip>

// The build system:
#ifndef NS3_COMPILATION_MODULE
# define NS3_COMPILATION_MODULE NS3_AODV_MODULE
#endif

// A module header file:
#include "ns3-modules.h"
#define NS3_MODULE NS3_ANTENNA_MODULE
#include "ns3-export.h"

// Helpers for this demo
#define stringify_it( name ) # name
#define stringify(name) stringify_it(name)
#define doc(name) std::left << std::setw (20) << # name << "\t" << stringify (name) << "\n"

int
main (int argc, char** argv)
{

std::cout << doc (NS3_MODULE)
<< doc (NS3_COMPILATION_MODULE)
<< doc (NS3_EXPORT);

return 0;
} </nowiki>

Two example builds and runs:

<nowiki>
g++ example.cc -o example && ./example
NS3_MODULE 1
NS3_COMPILATION_MODULE 2
NS3_EXPORT __declspec(dllimport)

g++ example.cc -o example -DNS3_COMPILATION_MODULE=NS3_ANTENNA_MODULE && ./example
NS3_MODULE 1
NS3_COMPILATION_MODULE 1
NS3_EXPORT __declspec(dllexport) </nowiki>

This appears to address the requirements above, in a more direct way than the original proposal:

* All exported headers have the same three line block defining their module identity, between two ns-3 includes
* No core file listing all modules; it's auto-generated and only exists in the build tree.
* Works equally well with contrib modules, since <code>ns3-modules.h</code> is auto-generated at build time, when the modules are known.
* Works transparently through macros, including the <code>ATTRIBUTE_</code> macros.

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-04-30T21:40:48Z

Pdbarnes: /* Alternative Proposals */ New proposal

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code from CORE is an example of code changed for Windows to produce the same log output:

<nowiki>#ifndef _WIN32
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__FUNCTION__ << "(): "; \
} \

#else
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__func__ << "(): "; \
} \

#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

* ''In this particular case, GCC also accepts'' __FUNCTION__ '''(see [https://gcc.gnu.org/onlinedocs/gcc/Function-Names.html#Function-Names GCC Function Names]) so we don't need to make this change.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''This changes is modifying the use of'' __FUNCTION__ ''under GCC to'' __func__ ''under Visual Studio. Under Visual Studio,'' __FUNCTION__ ''includes the complete path name,'' __func__ ''matches what'' __FUNCTION__ ''under GCC does.'' [[User:rammon|Robert Ammon]]
** ''I'm suggesting we can avoid conditional code completely in this case. How important is it to show full path names in log messages? Finding the matching function is what IDE's, grep, Doxygen are for.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Now that I stare at the current code, I see we use __FUNCTION__ already, so even to get full paths why is any change needed?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''The purpose of the change is to make the Visual Studio implementation match the GCC implementation (and not include full path names under Visual Studio). If you want them to be different, we can do that but I don't think the user community is going to like the difference because it increases the size of the log files generated by a factor of 2 or 3 when the full path name of the EXE is included in each log message when function names are enabled.'' [[User: rammon|Robert Ammon]]
** ''Yet this patch shows __FUNCTION__ for WIN32, and __func__ for all others. It sounds like WIN32 should use __func__, in which case they can both use __func__, and no need for conditional compilation.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''You have the cases reversed, the conditional at the start of the block is'' #ifndef _WIN32 ''not'' #ifdef _WIN32.'' [[User: rammon|Robert Ammon]]
** ''Doh! In any case can't they both use the same symbol __func__?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''I don't have any way to verify the behavior on the non Windows platforms other than gcc on Ubuntu 16.04'' [[User: rammon|Robert Ammon]]
*** ''That's sufficient. Does it work?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

These questions need to be addressed.

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach was not evaluated for two reasons, first the goal of the project was to set up a Visual Studio development environment that did not require any other tools or software beyond Visual Studio. Second, using an approach like this would eliminate developer control of what was exported. While this may not be an issue for core ns-3 modules, with a contributor model, contributor may not want to make all of the implementation visible or external.
** ''Exporting all symbols is the current behavior (with two possible exceptions, see below). What's wrong with keeping this as the default?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Is there room to modify the overall goals for the project? For example, instead of "pure VS environment" we could set the lower bar of "can be built and developed from VS", which leaves room for hybrid solutions, such as continuing to use waf, or other non-VS build tools/steps. In particular, this might enable us to do something like --export-all and leverage the list of exported headers already present in wscript to indicate what should be exported. This would provide the same granularity as presently available.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the<code>ATTRIBUTE_HELPER_*</code> macros have been extended. The <code>ATTRIBUTE_*</code> macros declare a three classes for each underlying type <code>X</code>: <code>XValue</code>, <code>XAccessor</code> and <code>XChecker</code>. These are impacted by the import/export tag discussed above. As a result, the tag for the module ''invoking'' the macro has to be passed through to the macro, so they now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the <code>ATTRIBUTE_HELPER_*</code> macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the <code>ATTRIBUTE_HELPER_*</code> macros locally within a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposals ====
Desirable attributes of any solution are:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

Could a refinement of the primary proposal be made to work?

* Auto-generate <code>ns3-modules.h</code> file (see below for a sketch)
** Which defines a unique numeric symbol for each module present in the build.

This file would be added to the hgignore file, so it never gets added to the repo.
By dynamically (at build time) assigning module numbers, we avoid numbering conflict from statically assigned module symbols, yet still facilitate simple (integer) comparisons between module tags and the current compilation unit tag.

This would enable a variation of an earlier (unworkable) proposal:

''build/ns3/ns3-modules.h:''
<nowiki>
/* This file autogenerated-do not edit. */

/* Make sure NS3_MODULE is undefined.
It will be defined by the file including this file. */
#ifdef NS3_MODULE
# undef NS3_MODULE
#endif

/* Define the module ids */
#ifndef NS3_MODULES_DEFINED
#define NS3_MODULES_DEFINED

#define NS3_ANTENNA_MODULE 1
#define NS3_AODV_MODULE 2
/* ... */

#endif /* NS3_MODULES_DEFINED */</nowiki>

''src/core/model/ns3-export.h:''
<nowiki>
/* No include guard. This is meant to appear many times
in a single compilation unit
*/

/* Usage:
Start each header with (assuming this is the core module):
#define NS3_MODULE NS3_CORE_MODULE
#include "ns3/ns3-export.h"

Label each class with

class NS3_EXPORT ...

The build system defines NS3_COMPILATION_MODULE to be
the current module being built.
*/

#ifdef NS3_EXPORT
# undef NS3_EXPORT
#endif

#if NS3_MODULE == NS3_COMPILATION_MODULE
# define NS3_EXPORT __declspec(dllexport)
#else
# define NS3_EXPORT __declspec(dllimport)
#endif </nowiki>

and an example source file:

''src/.../example.cc:''
<nowiki>
#include <iostream>
#include <iomanip>

// The build system:
#ifndef NS3_COMPILATION_MODULE
# define NS3_COMPILATION_MODULE NS3_AODV_MODULE
#endif

// A module header file:
#include "ns3-modules.h"
#define NS3_MODULE NS3_ANTENNA_MODULE
#include "ns3-export.h"

// Helpers for this demo
#define stringify_it( name ) # name
#define stringify(name) stringify_it(name)
#define doc(name) std::left << std::setw (20) << # name << "\t" << stringify (name) << "\n"

int
main (int argc, char** argv)
{

std::cout << doc (NS3_MODULE)
<< doc (NS3_COMPILATION_MODULE)
<< doc (NS3_EXPORT);

return 0;
} </nowiki>

Two example builds and runs:

<nowiki>
g++ example.cc -o example && ./example
NS3_MODULE 1
NS3_COMPILATION_MODULE 2
NS3_EXPORT __declspec(dllimport)

g++ example.cc -o example -DNS3_COMPILATION_MODULE=NS3_ANTENNA_MODULE && ./example
NS3_MODULE 1
NS3_COMPILATION_MODULE 1
NS3_EXPORT __declspec(dllexport) </nowiki>

This appears to address the requirements above, in a more direct way than the original proposal:

* All exported headers have the same three line block defining their module identity, between two ns-3 includes
* No core file listing all modules; it's auto-generated and only exists in the build tree.
* Works equally well with contrib modules, since <code>ns3-modules.h</code> is auto-generated at build time, when the modules are known.
* Works transparently through macros, including the <code>ATTRIBUTE_</code> macros.

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-04-30T20:39:07Z

Pdbarnes: /* Proposed Method */

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code from CORE is an example of code changed for Windows to produce the same log output:

<nowiki>#ifndef _WIN32
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__FUNCTION__ << "(): "; \
} \

#else
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__func__ << "(): "; \
} \

#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

* ''In this particular case, GCC also accepts'' __FUNCTION__ '''(see [https://gcc.gnu.org/onlinedocs/gcc/Function-Names.html#Function-Names GCC Function Names]) so we don't need to make this change.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''This changes is modifying the use of'' __FUNCTION__ ''under GCC to'' __func__ ''under Visual Studio. Under Visual Studio,'' __FUNCTION__ ''includes the complete path name,'' __func__ ''matches what'' __FUNCTION__ ''under GCC does.'' [[User:rammon|Robert Ammon]]
** ''I'm suggesting we can avoid conditional code completely in this case. How important is it to show full path names in log messages? Finding the matching function is what IDE's, grep, Doxygen are for.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Now that I stare at the current code, I see we use __FUNCTION__ already, so even to get full paths why is any change needed?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''The purpose of the change is to make the Visual Studio implementation match the GCC implementation (and not include full path names under Visual Studio). If you want them to be different, we can do that but I don't think the user community is going to like the difference because it increases the size of the log files generated by a factor of 2 or 3 when the full path name of the EXE is included in each log message when function names are enabled.'' [[User: rammon|Robert Ammon]]
** ''Yet this patch shows __FUNCTION__ for WIN32, and __func__ for all others. It sounds like WIN32 should use __func__, in which case they can both use __func__, and no need for conditional compilation.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''You have the cases reversed, the conditional at the start of the block is'' #ifndef _WIN32 ''not'' #ifdef _WIN32.'' [[User: rammon|Robert Ammon]]
** ''Doh! In any case can't they both use the same symbol __func__?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''I don't have any way to verify the behavior on the non Windows platforms other than gcc on Ubuntu 16.04'' [[User: rammon|Robert Ammon]]
*** ''That's sufficient. Does it work?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

These questions need to be addressed.

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach was not evaluated for two reasons, first the goal of the project was to set up a Visual Studio development environment that did not require any other tools or software beyond Visual Studio. Second, using an approach like this would eliminate developer control of what was exported. While this may not be an issue for core ns-3 modules, with a contributor model, contributor may not want to make all of the implementation visible or external.
** ''Exporting all symbols is the current behavior (with two possible exceptions, see below). What's wrong with keeping this as the default?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Is there room to modify the overall goals for the project? For example, instead of "pure VS environment" we could set the lower bar of "can be built and developed from VS", which leaves room for hybrid solutions, such as continuing to use waf, or other non-VS build tools/steps. In particular, this might enable us to do something like --export-all and leverage the list of exported headers already present in wscript to indicate what should be exported. This would provide the same granularity as presently available.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the<code>ATTRIBUTE_HELPER_*</code> macros have been extended. The <code>ATTRIBUTE_*</code> macros declare a three classes for each underlying type <code>X</code>: <code>XValue</code>, <code>XAccessor</code> and <code>XChecker</code>. These are impacted by the import/export tag discussed above. As a result, the tag for the module ''invoking'' the macro has to be passed through to the macro, so they now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the <code>ATTRIBUTE_HELPER_*</code> macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the <code>ATTRIBUTE_HELPER_*</code> macros locally within a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposals ====
Desirable attributes of any solution are:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-04-30T20:37:48Z

Pdbarnes: /* Alternative Proposal */ Remove unworkable suggestion; leave the criteria

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code from CORE is an example of code changed for Windows to produce the same log output:

<nowiki>#ifndef _WIN32
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__FUNCTION__ << "(): "; \
} \

#else
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__func__ << "(): "; \
} \

#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

* ''In this particular case, GCC also accepts'' __FUNCTION__ '''(see [https://gcc.gnu.org/onlinedocs/gcc/Function-Names.html#Function-Names GCC Function Names]) so we don't need to make this change.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''This changes is modifying the use of'' __FUNCTION__ ''under GCC to'' __func__ ''under Visual Studio. Under Visual Studio,'' __FUNCTION__ ''includes the complete path name,'' __func__ ''matches what'' __FUNCTION__ ''under GCC does.'' [[User:rammon|Robert Ammon]]
** ''I'm suggesting we can avoid conditional code completely in this case. How important is it to show full path names in log messages? Finding the matching function is what IDE's, grep, Doxygen are for.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Now that I stare at the current code, I see we use __FUNCTION__ already, so even to get full paths why is any change needed?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''The purpose of the change is to make the Visual Studio implementation match the GCC implementation (and not include full path names under Visual Studio). If you want them to be different, we can do that but I don't think the user community is going to like the difference because it increases the size of the log files generated by a factor of 2 or 3 when the full path name of the EXE is included in each log message when function names are enabled.'' [[User: rammon|Robert Ammon]]
** ''Yet this patch shows __FUNCTION__ for WIN32, and __func__ for all others. It sounds like WIN32 should use __func__, in which case they can both use __func__, and no need for conditional compilation.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''You have the cases reversed, the conditional at the start of the block is'' #ifndef _WIN32 ''not'' #ifdef _WIN32.'' [[User: rammon|Robert Ammon]]
** ''Doh! In any case can't they both use the same symbol __func__?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''I don't have any way to verify the behavior on the non Windows platforms other than gcc on Ubuntu 16.04'' [[User: rammon|Robert Ammon]]
*** ''That's sufficient. Does it work?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach was not evaluated for two reasons, first the goal of the project was to set up a Visual Studio development environment that did not require any other tools or software beyond Visual Studio. Second, using an approach like this would eliminate developer control of what was exported. While this may not be an issue for core ns-3 modules, with a contributor model, contributor may not want to make all of the implementation visible or external.
** ''Exporting all symbols is the current behavior (with two possible exceptions, see below). What's wrong with keeping this as the default?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Is there room to modify the overall goals for the project? For example, instead of "pure VS environment" we could set the lower bar of "can be built and developed from VS", which leaves room for hybrid solutions, such as continuing to use waf, or other non-VS build tools/steps. In particular, this might enable us to do something like --export-all and leverage the list of exported headers already present in wscript to indicate what should be exported. This would provide the same granularity as presently available.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the<code>ATTRIBUTE_HELPER_*</code> macros have been extended. The <code>ATTRIBUTE_*</code> macros declare a three classes for each underlying type <code>X</code>: <code>XValue</code>, <code>XAccessor</code> and <code>XChecker</code>. These are impacted by the import/export tag discussed above. As a result, the tag for the module ''invoking'' the macro has to be passed through to the macro, so they now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the <code>ATTRIBUTE_HELPER_*</code> macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the <code>ATTRIBUTE_HELPER_*</code> macros locally within a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposals ====
Desirable attributes of any solution are:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-04-30T20:34:29Z

Pdbarnes: /* ATTRIBUTE_x Macro Modifications */ clarification

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code from CORE is an example of code changed for Windows to produce the same log output:

<nowiki>#ifndef _WIN32
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__FUNCTION__ << "(): "; \
} \

#else
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__func__ << "(): "; \
} \

#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

* ''In this particular case, GCC also accepts'' __FUNCTION__ '''(see [https://gcc.gnu.org/onlinedocs/gcc/Function-Names.html#Function-Names GCC Function Names]) so we don't need to make this change.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''This changes is modifying the use of'' __FUNCTION__ ''under GCC to'' __func__ ''under Visual Studio. Under Visual Studio,'' __FUNCTION__ ''includes the complete path name,'' __func__ ''matches what'' __FUNCTION__ ''under GCC does.'' [[User:rammon|Robert Ammon]]
** ''I'm suggesting we can avoid conditional code completely in this case. How important is it to show full path names in log messages? Finding the matching function is what IDE's, grep, Doxygen are for.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Now that I stare at the current code, I see we use __FUNCTION__ already, so even to get full paths why is any change needed?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''The purpose of the change is to make the Visual Studio implementation match the GCC implementation (and not include full path names under Visual Studio). If you want them to be different, we can do that but I don't think the user community is going to like the difference because it increases the size of the log files generated by a factor of 2 or 3 when the full path name of the EXE is included in each log message when function names are enabled.'' [[User: rammon|Robert Ammon]]
** ''Yet this patch shows __FUNCTION__ for WIN32, and __func__ for all others. It sounds like WIN32 should use __func__, in which case they can both use __func__, and no need for conditional compilation.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''You have the cases reversed, the conditional at the start of the block is'' #ifndef _WIN32 ''not'' #ifdef _WIN32.'' [[User: rammon|Robert Ammon]]
** ''Doh! In any case can't they both use the same symbol __func__?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''I don't have any way to verify the behavior on the non Windows platforms other than gcc on Ubuntu 16.04'' [[User: rammon|Robert Ammon]]
*** ''That's sufficient. Does it work?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach was not evaluated for two reasons, first the goal of the project was to set up a Visual Studio development environment that did not require any other tools or software beyond Visual Studio. Second, using an approach like this would eliminate developer control of what was exported. While this may not be an issue for core ns-3 modules, with a contributor model, contributor may not want to make all of the implementation visible or external.
** ''Exporting all symbols is the current behavior (with two possible exceptions, see below). What's wrong with keeping this as the default?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Is there room to modify the overall goals for the project? For example, instead of "pure VS environment" we could set the lower bar of "can be built and developed from VS", which leaves room for hybrid solutions, such as continuing to use waf, or other non-VS build tools/steps. In particular, this might enable us to do something like --export-all and leverage the list of exported headers already present in wscript to indicate what should be exported. This would provide the same granularity as presently available.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the<code>ATTRIBUTE_HELPER_*</code> macros have been extended. The <code>ATTRIBUTE_*</code> macros declare a three classes for each underlying type <code>X</code>: <code>XValue</code>, <code>XAccessor</code> and <code>XChecker</code>. These are impacted by the import/export tag discussed above. As a result, the tag for the module ''invoking'' the macro has to be passed through to the macro, so they now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the <code>ATTRIBUTE_HELPER_*</code> macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the <code>ATTRIBUTE_HELPER_*</code> macros locally within a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposal ====
This alternative has been proposed, but not implemented or tested.

''src/core/model/ns3-export.h:''
<nowiki>
// No include guard. This is meant to appear many times in a single compilation unit

/*Usage: start each header with:
#define NS3_MODULE myModule
#include "ns3/ns-export.h"

Label each class with

class NS3_EXPORT ...

Have waf define NS3_COMPILATION_MODULE as the current module.
(Or repurpose what it currently defines, NS3_MODULE_COMPILATION=1
to hold the module name.)
*/

#ifdef NS3_EXPORT
# undef NS3_EXPORT
#endif

# From
# https://stackoverflow.com/questions/2335888/how-to-compare-strings-in-c-conditional-preprocessor-directives
constexpr int
NS3_MODULE_STRCMP (char const* lhs, char const* rhs)
{
return (('\0' == lhs[0]) && ('\0' == rhs[0])) ? 0
: (lhs[0] != rhs[0]) ? ((int)lhs[0] - (int)rhs[0])
: NS3_MODULE_STRCMP ( lhs + 1, rhs + 1 );
}

#if 0 == NS3_MODULE_STRCMP (NS3_COMPILATION_MODUL, NS3_MODULE)
# define NS3_EXPORT __declspec(dllexport)
#else
# define NS3_EXPORT __declspec(dllimport)
#endif </nowiki>

This proposal would simplify the implementation somewhat:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-04-30T20:25:17Z

Pdbarnes: /* Alternative Solutions */ comment on goals

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code from CORE is an example of code changed for Windows to produce the same log output:

<nowiki>#ifndef _WIN32
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__FUNCTION__ << "(): "; \
} \

#else
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__func__ << "(): "; \
} \

#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

* ''In this particular case, GCC also accepts'' __FUNCTION__ '''(see [https://gcc.gnu.org/onlinedocs/gcc/Function-Names.html#Function-Names GCC Function Names]) so we don't need to make this change.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''This changes is modifying the use of'' __FUNCTION__ ''under GCC to'' __func__ ''under Visual Studio. Under Visual Studio,'' __FUNCTION__ ''includes the complete path name,'' __func__ ''matches what'' __FUNCTION__ ''under GCC does.'' [[User:rammon|Robert Ammon]]
** ''I'm suggesting we can avoid conditional code completely in this case. How important is it to show full path names in log messages? Finding the matching function is what IDE's, grep, Doxygen are for.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Now that I stare at the current code, I see we use __FUNCTION__ already, so even to get full paths why is any change needed?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''The purpose of the change is to make the Visual Studio implementation match the GCC implementation (and not include full path names under Visual Studio). If you want them to be different, we can do that but I don't think the user community is going to like the difference because it increases the size of the log files generated by a factor of 2 or 3 when the full path name of the EXE is included in each log message when function names are enabled.'' [[User: rammon|Robert Ammon]]
** ''Yet this patch shows __FUNCTION__ for WIN32, and __func__ for all others. It sounds like WIN32 should use __func__, in which case they can both use __func__, and no need for conditional compilation.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''You have the cases reversed, the conditional at the start of the block is'' #ifndef _WIN32 ''not'' #ifdef _WIN32.'' [[User: rammon|Robert Ammon]]
** ''Doh! In any case can't they both use the same symbol __func__?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''I don't have any way to verify the behavior on the non Windows platforms other than gcc on Ubuntu 16.04'' [[User: rammon|Robert Ammon]]
*** ''That's sufficient. Does it work?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach was not evaluated for two reasons, first the goal of the project was to set up a Visual Studio development environment that did not require any other tools or software beyond Visual Studio. Second, using an approach like this would eliminate developer control of what was exported. While this may not be an issue for core ns-3 modules, with a contributor model, contributor may not want to make all of the implementation visible or external.
** ''Exporting all symbols is the current behavior (with two possible exceptions, see below). What's wrong with keeping this as the default?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Is there room to modify the overall goals for the project? For example, instead of "pure VS environment" we could set the lower bar of "can be built and developed from VS", which leaves room for hybrid solutions, such as continuing to use waf, or other non-VS build tools/steps. In particular, this might enable us to do something like --export-all and leverage the list of exported headers already present in wscript to indicate what should be exported. This would provide the same granularity as presently available.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the ATTRIBUTE_HELPER_* macros have been extended. All ATTRIBUTE_HELPER_* macros now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the ATTRIBUTE_HELPER_* macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the ATTRIBUTE_HELPER_* macros locally with a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposal ====
This alternative has been proposed, but not implemented or tested.

''src/core/model/ns3-export.h:''
<nowiki>
// No include guard. This is meant to appear many times in a single compilation unit

/*Usage: start each header with:
#define NS3_MODULE myModule
#include "ns3/ns-export.h"

Label each class with

class NS3_EXPORT ...

Have waf define NS3_COMPILATION_MODULE as the current module.
(Or repurpose what it currently defines, NS3_MODULE_COMPILATION=1
to hold the module name.)
*/

#ifdef NS3_EXPORT
# undef NS3_EXPORT
#endif

# From
# https://stackoverflow.com/questions/2335888/how-to-compare-strings-in-c-conditional-preprocessor-directives
constexpr int
NS3_MODULE_STRCMP (char const* lhs, char const* rhs)
{
return (('\0' == lhs[0]) && ('\0' == rhs[0])) ? 0
: (lhs[0] != rhs[0]) ? ((int)lhs[0] - (int)rhs[0])
: NS3_MODULE_STRCMP ( lhs + 1, rhs + 1 );
}

#if 0 == NS3_MODULE_STRCMP (NS3_COMPILATION_MODUL, NS3_MODULE)
# define NS3_EXPORT __declspec(dllexport)
#else
# define NS3_EXPORT __declspec(dllimport)
#endif </nowiki>

This proposal would simplify the implementation somewhat:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-04-17T18:20:25Z

Pdbarnes: /* Phase 3 – Visual Studio Class Declaration Changes */ refactor discussion

{{TOC}}

This is a page to summarize the Visual Studio compatibility work that Robert Ammon initiated during the ns-3.28 release cycle, and continues towards ns-3.29.

Some previous ports for older versions of Visual Studio (2010, 2012) can be found by searching the wiki, but are no longer maintained.

The ns-3 tracker issue is https://www.nsnam.org/bugzilla/show_bug.cgi?id=2726. A per-module status table can be found at https://www.nsnam.org/bugzilla/attachment.cgi?id=3088. As of ns-3.28 release (March 2018), the project is still working through the Phase 1 patches.

== Summary of changes ==

The following provides a summary of the changes for the Visual Studio Development environment. It highlights the changes necessary to the existing NS-3 files to support development for Windows using Visual Studio.

To support integration of the changes in a more manageable fashion, the changes necessary for the VS development environment are segregated into four phases. The four phases are defined as

* Phase 1 – Visual Studio Compiler Warning Resolution
* Phase 2 – Visual Studio Windows Conditional Compilation
* Phase 3 – Visual Studio Class Declaration Changes
* Phase 4 – NS-3 Implementation Changes for Visual Studio

=== Phase 1 – Visual Studio Compiler Warning Resolution ===

The changes in this phase are changes to the existing NS-3 source code files to eliminate compiler warnings under Visual Studio. Under the Visual Studio development environment, all compiler warnings are treated s errors. The changes for this phase eliminate the compiler warnings under Visual Studio. The changes mostly fall into the following categories:

* Elimination of automatic type casts to lower resolution data types (for example uint16_t to uint8_t)
: These changes either add static cast declarations or modify the code (if possible) to eliminate the need for a type case

* Elimination of unused function parameters
: These changes either eliminate the unused parameters (if possible) or add NS_UNUSED references to the parameter.

* Elimination of hidden variables (for example, a for loop using index i inside of a for loop using index i)
: These changes rename the inner variable that is hiding the outer variable.

The Phase 1 changes will be applied in first before the Phase 2, Phase 3 and Phase 4 changes. The Phase 1 changes apply to the majority of the NS-3 modules but not all modules.

=== Phase 2 – Visual Studio Windows Conditional Compilation ===
The changes in this phase are changes to the existing NS-3 source code files to add conditional code for the Visual Studio development environment. These changes add code that is executed under the Windows configuration only.

For example, the following code from CORE is an example of code changed for Windows to produce the same log output:

<nowiki>#ifndef _WIN32
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__FUNCTION__ << "(): "; \
} \

#else
#define NS_LOG_APPEND_FUNC_PREFIX \
if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC)) \
{ \
std::clog << g_log.Name () << ":" << \
__func__ << "(): "; \
} \

#endif</nowiki>

The modifications in this phase affect a minority of the NS-3 source code files.

* ''In this particular case, GCC also accepts'' __FUNCTION__ '''(see [https://gcc.gnu.org/onlinedocs/gcc/Function-Names.html#Function-Names GCC Function Names]) so we don't need to make this change.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''This changes is modifying the use of'' __FUNCTION__ ''under GCC to'' __func__ ''under Visual Studio. Under Visual Studio,'' __FUNCTION__ ''includes the complete path name,'' __func__ ''matches what'' __FUNCTION__ ''under GCC does.'' [[User:rammon|Robert Ammon]]
** ''I'm suggesting we can avoid conditional code completely in this case. How important is it to show full path names in log messages? Finding the matching function is what IDE's, grep, Doxygen are for.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''Now that I stare at the current code, I see we use __FUNCTION__ already, so even to get full paths why is any change needed?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''The purpose of the change is to make the Visual Studio implementation match the GCC implementation (and not include full path names under Visual Studio). If you want them to be different, we can do that but I don't think the user community is going to like the difference because it increases the size of the log files generated by a factor of 2 or 3 when the full path name of the EXE is included in each log message when function names are enabled.'' [[User: rammon|Robert Ammon]]
** ''Yet this patch shows __FUNCTION__ for WIN32, and __func__ for all others. It sounds like WIN32 should use __func__, in which case they can both use __func__, and no need for conditional compilation.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''You have the cases reversed, the conditional at the start of the block is'' #ifndef _WIN32 ''not'' #ifdef _WIN32.'' [[User: rammon|Robert Ammon]]
** ''Doh! In any case can't they both use the same symbol __func__?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
** ''I don't have any way to verify the behavior on the non Windows platforms other than gcc on Ubuntu 16.04'' [[User: rammon|Robert Ammon]]
*** ''That's sufficient. Does it work?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

=== Phase 3 – Visual Studio Class Declaration Changes ===
While the Windows DLLs are similar to the Unix shared libraries, there are a couple of significant differences between them. One of the differences which cause changes in the ns-3 source code is items in a Windows DLL are hidden from consumers of the DLL unless specifically identified as exported items. This means that the classes in the ns-3 modules that are accessible by other ns-3 modules or user programs.

Here is an example provided by Peter Barnes that illustrates the issue. Assuming you have the following code:

''src/foo/model/foo.h:''
<nowiki>
class foo
{
...
}; // class foo </nowiki>

''src/bar/model/bar.h:''
<nowiki>
#include “ns3/foo.h”
class bar
{
...
}; // class bar </nowiki>

When compiling module foo, the symbols in foo.h should be labeled <code>dllexport</code> (because the implementation lives in this executable unit foo which is a separate DLL). When compiling bar.cc, those same symbols in foo.h should be labeled <code>dllimport</code> (because the implementation is located in a different execution unit, the DLL containing bar needs to import them from the DLL containing foo). In the specific case of ns-3, each module is a separate DLL so references to a class that is exposed for consumption by other executable units (DLLs or programs) need to change this declaration depending on what's being compiled.

==== Proposed Method ====
This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

''src/core/ns3dll.h code fragment''
<nowiki>
#ifndef NS3DLL_H
#define NS3DLL_H

#ifdef _WIN32
# ifdef _ANT
# define NS3ANTLIB __declspec(dllexport)
# else
# define NS3ANTLIB __declspec(dllimport)
# endif
...
#else /* _WIN32 */
# define NS3ANTLIB
...
#endif /* _WIN32 */

#endif /* NS3DLL_H */</nowiki>

* ''Clarification:'' <code>NS3ANTLIB</code> ''refers to the antenna module. In the current proposal a stanza like this exists for every module. The build system toggles the'' <code>_MODULE</code> ''flag for the module DLL currently being built, so its symbols are marked'' <code>dllexport</code>'', while symbols in all other headers (which this module depends on) are marked'' <code>dllimport</code>. [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
* ''Here's a decent discussion: https://gcc.gnu.org/wiki/Visibility'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

Each exported symbol needs the corresponding module export/import token as a label. Here is an example class declaration:

<nowiki>class NS3ANTLIB AntennaModel : public Object</nowiki>

This approach has these drawbacks:
* Every module needs a mention in a core file, ns3dll.h
* Not clear what to do with contrib modules. Does bake have to know how to insert contrib modules in this core file?
* How do we prevent modified ns3dll.h files from being pushed accidentally?

==== Alternative Solutions ====
A question that has been received is "are there are other ways to indicate export/import"?

(1) For Microsoft Windows targets there are alternative methods for including the symbol in the DLL’s export table such as using a .def file with an EXPORTS section

* ''This will work, but the names in the EXPORTS section must be the "object code" names of the items. Remember that in C++, the actual names of functions, global variables, classes, etc. are NOT the names assigned in the source code, they are decorated names created by the compiler. In order to use a .def file for this, a developer would have to know the compiler decorated name of the item. Also, Microsoft strongly recommends that the decorated names NOT be used by developers since the scheme used to create the decorated name by the compiler can change with a new compiler version ''
** ''Agreed, manually updating mangled names is a bad idea. Can this be automated?`` [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

(2) With GNU ld, using the --export-all linker flag

* ''This approach was not evaluated for two reasons, first the goal of the project was to set up a Visual Studio development environment that did not require any other tools or software beyond Visual Studio. Second, using an approach like this would eliminate developer control of what was exported. While this may not be an issue for core ns-3 modules, with a contributor model, contributor may not want to make all of the implementation visible or external.
** ''Exporting all symbols is the current behavior (with two possible exceptions, see below). What's wrong with keeping this as the default?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])

==== Digression on Current Symbol Export ====
The current behavior is to export all symbols in headers listed in wscript:
<nowiki>
headers = bld(features='ns3header')
headers.module = 'internet'
headers.source = [
''model/udp-header.h',
...</nowiki >

Private headers are simply not listed, so they are not copied to <code>build/ns3/</code> and so aren't visible outside the declaring module.

An alternative method is to include a "private header" stanza in wscript (see a remnant from <nowiki>src/internet/wscript</nowiki>):
<nowiki>
privateheaders = bld(features='ns3privateheader')
privateheaders.module = 'internet'
privateheaders.source = [
] </nowiki>

This feature is not used at the moment. It was used at one point to expose a private (non-exported) header to test code.

==== Questions/Discussion ====
# Can this use the existing NS3_MODULE_x symbol for the declaration?
#* ''Any name can be used for the export / import symbol name. The names chosen and list in ns3dll.h were created by me to be short (since they have to be added to the source code) yet provide enough detail on what they represent.
# Why does the value of the symbol need to be dynamic?
#Why don't all headers include ns3dll.h?
#* ''All headers need the declarations provided in ns3dll.h. If ns3dll.h is included by another header file that is included in the header file (either directly or indirectly), it has already been included and adding it to the header file is not necessary. NOTE: There is no reason that this header file could not be included in every other header file, the patches submitted for review only included this file where it was necessary to reduce the size of the changes.

==== ATTRIBUTE_x Macro Modifications ====
Another example is all of the ATTRIBUTE_HELPER_* macros have been extended. All ATTRIBUTE_HELPER_* macros now have an additional parameter (same one as previous section) that defines the DLL the "implementation" is located in. The following is an example from the CORE module. Use of any of the ATTRIBUTE_HELPER_* macros within a base ns-3 module require the new macro with the additional parameter.
<nowiki>
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);</nowiki>

Note: Use of the ATTRIBUTE_HELPER_* macros locally with a program continue to use the previous macro and parameter sequence. An example is the following code from attribute-test-suite.c

<nowiki>
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);</nowiki>

The modifications in this phase affect almost every header file in the ns-3 source code.

==== Alternative Proposal ====
This alternative has been proposed, but not implemented or tested.

''src/core/model/ns3-export.h:''
<nowiki>
// No include guard. This is meant to appear many times in a single compilation unit

/*Usage: start each header with:
#define NS3_MODULE myModule
#include "ns3/ns-export.h"

Label each class with

class NS3_EXPORT ...

Have waf define NS3_COMPILATION_MODULE as the current module.
(Or repurpose what it currently defines, NS3_MODULE_COMPILATION=1
to hold the module name.)
*/

#ifdef NS3_EXPORT
# undef NS3_EXPORT
#endif

# From
# https://stackoverflow.com/questions/2335888/how-to-compare-strings-in-c-conditional-preprocessor-directives
constexpr int
NS3_MODULE_STRCMP (char const* lhs, char const* rhs)
{
return (('\0' == lhs[0]) && ('\0' == rhs[0])) ? 0
: (lhs[0] != rhs[0]) ? ((int)lhs[0] - (int)rhs[0])
: NS3_MODULE_STRCMP ( lhs + 1, rhs + 1 );
}

#if 0 == NS3_MODULE_STRCMP (NS3_COMPILATION_MODUL, NS3_MODULE)
# define NS3_EXPORT __declspec(dllexport)
#else
# define NS3_EXPORT __declspec(dllimport)
#endif </nowiki>

This proposal would simplify the implementation somewhat:
* All (exported) headers would have a common format
* No need to mention every module in a core file (ns3dll.h)
* Scales to contrib modules
* No need to extend the ATTRIBUTE_x macros

=== Phase 4 – NS-3 Implementation Changes for Visual Studio ===

In a few of the NS-3 implementations, there are differences in the implementation between Linux and Windows. These are cases where the same source code does not produce the exact same results, either to differences in the OS, third party libraries of compiler code generation. For these changes, the source code has been modified to produce equivalent behavior on all platforms that matches the original implementation.

The number of changes in this phase are limited to a few examples.

Ns-3 on Visual Studio

2018-04-17T17:05:21Z

Pdbarnes: /* Phase 2 – Visual Studio Windows Conditional Compilation */ comment on __FUNCTION__

Ns-3 on Visual Studio

2018-04-12T23:49:43Z

Pdbarnes: /* Phase 2 – Visual Studio Windows Conditional Compilation */ comment/Q

Ns-3 on Visual Studio

2018-04-06T19:43:05Z

Pdbarnes: /* Phase 2 – Visual Studio Windows Conditional Compilation */ typo

Ns-3 on Visual Studio

2018-04-06T19:42:36Z

Pdbarnes: /* Phase 2 – Visual Studio Windows Conditional Compilation */ comment/Q

Ns-3 on Visual Studio

2018-04-06T19:30:12Z

Pdbarnes: /* Phase 2 – Visual Studio Windows Conditional Compilation */ comment/Q

Ns-3 on Visual Studio

2018-04-06T00:39:09Z

Pdbarnes: /* Phase 2 – Visual Studio Windows Conditional Compilation */ comment on __FUNCTION__

Ns-3 on Visual Studio

2018-04-05T19:06:33Z

Pdbarnes: comments

Ns-3 on Visual Studio

2018-04-05T18:50:28Z

Pdbarnes: /* Loading DLLs */ comments

Ns-3 on Visual Studio

2018-04-04T18:46:54Z

Pdbarnes: /* Phase 3 – Visual Studio Class Declaration Changes */ Clarification and background on DLL import/export machinery

Ns-3 on Visual Studio

2018-04-04T18:24:00Z

Pdbarnes: /* Phase 2 – Visual Studio Windows Conditional Compilation */ Questions to clarify the requirements

Ns-3-users-guidelines-for-posting

2017-03-10T18:15:15Z

Pdbarnes: /* Preliminaries */ Add exceptions and crashes section

{{TOC}}

== Preliminaries ==

This is the short form of our posting guide. More lengthy explanations are in section 2.

=== Do your homework ===

==== Work through the [https://www.nsnam.org/ns-3-24/documentation/ tutorial], all of it ====
==== Read the [http://www.nsnam.org/documentation documentation] about models and the reference manual ====
==== Search the [https://groups.google.com/forum/#!forum/ns-3-users Google Groups] to see if your question was asked before ====

=== Subjects/topics ===

==== Search for related discussions ====

Add to existing threads if the last reply is less than a year old. If older than a year, start a new thread, specifically linking to the prior thread.

==== Use a specific subject line ====

Do not ask unrelated questions in reply to a topic about something else. Start a new thread with a specific subject line.

=== Information to include in your message ===

==== Platform ====

If you are reporting a problem such as a installation failure, please report enough details about your platform to allow a maintainer to reproduce.

==== Source Code ====

Use the attachment feature for posting scripts; only short snippets (less than 10 lines) should be inline.

Create the simplest possible script which illustrates the issue you are facing.

It’s almost always impossible to give a helpful reply when looking at a snippet from a larger script, or worse a snippet which refers to code models not part of the distribution.

If there is the remotest chance you changed something in an ns-3 module, state that up front. Attach your modified files and a minimal main script that triggers the problem.

==== Exceptions and Crashes ====

Exceptions and crashes are a normal part of debugging. Learn to use a debugger; this isn't the right place to ask what to do next when the <tt>gdb></tt> prompt appears. When someone (or an error message) suggests running your script in a debugger, expect to do some work to learn more about what's going on, beyond just the stack trace. it's almost always impossible to make useful suggestions from just that. Don't waste everyone's time, including yours, by just posting it and asking for help. Reread the previous section on [[#Source Code]].

== Posting Guide: How to ask good questions that prompt useful answers ==

This is the long form of the posting guide, summarized above.

This guide is intended to make more productive use of the ns-3-users group by recommending best practices for posting questions and answers. Please keep in mind that over 5000 people subscribe to this group, so it is common courtesy to follow this guidance.

If one of the project maintainers responds to your question by citing this guide, please re-read the guidance before asking your question again.

This guide is freely adapted from the R Posting Guide (http://www.r-project.org/posting-guide.html)

=== Good manners: ===

ns-3 is open source software, constructed and maintained by volunteers. They have various reasons for contributing software and participating on the group, but often have limited time. Please help them quickly understand the details about your problem, and please avoid asking questions that have already been answered.

Follow etiquette and professionalism guidelines found in [https://www.ietf.org/rfc/rfc1855.txt RFC1855] and [https://www.ietf.org/rfc/rfc7704.txt RFC7704]. Please read these if you haven't already.

Customs differ. Some people are very direct. Others surround everything they say with hedges and apologies. Be tolerant. Rudeness is never warranted, but sometimes `read the manual' ''is'' the appropriate response. Don't waste time discussing such matters on the list. Ad hominem comments are absolutely out of place.

Note: if moderators find posts that lack etiquette or professionalism, we will follow an escalation path that will result in private and/or public warnings, and eventual ban from the group if behavior is not modified.

=== Which group (or mailing list)?: ===

ns-3-users or ns-developers? There are two widely used mailing lists for questions and discussion about ns-3.

* '''ns-3-users''' is intended for people who want to use ns-3 but who are not necessarily interested in developing new or extending existing modules for public release.
* '''ns-developers''' is intended for questions and discussion about code development in ns-3, new features, etc.

Questions such as "Does ns-3 support <insert-protocol-model> because I'd like to reuse it if so?" should always be asked on ns-3-users. Questions such as "Is anyone developing a model of <insert-protocol-model> for contributing back to ns-3?" are appropriate for ns-developers or ns-3-users.

New users, or users seeking help in performing a particular task are probably more comfortable with ns-3-users. The ns-developers mailing list is friendly as well, but it assumes that you have some knowledge of ns-3, and out-of-scope posts will usually be redirected to ns-3-users.

Please do not post the same message to both lists; pick one. ns-3 maintainers read both lists.

The ns-3-users group primarily intended for questions and discussion about the ns-3 software. However, questions about networking protocols are sometimes posted. If the question is well-asked and of interest to someone on the list, it may elicit an informative up-to-date answer.

=== Do your homework before posting: ===

If it is clear that you have done basic background research and searched already for the answer, you are far more likely to get an informative response.

* Search the ns-3-users group. The web interface has a nice search feature, use it.
* Search the web. Use your preferred search engine, you may find good tips.
* Search the ns-3 wiki, manual and Doxygen.
* For ''any'' result found, pay attention to the post date. Some posts are about very old ns-3 versions, and the solution may not be working anymore. Or the problem may have been fixed altogether.
* When possible, always use the latest ns-3 release. If you are using an older release, please try to reproduce your problem on the most recent release or development code to see if it has already been fixed.
* If you have doubts that something changed from release to release, consult the ns-3 changes file (it is named CHANGES.html).
* If you search for help for an unsupported module (e.g., one not distributed with ns-3-allinone), contact the module developer first.

=== Useful posting tips: ===

In order to have more chances to have a fast and meaningful answer, please do the following:

* Use an informative subject line (not something like `question', or 'help me').
* Do not ask another unrelated question by replying to an existing thread with a different subject line; start a new thread instead.
* Don't expect a reply in hours. Feel free to bump the question, but only after a couple of days.
* Only reply to ''recent'' threads (less then 1 year old).
* The more threads you ask the same question in, the ''less'' you will receive an answer.
* Do not include more than 10 lines of code in the message. The group allows attachments, use them.
* The ns-3-users group is not the best place to ask basic C++ questions.
* If relevant, state clearly the ns-3 version, compiler version, OS (type and version). If you're in doubt if it's relevant, then it is.
** the ns-3 version can be found in RELEASE_NOTES, the compiler version from ''g++ --version'' and the OS type/version from ''uname -a''
* Some consider it good manners to include a concise signature specifying your affiliation, but this is not required.

=== Surprising behavior and bugs: ===

What you think is a bug may be many other things, such as a default behavior that you do not like, a feature, an undocumented feature, or a bug in the documentation.
If you think you have found a bug, feel free to discuss about it in the ns-3-users group. In order to simplify the bug processing, please try to do the following:

* Search the ns-3 Bugzilla for similar bugs. In case, feel free to ask for the estimated resolution time.
* Debug your script. Using gdb or any debugger GUI is mandatory to discriminate between a ns-3 bug and a mistake in the user's script.
* Simplify the offending script to the bare minimum. Try to reproduce reliably the misbehaviour in the very latest ns-3 version, possibly ns-3-dev.
* When opening or replying to a bug, remember that:
*# Any bug is maximum priority for who found it, but it may not be for others. Be realistic.
*# Clearly state what was the expected behaviour and the one you got.
*# Include a script showing the bug.
*# Bugs are fixed in ns-3-dev. Make sure that your bug is present in ns-3-dev.
*# If possible, include a patch...

=== Responding to other posts: ===

* Rudeness and ad hominem comments are not acceptable. Brevity is OK.
* Take care when you quote other people's comments to respect their rights. In particular:
** Private (non-group or non-list) messages should never be quoted or forwarded to a list without the author's permission. Don't assume "it is OK"-- always ask first.
** The original authorship and meaning should always be clear.
* It is common practice to quote prior messages in entirety.
* If you edit the quoted text from prior messages, include sufficient context so that the content is clear even if your archived message is referenced at a much later date and in isolation from other messages.
* When responding to a very simple question, use the following algorithm:
** Check if someone else posted a reply. If the question has just arrived in your inbox, wait half an hour.
** If no one has posted a reply, then post your reply.
* Use professional writing guidelines to convey information in a clear, efficient way
** No profanity, and never do jokes about sex, religion, culture, or about someone's misuse of the English language. You can be funny without being offensive.
** Avoid interactions that could be considered to be harassing or mocking someone else. If you are interacting with someone who you feel is not making a fair effort to follow the list guidelines, it is best to just stop replying further, rather than to post something out of anger or frustration or to try to get the last word in.
** Keep in mind also, if writers are trying their best not to be offensive, readers should try not to be offended too easily.
** Do not plead (e.g., repeatedly asking the same question or with capitalization or many exclamation points) if you do not get the answer you want as quickly as you may want it.
* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.

=== Common posting mistakes: ===

* Missing or non-specific message subject
* Not doing basic homework before posting a question
* Not being more specific than `function xxx doesn't work'
* Being overly specific and not stating your real goal; there may be another solution if your underlying goal is better understood
* Not including version and OS information in question regarding unexpected behavior.
* Finding a bug in an old version of ns-3 that has been fixed in the most recent version.
* Claiming that something is a bug when in fact the software is working as intended and documented, just not in the way you first expected.
* Threatening not to use the software if you cannot get your question answered. Even when intended as a statement of fact, this tends to create negative attitudes.
* Posting the same question more than once per day (in different threads).

=== Basic networking and classroom homework: ===

The ns-3 user group is not intended for basic networking or classroom homework. Feel free to ask questions, but don't ask to help solving a class assignment (it's cheating, and your teacher will find it).

=== Announcements: ===

Job postings specific to ns-3 (e.g. postdoctoral or professional appointments related to ns-3 specifically) are allowed. General job postings unrelated to ns-3 are inappropriate.

Calls for participation in events related to ns-3 (e.g. Workshop on ns-3, or other simulation/emulation workshops where ns-3 would be considered a mainstream topic) are allowed. General conference/workshop/journal call for papers are inappropriate.

=== Final words: ===

It is a skill to ask good questions. If at first you don't get the answers that are useful to you, don't get discouraged. A response that is concise and technically accurate may be just that, and not an intended putdown. If you feel insulted by some response to a post of yours, don't make any hasty response in return - you're more likely than not to regret it. Read Eric Raymond's essay [http://www.catb.org/esr/faqs/smart-questions.html How To Ask Questions The Smart Way] for more suggestions, and for insight into people's behavior on technical mailing lists.

Posters should be aware that the ns-3 lists are public discussion lists and anything you post will be archived and accessible via several websites for many years, and we cannot remove any posts (it is a Google service).

BakeIntegration

2017-02-23T19:09:33Z

Pdbarnes: add link to spack

{{TOC}}

This page is for describing functional requirements of the [http://www-sop.inria.fr/members/Daniel.Camara/bake/ bake tool] for [http://www.nsnam.org/wiki/index.php/Ns-3.26 ns-3.26] and for future releases.

= Background and Motivation =

Presently, ns-3 has a large backlog of unmerged contributed code, and the build of ns-3 can take very long, including modules that are not of interest to most users. We therefore want to move the project towards a more modular arrangement of 'core' modules and 'contributed' modules, and a more user-friendly way of tailoring the build of ns-3 to a specific user's needs. We need a build orchestration tool to facilitate this.

bake.py is a tool developed at INRIA to orchestrate the Direct Code Execution (DCE) build. It was developed with some goals of generality (e.g. ns-3-specific constructs were avoided), but in practice is only being used these days to build DCE and some optional components of the ns-3-allinone build. bake.py is a build orchestration tool, in that it is not a build tool like 'make' or 'Waf', but instead calls to those build tools to orchestrate a build of several libraries in a correct order. bake.py was developed because the available build orchestration tools examined at the time of development were considered to be insufficient to meet the requirements.

For the ns-3.27 release, we want to take the step towards making a number of contributed ns-3 modules readily available. We do not have time in this release cycle to create the perfect tool or transition away from bake to another build orchestration tool for ns-3.27, so we will prioritize getting something reasonably usable in place for ns-3.27, with as many modules enabled as we have time to do, and study later whether we want to make a bigger change such as moving to an externally supported build orchestration tool such as nixpkgs, or work on binary package management.

= Executive summary =

#. ns-3 will add a 'contrib/' directory in parallel with 'src/'; contrib/ will be the landing spot for contributed modules
#* Patch pending in https://www.nsnam.org/bugzilla/show_bug.cgi?id=2630
#. contributed modules will be organized according to the standard module layout and hosted somewhere on the web (tar archives, github, bitbucket, etc.)
#. a small bake XML configuration file will tell bake how to download the new module into contrib/, and will be available to express any other library dependencies of the module. These XML files will be stored in 'bake/contrib' directory.
#* Patch pending in https://www.nsnam.org/bugzilla/show_bug.cgi?id=2631
#. users will tailor their contributed module downloads using the bake tool; users will continue to tailor their ns-3 build using Waf
#. modules will become more stand-alone, with ability to run Sphinx documentation and Doxygen on them independently.
#* create-module.py program can migrate from src/ to contrib/ directory and extended to generate initial bake module XML
#. we will start with a small set of such modules for ns-3.27 initial release and add them throughout the year. Tentative modules for ns-3.27:
#* Magister's Satellite Network Simulator 3 (SNS3)
#* UAN integration with World Ocean Simulation System (WOSS)
#* SiFT routing
#* Routes Mobility Model
#* (others TBD)

Development repos:

1) ns-3-modular: This contains the ns-3 contrib patch
https://bitbucket.org/tomhend/ns-3-dev-modular

2) bake-modular: This contains the bake contrib patch
https://bitbucket.org/tomhend/bake-modular

3) sift-ns3: This is a sample contrib module, for testing purposes
https://bitbucket.org/tomhend/sift-ns3

= How bake is used now =

Bake is used to construct a virtual environment for DCE. Users can request the enabling of one or more modules, and bake will check for needed system dependencies, will perform the download of libraries that are not system dependencies, can locally patch downloaded libraries if needed, can build and install libraries into a local bin and lib directory, and can build ns-3.

The below shows how this is basically done today.

1) ./bake.py check
2) export BAKE_HOME=`pwd`
3) export PATH=$PATH:$BAKE_HOME:$BAKE_HOME/build/bin
4) export PYTHONPATH=$PYTHONPATH:$BAKE_HOME:$BAKE_HOME/build/lib
5) ./bake.py configure -e dce-linux-1.8 -e dce-quagga-1.8
6) ./bake.py show
7) ./bake.py download
8) ./bake.py build

Bake will, in turn:

1) check that necessary bake prerequisites are filled

2-4) set environment variables so that bake, the python modules, and the built libraries can be found by the user's shell

5) create a bakefile.xml after the configure step, caching the user's configuration details, and selecting the DCE Linux and quagga modules and their module dependencies

6) show the enabled modules and their dependencies

7) download the module sources into a 'source' directory

8) build, using the module's native build tool, within each module's source directory, and perform a 'make install' into a local 'build' directory containing a 'bin', 'lib', and 'include' directory for the built components

Users can recurse into the source/ns-3-dce directory to start using this directly; that is, bake.py can be thought of as the step to get a custom development environment in place, then it can get out of the way and users can just use Waf at the ns-3 level.

The user's shell keeps track of where bake and its installed components live via environment variables
LD_LIBRARY_PATH, PATH, and PYTHONPATH.

= Proposed changes for ns-3.27 =

The basic goal is to add a 'contrib' directory for contributed modules, and to publish metadata about available contributed modules. Some of these modules will be pure ns-3 modules; some will have additional library dependencies that bake can coordinate. Users should be able to easily discover the list of available modules and pick the ones of interest. Contributors who work with the release manager can get their module descriptions published, but will host their code at the location of their choice (e.g. github, bitbucket, or their departmental web server).

As a concrete example, let's assume that [[RoutesMobilityModel | routes mobility model]] and [https://codereview.appspot.com/13831049/ epidemic routing] are two modules of interest to a future ns-3.27 user. ns-3.27 will be distributed with all existing modules as before, but not with these contributed modules. Upon downloading the base ns-3.27, the directory structure will be the same as before:

$ ls ns-3.27/src/
antenna dsdv netanim test
aodv dsr network topology-read
...

but there will be a sparse contrib/ directory with a build script and a create-module program:

$ ls ns-3.27/contrib/
create-module.py wscript

Let's assume that the user uses bake to download 'routes-mobility-model' and 'epidemic-routing' modules as contributed modules. After doing so, the following will show up under a 'contrib' directory:

$ ls ns-3.26/contrib/
create-module.py epidemic-routing routes-mobility-model wscript

All Waf commands will treat the 'src/' and 'contrib/' directories equally; that is, Waf will operate on the union of 'src/' and 'contrib/' when performing operations like building documentation, enabling or disabling modules, etc. As a consequence, providers of contributed modules need to ensure that their modules behave as if they were located in the src/ directory.

== Module discovery ==

The next topic is to describe how users will discover that contributed modules are available to be added to their build.

First, the project will maintain documentation on the web site about the status and availability of contributed modules, on a per-release basis, so users who go to the main documentation page for ns-3.27 would see a pointer to an HTML page with a listing of contributed modules compatible with that release (perhaps other details such as testing status, etc.).

Users will also be able to discover available modules through bake.py. To enable this, bake module description will be extended with an 'ns-contrib' module type.

./bake.py list --contrib
contrib: epidemic-routing
contrib: routes-mobility-model

In practice, the above will be more fully populated with many contrib modules and version numbering of them.

== Example ==

To work through a concrete example, suppose the user obtains the base ns-3 with pybindgen and netanim (current defaults for allinone), the user will do:

./bake.py configure -e ns-allinone-3.27
./bake.py show

which outputs:

....
module: ns-allinone-3.27 (enabled)
depends on:
netanim-3.107 (optional:True)
pybindgen-0.17.0.post49+ng0e4e3bc (optional:True)
pyviz-prerequisites (optional:True)
ns-3.27 (optional:False)
...

We can use a new command 'list' to show available modules, and sub-commands specialized to the ns-3 contributed modules.

./bake.py list

/* lists all modules in the bakefile */

./bake.py list --contrib

/* list all modules of type 'ns-contrib'; e.g.
contrib: routes-mobility-model
*/

In the future (not for ns-3.27), we may append some version information about the compatibility of the modules, with minimum and maximum ns-3 versions. Let's assume that epidemic-routing went unmaintained and stopped working with ns-3 versions greater than 3.25, but routes-mobility-model is always maintained to stay compatible with the latest release. The user doing a

./bake.py list contrib

would see something like this:

module name version minimum ns-3 version maximum ns-3 version
... ... ... ...
routes-mobility-model 1.0 3.25 unspecified
epidemic-routing 0.9.1 3.23 3.26
... ... ... ...

To further specialize this list, the user could then list all contrib specific to ns-3.25

./bake.py list contrib 3.25

and the above list would be filtered to include only those available for ns-3.25 (not implemented yet).

We should also support some filtering to get specific information, such as making the following to be equivalent:

./bake.py list | grep epidemic
./bake.py list epidemic
./bake.py list epi

To get more information about any module, we can support a new 'info' command, with support for extensions:

./bake.py info epidemic
./bake.py info epi

would print out something based on the metadata found in the XML:

module: epidemic-routing
description: ...
homepage: ...
version: ...
minimum-ns-3-version: ...
maximum-ns-3-version: ...
...

and if these information fields are missing in the XML, they will simply not print out.

The next steps would be to actually configure the contributed modules to 'enabled' status, so that they are downloaded to the src/contrib directory when ./bake.py download is called.

We aim to support an API like this, using the '-e' option to configure to support the adding of contributed modules. In general, we aim to not require (but still allow) users to specify the contributed module version, as follows:

./bake.py configure -c
./bake.py show /* should result in an empty config */

./bake.py configure -a routes-mobility-model
> Error: Module "routes-mobility-model" has unmet dependency: ns-3.27

./bake.py configure -e ns-3.27 /* Now I have a base of ns-3.27 module, and I can add to it */

./bake.py configure -e pybindgen /* add python bindings support */

./bake.py configure -e routes-mobility-model /* add routes-mobility-model to build */

./bake.py configure -e epidemic-prime
Error: epidemic-prime not found for ns-3.27

./bake.py configure -d routes-mobility-model /* remove routes-mobility-model from configuration */

./bake.py show /* should show now that ns-3.27 and pybindgen are configured */

Enabling of modules can also be done on a single statement:

./bake.py configure -e ns-3.25 -e pybindgen -e routes-mobility-model -e epidemic-routing

= Open issues =

What modules go into the ns-allinone package in the future, if not the universe of compatible libraries and extensions? I would lean towards requiring that contrib modules be fetched online and that we do not bundle the universe but define a minimum set, like we do today.

How this relates to binary package distribution/preparation is TBD.

Whether we try to replace bake with something like [https://nixos.org/nixpkgs/manual/ nixpkgs] or [https://spack.readthedocs.io/en/latest/ spack] TBD.

HOWTO use the ConfigStore

2016-09-21T20:34:03Z

Pdbarnes: add command line to read in a config file

==File-based ConfigStore==
You need your simulation program to be written like this:
<pre>
int main (...)
{
CommandLine cmd;
cmd.Parse (...);

ConfigStore config;
config.ConfigureDefaults ();

... topology creation

config.ConfigureAttributes ();

Simulator::Run ();
}
</pre>

then run your simulation program with the following parameters to save a plain text file (in this example, config.txt):
<pre>
./waf --run "scratch/myprogram --ns3::ConfigStore::Mode=Save --ns3::ConfigStore::Filename=config.txt"
</pre>

and to read in a configuration
<pre>
./waf --run "scratch/myprogram --ns3::ConfigStore::Mode=Load --ns3::ConfigStore::FileFormat==RawText --ns3::ConfigStore::Filename=config.txt"
</pre>

==GtkConfigStore==

You need your simulation program to be written like this:
<pre>
int main (...)
{

... topology creation

GtkConfigStore configstore;
configstore.ConfigureAttributes();

Simulator::Run ();
}
</pre>

Then before the simulation runs a window will pop up allowing you to browse Object attributes and to save/load the configuration.

Project Ideas

2016-09-21T20:31:00Z

Pdbarnes: fix broken email link

{{TOC}}

One way to get involved with ns-3 is to work with a mentor on a suggested project. These are typically project suggestions that would be valued contributions but the proposer does not have enough time to do it himself or herself, but is willing to mentor someone else to do it.

Another possibility for students is to get involved in the [http://code.google.com/soc/ Google Summer of Code] program. This program is administered by Google and acceptance is competitive.

How does a mentored project work? You contact the mentor and describe your interests and availability to work on the module. You and the mentor will work out a plan to regularly review and discuss the development of your module, following the [https://www.nsnam.org/docs/manual/html/new-modules.html guidelines for developing new models for ns-3]. You will set up a public repository somewhere such as [http://mercurial.selenic.com/wiki/MercurialHosting a site listed here] or your own mercurial server.

Not all projects are mentored, nor do they all need to be. Please suggest new project ideas on this page and whether you would mentor them.

= Introductory projects =

This project category is for smaller, simpler projects for new developers to get started. If you would like to work on one of these, please coordinate with the named mentor.

== Sockets should support the setting of QoS ==

'''Mentor''': [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

References:
* http://groups.google.com/group/ns-3-users/browse_thread/thread/5be010835c4b5b71
* https://www.nsnam.org/bugzilla/show_bug.cgi?id=1361

== Reducing header dependencies ==

'''Mentor''': [mailto:tomh@tomh.org Tom Henderson]

Bug [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1832 1832] describes some software maintenance that could be performed on ns-3, to reduce unnecessary header dependencies. Patches are welcome for even a small part of the overall solution.

I would suggest to adapt deheader and place it in utils/deheader.py. Running utils/deheader.py should list all the unnecessary includes, and let the maintainers decide whether they want to go clean these up.

Daniel Camara performed this work already, but the work was not finished and merged. Bug 1832 has the details.

References:
* http://www.catb.org/~esr/deheader/
* http://code.google.com/p/include-what-you-use/

== Fixing Doxygen errors and warnings ==

'''Mentor''': [mailto:tomh@tomh.org Tom Henderson], [mailto:rivanvx@gmail.com Vedran Miletic], or [mailto:pdbarnes@llnl.gov Peter Barnes]

Bug [https://www.nsnam.org/bugzilla/show_bug.cgi?id=938 938] describes an overall effort to eliminate Doxygen warnings (primarily, for missing Doxygen) from our modules. Any patches that contribute to the overall goal would be welcome. Contact one of the mentors if interested.

= Projects needing completion =

Some projects were started in the past and never brought to completion.

== Wifi rate control example ==

ns-3 supports many different wifi rate controls, but there isn't a good example program that allows users to clearly contrast the performance of different ones. The example program 'examples/wireless/multirate.cc' does this a little bit, but it focuses on sampling the throughput.

The suggested project is to work with improving multirate.cc so that users can clearly see the difference between selecting the different rate control algorithms, perhaps by running for longer amount of time and finding a way to plot the rate chosen by the control algorithm as a function of time.

== Perfect ARP ==

[https://www.nsnam.org/bugzilla/show_bug.cgi?id=187 Bug 187] has a patch that needs further review, updating to ns-3-dev, and finishing off. The enhancement is described as follows:

We need an implementation of ARP which avoids the generation of ARP request/reply packets and assumes a 'perfect' ARP table is always available and up-to-date.

== IPv6 Routing ==

'''Mentor''': [mailto:tomh@tomh.org Tom Henderson], [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella],

There is little support for global (i.e. god) routing routing for IPv6. This was started in a 2011 ns-3 summer of code project.
IPv6 can use Dynamic routing (RIPng is included in ns-3.20), but more protocols are welcome.

However, global routing is still needed. Moreover, all the ad-hoc routing protocols are currently IPv4-only.

== Refactor AODV Hello ==

[https://www.nsnam.org/bugzilla/show_bug.cgi?id=1188 Bug 1188] describes a problem with the current AODV implementation that Hellos are sent even without any active routes.

We would like for someone to align our implementation with the AODV RFC (or with working implementations) in this regard.

'''Mentor''': [mailto:nikkipui@gmail.com Daniel Lertpratchya]

= Mentored projects =

This section lists project ideas for which there is interest by an ns-3 developer or maintainer to serve as a mentor in the development of a new feature for ns-3.

Please do not apply for mentoring help on a class project unless you have approval from the instructor to receive mentoring.

== Decouple traffic generation from sockets ==

'''Mentor''': [mailto:tomh@tomh.org Tom Henderson]

All ns-3 simulations are IP based but there is no template for how to do this for non-IP-based stacks. One issue that should be addressed in the long term is that applications that generate traffic are strongly coupled to the sockets interface. It would be nice to decouple the traffic generation aspects of these applications from the sockets-related code.

#* ''summary'': Proposed decoupling to generalize applications
#* ''ns-developers post'': http://mailman.isi.edu/pipermail/ns-developers/2007-July/003136.html
#* ''code location'': http://code.nsnam.org/laprisee/ns-3-mp/
#* ''status'': Was under discussion in the summer.
#:

== SCTP (Stream Control Transmission Protocol) ==

'''Mentor''': [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella]

[http://en.wikipedia.org/wiki/Stream_Control_Transmission_Protocol SCTP] is a message-based L4 protocol with features similar to both TCP and UDP. It was originally developed as a reliable protocol to transport PSTN control streams, and it's currently used to carry 3G and 4G signaling over IP networks. The use of SCTP, however, is not limited to signaling transport, as its features makes it very interesting for a lot of other applications where UDP or TCP fails.
Currently there is no SCTP implementation for ns-3. An SCTP implementation would have to comply with the IPv4 and IPv6 layers and have programming APIs toward the application layer similar to the ones defined in the available SCTP implementations for Linux.
* Required Experience: C++
* Bonus Experience: L4 protocols understanding
* Interests: L4 protocols modeling and simulation
* Difficulty: medium
* Recommended reading:
** [http://tools.ietf.org/html/rfc3286 RFC 3286] An Introduction to the Stream Control Transmission Protocol
** [http://tools.ietf.org/html/rfc6458 RFC 6458] Sockets API Extensions for the Stream Control Transmission Protocol
** all the relevant RFCs about SCTP

= Feature requests =

The following projects have been suggested in the past. If you are working on them, please let us know on the developers or users list so that we can coordinate activities. If you want to add a project, please describe it below.

== Path MTU discovery ==

When a L4 packet is passed to the IPv4 or IPv6 stacks, the MTU (i.e., the size of the outgoing IP packets) is usually set to the local interface MTU. Or so it is the popular belief. Using the local interface MTU might lead to IP-level fragmentation, more overhead, and poor network performance.+

As a consequence, multiple techniques to discover the end-to-end MTU (called Path MTU) are available.
The current PMTU discovery ns-3 capability status is listed below.

=== Path MTU discovery for IPv4 stacks ===

'''Status:''' Being worked on by Vedran Miletic

There is no [http://en.wikipedia.org/wiki/Path_MTU_discovery path MTU discovery] implemented for IPv4. This makes guessing the end-to-end MTU imperative for ns-3 simulations. We would welcome a contribution that introduced path MTU discovery to ns-3.

Vedran expressed interest in working on PMTU discovery.

=== Path MTU discovery for IPv6 stacks ===

[http://en.wikipedia.org/wiki/Path_MTU_discovery path MTU discovery] is implemented in ns-3's IPv6 stack.

=== Packetization Layer Path MTU Discovery ===
[http://tools.ietf.org/html/rfc4821 RFC 4821] describes a method to detect PMTU at packetization (i.e., L4) level. This is another good candidate to be implemented.

=== L4 compliance with PMTU ===
Even if IPv6 is able to detect PMTU, and IPv4 could be, currently there is no API to probe for a specific PMTU from L4 (e.g., UDP, TCP, etc.).
Moreover, TCP is blind with respect to PMTU. I.e., its MSS (Maximum Segment Size) is fixed.

In order to reproduce real TCP performance it is of paramount importance to:

# Define an API to be used by L4 protocols, for PMTU probing.
# Update TCP to react to PMTU changes (dynamic MSS).
# Update TCP to not decrement its Congestion Window upon losses due to PMTU discovery (especially important for IPv6).

== DSR RFC compliance ==

'''Note:''' As of June 2015, Gaurangi Saxena is working on this (see: http://mailman.isi.edu/pipermail/ns-developers/2015-June/012842.html).

The ns-3 DSR implementation is not following strictly the [http://datatracker.ietf.org/doc/rfc4728/ RFC 4728]. The topic has been briefly discussed in [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1895 bug# 1895].

It would be nice to have a switch to change from the current behaviour to the "RFC-strict" behaviour.
As a byproduct, DSR could be updated to support IPv6. Although not explicitly stated by the rFC, DSR can be used for IPv6 as well.

Ns-3.26

2016-09-21T20:26:51Z

Pdbarnes: add Tentative section, and bug 2507

{{TOC}}

This page summarizes the release planning for ns-3.26 (originally planned for June 2016; rescheduled to early September 2016). The ns-3 release process is listed [http://www.nsnam.org/developers/release-process/ here] and [[Release Process | here]].

This page has been recently revised and some original goals for ns-3.26 have slipped to a new [[ns-3.27]] page.

= Revised schedule =

The revised (again) schedule is as follows:

* code freeze once outstanding issues resolved
* release shortly afterwards

= Remaining issues being worked for ns-3.26 =

(Updated Sept 21)

There are a few interrelated bugs in wifi that must be fixed (2493, 2477, 2306, 2369), and there is a small bindings generation problem; after those are fixed we can make a release candidate.

* <s>(multiple modules): fix warnings due to Wstrict-overflow across codebase</s> this is resolved for ns-3.26
* <s>aodv: merge patch to 2123 (Tommaso)</s>
* <s>core: merge patch to 2459 on ./waf --check-config (Peter)</s>
* <s>core: resolve attribute errors/attribute spaces/attribute deprecation (issues 2447, 2344, 2149) (Tom and Peter)</s>
* <s>internet: global routing and bridging bug 2102 reopened (Tom)</s>
* <s> network: investigate recent packet metadata bugs (2407, 2415), fix if solution found shortly (Tom)</s> can't reproduce on ns-3-dev; marking as NEEDINFO
* <s>mobility: check and merge patch to 2390 (on waypoint mobility) (Tom)</s>
* wifi: merge patch to 2306 and update AODV regression traces (Tom)
** Patch pending and being tested
* wave: merge patch to 2314 (related to 2306) (Tom)
** This depends on fixing 2306
* wifi: investigate DCF assert bug 2477; will fix if solution found shortly (Tom)
** Patch pending and being tested
* wifi: investigate DCF assert bug 2493; will fix if solution found shortly (Tom)
** Patch pending and being tested
* wifi: Supported Rates bug (https://www.nsnam.org/bugzilla/show_bug.cgi?id=2496)
** Patch pending and being tested
* wifi: Immediate access patch
** Patch pending and being tested
* <s>uan: merge patch to 2488 (Tom)</s>

== Tentative ==
* config-store: [https://www.nsnam.org/bugzilla/show_bug.cgi?id=2507 bug 2507]: ConfigStore RawTextConfigLoad doesn't reset stream error state
** Patch pending, has been tested

Doxygen-warnings

2016-01-25T19:36:39Z

Pdbarnes: /* Hnts and tips */ Clarify oxygen.warnings.report.sh options for reducing the volume of output

{{TOC}}

= Doxygen warning removal =

This page is to help coordinating the efforts in fixing [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].

As a followup of [[Sprints|Friday November 15 ns-3 Sprint]], we'd like to coordinate the efforts of Doxygen warning removal.

It must be pointed out that warning removing is not good per-se. It is a way to complete the documentation and make it better. 

Undocumented functions leads to poor coding and, ultimately, not be able to use the ns-3 full power. 

Moreover, bad or missing documentation means '''bugs''' !

= Doxygen work status =
The following table might seems overwhelming. And the warning are just the ones in the model and helper folders. 

However, mind that many are chain-warnings, meaning that once you fix the master one in the base class, many of them will disappear. More on that at the bottom of the page.

The current doxygen warning status, by module is:
{| class="wikitable"
|-
! Number of warnings !! Module !! Who's working on it
|-

| 3369 || lte ||
|-
| 1523 || wimax ||
|-
| 840 || wifi || Daniel L.
|-
| 521 || mesh ||
|-
| 459 || visualizer ||
|-
| 236 || dsr ||
|-
| 227 || netanim ||
|-
| 211 || wave ||
|-
| 210 || spectrum ||
|-
| 195 || olsr ||
|-
| 127 || aodv ||
|-
| 108 || config-store ||
|-
| 98 || buildings ||
|-
| 90 || mpi ||
|-
| 87 || energy ||
|-
| 74 || dsdv ||
|-
| 46 || openflow ||
|-
| 28 || brite ||
|-
| 22 || nix-vector-routing ||
|-
| 20 || network ||
|-
| 18 || antenna ||
|-
| 17 || virtual-net-device ||
|-
| 15 || internet ||
|-
| 2 || propagation ||
|-
| 2 || sixlowpan ||
|-
| 2 || topology ||
|}

= How to proceed =
The procedure is simple.
# Post online that you're working on a module. Eventually coordinate with who's already working on the same module.
# Follow the direction in the [[Sprints|Sprint]] page to setup Doxygen to show you the warnings.
# Start with base classes. Mind that ''virtual'' functions can (and should) be documented only in the base class.
# Don't be afraid of the numbers. I was able to kill 1400 warnings in 2 days (just in my spare time).
# Once you have a patch, post it in Bugzilla: [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].
# Go drink a beer, you deserve it.

= Hint and tips =

The <tt>doxygen.warnings.report.sh</tt> script will make a long list of warnings. You're probably interested in the ones from a single module. The script has a number of options which can help:

$ doc/doxygen.warnings.report.sh -h
...
Usage: doxygen.warnings.report.sh [-eithv] [-s <log-file> | -l | -w] [-m <module>] [-f <regex>] [-F <regex>]
...
-e Filter out warnings from */examples/*
-t Filter out warnings from */test/*
-m Only include files matching src/<module>
-f Only include files matching the <regex>
-F Exclude files matching the <regex>

Note the <tt>-m <module></tt>, <tt>-e</tt> and <tt>-t</tt> options. The <tt>-m <module></tt> will show the full warning messages from just files in <tt>src/<module></tt>.

Now you have a shorter list of bugs to work with. Cut out the ones from the tests and examples (or not, depends on how pedantic you are). Those are your warnings to kill.

= User's opinions =

Some time ago I did a poll, an I asked the users the documentation they need most. Here is the result.

[[File:UsersPollResults.png]]

--[[User:Tommaso|Tommaso]] ([[User talk:Tommaso|talk]]) 16:29, 26 November 2013 (EST)

Doxygen-warnings

2015-11-13T06:03:36Z

Pdbarnes: /* Doxygen work status */ Update core warnings (down to zero!)

{{TOC}}

= Doxygen warning removal =

This page is to help coordinating the efforts in fixing [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].

As a followup of [[Sprints|Friday November 15 ns-3 Sprint]], we'd like to coordinate the efforts of Doxygen warning removal.

It must be pointed out that warning removing is not good per-se. It is a way to complete the documentation and make it better. 

Undocumented functions leads to poor coding and, ultimately, not be able to use the ns-3 full power. 

Moreover, bad or missing documentation means '''bugs''' !

= Doxygen work status =
The following table might seems overwhelming. And the warning are just the ones in the model and helper folders. 

However, mind that many are chain-warnings, meaning that once you fix the master one in the base class, many of them will disappear. More on that at the bottom of the page.

The current doxygen warning status, by module is:
{| class="wikitable"
|-
! Number of warnings !! Module !! Who's working on it
|-

| 3369 || lte ||
|-
| 1523 || wimax ||
|-
| 840 || wifi || Daniel L.
|-
| 521 || mesh ||
|-
| 459 || visualizer ||
|-
| 236 || dsr ||
|-
| 227 || netanim ||
|-
| 211 || wave ||
|-
| 210 || spectrum ||
|-
| 195 || olsr ||
|-
| 127 || aodv ||
|-
| 108 || config-store ||
|-
| 98 || buildings ||
|-
| 90 || mpi ||
|-
| 87 || energy ||
|-
| 74 || dsdv ||
|-
| 46 || openflow ||
|-
| 28 || brite ||
|-
| 22 || nix-vector-routing ||
|-
| 20 || network ||
|-
| 18 || antenna ||
|-
| 17 || virtual-net-device ||
|-
| 15 || internet ||
|-
| 2 || propagation ||
|-
| 2 || sixlowpan ||
|-
| 2 || topology ||
|}

= How to proceed =
The procedure is simple.
# Post online that you're working on a module. Eventually coordinate with who's already working on the same module.
# Follow the direction in the [[Sprints|Sprint]] page to setup Doxygen to show you the warnings.
# Start with base classes. Mind that ''virtual'' functions can (and should) be documented only in the base class.
# Don't be afraid of the numbers. I was able to kill 1400 warnings in 2 days (just in my spare time).
# Once you have a patch, post it in Bugzilla: [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].
# Go drink a beer, you deserve it.

= Hint and tips =

The doxygen.warnings.report.sh script will make a long list of warnings. You're probably interested in the ones from a single module. The following command might help:

grep <module name> doc/doxygen.warnings.log | sort > doc/my.doxygen.warnings.txt
Now you have a shorter list of bugs to work with. Cut out the ones from the tests and examples (or not, depends on how pedantic you are). Those are your warnings to kill.

= User's opinions =

Some time ago I did a poll, an I asked the users the documentation they need most. Here is the result.

[[File:UsersPollResults.png]]

--[[User:Tommaso|Tommaso]] ([[User talk:Tommaso|talk]]) 16:29, 26 November 2013 (EST)

Doxygen-warnings

2015-11-12T04:07:11Z

Pdbarnes: /* Doxygen work status */ Update core stats

{{TOC}}

= Doxygen warning removal =

This page is to help coordinating the efforts in fixing [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].

As a followup of [[Sprints|Friday November 15 ns-3 Sprint]], we'd like to coordinate the efforts of Doxygen warning removal.

It must be pointed out that warning removing is not good per-se. It is a way to complete the documentation and make it better. 

Undocumented functions leads to poor coding and, ultimately, not be able to use the ns-3 full power. 

Moreover, bad or missing documentation means '''bugs''' !

= Doxygen work status =
The following table might seems overwhelming. And the warning are just the ones in the model and helper folders. 

However, mind that many are chain-warnings, meaning that once you fix the master one in the base class, many of them will disappear. More on that at the bottom of the page.

The current doxygen warning status, by module is:
{| class="wikitable"
|-
! Number of warnings !! Module !! Who's working on it
|-

| 3369 || lte ||
|-
| 1523 || wimax ||
|-
| 840 || wifi || Daniel L.
|-
| 521 || mesh ||
|-
| 459 || visualizer ||
|-
| 236 || dsr ||
|-
| 227 || netanim ||
|-
| 211 || wave ||
|-
| 210 || spectrum ||
|-
| 195 || olsr ||
|-
| 127 || aodv ||
|-
| 108 || config-store ||
|-
| 98 || buildings ||
|-
| 90 || mpi ||
|-
| 87 || energy ||
|-
| 74 || dsdv ||
|-
| 49 || core ||
|-
| 46 || openflow ||
|-
| 28 || brite ||
|-
| 22 || nix-vector-routing ||
|-
| 20 || network ||
|-
| 18 || antenna ||
|-
| 17 || virtual-net-device ||
|-
| 15 || internet ||
|-
| 2 || propagation ||
|-
| 2 || sixlowpan ||
|-
| 2 || topology ||
|}

= How to proceed =
The procedure is simple.
# Post online that you're working on a module. Eventually coordinate with who's already working on the same module.
# Follow the direction in the [[Sprints|Sprint]] page to setup Doxygen to show you the warnings.
# Start with base classes. Mind that ''virtual'' functions can (and should) be documented only in the base class.
# Don't be afraid of the numbers. I was able to kill 1400 warnings in 2 days (just in my spare time).
# Once you have a patch, post it in Bugzilla: [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].
# Go drink a beer, you deserve it.

= Hint and tips =

The doxygen.warnings.report.sh script will make a long list of warnings. You're probably interested in the ones from a single module. The following command might help:

grep <module name> doc/doxygen.warnings.log | sort > doc/my.doxygen.warnings.txt
Now you have a shorter list of bugs to work with. Cut out the ones from the tests and examples (or not, depends on how pedantic you are). Those are your warnings to kill.

= User's opinions =

Some time ago I did a poll, an I asked the users the documentation they need most. Here is the result.

[[File:UsersPollResults.png]]

--[[User:Tommaso|Tommaso]] ([[User talk:Tommaso|talk]]) 16:29, 26 November 2013 (EST)

Doxygen-warnings

2015-11-12T03:35:47Z

Pdbarnes: /* Doxygen work status */ Correct typo

{{TOC}}

= Doxygen warning removal =

This page is to help coordinating the efforts in fixing [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].

As a followup of [[Sprints|Friday November 15 ns-3 Sprint]], we'd like to coordinate the efforts of Doxygen warning removal.

It must be pointed out that warning removing is not good per-se. It is a way to complete the documentation and make it better. 

Undocumented functions leads to poor coding and, ultimately, not be able to use the ns-3 full power. 

Moreover, bad or missing documentation means '''bugs''' !

= Doxygen work status =
The following table might seems overwhelming. And the warning are just the ones in the model and helper folders. 

However, mind that many are chain-warnings, meaning that once you fix the master one in the base class, many of them will disappear. More on that at the bottom of the page.

The current doxygen warning status, by module is:
{| class="wikitable"
|-
! Number of warnings !! Module !! Who's working on it
|-

| 3369 || lte ||
|-
| 1523 || wimax ||
|-
| 840 || wifi || Daniel L.
|-
| 521 || mesh ||
|-
| 459 || visualizer ||
|-
| 420 || core ||
|-
| 236 || dsr ||
|-
| 227 || netanim ||
|-
| 211 || wave ||
|-
| 210 || spectrum ||
|-
| 195 || olsr ||
|-
| 127 || aodv ||
|-
| 108 || config-store ||
|-
| 98 || buildings ||
|-
| 90 || mpi ||
|-
| 87 || energy ||
|-
| 74 || dsdv ||
|-
| 46 || openflow ||
|-
| 28 || brite ||
|-
| 22 || nix-vector-routing ||
|-
| 20 || network ||
|-
| 18 || antenna ||
|-
| 17 || virtual-net-device ||
|-
| 15 || internet ||
|-
| 2 || propagation ||
|-
| 2 || sixlowpan ||
|-
| 2 || topology ||
|}

= How to proceed =
The procedure is simple.
# Post online that you're working on a module. Eventually coordinate with who's already working on the same module.
# Follow the direction in the [[Sprints|Sprint]] page to setup Doxygen to show you the warnings.
# Start with base classes. Mind that ''virtual'' functions can (and should) be documented only in the base class.
# Don't be afraid of the numbers. I was able to kill 1400 warnings in 2 days (just in my spare time).
# Once you have a patch, post it in Bugzilla: [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].
# Go drink a beer, you deserve it.

= Hint and tips =

The doxygen.warnings.report.sh script will make a long list of warnings. You're probably interested in the ones from a single module. The following command might help:

grep <module name> doc/doxygen.warnings.log | sort > doc/my.doxygen.warnings.txt
Now you have a shorter list of bugs to work with. Cut out the ones from the tests and examples (or not, depends on how pedantic you are). Those are your warnings to kill.

= User's opinions =

Some time ago I did a poll, an I asked the users the documentation they need most. Here is the result.

[[File:UsersPollResults.png]]

--[[User:Tommaso|Tommaso]] ([[User talk:Tommaso|talk]]) 16:29, 26 November 2013 (EST)

Doxygen-warnings

2015-11-12T03:34:48Z

Pdbarnes: /* Doxygen work status */ Update table numbers

{{TOC}}

= Doxygen warning removal =

This page is to help coordinating the efforts in fixing [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].

As a followup of [[Sprints|Friday November 15 ns-3 Sprint]], we'd like to coordinate the efforts of Doxygen warning removal.

It must be pointed out that warning removing is not good per-se. It is a way to complete the documentation and make it better. 

Undocumented functions leads to poor coding and, ultimately, not be able to use the ns-3 full power. 

Moreover, bad or missing documentation means '''bugs''' !

= Doxygen work status =
The following table might seems overwhelming. And the warning are just the ones in the model and helper folders. 

However, mind that many are chain-warnings, meaning that once you fix the master one in the base class, many of them will disappear. More on that at the bottom of the page.

The current doxygen warning status, by module is:
{| class="wikitable"
|-
! Number of warnings !! Module !! Who's working on it
|-

| 33336964 || lte ||
|-
| 1523 || wimax ||
|-
| 840 || wifi || Daniel L.
|-
| 521 || mesh ||
|-
| 459 || visualizer ||
|-
| 420 || core ||
|-
| 236 || dsr ||
|-
| 227 || netanim ||
|-
| 211 || wave ||
|-
| 210 || spectrum ||
|-
| 195 || olsr ||
|-
| 127 || aodv ||
|-
| 108 || config-store ||
|-
| 98 || buildings ||
|-
| 90 || mpi ||
|-
| 87 || energy ||
|-
| 74 || dsdv ||
|-
| 46 || openflow ||
|-
| 28 || brite ||
|-
| 22 || nix-vector-routing ||
|-
| 20 || network ||
|-
| 18 || antenna ||
|-
| 17 || virtual-net-device ||
|-
| 15 || internet ||
|-
| 2 || propagation ||
|-
| 2 || sixlowpan ||
|-
| 2 || topology ||
|}

= How to proceed =
The procedure is simple.
# Post online that you're working on a module. Eventually coordinate with who's already working on the same module.
# Follow the direction in the [[Sprints|Sprint]] page to setup Doxygen to show you the warnings.
# Start with base classes. Mind that ''virtual'' functions can (and should) be documented only in the base class.
# Don't be afraid of the numbers. I was able to kill 1400 warnings in 2 days (just in my spare time).
# Once you have a patch, post it in Bugzilla: [http://www.nsnam.org/bugzilla/show_bug.cgi?id=938 Bug 938: missing Doxygen in ns-3].
# Go drink a beer, you deserve it.

= Hint and tips =

The doxygen.warnings.report.sh script will make a long list of warnings. You're probably interested in the ones from a single module. The following command might help:

grep <module name> doc/doxygen.warnings.log | sort > doc/my.doxygen.warnings.txt
Now you have a shorter list of bugs to work with. Cut out the ones from the tests and examples (or not, depends on how pedantic you are). Those are your warnings to kill.

= User's opinions =

Some time ago I did a poll, an I asked the users the documentation they need most. Here is the result.

[[File:UsersPollResults.png]]

--[[User:Tommaso|Tommaso]] ([[User talk:Tommaso|talk]]) 16:29, 26 November 2013 (EST)

GSOC2015MpTcpImplementation

2015-06-08T17:58:48Z

Pdbarnes: /* Week 2 - Step 2 */ line breaks in references

Python3

2015-06-03T21:25:48Z

Pdbarnes: /* Tasks */ raise upload.py

{{TOC}}

This page is tracking Python3 compatibility for ns-3 and related projects. As of ns-3.23 (May 2015), only Python2 (2.7 series) is supported.

== Goals ==

Make ns-3 and related projects (bake build system, pyviz visualizer) compatible with both Python 2.7 and 3.4.

== Tasks ==

The following ports for basic ns-3 operation need to be accomplished (if found incompatible with Python3):

# All scripts for the waf build system (waf-tools, wutils.py, etc.)
# All ns-3 python programs (e.g. first.py)
# src/visualizer
# The test.py test runner program
# All python programs in the documentation directories (e.g. conf.py)
# All scripts in ns-3-allinone (build.py dist.py download.py)
# src/create-module.py
# utils.py
# utils/check-style.py
# utils/grid.py
# utils/python-unit-tests.py

[[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]]) ''What about the Rietveld'' upload.py ''script used for code review? This is their [https://github.com/rietveld-codereview/rietveld/issues/486 issue #486]''

Also, the bake build system must be ported.

Also, the Python API scanning process needs to be upgraded. This relies on third party tools (particularly [https://github.com/gccxml/pygccxml pygccxml] and [https://code.google.com/p/pybindgen/ pybindgen]) that need to be investigated.

== Status ==

The most recent code is maintained at http://code.nsnam.org/tomh/ns-3-dev-python3/ until we merge it. A [[Python3_Project | summer project from 2014]] by Siddharth Sankurtar has accomplished much of the initial port of ns-3 portions (above) to Python-3.3.5; the above repository includes Siddharth's previous work on this.

One of the goals of ns-3.24 release is to at least get to compatibility of the core of ns-3, even if bake and python scanning does not yet work.

There are three main remaining issues (patches requested for 1) and 2)):

1. Something has broken in moving from Python 3.3 to Python 3.4

_pickle.PicklingError: Can't pickle <class 'waflib.Node.Context.__init__.<locals>.node_class'>: attribute lookup
Context.__init__.<locals>.node_class on waflib.Node failed

and

os.chmod(dst, 0600)
^
SyntaxError: invalid token

2. In python 3.3, the following issue was encountered and not debugged yet.

During the first build phase, waf generates signatures for every task. Upon successful completion of the task, the signature of the task is stored into a hidden file in the build directory. The task signatures are serialized using the Pickle library.

Following builds after this would load the task signatures from the hidden file. For every task, it generates its signature and checks if it is present in the dictionary of the loaded task signatures. In case of Python3, for some tasks, the newly generated signature fails to match with the loaded signature, causing a KeyError and consequently a re-building of that task. The issue possibly lies in the signature generation in Python3.

3. Siddharth has written some test programs to test waf and test.py themselves; do we want to add them to a test directory? See:

* utils/tests/TestBase.py
* utils/tests/test-test.py
* utils/tests/test-waf.py

Also, beyond basic ns-3, we need volunteers to work on these additional issues:

* Siddharth Santurkar has volunteered to port bake
* We don't have anyone working on Python API scanning toolchain (please contact us if you want to work on this)

== Testing ==

The latest ns-3 code is available at http://code.nsnam.org/tomh/ns-3-dev-python3

Python3 can be tested on most Linux systems using the [http://docs.python-guide.org/en/latest/dev/virtualenvs/ virtualenv] system.

If you have 'pip' installed, you can install virtualenv as follows:

$ sudo pip install virtualenv

Then, the following steps are recommended:

$ mkdir my_project_folder && cd $_
$ hg clone http://code.nsnam.org/ns-3-allinone
$ cd ns-3-allinone
$ /usr/bin/python2.7 download.py
$ hg clone http://code.nsnam.org/tomh/ns-3-dev-python3
$ virtualenv -p /usr/bin/python3 venv
$ source venv/bin/activate

Your prompt should now look like this, prepended with '(venv)':

(venv)buildslave@slave-ubuntu-15:~/my_project_folder/ns-3-allinone$

Now you are in a special environment for which any calls to 'python' will use the python3 version. To see this, try calling:

(venv)buildslave@slave-ubuntu-15:~/my_project_folder/ns-3-allinone$ python -V

To drop out of this virtualenv, type:

$ deactivate

You may also consider to run the test-test.py and test-waf.py programs (which unit test the test.py and waf programs and their options) found in ``utils/tests/`` directory.

GSOC2015MpTcpImplementation

2015-05-01T16:28:44Z

Pdbarnes: /* Week 7 - Deliverable for Step 3; start of Step 4 */ aggregate clock, instead of member variable

Sprints

2014-09-26T19:21:40Z

Pdbarnes: /* How to build Doxygen for ns-3 and find the errors */ formatting

{{TOC}}

= 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 [https://code.djangoproject.com/wiki/Sprints 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.

= Upcoming sprints =

== Friday October 3, 14h00-20h00 UTC ==
('''note:''' attendees are welcome to attend a subset of the 6-hour slot, if so desired)
* '''Etherpad:''' http://etherpad.osuosl.org/gMofL8fupm
* '''Topic:''' Documentation improvement. https://www.nsnam.org/bugzilla/show_bug.cgi?id=938. In particular, we will work on reducing the number of doxygen warnings that are generated due to missing Doxygen. This is a long-standing issue that just requires group effort to resolve.
* '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
* '''Preparation:'''
*# Read the general preparation below
*# Make sure you have Doxygen installed on your system, and can run the shell script <tt>doc/doxygen.warnings.report.sh</tt> (it may take a while to run, and should generate a lot of warnings).
*# Review this link about building doxygen, and filtering for output that you care about: http://www.nsnam.org/docs/manual/html/documentation.html#building-doxygen-docs
*# Review this link for ns-3 specific formatting: http://www.nsnam.org/docs/manual/html/documentation.html#id1
*# Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
* '''Tasks:'''
: 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-September/015625.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.
* '''Coordination:''' We will use IRC and [http://etherpad.org 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 [http://doxygen.org Doxygen] installed on your machine.

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

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

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

$ ./doc/doxygen.warnings.report.sh

This will produce lots of summary statistics like:

Warnings by module/directory:

Count Directory
----- ----------------------------------
3219 src/lte/model
1173 src/wimax/model
1066 src/core/model
646 src/lte/test
518 src/wifi/model
...

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

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

The <tt>-s</tt> 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 <tt>-s</tt> option. The <tt>-m <module></tt> option only shows
results from the <tt>./src/<module></tt> module; after printing the
warnings counts by file, it shows the actual errors from each file:

...
Filtered Warnings
========================================
src/wifi/examples/wifi-phy-test.cc:53: warning: Compound PsrExperiment::Output is not documented.
...

This means the type (probably a struct) <tt>PsrExperiment::Output</tt> has no documentation,
and it's declared in <tt>src/wifi/examples/wifi-phy-test.cc</tt> around line 53.

To see just the warnings from a single file (or a set of files matching a regular expression)
use the <tt>-F <file-name-or-regex></tt> 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 [http://etherpad.osuosl.org/gMofL8fupm 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 [http://www.nsnam.org/docs/manual/html/documentation.html#id1 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 <tt>doxygen.warnings.report.sh</tt> script without the <tt>-s</tt> option:

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

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

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 [https://www.nsnam.org/bugzilla/show_bug.cgi?id=938 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 [http://www.nsnam.org/developers/contributing-code/submit/ 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

Sprints

2014-09-26T19:20:43Z

Pdbarnes: /* How to build Doxygen for ns-3 and find the errors */ fix output block formatting

Sprints

2014-09-26T19:19:19Z

Pdbarnes: /* Upcoming sprints */ revise documentation instructions

{{TOC}}

= 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 [https://code.djangoproject.com/wiki/Sprints 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.

= Upcoming sprints =

== Friday October 3, 14h00-20h00 UTC ==
('''note:''' attendees are welcome to attend a subset of the 6-hour slot, if so desired)
* '''Etherpad:''' http://etherpad.osuosl.org/gMofL8fupm
* '''Topic:''' Documentation improvement. https://www.nsnam.org/bugzilla/show_bug.cgi?id=938. In particular, we will work on reducing the number of doxygen warnings that are generated due to missing Doxygen. This is a long-standing issue that just requires group effort to resolve.
* '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
* '''Preparation:'''
*# Read the general preparation below
*# Make sure you have Doxygen installed on your system, and can run the shell script <tt>doc/doxygen.warnings.report.sh</tt> (it may take a while to run, and should generate a lot of warnings).
*# Review this link about building doxygen, and filtering for output that you care about: http://www.nsnam.org/docs/manual/html/documentation.html#building-doxygen-docs
*# Review this link for ns-3 specific formatting: http://www.nsnam.org/docs/manual/html/documentation.html#id1
*# Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
* '''Tasks:'''
: 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-September/015625.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.
* '''Coordination:''' We will use IRC and [http://etherpad.org 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 [http://doxygen.org Doxygen] installed on your machine.

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

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

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

$ ./doc/doxygen.warnings.report.sh

This will produce lots of summary statistics like:

Warnings by module/directory:
Count Directory ----- ---------------------------------- 3219 src/lte/model 1173 src/wimax/model 1066 src/core/model 646 src/lte/test 518 src/wifi/model ... </nowiki>

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

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

The <tt>-s</tt> 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 <tt>-s</tt> option. The <tt>-m <module></tt> option only shows
results from the <tt>./src/<module></tt> module; after printing the
warnings counts by file, it shows the actual errors from each file:

...
Filtered Warnings
========================================
src/wifi/examples/wifi-phy-test.cc:53: warning: Compound PsrExperiment::Output is not documented.
...

This means the type (probably a struct) <tt>PsrExperiment::Output</tt> has no documentation,
and it's declared in <tt>src/wifi/examples/wifi-phy-test.cc</tt> around line 53.

To see just the warnings from a single file (or a set of files matching a regular expression)
use the <tt>-F <file-name-or-regex></tt> 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 [http://etherpad.osuosl.org/gMofL8fupm 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 [http://www.nsnam.org/docs/manual/html/documentation.html#id1 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 <tt>doxygen.warnings.report.sh</tt> script without the <tt>-s</tt> option:

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

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

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 [https://www.nsnam.org/bugzilla/show_bug.cgi?id=938 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 [http://www.nsnam.org/developers/contributing-code/submit/ 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

Ns-3.22

2014-09-19T18:23:13Z

Pdbarnes: /* Bugs or issues in ns-3 core */ carry over open bugs from ns-3.21 release page

{{TOC}}

This page summarizes the release planning for ns-3.22. The ns-3 release process is listed [http://www.nsnam.org/developers/release-process/ here] and [[Release Process | here]].

The release manager is [mailto:tomh@tomh.org Tom Henderson]. Please contact him if you would like to participate in any way in preparing the ns-3.22 release.

= Release goals =

1) make a major dent in the [http://www.nsnam.org/bugzilla bug tracker]. Can we clean out most issues on our actively maintained modules, including closing out feature requests for which we do not have anyone working on them?

2) continue the transition to a [[BakeIntegration | more modular build system]]. While a major change to the build system is not planned for ns-3.22, one goal is to start to allow modules outside the core of ns-3 to be maintained in separate places, and integrated using the 'bake' tool (rather than merge everything into ns-3-dev).

3) merge (into ns-3-dev or to a bake-enabled repository) as many new features as we can get ready, including all remaining features from 2013 and 2014 GSOC and SOCIS projects, and 2014 summer projects

= Release schedule =

ns-3.22 is planned for mid-January, 2015. ns-3 makes roughly three releases per year (Dec/Jan, Apr/May, and Aug/Sept timeframes).

This means that we ought to get most new features and major changes into the simulator by early December.

= Packaging =

ns-3.22 will be packaged as a source tarball as before: ns-allinone-3.22.tar.bz2.

The tarball will contain:
* Latest version of pybindgen
* Latest version of netanim
* ns-3.22
* bake

where bake is used to fetch optional ns-3 components, including DCE.

A patch from ns-3.21 to ns-3.22 will also be posted.

Whether ns-3.22 is prepared in other packaging (e.g. Debian) is ''to be determined.''

Whether ns-3.22 will be distributed also as a [http://www.docker.com Docker container] is ''to be determined.''

= Release platforms =

We usually try to keep pace with the latest popular versions of Linux, OS X, and FreeBSD. For the ns-3.22 release, we plan to support the following systems and compilers:

* OS X 10.10 Yosemite with latest Xcode
* Ubuntu 14.04 and 14.10 (gcc-4.8, 4.9)
* Fedora 20 and 21 (gcc-4.8, 4.9)
* Debian 7 (gcc-4.9)
* FreeBSD 10.1 (clang 3)
* some legacy platforms (''to be determined''); likely older Ubuntu LTS and CentOS systems, and OS X 10.9

== New features ==

Developers are working or planning to work on the following new features for ns-3.22. '''Note:''' there is no guarantee that the features will be finished by the end of the year, so check back for progress/status.

=== Changes to the simulation core ===

* [[Python3_Project | Python 3 support]] (Siddharth Sankurdar)
** '''Synopsis:''' ns-3 is Python 2 based, and must be upgraded to support both Python 2 and 3
* Discuss changes due to Object Start/Stop discussion held at [http://www.nsnam.org/docs/meetings/ns-3-developer-meeting-notes-May14.pdf May developers meeting].
* Shared RngStream (Peter Barnes)
** '''Synopsis:''' Add API to allow multiple random variables to share an underlying RNG stream
** https://codereview.appspot.com/114060043/
* Changes to better support [[Ns-3_on_Visual_Studio_2012 | ns-3 on Windows Visual Studio]]
** https://codereview.appspot.com/8932044/

''' Others to be determined'''

=== Statistics ===

* Add a basic statistics collector, and convert some existing stats helpers in LTE and WiFi to use the statistics framework (Tom Henderson and Li Li)

=== Internet module ===

* An implementation of MLDv2 for IPv6 (Krishna Teja Yadavalli and Tommaso Pecorella)
** http://www.nsnam.org/wiki/GSOC2014MulticastIPv6
* FQ-Codel and SFQ-Codel models (Anh Nguyen and Dave Taht)
** http://www.nsnam.org/wiki/GSOC2014Bufferbloat
** This will require some refactoring to allow AQM queues that need access to the IP and transport headers to get access at the layer at which ns3::Queue operates
* Move RED queue from network module to internet module

=== TCP ===

* TCP variants for satellite networks (Natale Patriciello)
**
* RttEstimator improvements (Natale Patriciello)
* Multipath TCP ([mailto:M.Kheirkhah@sussex.ac.uk Morteza Kheirkhah Sabetghadam])

=== WiFi ===

* MPDU aggregation for 802.11n ([mailto:sebastien.deronne@gmail.com Sebastien Deronne] and [mailto:gbadawy@gmail.com Ghada Badawy], and others)
** https://codereview.appspot.com/14549044/

=== Vehicular networks ===

* WAVE for 802.11 vehicular networks (Scott Carpenter and Junling Bu)
** Finish off the 2013 GSoC code merging
* VANET example (Scott Carpenter)
** https://codereview.appspot.com/103470050/
* [[RoutesMobilityModel | Routes Mobility Model]] (Tiago Cerqueira)

=== Delay-tolerant networking ===

* Self-Delimiting Numeric Values (Dizhi Zhou and Ruben Martinez)
** https://codereview.appspot.com/97540043/
* Licklider Transport Protocol (Ruben Martinez)
* Bundle Protocol from SOCIS 2013 (Dizhi Zhou)

=== DSR ===

* LEAR extensions https://codereview.appspot.com/96130043/

=== CSMA improvements ====
* https://codereview.appspot.com/109450044/ (Mehdi Moussouni)

=== Epidemic Routing ===
* https://codereview.appspot.com/13831049/

== Software maintenance issues ==
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1945 Remove emu module from codebase (1945)] (Tom Henderson)
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1770 Mesh test crashes for certain configurations]
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1900 Time arithmetic consistency]
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1868 Wstrict-overflow and gcc-4.9] (Tom Henderson and Peter Barnes)
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1941 Remove unnecessary dependency on Application module in other modules (1941)] Tommaso Pecorella
** Cleanup of remaining modules unnecessarily dependent on applications (aodv, mesh, olsr, lte)

== Documentation improvements ==
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1490 improve documentation on linking ns-3 with other libraries] (Tom Henderson)

''others to be determined''

== Bugs or issues in ns-3 core ==

* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1962 RandomVariableStream::GetStream returns -1 for all automatically assigned streams (1962)] Peter Barnes
* Close [https://www.nsnam.org/bugzilla/show_bug.cgi?id=954 Changing the simulation time resolution does not work well with attributes (954)] ?
* Close [https://www.nsnam.org/bugzilla/show_bug.cgi?id=764 feature request: non-doxygen trace source introspection program needed] with status Resolved?

== Bugs in models to fix ==

'' To be determined ''

Ns-3.21

2014-09-12T22:50:45Z

Pdbarnes: /* Also Possible */ bug 764

{{TOC}}

This page summarizes the release planning for ns-3.21. The ns-3 release process is listed [http://www.nsnam.org/developers/release-process/ here] and [[Release Process | here]].

The release manager is Tom Henderson.

= Release schedule =

ns-3.21 is planned for September 17, 2014. New feature code should be ready for merge by no later than 5 September. An initial release candidate should be available by 12 September.

= Packaging =

ns-3.21 will be packaged as a source tarball as before: ns-allinone-3.21.tar.bz2.

The tarball will contain:
* Latest version of pybindgen
* Latest version of netanim
* ns-3.21
* bake

where bake is used to fetch optional ns-3 components, including DCE.

A patch from ns-3.20 to ns-3.21 will also be posted.

= Release platforms =

We usually try to keep pace with the latest popular versions of Linux, OS X, and FreeBSD. For the ns-3.21 release, we plan to support the following systems and compilers:

* OS X 10.9 Mavericks with Xcode 5.1
* Ubuntu 14.04 (gcc-4.8)
* Fedora 20 (gcc-4.8)
* Debian 7 (gcc-4.9)
* Ubuntu 10.04 LTS (gcc-4.4)
* Ubuntu 12.04 LTS (gcc-4.6)
* Centos 6.4 (gcc-4.4)
* FreeBSD 9.3 (clang 3.3)

== New features ==

Pending new features:
* Self-Delimiting Numeric Values (https://codereview.appspot.com/97540043/)
** '''Update:''' Slipping to [[ns-3.22]]
* TCP options code from [[SOCIS2014TCP | SOCIS TCP project]] (including window scale and timestamps)
** Code review issue: https://codereview.appspot.com/110860043/
** <s>'''Update:''' A repo (http://code.nsnam.org/repositories/tomh/ns-3-dev-tcp-options-for-merge) is staged for final review; a few minor issues are being worked out for Friday</s> Merged
** RttEstimator improvements will slip until [[ns-3.22]]
* (enhancement) Add propagation delay capability to SimpleChannel (for testing purposes)
** <s>code review issue: https://codereview.appspot.com/132870043/</s> Merged
* CoDel queue support (from [[GSOC2014Bufferbloat | GSoC bufferbloat project]])
** <s>'''Update:''' A repo (http://code.nsnam.org/repositories/tomh/ns-3-dev-codel-for-merge) is staged for final review</s> Merged
** FQ-CoDel and SFQ-CoDel will slip until [[ns-3.22]]
* Energy harvesting model
** Code review issue: https://codereview.appspot.com/103750047/
** <s>'''Update:''' Cristiano has updated this and it appears ready for merging</s> Merged
* LTE FFR models from GSoC project
** Code review issue: https://codereview.appspot.com/130130043/
** <s>'''Update:''' Piotr has created a staging repo for final merge: http://code.nsnam.org/pgawlowicz/ns-3-dev/</s> Merged

WiFi-related:
* [https://codereview.appspot.com/57210044/ Wifi Sleep mode]
** <s>'''Update:''' Stefano has created a final patch (emailed offlist), ready for merge with Cristiano's energy harvesting patch</s> Merged
* [https://codereview.appspot.com/14549044/ MPDU aggregation]
** Will slip to [[ns-3.22]]
* [https://codereview.appspot.com/103470050/ new VANET example]
** '''Update:''' Not yet ready for merge, may slip to [[ns-3.22]]

== Software maintenance issues ==

* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1945 Remove emu module from codebase (1945)] (Tom Henderson)
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1770 Mesh test crashes for certain configurations]
** There is likely not enough time to finish this off before release
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1900 Time arithmetic consistency]
** There is likely not enough time to finish this off before release
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1868 Wstrict-overflow and gcc-4.9] (Tom Henderson and Peter Barnes)
** Tom to take next step to see what progress he can make on this bug
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1941 Remove unnecessary dependency on Application module in other modules (1941)] Tommaso Pecorella
** <s> Depends on merging of simple applications https://codereview.appspot.com/45320043 </s> merged
** Cleanup of remaining modules dependent on applications (aodv, mesh, olsr, lte) will slip to 3.22

== Bugs or issues in ns-3 core ==

* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1972 Command line argument handling (1972)] Peter Barnes (patch in bugzilla)
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1964 GetInteger off-by-one (1964)] Peter Barnes and Tom Henderson
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1962 RandomVariableStream::GetStream returns -1 for all automatically assigned streams (1962)] Peter Barnes
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1959 Config::Path not parsed correctly (1959)] Tom Henderson
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1824 L4 protocol sockets should support BindToNetDevice over IPv6 (1824)] Tommaso Pecorella - waiting comments
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1911 AODV can not work on nodes with more than one NetDevice (1911)] Tommaso Pecorella - waiting comments

=== Also Possible ===
* Close [https://www.nsnam.org/bugzilla/show_bug.cgi?id=954 Changing the simulation time resolution does not work well with attributes (954)] ?
* Apply patch for [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1652 Storage of the log name in LogComponent (1652)] ?
* Close [https://www.nsnam.org/bugzilla/show_bug.cgi?id=764 feature request: non-doxygen trace source introspection program needed] with status Resolved?

== Bugs in models being worked by someone ==

TBD

== Documentation improvements ==
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1490 improve documentation on linking ns-3 with other libraries] (Tom Henderson)
** Not likely to be fully fixed for ns-3.21 but may take a stab at this, time permitting
* Wifi documentation patch from Sebastien Deronne (Daniel L)
* Fix tutorial first.cc and documentation to explicitly call out the need for StopApplication() (Tommaso and/or Tom)

Ns-3.21

2014-09-12T22:16:59Z

Pdbarnes: /* Bugs or issues in ns-3 core */ Bug 1652

{{TOC}}

This page summarizes the release planning for ns-3.21. The ns-3 release process is listed [http://www.nsnam.org/developers/release-process/ here] and [[Release Process | here]].

The release manager is Tom Henderson.

= Release schedule =

ns-3.21 is planned for September 17, 2014. New feature code should be ready for merge by no later than 5 September. An initial release candidate should be available by 12 September.

= Packaging =

ns-3.21 will be packaged as a source tarball as before: ns-allinone-3.21.tar.bz2.

The tarball will contain:
* Latest version of pybindgen
* Latest version of netanim
* ns-3.21
* bake

where bake is used to fetch optional ns-3 components, including DCE.

A patch from ns-3.20 to ns-3.21 will also be posted.

= Release platforms =

We usually try to keep pace with the latest popular versions of Linux, OS X, and FreeBSD. For the ns-3.21 release, we plan to support the following systems and compilers:

* OS X 10.9 Mavericks with Xcode 5.1
* Ubuntu 14.04 (gcc-4.8)
* Fedora 20 (gcc-4.8)
* Debian 7 (gcc-4.9)
* Ubuntu 10.04 LTS (gcc-4.4)
* Ubuntu 12.04 LTS (gcc-4.6)
* Centos 6.4 (gcc-4.4)
* FreeBSD 9.3 (clang 3.3)

== New features ==

Pending new features:
* Self-Delimiting Numeric Values (https://codereview.appspot.com/97540043/)
** '''Update:''' Slipping to [[ns-3.22]]
* TCP options code from [[SOCIS2014TCP | SOCIS TCP project]] (including window scale and timestamps)
** Code review issue: https://codereview.appspot.com/110860043/
** <s>'''Update:''' A repo (http://code.nsnam.org/repositories/tomh/ns-3-dev-tcp-options-for-merge) is staged for final review; a few minor issues are being worked out for Friday</s> Merged
** RttEstimator improvements will slip until [[ns-3.22]]
* (enhancement) Add propagation delay capability to SimpleChannel (for testing purposes)
** <s>code review issue: https://codereview.appspot.com/132870043/</s> Merged
* CoDel queue support (from [[GSOC2014Bufferbloat | GSoC bufferbloat project]])
** <s>'''Update:''' A repo (http://code.nsnam.org/repositories/tomh/ns-3-dev-codel-for-merge) is staged for final review</s> Merged
** FQ-CoDel and SFQ-CoDel will slip until [[ns-3.22]]
* Energy harvesting model
** Code review issue: https://codereview.appspot.com/103750047/
** <s>'''Update:''' Cristiano has updated this and it appears ready for merging</s> Merged
* LTE FFR models from GSoC project
** Code review issue: https://codereview.appspot.com/130130043/
** <s>'''Update:''' Piotr has created a staging repo for final merge: http://code.nsnam.org/pgawlowicz/ns-3-dev/</s> Merged

WiFi-related:
* [https://codereview.appspot.com/57210044/ Wifi Sleep mode]
** <s>'''Update:''' Stefano has created a final patch (emailed offlist), ready for merge with Cristiano's energy harvesting patch</s> Merged
* [https://codereview.appspot.com/14549044/ MPDU aggregation]
** Will slip to [[ns-3.22]]
* [https://codereview.appspot.com/103470050/ new VANET example]
** '''Update:''' Not yet ready for merge, may slip to [[ns-3.22]]

== Software maintenance issues ==

* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1945 Remove emu module from codebase (1945)] (Tom Henderson)
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1770 Mesh test crashes for certain configurations]
** There is likely not enough time to finish this off before release
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1900 Time arithmetic consistency]
** There is likely not enough time to finish this off before release
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1868 Wstrict-overflow and gcc-4.9] (Tom Henderson and Peter Barnes)
** Tom to take next step to see what progress he can make on this bug
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1941 Remove unnecessary dependency on Application module in other modules (1941)] Tommaso Pecorella
** <s> Depends on merging of simple applications https://codereview.appspot.com/45320043 </s> merged
** Cleanup of remaining modules dependent on applications (aodv, mesh, olsr, lte) will slip to 3.22

== Bugs or issues in ns-3 core ==

* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1972 Command line argument handling (1972)] Peter Barnes (patch in bugzilla)
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1964 GetInteger off-by-one (1964)] Peter Barnes and Tom Henderson
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1962 RandomVariableStream::GetStream returns -1 for all automatically assigned streams (1962)] Peter Barnes
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1959 Config::Path not parsed correctly (1959)] Tom Henderson
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1824 L4 protocol sockets should support BindToNetDevice over IPv6 (1824)] Tommaso Pecorella - waiting comments
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1911 AODV can not work on nodes with more than one NetDevice (1911)] Tommaso Pecorella - waiting comments

=== Also Possible ===
* Close [https://www.nsnam.org/bugzilla/show_bug.cgi?id=954 Changing the simulation time resolution does not work well with attributes (954)] ?
* Apply patch for [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1652 Storage of the log name in LogComponent (1652)] ?

== Bugs in models being worked by someone ==

TBD

== Documentation improvements ==
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1490 improve documentation on linking ns-3 with other libraries] (Tom Henderson)
** Not likely to be fully fixed for ns-3.21 but may take a stab at this, time permitting
* Wifi documentation patch from Sebastien Deronne (Daniel L)
* Fix tutorial first.cc and documentation to explicitly call out the need for StopApplication() (Tommaso and/or Tom)

Ns-3.21

2014-09-12T22:09:27Z

Pdbarnes: /* Bugs or issues in ns-3 core */ Consider closing 954

{{TOC}}

This page summarizes the release planning for ns-3.21. The ns-3 release process is listed [http://www.nsnam.org/developers/release-process/ here] and [[Release Process | here]].

The release manager is Tom Henderson.

= Release schedule =

ns-3.21 is planned for September 17, 2014. New feature code should be ready for merge by no later than 5 September. An initial release candidate should be available by 12 September.

= Packaging =

ns-3.21 will be packaged as a source tarball as before: ns-allinone-3.21.tar.bz2.

The tarball will contain:
* Latest version of pybindgen
* Latest version of netanim
* ns-3.21
* bake

where bake is used to fetch optional ns-3 components, including DCE.

A patch from ns-3.20 to ns-3.21 will also be posted.

= Release platforms =

We usually try to keep pace with the latest popular versions of Linux, OS X, and FreeBSD. For the ns-3.21 release, we plan to support the following systems and compilers:

* OS X 10.9 Mavericks with Xcode 5.1
* Ubuntu 14.04 (gcc-4.8)
* Fedora 20 (gcc-4.8)
* Debian 7 (gcc-4.9)
* Ubuntu 10.04 LTS (gcc-4.4)
* Ubuntu 12.04 LTS (gcc-4.6)
* Centos 6.4 (gcc-4.4)
* FreeBSD 9.3 (clang 3.3)

== New features ==

Pending new features:
* Self-Delimiting Numeric Values (https://codereview.appspot.com/97540043/)
** '''Update:''' Slipping to [[ns-3.22]]
* TCP options code from [[SOCIS2014TCP | SOCIS TCP project]] (including window scale and timestamps)
** Code review issue: https://codereview.appspot.com/110860043/
** <s>'''Update:''' A repo (http://code.nsnam.org/repositories/tomh/ns-3-dev-tcp-options-for-merge) is staged for final review; a few minor issues are being worked out for Friday</s> Merged
** RttEstimator improvements will slip until [[ns-3.22]]
* (enhancement) Add propagation delay capability to SimpleChannel (for testing purposes)
** <s>code review issue: https://codereview.appspot.com/132870043/</s> Merged
* CoDel queue support (from [[GSOC2014Bufferbloat | GSoC bufferbloat project]])
** <s>'''Update:''' A repo (http://code.nsnam.org/repositories/tomh/ns-3-dev-codel-for-merge) is staged for final review</s> Merged
** FQ-CoDel and SFQ-CoDel will slip until [[ns-3.22]]
* Energy harvesting model
** Code review issue: https://codereview.appspot.com/103750047/
** <s>'''Update:''' Cristiano has updated this and it appears ready for merging</s> Merged
* LTE FFR models from GSoC project
** Code review issue: https://codereview.appspot.com/130130043/
** <s>'''Update:''' Piotr has created a staging repo for final merge: http://code.nsnam.org/pgawlowicz/ns-3-dev/</s> Merged

WiFi-related:
* [https://codereview.appspot.com/57210044/ Wifi Sleep mode]
** <s>'''Update:''' Stefano has created a final patch (emailed offlist), ready for merge with Cristiano's energy harvesting patch</s> Merged
* [https://codereview.appspot.com/14549044/ MPDU aggregation]
** Will slip to [[ns-3.22]]
* [https://codereview.appspot.com/103470050/ new VANET example]
** '''Update:''' Not yet ready for merge, may slip to [[ns-3.22]]

== Software maintenance issues ==

* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1945 Remove emu module from codebase (1945)] (Tom Henderson)
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1770 Mesh test crashes for certain configurations]
** There is likely not enough time to finish this off before release
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1900 Time arithmetic consistency]
** There is likely not enough time to finish this off before release
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1868 Wstrict-overflow and gcc-4.9] (Tom Henderson and Peter Barnes)
** Tom to take next step to see what progress he can make on this bug
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1941 Remove unnecessary dependency on Application module in other modules (1941)] Tommaso Pecorella
** <s> Depends on merging of simple applications https://codereview.appspot.com/45320043 </s> merged
** Cleanup of remaining modules dependent on applications (aodv, mesh, olsr, lte) will slip to 3.22

== Bugs or issues in ns-3 core ==

* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1972 Command line argument handling (1972)] Peter Barnes
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1964 GetInteger off-by-one (1964)] Peter Barnes and Tom Henderson
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1962 RandomVariableStream::GetStream returns -1 for all automatically assigned streams (1962)] Peter Barnes
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1959 Config::Path not parsed correctly (1959)] Tom Henderson
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1824 L4 protocol sockets should support BindToNetDevice over IPv6 (1824)] Tommaso Pecorella - waiting comments
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1911 AODV can not work on nodes with more than one NetDevice (1911)] Tommaso Pecorella - waiting comments
* Close [https://www.nsnam.org/bugzilla/show_bug.cgi?id=954 Changing the simulation time resolution does not work well with attributes (954)] ?

== Bugs in models being worked by someone ==

TBD

== Documentation improvements ==
* [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1490 improve documentation on linking ns-3 with other libraries] (Tom Henderson)
** Not likely to be fully fixed for ns-3.21 but may take a stab at this, time permitting
* Wifi documentation patch from Sebastien Deronne (Daniel L)
* Fix tutorial first.cc and documentation to explicitly call out the need for StopApplication() (Tommaso and/or Tom)

DevelMeetingMay2014

2014-04-08T17:20:09Z

Pdbarnes:

{{TOC}}

= Location and Schedule =

The meeting will occur Thursday-Friday, May 8-9 at Georgia Tech, Atlanta GA.

A more detailed schedule will be posted at a later date but the schedule will be primarily driven by who is attending and what everyone proposes to discuss.

= Local Information =

See [http://www.nsnam.org/consortium/activities/annual-meeting-may-2014/training-flyer/ information] regarding WNS3 and ns-3 training

= Remote attendance =

We will create a hangout and use a speakerphone, to the extent possible.

= Attendees =

Please add your name here if you intend to attend, and which days.

{| class="wikitable sortable"
|-
! Who !! Thu !! Fri
|-
| Peter Barnes || ✔ || ✔
|-
| Daniel Lertpratchya || ✔ || ✔
|-
| Brian Swenson || ✔ || ✔
|-
| Jared Ivey || ✔ || ✔
|-
| Tommaso Pecorella
(depends on time difference, local time: UTC+2)
|| ✔ || ✔
|}
= Suggested agenda/topics =

Please list suggested discussion topics below and we will build a schedule at a later date. Please also suggest 'read-ahead' items as needed.

* Object Start/Stop progress
* WiFi interaction between 802.11n and 802.11p features
* Memory scaling (PDB)

= Meeting Notes =

To be posted later.

[[Category:DevelMeeting]]

DevelMeetingMay2014

2014-04-08T17:19:49Z

Pdbarnes: add Memory Scaling topic

{{TOC}}

= Location and Schedule =

The meeting will occur Thursday-Friday, May 8-9 at Georgia Tech, Atlanta GA.

A more detailed schedule will be posted at a later date but the schedule will be primarily driven by who is attending and what everyone proposes to discuss.

= Local Information =

See [http://www.nsnam.org/consortium/activities/annual-meeting-may-2014/training-flyer/ information] regarding WNS3 and ns-3 training

= Remote attendance =

We will create a hangout and use a speakerphone, to the extent possible.

= Attendees =

Please add your name here if you intend to attend, and which days.

* [[User:Tomh|Tom Henderson]]: Thurs, Fri
* Peter Barnes: Thurs, Fri
* Daniel Lertpratchya: Thurs, Fri
* Brian Swenson: Thurs, Fri
* Jared Ivey: Thurs, Fri
* Tommaso Pecorella: Thurs, Fri (depends on time difference, local time: UTC+2)

{| class="wikitable sortable"
|-
! Who !! Thu !! Fri
|-
| Peter Barnes || ✔ || ✔
|-
| Daniel Lertpratchya || ✔ || ✔
|-
| Brian Swenson || ✔ || ✔
|-
| Jared Ivey || ✔ || ✔
|-
| Tommaso Pecorella
(depends on time difference, local time: UTC+2)
|| ✔ || ✔
|}
= Suggested agenda/topics =

Please list suggested discussion topics below and we will build a schedule at a later date. Please also suggest 'read-ahead' items as needed.

* Object Start/Stop progress
* WiFi interaction between 802.11n and 802.11p features
* Memory scaling (PDB)

= Meeting Notes =

To be posted later.

[[Category:DevelMeeting]]

HOWTO use Valgrind to debug memory problems

2013-05-24T20:02:37Z

Pdbarnes: remove extraneous space in "--run"

{{TOC}}

Memory leaks or errors can be found with [http://www.valgrind.org Valgrind]. Support for valgrind is built into the ./waf system by typing:

./waf --command-template="valgrind [options] %s" --run ns-3-program-name

for example:
./waf --command-template="valgrind --leak-check=full --show-reachable=yes %s" --run main-propagation-loss

== Common errors ==

Please list hints here as to what kind of errors have known resolution.

=== Failure to call Simulator::Destroy() ===

Simulator::Destroy() will free memory that is created with the ns-3 object system. Forgetting to call Simulator::Destroy () when you are done will lead to reachable memory being reported by valgrind, such as this trace of the main-propagation-loss example:

==16325== 88 bytes in 1 blocks are still reachable in loss record 4 of 4
==16325== at 0x4A069D5: operator new(unsigned long) (vg_replace_malloc.c:261)
==16325== by 0x4C87A6B: ns3::TypeId ns3::TypeId::AddConstructor<ns3::DefaultSimulatorImpl>()::Maker::Create() (type-id.h:429)
==16325== by 0x4C778A3: ns3::FunctorCallbackImpl<ns3::ObjectBase* (*)(), ns3::ObjectBase*, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty>::operator()() (callback.h:166)
==16325== by 0x4CBF22C: ns3::Callback<ns3::ObjectBase*, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty, ns3::empty>::operator()() const (callback.h:407)
==16325== by 0x4CBE05E: ns3::ObjectFactory::Create() const (object-factory.cc:69)
==16325== by 0x4C8569E: ns3::Ptr<ns3::SimulatorImpl> ns3::ObjectFactory::Create<ns3::SimulatorImpl>() const (object-factory.h:110)
==16325== by 0x4C823FB: ns3::GetImpl() (simulator.cc:93)
==16325== by 0x4C831B1: ns3::Simulator::Stop(ns3::Time const&) (simulator.cc:184)
==16325== by 0x404157: TestDeterministic(ns3::Ptr<ns3::PropagationLossModel>) (main-propagation-loss.cc:83)
==16325== by 0x405CC1: main (main-propagation-loss.cc:225)
==16325==
==16325== LEAK SUMMARY:
==16325== definitely lost: 0 bytes in 0 blocks
==16325== indirectly lost: 0 bytes in 0 blocks
==16325== possibly lost: 0 bytes in 0 blocks
==16325== still reachable: 200 bytes in 4 blocks
==16325== suppressed: 0 bytes in 0 blocks
==16325==
==16325== For counts of detected and suppressed errors, rerun with: -v
==16325== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 7 from 7)

Here, the clue is the line that says ''"ns3::Ptr<ns3::SimulatorImpl> ns3::ObjectFactory::Create<ns3::SimulatorImpl>() const (object-factory.h:110)"'' and the lines above it. If you see an error such as that reporting "still reachable" blocks, it is often the case that you forgot to call Simulator::Destroy() to free objects that have been created as factory objects.

== test.py memory leaks ==

Sometimes a memory leak pop up on a test program (the ones enabled by ''"configure --enable-tests''" and launched with ''"./test.py -g something''"). That's ok, the test programs are there with this precise purpose: to show memory leaks and to check the correct ns-3 behavior.

The trick, however, is to *not* search for the memory leak using the test program. Write an equivalent ns-3 simulation, the simple, the better. Then use valgrind on that one, find the leak and exterminate it.
The rationale is: the test programs are launched by a slightly different system than the usual waf launcher (built to run a lot of different tests sequentially). Hence, you could find in the valgrind report a lot of obscure data that (probably) will point you in the wrong direction.

If, however, you can not replicate the memory leak in a "normal" ns-3 simulation, remember that the memory leak might be as well in the test program... in that case: good luck.

DevelMeetingMar2013

2013-04-08T17:26:40Z

Pdbarnes: Add Peter's slides, link to Meeting Notes

{{TOC}}

= Location and Schedule =

The meeting will occur Wed March 6 through Fri March 8 at INRIA Sophia Antipolis. INRIA will provide us with a large enough conference room to meet. We will meet for three days, and people can attend whatever portion they feel like.

A more detailed schedule will be posted at a later date.

== Other events this week ==

* Information about Monday's [http://www.nsnam.org/consortium/activities/annual-meeting-march-2013/ Annual Meeting March 2013]
* Information about Tuesday's [http://www.nsnam.org/wns3/wns3-2013/ Workshop on ns-3 2013]

== Lodging and Directions ==

INRIA Sophia Antipolis is located on a hillside above [http://en.wikipedia.org/wiki/Antibes Antibes] / [http://en.wikipedia.org/wiki/Juan-les-Pins Juan les Pins], France. It is possible to reach the center by public transport from Antibes, Nice, and Cannes.

* [https://www.nsnam.org/consortium/activities/annual-meeting-march-2013/venue-and-useful-information/ Venue and Useful Information]
* [https://www.nsnam.org/consortium/activities/annual-meeting-march-2013/accommodation/ Hotel accommodations]

== Registration ==

Attendance is free but everyone must obtain a visitor badge to enter INRIA. Please list yourself as an attendee and provide contact information as needed to tomh@tomh.org if you want to attend.

== Attendees ==

Please add your name here if you intend to attend, and which days.

* [[User:Tomh|Tom Henderson]], Wed, Thurs, Fri
* [[User:Vedranm|Vedran Miletic]], Wed, Thurs, Fri (Fri half day only)
* George Riley, Wed, Thurs
* Brian Swenson, Wed, Thurs
* Nicola Baldo, Wed, Thurs, Fri (Fri half day only)
* Daniel Camara, Wed, Thurs, Fri
* Peter Barnes, Fri (and possibly parts of Wed, Thurs)
* [[User:tommaso|Tommaso Pecorella]], Wed, Thurs, Fri (Fri half day only)
* [[User:Tazaki|Hajime Tazaki]], Wed, Thurs, Fri
* Alina Quereilhac, Wed, Thurs, Fri
* Brian Swenson, Wed, Thurs
* George Riley, Wed
* Takai Eddine, Wed, Thurs, Fri

* Giovanni Rigazzi, Wed, Thurs, Fri (Fri half day only)

= Suggested agenda/topics =

Please list suggested discussion topics below and we will build a schedule at a later date. Please also suggest 'read-ahead' items as needed.

* Object Start/Stop
* ns-3 in education
* XML as a language for simulation specification, Peter Barnes' talk
** some ideas could be taken from SimGrid guys, they have rather small XML files that say a lot of things
* data collection framework
* variable test scope (bug 1563)
* Modularization of ns-3
* user feedback: what areas (documentation, API) can be improved from a user standpoint? This discussion will be based on feedback from people who have been active on the ns-3-users mailing list.
* DCE release plan review
* Time::SetResolution patch by Peter Barnes and Mathieu Lacage, how to fix it and proceed with merging
** Peter has a proposal to discuss, ([[media:Ns-3-devel-2013-03-8-Time-SetResolution.pdf|.pdf]], [[media:Ns-3-devel-2013-03-8-Time-SetResolution.pptx|.pptx]])

= Meeting Notes =

* [http://www.nsnam.org/docs/meetings/ns-3-developer-meeting-notes-Mar13.pdf|Meeting Notes (.pdf)]

[[Category:DevelMeeting]]

File:Ns-3-devel-2013-03-8-Time-SetResolution.pdf

2013-04-08T17:24:07Z

Pdbarnes:

File:Ns-3-devel-2013-03-8-Time-SetResolution.pptx

2013-04-08T17:19:48Z

Pdbarnes:

DevelMeetingMar2013

2013-02-27T17:33:53Z

Pdbarnes: /* Suggested agenda/topics */

{{TOC}}

= Location and Schedule =

The meeting will occur Wed March 6 through Fri March 8 at INRIA Sophia Antipolis. INRIA will provide us with a large enough conference room to meet. We will meet for three days, and people can attend whatever portion they feel like.

A more detailed schedule will be posted at a later date.

== Other events this week ==

* Information about Monday's [http://www.nsnam.org/consortium/activities/annual-meeting-march-2013/ Annual Meeting March 2013]
* Information about Tuesday's [http://www.nsnam.org/wns3/wns3-2013/ Workshop on ns-3 2013]

== Lodging and Directions ==

INRIA Sophia Antipolis is located on a hillside above [http://en.wikipedia.org/wiki/Antibes Antibes] / [http://en.wikipedia.org/wiki/Juan-les-Pins Juan les Pins], France. It is possible to reach the center by public transport from Antibes, Nice, and Cannes.

* [https://www.nsnam.org/consortium/activities/annual-meeting-march-2013/venue-and-useful-information/ Venue and Useful Information]
* [https://www.nsnam.org/consortium/activities/annual-meeting-march-2013/accommodation/ Hotel accommodations]

== Registration ==

Attendance is free but everyone must obtain a visitor badge to enter INRIA. Please list yourself as an attendee and provide contact information as needed to tomh@tomh.org if you want to attend.

== Attendees ==

Please add your name here if you intend to attend, and which days.

* [[User:Tomh|Tom Henderson]], Wed, Thurs, Fri
* [[User:Vedranm|Vedran Miletic]], Wed, Thurs, Fri (Fri half day only)
* George Riley, Wed, Thurs
* Brian Swenson, Wed, Thurs
* Nicola Baldo, Wed, Thurs, Fri (Fri half day only)
* Daniel Camara, Wed, Thurs, Fri
* Peter Barnes, Fri (and possibly parts of Wed, Thurs)

* [[User:tommaso|Tommaso Pecorella]], Wed, Thurs, Fri (Fri half day only)

* [[User:Tazaki|Hajime Tazaki]], Wed, Thurs, Fri
* Alina Quereilhac, Wed, Thurs, Fri

= Suggested agenda/topics =

Please list suggested discussion topics below and we will build a schedule at a later date. Please also suggest 'read-ahead' items as needed.

* Object Start/Stop
* ns-3 in education
* XML as a language for simulation specification, Peter Barnes' talk
** some ideas could be taken from SimGrid guys, they have rather small XML files that say a lot of things
* data collection framework
* variable test scope (bug 1563)
* Modularization of ns-3
* user feedback: what areas (documentation, API) can be improved from a user standpoint? This discussion will be based on feedback from people who have been active on the ns-3-users mailing list.
* DCE release plan review
* Time::SetResolution patch by Peter Barnes and Mathieu Lacage, how to fix it and proceed with merging
** Peter has a proposal to discuss

[[Category:DevelMeeting]]

DevelMeetingMar2013

2013-02-12T23:58:22Z

Pdbarnes: add Peter Barnes to Attendees

DevelMeetingMar2012

2012-02-28T18:03:30Z

Pdbarnes:

{{TOC}}

= Location and Schedule =

At the same hotel as SIMUTools 2012, on Saturday March 24, the day after [http://www.nsnam.org/wns3/wns3-2012/ WNS3]

* The meeting site is the [http://www.simutools.org/2012/Venue/ConferenceSite same site] as the conference
* The meeting has no registration fees
* The meeting is open to anyone interested
* Arrangements for lunch and coffee are still being investigated.
* The tentative schedule is 09h00-17h00 with lunch break.
* Remote participation (e.g. WebEx and audio) is being investigated.

= Tentative Attendance =

If you'd like to attend, please add your name.

* Tommaso Pecorella (University of Florence)
* Tom Henderson
* Felipe Perrone
* George Riley
* Lalith Suresh
* Peter Barnes

= Tentative Topics =
* Memory leaks extermination process, see John Abraham mail: [http://mailman.isi.edu/pipermail/ns-developers/2012-February/009990.html]
* Review ns-3 packaging (Fedora/Ubuntu), discuss long term support for releases

= Action Points =