From a0476f4f877099c3d9b78f5e373d3065b9221e3c Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Wed, 7 Dec 2011 16:11:42 -0800 Subject: [PATCH] Fix outdated README information --- README | 41 +++++++++++++++++++++++----------------- doc/build.txt | 52 +++++++++++++++++++++++++-------------------------- 2 files changed, 50 insertions(+), 43 deletions(-) diff --git a/README b/README index aa88bef53..80af14971 100644 --- a/README +++ b/README @@ -24,14 +24,15 @@ the missing pieces of the models we have not yet implemented will be contributed by the community in an open collaboration process. -Contributing to the ns-3 project is still a very informal -process because that process depends heavily on the background -of the people involved, the amount of time they can invest -and the type of model they want to work on. +The process of contributing to the ns-3 project varies with +the people involved, the amount of time they can invest +and the type of model they want to work on, but the current +process that the project tries to follow is described here: +http://www.nsnam.org/developers/contributing-code/ -Despite this lack of a formal process, there are a number of -steps which naturally stem from the open-source roots of the -project. These steps are described in doc/contributing.txt +This README excerpts some details from a more extensive +tutorial that is maintained at: +http://www.nsnam.org/documentation/latest/ 2) Building ns-3 ---------------- @@ -47,9 +48,13 @@ tool 'waf'. Detailed information on how use waf is included in the file doc/build.txt However, the real quick and dirty way to get started is to -type the command "./waf configure; ./waf" the the directory which contains +type the command + ./waf configure --enable-examples +followed by + ./waf +in the the directory which contains this README file. The files built will be copied in the -build/debug or build/optimized. +build/ directory. The current codebase is expected to build and run on the set of platforms listed in the RELEASE_NOTES file. @@ -60,15 +65,16 @@ improve the portability of the code to these other platforms. 3) Running ns-3 --------------- -On recent Linux systems, once you have built ns-3, it -should be easy to run the sample programs with the -following command: +On recent Linux systems, once you have built ns-3 (with examples +enabled), it should be easy to run the sample programs with the +following command, such as: -./waf --run simple-global-routing + ./waf --run simple-global-routing That program should generate a simple-global-routing.tr text trace file and a set of simple-global-routing-xx-xx.pcap binary pcap trace files, which can be read by tcpdump -tt -r filename.pcap +The program source can be found in the examples/routing directory. 4) Getting access to the ns-3 documentation ------------------------------------------- @@ -79,18 +85,19 @@ quite likely that you will want to get started on reading some ns-3 documentation. All of that documentation should always be available from -the ns-3 website: http:://www.nsnam.org/ but we -include some of it in this release for ease of use. +the ns-3 website: http:://www.nsnam.org/documentation/. This documentation includes: - a tutorial - - a manual + - a reference manual + + - models in the ns-3 model library - a wiki for user-contributed tips: http://www.nsnam.org/wiki/ - - an API documentation generated using doxygen: this is + - API documentation generated using doxygen: this is a reference manual, most likely not very well suited as introductory text: http://www.nsnam.org/doxygen/index.html diff --git a/doc/build.txt b/doc/build.txt index 15b398b44..5f424f3d6 100644 --- a/doc/build.txt +++ b/doc/build.txt @@ -23,28 +23,28 @@ To build ns-3 with waf type the commands from the top-level directory: To see valid configure options, type ./waf --help. The most important option is -d . Valid debug levels (which are listed in -waf --help) are: "debug" or "optimized". It is +waf --help) are: "debug" or "optimized", with debug being default. It is also possible to change the flags used for compilation with (e.g.): -CXXFLAGS="-O3" ./waf configure. +CXXFLAGS="-O3" ./waf configure. By default, ns-3 is built as debug code, +with examples and tests disabled, and with python bindings enabled. [ Note: Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than the build stage (i.e., "./waf -d optimized" will not work; instead, do "./waf -d optimized configure; ./waf" ] -The resulting binaries are placed in build//srcpath. +The resulting executables and libraries are placed in build/. Other waf usages include: 1. ./waf configure --enable-examples --enable-tests Turn on examples and tests. - 2. ./waf --doxygen - Run doxygen to generate documentation + 2. ./waf configure --disable-python + Disable python bindings. - 3. ./waf --lcov-report - Run code coverage analysis (assuming the project was configured -with --enable-gcov) + 3. ./waf --doxygen + Run doxygen to generate documentation 4. ./waf --run "program [args]" Run a ns3 program, given its target name, with the given @@ -79,29 +79,29 @@ To add new modules: 1. Create the module directory under src; 2. Add the source files to it; 3. Add a 'wscript' describing it; - 4. Add the module subdirectory name to the all_modules list in src/wscript. + +A convenience program to auto-generate the template of a new module can +be found in src/create-module.py. A module's wscript file is basically a regular Waf script. A ns-3 module is created as a cpp/shlib object, like this: def build(bld): - obj = bld.create_obj('cpp', 'shlib') + module = bld.create_ns3_module('ns3-mymodule', ['core']) + module.source = [ + 'model/ns3-mymodule.cc', + 'helper/ns3-mymodule-helper.cc', + ] - ## set module name; by convention it starts with ns3- - obj.name = 'ns3-mymodule' - obj.target = obj.name - - ## list dependencies to other modules - obj.uselib_local = ['ns3-core'] - - ## list source files (private or public header files excluded) - obj.source = [ - 'mymodule.cc', - ] - - ## list module public header files - headers = bld.create_obj('ns3header') + headers = bld.new_task_gen(features=['ns3header']) + headers.module = 'ns3-mymodule' headers.source = [ - 'mymodule-header.h', - ] + 'model/ns3-mymodule.h', + 'helper/ns3-mymodule-helper.h', + ] + + if bld.env.ENABLE_EXAMPLES: + bld.add_subdirs('examples') + + # bld.ns3_python_bindings()