[Ns-developers] More gratuitous API breakage in ns-3-dev

[Gustavo Carneiro]

2008/7/8 Gustavo Carneiro <gjcarneiro at gmail.com>:

> I was re-syncing the ns-3-learning-bridge branch with ns-3-dev, and my
> learning bridge example is not compiling any more:
>
> ../examples/csma-bridge.cc: In function 'int main(int, char**)':
> ../examples/csma-bridge.cc:80: error: 'class ns3::CsmaHelper' has no member
> named 'SetChannelParameter'
> ../examples/csma-bridge.cc:81: error: 'class ns3::CsmaHelper' has no member
> named 'SetChannelParameter'
>
>
> Investigating the matter it is in bug 232.  Just a terminology change, but
> it so happens that it breaks API!  Come on, is it so hard to provide
> compatibility for this, something like below.  You could remove the
> compatibility APIs after a couple of ns-3 releases.  It's very easy if the
> deprecated APIs are correctly marked like in my patch.


Just to complete my previous email, a better way to handle deprecations is
to mark them with gcc __attribute__ ((deprecated)).  This ensures that
deprecations are discovered, but are not fatal:


diff -r 4e4cb6a885ca src/helper/csma-helper.h
--- a/src/helper/csma-helper.h    Tue Jul 08 14:40:01 2008 +0100
+++ b/src/helper/csma-helper.h    Tue Jul 08 15:05:25 2008 +0100
@@ -78,6 +78,9 @@
    * by CsmaHelper::Install
    */
   void SetChannelAttribute (std::string n1, const AttributeValue &v1);
+
+  void SetChannelParameter (std::string n1, const AttributeValue &v1)
+    __attribute__ ((deprecated)) { SetChannelAttribute (n1, v1); }

   /**
    * \param filename filename prefix to use for pcap files.
diff -r 4e4cb6a885ca wscript
--- a/wscript    Tue Jul 08 14:40:01 2008 +0100
+++ b/wscript    Tue Jul 08 15:05:25 2008 +0100
@@ -194,7 +194,7 @@

     if (os.path.basename(conf.env['CXX']).startswith("g++")
         and 'CXXFLAGS' not in os.environ):
-        variant_env.append_value('CXXFLAGS', ['-Werror'])
+        variant_env.append_value('CXXFLAGS', ['-Werror',
'-Wno-error=deprecated-declarations'])

     if 'debug' in Params.g_options.debug_level.lower():
         variant_env.append_value('CXXDEFINES', 'NS3_ASSERT_ENABLE')


Of course that for portability __attribute__ ((deprecated)) would have to be
a NS3_DEPRECATED macro defined conditionally as a -D option in
compilation...

The result is something like:

[421/470] cxx: examples/csma-bridge.cc ->
build/debug/examples/csma-bridge_7.o
../examples/csma-bridge.cc: In function 'int main(int, char**)':
../examples/csma-bridge.cc:80: warning: 'SetChannelParameter' is deprecated
(declared at debug/ns3/csma-helper.h:83)
../examples/csma-bridge.cc:81: warning: 'SetChannelParameter' is deprecated
(declared at debug/ns3/csma-helper.h:83)


-- 
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert