From b021f53ea21de882a0a823acd2988b23c4faf148 Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Sat, 21 Jul 2018 16:31:05 -0700
Subject: [PATCH] Document the API change from removing --no32bit-scan

---
 CHANGES.html                 |  1 +
 RELEASE_NOTES                |  1 +
 doc/manual/source/python.rst | 58 ++++++++++++------------------------
 utils/tests/test-waf.py      |  3 +-
 4 files changed, 22 insertions(+), 41 deletions(-)

diff --git a/CHANGES.html b/CHANGES.html
index b42bac8ef..3bf6768f4 100644
--- a/CHANGES.html
+++ b/CHANGES.html
@@ -97,6 +97,7 @@ or with a string value with 'b' (bytes) or 'p' (packets) suffix, such as:
 </ul>
 <h2>Changes to build system:</h2>
 <ul>
+  <li>The '--no32bit-scan' argument is removed from Waf apiscan; generation of ILP32 bindings is now automated from the LP64 bindings.</li>
 </ul>
 <h2>Changed behavior:</h2>
 <ul>
diff --git a/RELEASE_NOTES b/RELEASE_NOTES
index 217a82fd8..1e627b316 100644
--- a/RELEASE_NOTES
+++ b/RELEASE_NOTES
@@ -37,6 +37,7 @@ Bugs fixed
 - Bug 2911 - aodv:  Binary exponential backoff can become unlimited
 - Bug 2901 - Add CommandLine::Parse (const std::vector<std::string>> args)
 - Bug 2891 - netanim:  dumbbell-animation breaks when RightCount > LeftCount
+- Bug 2451 - bindings: (partial fix) generating ILP32 bindings from LP64
 - Bug 2461 - CommandLine should handle non-option arguments
 - Bug 2801 - FdNetDevice device MTU is not set correctly
 - Bug 2819 - FqCoDel handling of non-IP packets
diff --git a/doc/manual/source/python.rst b/doc/manual/source/python.rst
index 2a09e5312..645d8de7b 100644
--- a/doc/manual/source/python.rst
+++ b/doc/manual/source/python.rst
@@ -265,16 +265,15 @@ Process Overview
 ################
 
 |ns3| has an automated process to regenerate Python bindings from the C++
-header files.  The automated process is only semi-automated at the moment
-(ns-3.27) because we are in the midst of transition to new tools.  The
+header files.  The process is only supported for Linux at the moment
+(ns-3.29) because we are in the midst of transition to new tools.  The
 current process is outlined below.  In short, the process currently 
 requires the following steps.
 
 1.  Prepare the system for scanning by installing the prerequisites,
     including a development version of ``clang``, the ``CastXML`` package,
     and ``pygccxml``.
-2.  Perform a 64-bit scan of the module or modules of interest
-3.  Create the 32-bit bindings file from the 64-bit scan output
+2.  Perform a scan of the module of interest or all modules
 
 Installing a clang development environment
 ##########################################
@@ -382,24 +381,8 @@ In this case, the user must take steps to install castxml and pygccxml;
 castxml binary must be in the shell's path, and pygccxml must be in the
 Python path.
 
-Rescan 64-bit
-#############
-
-It is important that you scan the failing module with '--no32bit-scan'; e.g.:
-
-::
-
-    $ cd source/ns-3-dev
-    $ ./waf --apiscan=wifi --no32bit-scan
-
-Generate 32-bit
-###############
-
-Once the 64-bit bindings are fixed, if you are a maintainer and need to
-generate the 32-bit equivalent: 
-
-1. copy the newly scanned LP64.py file(s) to the ILP32.py filename
-2. on the ILP32.py file(s), perform global substitition of ``unsigned long`` with ``unsigned long long``
+LP64 vs ILP32 bindings
+######################
 
 Linux (64-bit, as most modern installations use) and MacOS use different
 data models, as explained here:  https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.cbcpx01/datatypesize64.htm
@@ -410,36 +393,33 @@ each ns-3 module directory; one with an ILP32.py suffix and one with
 an LP64.py suffix.  Only one is used on any given platform.  The main
 difference is in the representation of the 64 bit integer type as either
 a 'long' (LP64) or 'long long' (ILP32).  
+
+The process (only supported on Linux at present) generates the LP64
+bindings using the toolchain and then copies the LP64 bindings to the
+ILP32 bindings with some type subsitutions automated by Waf scripts.
   
-As of ns-3.27, the CastXML framework can generate LP64 bindings by passing
-the ``--no32bit-scan`` flag.  However, the framework does not automatically
-generate 32bit scans at the moment.  Instead, users must manually generate
-the ILP32.py equivalents by taking all instances of 'unsigned long' in the
-bindings file and converting them to 'unsigned long long', such as:
+Rescanning a module
+###################
+
+To re-scan a module:
 
 ::
 
-  -    cls.add_instance_attribute('nMarkedBytes', 'std::map< std::string, unsigned long >', is_const=False)
-  +    cls.add_instance_attribute('nMarkedBytes', 'std::map< std::string, unsigned long long >', is_const=False)
+    $ cd source/ns-3-dev
+    $ ./waf --apiscan=wifi
 
-In summary, to generate LP64 bindings for Linux 64-bit systems, it is
-sufficient to call (e.g. for the ``core`` module):
+To re-scan all modules:
 
 ::
 
-  $ ./waf --apiscan=core --no32bit-scan
-
-To generate ILP32 bindings, one first must generate the LP64.py file as above,
-and then copy the file to be named with an ILP32.py suffix, and then 
-hand-edit that file, replacing all instances of 'unsigned long' with
-'unsigned long long'.  |ns3| maintainers are working to better automate
-this process for future releases.
+    $ cd source/ns-3-dev
+    $ ./waf --apiscan=all
 
 Generating bindings on MacOS
 ############################
 
 In principle, this should work (and should generate the 32-bit bindings).
-However, it is untested and we are not sure what instructions to offer.
+However, maintainers have not been able to complete this port as of ns-3.29.
 We would welcome suggestions on how to enable scanning for MacOS. 
 
 Organization of the Modular Python Bindings
diff --git a/utils/tests/test-waf.py b/utils/tests/test-waf.py
index 55f38312c..ed8adad3c 100644
--- a/utils/tests/test-waf.py
+++ b/utils/tests/test-waf.py
@@ -94,7 +94,6 @@ def main(argv):
         "--disable-python",
         "--apiscan=all",
         "--with-python=/usr/bin/python2.7",
-        "--no32bit-scan",
         "-o test_out && rm -rf test_out",
         "--out=test_out && rm -rf test_out",
         "-t test_top && rm -rf test_top",
@@ -192,4 +191,4 @@ def main(argv):
     return runner.runtests(cmd_execute_list)
 
 if __name__ == '__main__':
-    sys.exit(main(sys.argv))
\ No newline at end of file
+    sys.exit(main(sys.argv))