--- a/bindings/python/genbinds.py Wed Feb 12 15:18:20 2014 +0100
+++ b/bindings/python/genbinds.py Wed Feb 12 16:49:01 2014 +0100
@@ -16,41 +16,11 @@
## during gccxml scanning.
import ns3modulegen_core_customizations
-
-includes_dce = [
- #'dce-module.h',
- 'dce-manager.h',
- 'task-scheduler.h',
- 'task-manager.h',
- 'socket-fd-factory.h',
- 'loader-factory.h',
- 'dce-application.h',
- 'ipv4-dce-routing.h',
- 'ipv4-linux.h',
- 'process-delay-model.h',
- 'linux-ipv4-raw-socket-factory.h',
- 'linux-udp-socket-factory.h',
- 'linux-tcp-socket-factory.h',
- 'linux-dccp-socket-factory.h',
- 'dce-manager-helper.h',
- 'dce-application-helper.h',
- 'ccn-client-helper.h',
- 'ipv4-dce-routing-helper.h',
- 'linux-stack-helper.h'
-]
-
includes_dce = [
'dce-application.h',
'dce-application-helper.h',
'dce-manager-helper.h',
]
-includes_dce_helper = [
- #'dce-application-helper.h',
- #dce-manager-helper.h',
- #'ccn-client-helper.h',
- #'linux-stack-helper.h',
- #'ipv4-dce-routing-helper.h'
-]
type_annotations = {
@@ -331,13 +301,14 @@
def dcepy_module_gen( binddir, ns3path, dcepath ):
DCE_INCLUDE_PATH=dcepath
-
+ '''
print "************************* dcepy_module_gen"
print "* binddir = " + binddir
print "* ns3path = " + ns3path
print "* dcepath = " + dcepath
print "******************************************"
-
+ '''
+
cflags = ''
bldpath = 'bindings/python'
@@ -364,15 +335,9 @@
inclfiles.append( ref_header_dir+"/"+hf )
#inclfiles.append( dcepath+"/model/"+hf )
- #for hf in includes_dce_helper:
- # inclfiles.append( dcepath+"/helper/"+hf )
#whitelist_paths=[ dcepath+"/model", dcepath + "/helper", ns3path ]
whitelist_paths=[ ref_header_dir ]
-# #module = module_parser.parse(inclfiles, \
-# whitelist_paths=whitelist_paths, \
-# gccxml_options=gccxml_options, \
-# )
module_parser = ModuleParser('DCE', 'ns3')
module_parser.enable_anonymous_containers = True
--- a/bindings/python/wscript Wed Feb 12 15:18:20 2014 +0100
+++ b/bindings/python/wscript Wed Feb 12 16:49:01 2014 +0100
@@ -37,12 +37,12 @@
help=("Don't build Python bindings."),
action="store_true", default=False,
dest='python_disable')
- #opt.add_option('--apiscan',
+ #opt.add_option('',
# help=("Rescan the API for the indicated module(s), for Python bindings. "
# "Needs working GCCXML / pygccxml environment. "
# "The metamodule 'all' expands to all available ns-3 modules."),
# default=None, dest='apiscan', metavar="MODULE[,MODULE...]")
- opt.add_option('--genbind',
+ opt.add_option('--apiscan',
help=("Rescan the API for Python bindings. Needs working GCCXML / pygccxml environment. " ),
action="store_true", default=False,
dest='genbind' )
--- a/doc/source/dce-dev-python.rst Wed Feb 12 15:18:20 2014 +0100
+++ b/doc/source/dce-dev-python.rst Wed Feb 12 16:49:01 2014 +0100
@@ -3,8 +3,79 @@
Python Bindings
***************
- --disable-python Don't build Python bindings.
- --genbind Rescan the API for Python bindings. Needs working GCCXML / pygccxml environment.
- --with-pybindgen=WITH_PYBINDGEN
- Path to an existing pybindgen source tree to use.
- --with-python=WITH_PYTHON
+This section describes how generate the DCE Python bindings. The intended audience
+are the DCE developers, not the users willing to make simulations. People not
+interested in adding new public API can ignore this section, and read the chapter
+:ref:`python_scripts-label`.
+
+Waf configuration scripts generate the Python bindings in a semi-automatic way,
+matching almost closely what ns-3 does. It uses `PyBindGen <http://packages.python.org/PyBindGen>`_
+to generate a Python script, that needs to be manually calibrated. This intermediate
+script will generate a C++ source file that can be then compiled as a shared object,
+installed and imported by the Python scripts.
+
+Step by Step
+############
+
+Step 1: Api scan
+----------------
+
+In this step, ``Waf`` calls PyBindGen to analyze the DCE public reference headers,
+in order to generate a temporary Python file that will generate a C++ file.
+
+.. code-block:: sh
+
+ ./waf --apiscan
+
+
+Step 2: Pybindgen script update
+-------------------------------
+
+The Pyhon script generated in the first step needs to be adjusted and renamed as
+``ns3_module_dce.py``. In particular to reduce the coupling with the ns-3
+installation the waf configuration has been simplified. For this reason you
+need to paste the correct references for the ns-3 exported symbols, as for example:
+
+.. code-block:: python
+
+ module.add_class('Object', import_from_module='ns.core')
+ module.add_class('Node', import_from_module='ns.network')
+ module.add_class('NodeContainer', import_from_module='ns.network')
+
+
+Step 3: C++ source code generation
+----------------------------------
+
+``ns3_module_dce.py`` can directly generate a C++ file for the Python module:
+
+.. code-block:: sh
+
+ export PYTHONPATH=HERE_THE_PATH_TO_PYBINDGEN/pybindgen
+ python ns3_module_dce.py > dce_bindings.cpp
+
+The file ``dce_bindings.cpp`` should be added to the code revision system
+and included in the distribution.
+
+Step 4: Compilation
+-------------------
+
+In the compilation phase, ``wscript`` (the Waf installation module), compiles
+``dce_bindings.cpp`` and generate a shared object called DCE.so. This is
+the Python binding module.
+
+.. code-block:: sh
+
+ ./waf
+ ./waf install
+
+
+Configuration parameters
+########################
+waf configuration flags:
+
+ --disable-python Don't build Python bindings.
+ --apiscan Rescan the API for Python bindings. Needs working GCCXML / pygccxml environment.
+ --with-pybindgen=WITH_PYBINDGEN Path to an existing `Pybindgen <http://packages.python.org/PyBindGen>`_ source tree to use.
+ --with-python=WITH_PYTHON Path to an existing Pyhton installation
+
+
--- a/doc/source/dce-user-basic.rst Wed Feb 12 15:18:20 2014 +0100
+++ b/doc/source/dce-user-basic.rst Wed Feb 12 16:49:01 2014 +0100
@@ -7,7 +7,6 @@
:maxdepth: 2
dce-user-newapps
- dce-user-python
dce-user-kernel
dce-user-syscalls
dce-user-submodule
--- a/doc/source/dce-user-doc.rst Wed Feb 12 15:18:20 2014 +0100
+++ b/doc/source/dce-user-doc.rst Wed Feb 12 16:49:01 2014 +0100
@@ -20,4 +20,5 @@
dce-user-basic
dce-user-advanced
dce-user-tech
+ dce-user-python
--- a/doc/source/dce-user-python.rst Wed Feb 12 15:18:20 2014 +0100
+++ b/doc/source/dce-user-python.rst Wed Feb 12 16:49:01 2014 +0100
@@ -1,7 +1,9 @@
.. include:: replace.txt
-Write Python Scripts
-********************
+.. _python_scripts-label:
+
+DCE Python Scripts
+******************
Currently DCE includes an experimental support to the `Python <http://www.python.org/>`_ language.
To enable it, you may need to recompile it with the flags:
@@ -17,3 +19,54 @@
--with-python=HERE_THE_PYTHON_PATH
+The first thing you may want to do is to import the DCE module.
+For example a minimal DCE script in Python could be:
+
+.. code-block:: python
+
+ from ns.DCE import *
+ print "It works!"
+
+A first example
+###############
+
+In this example, DCE executes a program running ten seconds on a single node.
+
+.. code-block:: python
+
+ # DCE import
+ from ns.DCE import *
+ # ns-3 imports
+ import ns.applications
+ import ns.core
+ import ns.network
+
+ # Increase the verbosity level
+ ns.core.LogComponentEnable("Dce", ns.core.LOG_LEVEL_INFO)
+ ns.core.LogComponentEnable("DceManager", ns.core.LOG_LEVEL_ALL)
+ ns.core.LogComponentEnable("DceApplication", ns.core.LOG_LEVEL_INFO)
+ ns.core.LogComponentEnable("DceApplicationHelper", ns.core.LOG_LEVEL_INFO)
+
+ # Node creation
+ nodes = ns.network.NodeContainer()
+ nodes.Create(1)
+
+ # Configure DCE
+ dceManager = ns.DCE.DceManagerHelper()
+ dceManager.Install (nodes);
+ dce = ns.DCE.DceApplicationHelper()
+
+ # Set the binary
+ dce.SetBinary ("tenseconds")
+ dce.SetStackSize (1<<20)
+
+ # dce.Install returns an instance of ns.DCE.ApplicationContainer
+ apps = dce.Install (nodes )
+ apps.Start ( ns.core.Seconds (4.0))
+
+ # Simulation
+ ns.core.Simulator.Stop (ns.core.Seconds(220.0))
+ ns.core.Simulator.Run ()
+ ns.core.Simulator.Destroy ()
+ print "Done."
+
\ No newline at end of file