added symbian/ directory containing build files for Symbian, and added
[speexdsp.git] / README.symbian
1 Using Speex on Symbian OS
2 Conrad Parker and Colin Ward, CSIRO Australia, July 2004
3
4
5 Introduction
6 ------------
7
8 Some minor modifications to libspeex and applications using the libspeex API
9 are required due to the following limitation imposed on DLLs in Symbian OS:
10
11     The Symbian OS architecture does not allow DLLs to have a data
12     segment (initialised or uninitialised). 
13
14     -- Coding Idioms for Symbian OS, Oct 2002 [1]
15
16 This file (README.symbian) outlines how to build libspeex for Symbian OS,
17 and how to develop applications using the modified libspeex API.
18
19 Note that these modifications have been implemented in a portable manner so
20 that they may also be used on other platforms with similar restrictions,
21 and may be safely tested on more forgiving platforms such as Unix/Linux.
22
23
24 libspeex build modifications
25 ----------------------------
26
27 The modifications required for libspeex on Symbian OS are fully contained in
28 the file libspeex/modes_noglobals.c. This file should be built instead of
29 libspeex/modes.c.
30
31 Additionally, the header file include/speex/speex_noglobals.h should be
32 installed into the system include directory, along with the other
33 speex_* headers.
34
35 When building in a GNU environment, this behaviour can be configured by:
36
37   ./configure --disable-global-pointers
38
39 The symbian/ directory contains the following files for Symbian's abuild tool:
40
41   bld.inf    Component definition file
42   speex.mmp  Project specification file
43   config.h   Configuration options for both emulator and device builds
44
45
46 Developing applications for libspeex modified for Symbian OS
47 ------------------------------------------------------------
48
49 The only part of the libspeex API which has been modified for Symbian OS,
50 and thus affects user code which links against libspeex, is the removal of
51 statically defined SpeexMode structures: speex_nb_mode, speex_wb_mode,
52 speex_uwb_mode, and the array speex_mode_list[]. All other aspects of
53 application development using the libspeex API remain unchanged.
54
55
56   1. applications must additionally include the header:
57
58 +    #include <speex_noglobals.h>
59
60
61   2. any references to the statically defined SpeexMode structures must be
62      replaced by a call to a constructor for that mode; and the
63      constructed mode must later be free'd appropriately.
64
65      * References to the statically defined array speex_mode_list[modeID]
66      must be replaced by a call to speex_mode_new_byID (modeID):
67
68 -      mode = speex_mode_list[modeID];
69 +      mode = speex_mode_new_byID (modeID);
70
71      and later free'd:
72
73 +      speex_mode_free_byID (mode, modeID);
74
75      note that you must remember the association between a constructed
76      mode and its modeID in order to correctly free it later. Failure to
77      do so may introduce memory leaks or runtime errors.
78
79      * References to the statically defined mode structures must be replaced:
80
81        SpeexMode * mode1, * mode2, * mode3;
82
83 -      mode1 = &speex_nb_mode;
84 +      mode1 = speex_nb_mode_new ();
85
86 -      mode2 = &speex_wb_mode;
87 +      mode2 = speex_wb_mode_new ();
88
89 -      mode3 = &speex_uwb_mode;
90 +      mode3 = speex_uwb_mode_new ();
91
92      Constructed modes must be free'd after use:
93
94 +      speex_nb_mode_free (mode1);
95 +      speex_wb_mode_free (mode2);
96 +      speex_uwb_mode_free (mode3);
97
98
99   3. It is fairly easy to conditionally build an application for either
100      usage of the libspeex API. For example using GNU Autoconf, you can
101      check for the existence of a symbol such as speex_mode_new_byID in
102      configure.ac. The following example is from libfishsound[2]:
103
104     dnl Test for libspeex SPEEX_DISABLE_GLOBAL_POINTERS API
105     dnl If so, we need to use a different API to access available modes,
106     dnl and free them after use.
107     AC_CHECK_LIB(speex, speex_mode_new_byID, DISABLE_GLOBAL_POINTERS="yes",
108       DISABLE_GLOBAL_POINTERS="no")
109     if test "x$DISABLE_GLOBAL_POINTERS" = xyes ; then
110       AC_DEFINE(SPEEX_DISABLE_GLOBAL_POINTERS, ,
111        [Define if libspeex uses SPEEX_DISABLE_GLOBAL_POINTERS API])
112     fi
113
114
115 References
116 ----------
117
118 [1] http://www.symbian.com/developer/techlib/papers/coding_idioms/2002_10_09_codingSymbianOS.pdf
119
120 [2] http://www.annodex.net/software/libfishsound/
121