build: Support tools and examples with multiple translation units

Change-Id: I71a5690391464d8275b91f55e914c004eed4f360
Refs: #2344

examples/README.md

@@ -0,0 +1,52 @@
+ndn-cxx examples
+================
+
+By default, examples in `examples/` folder are not built.  To enable them, use
+`--with-examples` configure option. For example:
+
+    ./waf configure --with-examples
+    ./waf
+
+There are two ways to add new examples, depending on their complexity:
+
+1. Examples with a single translation unit
+
+  For simple examples that have a single translation unit, the `.cpp` file can be directly put
+  in `examples/` folder and it will be automatically compiled on the next run of `./waf`. Name
+  of the compiled binary will be determined by the base name of the `.cpp` file.  For example,
+  `examples/foo.cpp` will be compiled into binary `foo` in `<build>/examples` folder:
+
+        echo "int main() { return 0; }" > examples/foo.cpp
+        ./waf
+        # ... Compiling examples/foo.cpp
+        # ... Linking build/examples/foo
+
+        # To run the example
+        ./build/examples/foo
+
+2. Examples with multiple translation units
+
+  For more complex examples that contain multiple translation units, one can use
+  the following directory structure:
+
+  - Create a directory under `examples/` folder (e.g., `examples/bar`).
+    The name of this directory will determine the name of the compiled binary
+   (`<build>/examples/bar/bar`)
+
+  - Place any number of translation units (e.g., `examples/bar/a.cpp`, `examples/bar/b.cpp`,
+    ...) in this directory.  All `.cpp` files in this directory will be compiled and linked
+    together to produce the binary of the example.  One of the .cpp files should contain
+    the `main()` function.
+
+  For example:
+
+        mkdir examples/bar
+        echo "int bar(); int main() { return bar(); }" > examples/bar/a.cpp
+        echo "int bar() { return 10; } " > examples/bar/b.cpp
+        ./waf
+        # ... Compiling examples/bar/a.cpp
+        # ... Compiling examples/bar/b.cpp
+        # ... Linking build/examples/bar/bar
+
+        # To run the example
+        ./build/examples/bar/bar

examples/wscript

@@ -3,10 +3,22 @@
 top = '..'
 
 def build(bld):
-    for app in bld.path.ant_glob('*.cpp'):
+    # List all .cpp files (whole example should be in one .cpp)
+    for i in bld.path.ant_glob(['*.cpp']):
+        name = str(i)[:-len(".cpp")]
         bld(features=['cxx', 'cxxprogram'],
-            target = '%s' % (str(app.change_ext('','.cpp'))),
-            source = app,
-            use = 'ndn-cxx',
-            install_path = None,
+            target=name,
+            source=[i] + bld.path.ant_glob(['%s/**/*.cpp' % name]),
+            use='ndn-cxx',
+            install_path=None
+            )
+
+    # List all directories files (example can has multiple .cpp in the directory)
+    for name in bld.path.ant_glob(['*'], dir=True, src=False):
+        bld(features=['cxx', 'cxxprogram'],
+            target="%s/%s" % (name, name),
+            source=bld.path.ant_glob(['%s/**/*.cpp' % name]),
+            use='ndn-cxx',
+            install_path=None,
+            includes='%s' % name,
             )

tools/README.md

@@ -0,0 +1,55 @@
+ndn-cxx tools
+=============
+
+Unless disabled with `--without-tools` configuration option, files in `tools/` directory
+are automatically build and installed to `${PREFIX}/bin` folder.
+
+There are two ways to add new tools, depending on their complexity:
+
+1. Tools with a single translation unit
+
+  For simple tools that have a single translation unit, the `.cpp` file can be directly put
+  in `tools/` folder and it will be automatically compiled on the next run of `./waf`. Name
+  of the compiled binary will be determined by the base name of the `.cpp` file.  For example,
+  `tools/foo.cpp` will be compiled into binary `foo` in `<build>/bin/` folder:
+
+        echo "int main() { return 0; }" > tools/foo.cpp
+        ./waf
+        # ... Compiling tools/foo.cpp
+        # ... Linking build/bin/foo
+
+        sudo ./waf install
+        # ... install /usr/local/bin/foo (from build/bin/foo)
+
+        # To run the tool
+        /usr/local/bin/foo
+
+2. Tools with multiple translation units
+
+  For more complex tools that contain multiple translation units, one can use
+  the following directory structure:
+
+  - Create a directory under `tools/` folder (e.g., `tools/bar`).
+    The name of this directory will determine the name of the compiled binary
+   (`<build>/bin/bar`)
+
+  - Place any number of translation units (e.g., `tools/bar/a.cpp`, `tools/bar/b.cpp`,
+    ...) in this directory.  All `.cpp` files in this directory will be compiled and linked
+    together to produce the binary of the tool.  One of the .cpp files should contain
+    the `main()` function.
+
+  For example:
+
+        mkdir tools/bar
+        echo "int bar(); int main() { return bar(); }" > tools/bar/a.cpp
+        echo "int bar() { return 10; } " > tools/bar/b.cpp
+        ./waf
+        # ... Compiling tools/bar/a.cpp
+        # ... Compiling tools/bar/b.cpp
+        # ... Linking build/bin/bar
+
+        sudo ./waf install
+        # ... install /usr/local/bin/bar (from build/bin/bar)
+
+        # To run the tool
+        /usr/local/bin/bar

tools/wscript

@@ -8,17 +8,28 @@ def configure(conf):
     conf.find_program('sh')
 
 def build(bld):
-    for app in bld.path.ant_glob('*.cpp'):
+    # List all .cpp files (whole tool should be in one .cpp)
+    for i in bld.path.ant_glob(['*.cpp']):
+        name = str(i)[:-len(".cpp")]
         bld(features=['cxx', 'cxxprogram'],
-            target = '%s' % (str(app.change_ext('','.cpp'))),
-            source = app,
-            use = 'ndn-cxx',
+            target="../bin/%s" % name,
+            source=[i] + bld.path.ant_glob(['%s/**/*.cpp' % name]),
+            use='ndn-cxx'
             )
 
-    bld(features = "subst",
-        source = bld.path.ant_glob(['wrapper/*.sh']),
-        target = ['%s' % node.change_ext('', '.sh')
-                  for node in bld.path.ant_glob(['wrapper/*.sh'])],
-        install_path = "${BINDIR}",
-        chmod = Utils.O755,
+    # List all directories files (tool can has multiple .cpp in the directory)
+    for name in bld.path.ant_glob(['*'], dir=True, src=False, excl=['wrapper']):
+        bld(features=['cxx', 'cxxprogram'],
+            target="../bin/%s" % name,
+            source=bld.path.ant_glob(['%s/**/*.cpp' % name]),
+            use='ndn-cxx',
+            includes='%s' % name,
+            )
+
+    bld(features="subst",
+        source=bld.path.ant_glob(['wrapper/*.sh']),
+        target=['%s' % node.change_ext('', '.sh')
+                for node in bld.path.ant_glob(['wrapper/*.sh'])],
+        install_path="${BINDIR}",
+        chmod=Utils.O755,
        )