pupnp (libupnp) snapshot from SourceForge: git clone git://pupnp.git.sourceforge...
[igd2-for-linux:pandonghui1211s-igd2-for-linux.git] / pupnp_branch-1.6.x / README
1 Portable SDK for UPnP* Devices (libupnp)
2
3 Copyright (c) 2000-2003 Intel Corporation - All Rights Reserved.
4 Copyright (c) 2005-2006 RĂ©mi Turboult <r3mi@users.sourceforge.net>
5 Copyright (c) 2006 Michel Pfeiffer and others <virtual_worlds@gmx.de>
6
7 See LICENSE for details.
8
9 This file contains information about the above product in the following 
10 sections: 
11
12 1.  Release Contents
13 2.  Package Contents
14 3.  System Requirements
15 4.  Build Instructions
16 5.  Install/Uninstall Instructions
17 6.  Product Release Notes
18 7.  New Features
19 8.  Support and Contact Information
20
21
22 1) Release Contents
23 -------------------------------------------
24
25 The Portable SDK for UPnP Devices is an SDK for development of UPnP device 
26 and control point applications.  It consists of the core UPnP 
27 protocols along with a UPnP-specific eXtensible Markup Language (XML) parser 
28 supporting the Document Object Model (DOM) Level 2 API and an optional, 
29 integrated mini web server for serving UPnP related documents.
30
31
32 2) Package Contents
33 -------------------------------------------
34
35 The SDK for UPnP Devices contains the following: 
36
37 README          This file.  Contains the installation and build instructions.
38 LICENSE         The licensing terms the SDK is distributed under.
39 NEWS            Changes and new features.
40 ixml\doc        The files for generating the XML parser documentation from
41                 the source code.
42 ixml\inc        The public include files required to use the XML parser.
43 ixml\src        The source code to the XML parser library.
44 threadutil\inc  The public include files required to the threading 
45                 utility library.
46 threadutil\src  The source code to the threading utility library.
47 upnp\doc        The files for generating the SDK documentation from the
48                 source code.
49 upnp\inc        The public include files required to use the SDK.
50 upnp\src        The source files comprising the SDK, libupnp.so.
51 upnp\sample     A sample device and control point application, illustrating the
52                 usage of the SDK.
53
54
55 3) System Requirements
56 -------------------------------------------
57
58 The SDK for UPnP Devices is designed to compile and run under several
59 operating systems.  It does, however, have dependencies on some
60 packages that may not be installed by default.  All packages that it
61 requires are listed below.
62
63 libpthread  The header and library are installed as part of the glibc-devel
64             package (or equivalent).
65
66 Additionally, the documentation for the SDK can be auto-generated from 
67 the UPNP.H header file using DOC++, a documentation system for C, C++, 
68 IDL, and Java*.  DOC++ generates the documentation in HTML or TeX format.
69 Using some additional tools, the TeX output can be converted into a
70 PDF file.  To generate the documentation these tools are required:
71
72 DOC++       The homepage for DOC++ is http://docpp.sourceforge.net/.
73             The current version as of this release of the SDK is
74             version 3.4.9.  DOC++ is the only requirement for generating
75             the HTML documentation.
76 LaTeX/TeX   To generate the PDF documentation, LaTeX and TeX tools are
77             necessary.  The tetex and tetex-latex packages provide these
78             tools.
79 dvips       dvips converts the DVI file produced by LaTeX into a PostScript*
80             file.  The tetex-dvips package provides this tool.
81 ps2pdf      The final step to making the PDF is converting the PostStript
82             into Portable Document Format.  The ghostscript package provides
83             this tool.
84
85 For the UPnP library to function correctly, networking must be configured
86 properly for multicasting.  To do this:
87
88 route add -net 239.0.0.0 netmask 255.0.0.0 eth0
89
90 where 'eth0' is the network adapter that the UPnP library will use.  Without
91 this addition, device advertisements and control point searches will not
92 function.
93
94
95
96 4) Build Instructions
97 -------------------------------------------
98
99 CORE LIBRARIES
100
101 The in the examples below, replace $(LIBUPNP) with "libupnp-x.y.z",
102 with x, y, and z corresponding to the version of the library that you have.
103
104 All pieces of the SDK are configured and built from the $(LIBUPNP) directory. 
105
106 % cd $(LIBUPNP)
107 % ./configure
108 % make
109
110 will build a version of the binaries without debug support, and with default 
111 options enabled (see below for options available at configure time).
112
113 % cd $(LIBUPNP)
114 % ./configure CFLAGS="-DSPARC_SOLARIS -mtune=<cputype> -mcpu=<cputype>"
115 % make
116
117 will build a Sparc Solaris version of the binaries without debug support
118 and with default options enabled (see below for options available at
119 configure time). Please note: <cputype> has to be replaced by a token that
120 fits to your platform and CPU (e.g. "supersparc").
121
122 To build the documentation, assuming all the necessary tools are installed 
123 (see section 3) :
124
125 To generate the HTML documentation:
126
127 % cd $(LIBUPNP)
128 % make html
129
130 To generate the PDF file:
131
132 % cd $(LIBUPNP)
133 % make pdf
134
135
136 A few options are available at configure time. Use "./configure --help"
137 to display a complete list of options. Note that these options 
138 may be combined in any order.
139 After installation, the file <upnp/upnpconfig.h> will provide a summary
140 of the optional features that have been included in the library.
141
142
143 % cd $(LIBUPNP)
144 % ./configure --enable-debug
145 % make 
146
147 will build a debug version with symbols support.
148
149 To build the library with the optional, integrated mini web server (note
150 that this is the default):
151
152 % cd $(LIBUPNP)
153 % ./configure --enable-webserver
154 % make 
155
156 To build without:
157
158 % cd $(LIBUPNP)
159 % ./configure --disable-webserver
160 % make 
161
162
163 The SDK also contains some additional helper APIs, declared in
164 inc/tools/upnptools.h.  If these additional tools are not required, they can
165 be compiled out:
166
167 % cd $(LIBUPNP)
168 % ./configure --disable-tools
169 % make 
170
171 By default, the tools are included in the library.
172
173 To further remove code that is not required, the library can be build with or 
174 with out the control point (client) or device specific code.  To remove this
175 code:
176
177 % cd $(LIBUPNP)
178 % ./configure --disable-client
179 % make 
180
181 to remove client only code or:
182
183 % cd $(LIBUPNP)
184 % ./configure --disable-device
185 % make 
186
187 to remove device only code.
188
189 By default, both client and device code is included in the library.  The
190 integrated web server is automatically removed when configuring with 
191 --disable-device.
192
193 To build the library without large-file support (enabled by default) :
194
195 % cd $(LIBUPNP)
196 % ./configure --disable-largefile
197 % make 
198
199
200 To remove all the targets, object files, and built documentation:
201
202 % cd $(LIBUPNP)
203 % make clean
204
205
206 CROSS COMPILATION
207
208 To cross compile the SDK, a special "configure" directive is all that is
209 required:
210
211 % cd $(LIBUPNP)
212 % ./configure --host=arm-linux
213 % make
214
215 This will invoke the "arm-linux-gcc" cross compiler to build the library.
216
217
218 SAMPLES
219
220 The SDK contains two samples: a TV device application and a control point
221 that talks with the TV device.  They are found in the $(LIBUPNP)/upnp/sample 
222 directory.  
223
224 To build the samples (note: this is the default behaviour):
225
226 % cd $(LIBUPNP)
227 % ./configure --enable-samples
228 % make
229
230 will build the sample device "$(LIBUPNP)/upnp/upnp_tv_device" and
231 sample control point "$(LIBUPNP)/upnp/upnp_tv_ctrlpt". 
232 Note : the sample device won't be built if --disable-device has been 
233 configured, and the sample control point won't be build if --disable-client 
234 has been configured.
235
236 To run the sample device, you need the "$(LIBUPNP)/upnp/sample/tvdevice/web" 
237 sub-directory. Example :
238
239 % cd $(LIBUPNP)/upnp/sample/tvdevice
240 % ../../upnp_tv_device
241
242
243
244 SOLARIS BUILD
245
246 The building process for the Solaris operating system is similar to the one
247 described above. Only the call to ./configure has to be done using an
248 additional parameter:
249
250 ./configure CFLAGS="-mcpu=<cputype> -mtune=<cputype> -DSPARC_SOLARIS"
251
252 where <cputype> has to be replaced by the appropriate CPU tuning flag (e.g.
253 "supersparc"). Afterwards
254
255 make
256 make install
257
258 can be called as described above.
259
260
261
262 WINDOWS BUILD
263
264 In order to build libupnp under Windows the pthreads-w32 package is required.
265 You can download a self-extracting ZIP file from the following location:
266
267 ftp://sources.redhat.com/pub/pthreads-win32/pthreads-w32-2-7-0-release.exe
268
269 Execute the self-extracting archive and copy the Pre-build.2 folder to the
270 top level source folder.
271 Rename Pre-build.2 to pthreads. 
272 Open the provided workspace build\libupnp.dsw with Visual C++ 6.0 and select
273 Build->Build libupnp.dll (F7)
274
275 For building a static library instead of a DLL and for using the static
276 pthreads-w32 library following switches need to be defined additionally:
277
278 UPNP_STATIC_LIB - for creating a statically linkable UPnP-library
279 PTW32_STATIC_LIB - for using the static pthreads32 library
280
281
282 5) Install/Uninstall Instructions
283 -------------------------------------------
284
285 Install
286
287 The top-level makefile for the UPnP SDK contains rules to install the 
288 necessary components.  To install the SDK, as root:
289
290 make install
291
292 Uninstall
293
294 Likewise, the top-level makefile contains an uninstall rule, reversing 
295 the steps in the install:
296
297 make uninstall
298
299
300 6) Product Release Notes
301 -------------------------------------------
302
303 The SDK for UPnP Devices v1.2.1a has these known issues:
304
305 - The UPnP library may not work with older versions of gcc and libstdc++, 
306   causing a segmentation fault when the library loads.  It is recommended
307   that gcc version 2.9 or later be used in building library.
308 - The UPnP library does not work the glibc 2.1.92-14 that ships with
309   Red Hat 7.0.  For the library to function, you must updated the glibc
310   and glibc-devel packages to 2.1.94-3 or later.  There is some issue with
311   libpthreads that has been resolved in the 2.1.94 version.
312
313
314 7) New Features
315 -------------------------------------------
316
317 See NEWS file.
318
319
320 8) Support and Contact Information
321 -------------------------------------------
322
323 Intel is not providing support for the SDK for UPnP Devices. Mailing lists
324 and discussion boards can be found at http://www.libupnp.org/.
325
326 If you find this SDK useful, please send an email to upnp@intel.com and let
327 us know.
328
329
330 * Other brands, names, and trademarks are the property of their respective 
331 owners.
332