Difference between revisions of "Ns-3 on Visual Studio"

From Nsnam
Jump to: navigation, search
(comments)
Line 34: Line 34:
  
 
=== Phase 2 – Visual Studio Windows Conditional Compilation ===
 
=== 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.  The changes mostly fall into the following categories:
+
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.   
  
Code to the example programs to produce crashdump files under the Release configuration (similar to core files produced under the Unix variant operating systems).
+
For example, the following code from CORE is an example of code changed for Windows to produce the same log output:
  
==== Additional CrashHandler header ====
+
<nowiki>#ifndef _WIN32
This includes adding an additional header file
+
#define NS_LOG_APPEND_FUNC_PREFIX                              \
 +
  if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC))                  \
 +
    {                                                          \
 +
      std::clog << g_log.Name () << ":" <<                      \
 +
      __FUNCTION__ << "(): ";                                  \
 +
    }                                                          \
  
<nowiki>#ifdef _WIN32
+
#else
#include "CrashHandler.h"
+
#define NS_LOG_APPEND_FUNC_PREFIX                              \
#endif</nowiki>
+
  if (g_log.IsEnabled (ns3::LOG_PREFIX_FUNC))                  \
 +
    {                                                          \
 +
      std::clog << g_log.Name () << ":" <<                      \
 +
      __func__ << "(): ";                                      \
 +
    }                                                          \
  
* ''Suggest adding this to'' <code>src/core/model/command-line.h</code>, since all executables'' should ''(at least in the main tree) have a'' <code>CommandLine</code> ''instance.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
 
** Suggested change incorporated, no need to modify individual programs to include header file.  Required updating a few programs to include command-line.h [[User:rammon|Robert Ammon]]
 
 
==== Instantiating the CrashHandler ====
 
And an additional installation function
 
 
<nowiki>#ifdef _WIN32
 
#ifndef _DEBUG
 
CCrashHandler ch;
 
ch.SetProcessExceptionHandlers();
 
ch.SetThreadExceptionHandlers();
 
#endif
 
 
#endif</nowiki>
 
#endif</nowiki>
 
to each main program.
 
 
* ''What scope and lifetime does the'' <code>CCrashHandler</code> ''instance require?  Can it be a data member of'' <code>CommandLine</code> ''? Or a global declared in'' <code>src/core/model/command-line.cc</code>''?'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
 
** Suggested change incorporated, no need to modify individual programs to include crash handler.  Suggestions eliminate changes to most examples [[User:rammon|Robert Ammon]]
 
 
==== Loading DLLs ====
 
Modification of existing code or addition of new code for the Windows configuration.  For example
 
 
<nowiki>#ifdef _WIN32
 
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean,NS3CORELIB);
 
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean,NS3CORELIB);
 
#else
 
ATTRIBUTE_CHECKER_DEFINE (Boolean);
 
ATTRIBUTE_ACCESSOR_DEFINE (Boolean);
 
#endif
 
 
#define ATTRIBUTE_CHECKER_DEFINE_LIB(type,lib)                          \
 
  class lib type ## Checker : public AttributeChecker {};              \
 
  lib Ptr<const AttributeChecker> Make ## type ## Checker (void)
 
 
#define ATTRIBUTE_CHECKER_DEFINE(type)                                  \
 
  class type ## Checker : public AttributeChecker {};                  \
 
  Ptr<const AttributeChecker> Make ## type ## Checker (void)
 
</nowiki>
 
  
 
The modifications in this phase affect a minority of the NS-3 source code files.
 
The modifications in this phase affect a minority of the NS-3 source code files.
 
* ''Examples like this need some explanation, at least indicating where (in what kinds of files) these lines would appear, how macros would be invoked.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
 
* ''This example is problematic for a couple of reasons.  First, not all attributes are in the core lib. Second, this doesn't effectively hide the WIN32 implementation: declarers of Attributes will still need a conditional block to invoke the _LIB version for public API, but only on WIN32.  Third, in this particular case, AttributeCheckers should always be public.'' [[User:Pdbarnes|Pdbarnes]] ([[User talk:Pdbarnes|talk]])
 
  
 
=== Phase 3 – Visual Studio Class Declaration Changes ===
 
=== Phase 3 – Visual Studio Class Declaration Changes ===
Line 116: Line 85:
  
 
  class NS3ANTLIB AntennaModel : public Object
 
  class NS3ANTLIB AntennaModel : public Object
 +
 +
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.
 +
 +
ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
 +
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);
 +
 +
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
 +
 +
ATTRIBUTE_HELPER_HEADER (ValueClassTest);
 +
ATTRIBUTE_HELPER_CPP (ValueClassTest);
  
 
The modifications in this phase affect almost every header file in the NS-3 source code.
 
The modifications in this phase affect almost every header file in the NS-3 source code.

Revision as of 23:21, 5 April 2018

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

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

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:

#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

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. This change adds a new header file to the core module and an additional conditional declaration to each class declaration.

NS3DLL.H code fragment
#ifndef NS3DLL_H
#define NS3DLL_H

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

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

Example class declaration

class NS3ANTLIB AntennaModel : public Object

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.

ATTRIBUTE_CHECKER_DEFINE_LIB (Boolean, NS3CORELIB);
ATTRIBUTE_ACCESSOR_DEFINE_LIB (Boolean, NS3CORELIB);

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

ATTRIBUTE_HELPER_HEADER (ValueClassTest);
ATTRIBUTE_HELPER_CPP (ValueClassTest);

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

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.