|
1 .. include:: replace.txt |
|
2 |
|
3 Resources |
|
4 --------- |
|
5 |
|
6 The Web |
|
7 ******* |
|
8 |
|
9 There are several important resources of which any |ns3| user must be |
|
10 aware. The main web site is located at http://www.nsnam.org and |
|
11 provides access to basic information about the |ns3| system. Detailed |
|
12 documentation is available through the main web site at |
|
13 http://www.nsnam.org/documents.html. You can also find documents |
|
14 relating to the system architecture from this page. |
|
15 |
|
16 There is a Wiki that complements the main |ns3| web site which you will |
|
17 find at http://www.nsnam.org/wiki/. You will find user and developer |
|
18 FAQs there, as well as troubleshooting guides, third-party contributed code, |
|
19 papers, etc. |
|
20 |
|
21 The source code may be found and browsed at http://code.nsnam.org/. |
|
22 There you will find the current development tree in the repository named |
|
23 ``ns-3-dev``. Past releases and experimental repositories of the core |
|
24 developers may also be found there. |
|
25 |
|
26 Mercurial |
|
27 ********* |
|
28 |
|
29 Complex software systems need some way to manage the organization and |
|
30 changes to the underlying code and documentation. There are many ways to |
|
31 perform this feat, and you may have heard of some of the systems that are |
|
32 currently used to do this. The Concurrent Version System (CVS) is probably |
|
33 the most well known. |
|
34 |
|
35 The |ns3| project uses Mercurial as its source code management system. |
|
36 Although you do not need to know much about Mercurial in order to complete |
|
37 this tutorial, we recommend becoming familiar with Mercurial and using it |
|
38 to access the source code. Mercurial has a web site at |
|
39 http://www.selenic.com/mercurial/, |
|
40 from which you can get binary or source releases of this Software |
|
41 Configuration Management (SCM) system. Selenic (the developer of Mercurial) |
|
42 also provides a tutorial at |
|
43 http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial/, |
|
44 and a QuickStart guide at |
|
45 http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart/. |
|
46 |
|
47 You can also find vital information about using Mercurial and |ns3| |
|
48 on the main |ns3| web site. |
|
49 |
|
50 Waf |
|
51 *** |
|
52 |
|
53 Once you have source code downloaded to your local system, you will need |
|
54 to compile that source to produce usable programs. Just as in the case of |
|
55 source code management, there are many tools available to perform this |
|
56 function. Probably the most well known of these tools is ``make``. Along |
|
57 with being the most well known, ``make`` is probably the most difficult to |
|
58 use in a very large and highly configurable system. Because of this, many |
|
59 alternatives have been developed. Recently these systems have been developed |
|
60 using the Python language. |
|
61 |
|
62 The build system Waf is used on the |ns3| project. It is one |
|
63 of the new generation of Python-based build systems. You will not need to |
|
64 understand any Python to build the existing |ns3| system, and will |
|
65 only have to understand a tiny and intuitively obvious subset of Python in |
|
66 order to extend the system in most cases. |
|
67 |
|
68 For those interested in the gory details of Waf, the main web site can be |
|
69 found at http://code.google.com/p/waf/. |
|
70 |
|
71 Development Environment |
|
72 *********************** |
|
73 |
|
74 As mentioned above, scripting in |ns3| is done in C++ or Python. |
|
75 As of ns-3.2, most of the |ns3| API is available in Python, but the |
|
76 models are written in C++ in either case. A working |
|
77 knowledge of C++ and object-oriented concepts is assumed in this document. |
|
78 We will take some time to review some of the more advanced concepts or |
|
79 possibly unfamiliar language features, idioms and design patterns as they |
|
80 appear. We don't want this tutorial to devolve into a C++ tutorial, though, |
|
81 so we do expect a basic command of the language. There are an almost |
|
82 unimaginable number of sources of information on C++ available on the web or |
|
83 in print. |
|
84 |
|
85 If you are new to C++, you may want to find a tutorial- or cookbook-based |
|
86 book or web site and work through at least the basic features of the language |
|
87 before proceeding. For instance, `this tutorial |
|
88 <http://www.cplusplus.com/doc/tutorial/>`_. |
|
89 |
|
90 The |ns3| system uses several components of the GNU "toolchain" |
|
91 for development. A |
|
92 software toolchain is the set of programming tools available in the given |
|
93 environment. For a quick review of what is included in the GNU toolchain see, |
|
94 http://en.wikipedia.org/wiki/GNU_toolchain. |ns3| uses gcc, |
|
95 GNU binutils, and gdb. However, we do not use the GNU build system tools, |
|
96 neither make nor autotools. We use Waf for these functions. |
|
97 |
|
98 Typically an |ns3| author will work in Linux or a Linux-like |
|
99 environment. For those running under Windows, there do exist environments |
|
100 which simulate the Linux environment to various degrees. The |ns3| |
|
101 project supports development in the Cygwin environment for |
|
102 these users. See http://www.cygwin.com/ |
|
103 for details on downloading (MinGW is presently not officially supported, |
|
104 although some of the project maintainers to work with it). Cygwin provides |
|
105 many of the popular Linux system commands. It can, however, sometimes be |
|
106 problematic due to the way it actually does its emulation, and sometimes |
|
107 interactions with other Windows software can cause problems. |
|
108 |
|
109 If you do use Cygwin or MinGW; and use Logitech products, we will save you |
|
110 quite a bit of heartburn right off the bat and encourage you to take a look |
|
111 at the `MinGW FAQ |
|
112 <http://oldwiki.mingw.org/index.php/FAQ>`_. |
|
113 |
|
114 Search for "Logitech" and read the FAQ entry, "why does make often |
|
115 crash creating a sh.exe.stackdump file when I try to compile my source code." |
|
116 Believe it or not, the ``Logitech Process Monitor`` insinuates itself into |
|
117 every DLL in the system when it is running. It can cause your Cygwin or |
|
118 MinGW DLLs to die in mysterious ways and often prevents debuggers from |
|
119 running. Beware of Logitech software when using Cygwin. |
|
120 |
|
121 Another alternative to Cygwin is to install a virtual machine environment |
|
122 such as VMware server and install a Linux virtual machine. |
|
123 |
|
124 Socket Programming |
|
125 ****************** |
|
126 |
|
127 We will assume a basic facility with the Berkeley Sockets API in the examples |
|
128 used in this tutorial. If you are new to sockets, we recommend reviewing the |
|
129 API and some common usage cases. For a good overview of programming TCP/IP |
|
130 sockets we recommend `TCP/IP Sockets in C, Donahoo and Calvert |
|
131 <http://www.elsevier.com/wps/find/bookdescription.cws_home/717656/description#description>`_. |
|
132 |
|
133 There is an associated web site that includes source for the examples in the |
|
134 book, which you can find at: |
|
135 http://cs.baylor.edu/~donahoo/practical/CSockets/. |
|
136 |
|
137 If you understand the first four chapters of the book (or for those who do |
|
138 not have access to a copy of the book, the echo clients and servers shown in |
|
139 the website above) you will be in good shape to understand the tutorial. |
|
140 There is a similar book on Multicast Sockets, |
|
141 `Multicast Sockets, Makofske and Almeroth |
|
142 <http://www.elsevier.com/wps/find/bookdescription.cws_home/700736/description#description>`_. |
|
143 that covers material you may need to understand if you look at the multicast |
|
144 examples in the distribution. |