mainpage.docs 25.5 KB
Newer Older
1
/* -*- text -*- */
Pekka Pessi's avatar
Pekka Pessi committed
2

3 4 5
/**@mainpage Sofia SIP User Agent Library - sofia-sip-ua

@section Introduction
Pekka Pessi's avatar
Pekka Pessi committed
6 7 8 9 10

This document contains automatically generated reference documentation
for Sofia-SIP components. Some introductory material and
pointers to the example code are also included.

11
For a list of module specific pages, see @ref subdirs
12
"source tree structure" or direct links to submodules:<br>
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
<a href="nua/index.html">nua</a>
<a href="su/index.html">su</a>
<a href="features/index.html">features</a>
<a href="soa/index.html">soa</a>
<a href="sdp/index.html">sdp</a>
<a href="nta/index.html">nta</a>
<a href="tport/index.html">tport</a>
<a href="sresolv/index.html">sresolv</a>
<a href="sip/index.html">sip</a>
<a href="msg/index.html">msg</a>
<a href="url/index.html">url</a>
<a href="stun/index.html">stun</a>
<a href="iptsec/index.html">iptsec</a>
<a href="nea/index.html">nea</a>
<a href="nth/index.html">nth</a>
<a href="http/index.html">http</a>
<a href="bnf/index.html">bnf</a>
<a href="ipt/index.html">ipt</a>
Pekka Pessi's avatar
Pekka Pessi committed
31 32 33

@section who Contact Information

34 35
You can download latest Sofia SIP from the project
<a href="http://sofia-sip.sf.net">home page</a> at
36 37
<a href="sf.net">Sourceforge.net</a>.

Pekka Pessi's avatar
Pekka Pessi committed
38 39
Please contact us if you have questions regarding this software:

40
<ul>
Pekka Pessi's avatar
Pekka Pessi committed
41 42
<li>Pekka Pessi <Pekka.Pessi@nokia.com></li>
<li>Kai Vehmanen <Kai.Vehmanen@nokia.com></li>
43
</ul>
Pekka Pessi's avatar
Pekka Pessi committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57

Or post to the Sofia-SIP mailing list:

<ul>
<li>mailto:sofia-sip-devel@lists.sourceforge.net</li>
<li>http://lists.sourceforge.net/lists/listinfo/sofia-sip-devel</li>
</ul>

*/

/**@page building Source Tree Structure

@section subdirs Directory Structure

58 59
In libsofia-sip-ua, there are subdirectories for different modules listed
below.
Pekka Pessi's avatar
Pekka Pessi committed
60

61
Terminal and high-level libraries used for both signaling and media:
Pekka Pessi's avatar
Pekka Pessi committed
62 63

Common runtime library:
Pekka Pessi's avatar
Pekka Pessi committed
64
 - <a href="su/index.html">"su" - sockets, memory management, threads</a>
65 66
 - <a href="sresolv/index.html">"sresolv" - Asynchronous DNS resolver</a>
 - <a href="ipt/index.html">"ipt" - IPT utility library</a>
Pekka Pessi's avatar
Pekka Pessi committed
67 68

SIP Signaling:
69 70
 - <a href="nua/index.html">"nua" - SIP User Agent library</a>
 - <a href="nea/index.html">"nea" - SIP Event API</a>
71
 - <a href="iptsec/index.html">"iptsec" -
72
    Digest authentication for HTTP and SIP</a>
Pekka Pessi's avatar
Pekka Pessi committed
73 74 75 76
 - <a href="nta/index.html">"nta" - SIP transaction engine</a>
 - <a href="tport/index.html">"tport" - Message transport</a>
 - <a href="sip/index.html">"sip" - SIP messages and headers</a>
 - <a href="msg/index.html">"msg" - Message handling </a>
77 78
 - <a href="url/index.html">"url" - URL handling</a>
 - <a href="bnf/index.html">"url" - low level parsing</a>
Pekka Pessi's avatar
Pekka Pessi committed
79 80 81 82 83 84 85 86

HTTP subsystem:
 - <a href="nth/index.html">"nth" - HTTP protocol engine</a>
 - <a href="http/index.html">"http" - HTTP messages and headers</a>

SDP processing:
 - <a href="soa/index.html">"soa" - SDP Offer/Answer engine for SIP</a>
 - <a href="sdp/index.html">"sdp" - SDP parser</a>
Pekka Pessi's avatar
Pekka Pessi committed
87

88 89 90 91 92 93
Other:
 - <a href="stun/index.html">"stun" - STUN library</a>

Features provided by Sofia-SIP library:
 - <a href="features/index.html">"features" - Features provided by Sofia SIP</a>

Pekka Pessi's avatar
Pekka Pessi committed
94
Documentation:
Pekka Pessi's avatar
Pekka Pessi committed
95
 - "docs" - Doxygen reference documentation
Pekka Pessi's avatar
Pekka Pessi committed
96 97 98 99 100 101 102 103 104 105

*/

/**
@page styleguide C Style Guide

This document gives general guidelines on generic C style and code
formatting within Sofia-SIP. The guidelines include identifier naming
conventions, indenting convention, and tool usage directions.

106
Please note that C style is always a matter of taste.
Pekka Pessi's avatar
Pekka Pessi committed
107 108 109 110

@section naming Naming Conventions

Generally, identifiers within each module are prefixed with the name of
111 112
that module. For instance, the functions within http parser module @b http
have prefix @c http_. Identifiers composed of multiple words have an
Pekka Pessi's avatar
Pekka Pessi committed
113
underscore "_" between the words, the words themselves are in lower
114
case. For instance, http_request_create().
Pekka Pessi's avatar
Pekka Pessi committed
115 116 117 118

Macros should be in upper case. File names should be in lower case using
underscore as delimiter if needed.

119 120 121
Normal typedefs have suffix @c _t, however, function types have suffix @c
_f. The enum names also sometimes have @c _e, struct names have @c _s and
union names @c _u.
Pekka Pessi's avatar
Pekka Pessi committed
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155

It is recommended that type itself is typedef'ed, not a pointer to the
type. It should be clear from variable declaration if the variable is a
pointer or not.

@code
typedef struct foo_s foo_t;
typedef int f_fun(foo_t *f, char const *s);
@endcode

Struct and union members should have common prefix. For instance,
@code
struct foo_s {
  int    f_len;
  char  *f_name;
  fun_f *f_fun;
};
@endcode

This prefix makes it easier to find where members are used.

@section formatting Indenting and Formatting code

Indentation in Sofia-SIP C code generally follows the @e K&R style with indent
of 2 characters (so you can use the default "GNU" c-style in Emacs). The
maximum line length should be 80 characters.

For example,

@code
void kluge(int foo)
{
  if (foo) {
    bar();
156 157
  }
  else {
Pekka Pessi's avatar
Pekka Pessi committed
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
    switch (baz()) {
    case a:
      eeny();
      break;
    case b:
      meeny();
      break;
    default:
      moe();
      break;
    }
  }
}
@endcode

The default indentation can be achieved with GNU indent with options
@code
-nbad -bap -bbo -nbc -br -brs -c33 -cd33 -ncdb -ce -ci2 -cli0 -cp33 -cs
-d0 -di1 -nfc1 -nfca -hnl -i2 -ip0 -l79 -lp -npcs -nprs -npsl -saf -sai
-saw -nsc -nsob -nss
@endcode

180
Loops without condition use @c for @c (;;) instead of @c while @c (1).
Pekka Pessi's avatar
Pekka Pessi committed
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222

@code
  for (;;) {
    foo();
    if (bar())
      break;
    baz();
  }
@endcode

There should be whitespace on both sides of infix operators, except
<code>.</code> or <code>-></code>, which require no space, or
<code>,</code> (comma) which requires space only after). There should be
whitespace between a keyword and parenthesis following it, but no
whitespace between an identifier and parenthesis following it. E.g.,

@code
  while (i++ < n)
    baz();
  for (;;) {
    x->x_foo();
    if (bar())
      break;
    z.z_baz++;
  }
  return (13 * i);
@endcode

 */

/**
@page programming Programming Guide

@section porting Writing Portable Code

Most of Sofia-SIP software is written as portable. All core modules are
(or at least should be) written in ANSI C 89 with some ANSI C 99
features. If there are platform specific parts, they are collected to
separate C files and isolated from the rest of the software with a
wrapper interface.

SU module handles abstraction to OS specific functionality such as
223
memory management, sockets, threads and time functions.
Pekka Pessi's avatar
Pekka Pessi committed
224 225 226 227 228 229 230 231 232

@subsection ansi_99 ANSI C 99 features

The following ANSI C 99 features are to be used in Sofia-SIP software:
- Integer types
- functions va_copy() and snprintf()

The following ANSI C 99 features shall not be used in Sofia-SIP software:
- definition of a variable in the middle of function code.
Pekka Pessi's avatar
Pekka Pessi committed
233
  (so always define your variables in the beginning of the block)
Pekka Pessi's avatar
Pekka Pessi committed
234 235 236

@subsection port_ints Integer Types

237 238 239 240 241 242
As you should know, the length of native storage size depends on hardware,
OS and compiler. This means in practice that the length of int or long is
not necessarily 32 bits. As a consequence, you need to make sure that the
value you intend to store in the int, can actually fit in int on different
platforms. As a rule of thumb, if the integer value can exceed 8 bits, you
should use types that have a defined length.
Pekka Pessi's avatar
Pekka Pessi committed
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262

Nevertheless its OK to use native integer types if you bear in mind
what was said above. The original reason for having only native
data type was performance. The int type is always stored in the
fastest (and usually biggest size) possible.

Never assume anything on the length of the type. Alway use sizeof()
operator to find out the length.

C 99 standard defines the following fixed length data types:

- int64_t
- uint64_t
- int32_t
- uint32_t
- int16_t
- uint16_t
- int8_t
- uint8_t

263
To use these data types you must include the <sofia-sip/su_types.h> header, which
Pekka Pessi's avatar
Pekka Pessi committed
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300
takes care of including correct file. If @b su includes are not available,
you must include the following code segment to each file where you plan to
use them:

@code
#if HAVE_STDINT_H
#include <stdint.h>
#elif HAVE_INTTYPES_H
#include <inttypes.h>
#else
#error Define HAVE_STDINT_H as 1 if you have <stdint.h>, \
 or HAVE_INTTYPES_H if you have <inttypes.h>
#endif
@endcode

@subsection port_byte_sex Byte order

The host byte order on different platforms vary. When you do only
local processing, need not to worry about the byte order. But as
soon as you start writing code that send or receives anything to
the network, you need to start worrying.

If you wish to convert the byte order, it is simply done by calling
one the following functions:

The htonl() function converts the unsigned integer hostlong from
host byte order to network byte order.

The htons() function converts the unsigned short integer hostshort
from host byte order to network byte order.

The ntohl() function converts the unsigned integer netlong from
network byte order to host byte order.

The ntohs() function converts the unsigned short integer netshort
from network byte order to host byte order.

301
You need to include <netinet/in.h> or <sofia-sip/su.h> to use these functions.
Pekka Pessi's avatar
Pekka Pessi committed
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324

@subsection port_struct Packing structures

By default, compilers usually arrange structures so that they are
quick to access. This means that most fields in the structure start
at the 32 bit boundary. If you need to conserve memory, you may use
structure packing.

To tell the compiler that you only need certain amount of bits to
store a variable, you can use bit-fields. Compiler may or may not
pack the bit-fields.

@code
struct foo {
  unsigned bar:5;
  unsigned foo:2;
  unsigned :0;
  int      something;
}
@endcode

If compiler decides to pack this structure, this code generates a
structure that has @a bar and @a foo in the first seven bits, and then
325
@a something beginning from the next 32 bit boundary.
Pekka Pessi's avatar
Pekka Pessi committed
326 327 328 329 330 331 332 333

One problem arises when using packed bit-fields: on ARM it is
generally not possible to access a 32 bit field that does not start from
the 32-bit boundary. Hence the example has the :0 padding member in the
structure. Seems handy but beware: initialization of this structure fails
on some ARM gcc compilers. (Ask Kai Vehmanen for details).

A way to force packing of a structure is to use preprocessor
Pekka Pessi's avatar
Pekka Pessi committed
334
directive @c @#pragma(pack). This directive is compiler specific, so if
Pekka Pessi's avatar
Pekka Pessi committed
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
you plan to write truly portable code, you cannot use it. We have
used it in some parts of the Sofia-SIP though. Only alternative is to
write functions that fetch the desired bits from a 32 bit field
with bit operations; not very handy and error prone.

The same aligment problem also arises if you cast for example char
buffer to a int32_t. You can only read int32_t from the 32bit boundary
on ARM platform. So be careful.

As a conclusion, when using bit-fields and stucture packing, beware
of the pitfalls. If you don't really need to use them (as in parsing
binary protocols), don't use them.

@section file_organization File and Directory Structure

A Sofia-SIP library module can be defined as a subdirectory under the
351 352 353
libsofia-sip-ua directory hierarchy that contains a file \<modulename\>.docs
(where the \<modulename\> of course referes to the actual name of
the module).
Pekka Pessi's avatar
Pekka Pessi committed
354 355 356 357 358 359 360 361 362 363 364 365 366

In case you like to start developing a new module, please
contact Sofia-SIP development team so that they can help you to set up
the basic module for you.

An overview of the contents of a module directory:
  - file \<modulename\>.docs \n
    Main documentation file for the module. See @ref module_docs
    for more information
  - subdirectory pictures \n
    Contains any pictures/images
    that are needed by the module documentation. The
    file formats to use are GIF (for html pages) and
367
    EPS (for latex). If some program (e.g. MS Visio) is
Pekka Pessi's avatar
Pekka Pessi committed
368 369 370 371 372 373
    used to create the pictures, also the original
    files must be stored here.\n
    (Note that old modules may have "images" subdirectory instead of
    "pictures")
  - files Makefile.am \n
    See section @ref build "dealing with GNU Autotools" below.
374
  - (optionally) source code file(s) of the module and module tests.
Pekka Pessi's avatar
Pekka Pessi committed
375
    The source code file(s) can also be located in subdirectories if necesary.
376

Pekka Pessi's avatar
Pekka Pessi committed
377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393

@section oo_with_c Writing Object-Oriented Code

While C does not provide any special object-oriented features on its own, it
is possible to program in object-oriented way using C, too. Sofia code make
use of many object-oriented features while being written entirely in C.

@subsection oo_hiding Data Hiding

Data hiding is a practice that makes separation between two modules very
clear. Outside code cannot directly access the data within a module, but it
has to use functions provided for that purpose. Data hiding also makes it
easier to define a protocol between two objects - all communication happens
using function calls.

How to implement data hiding in C? Easiest answer is to only declare data
structures in the header files, not to define them. We have a typedef #msg_t
394 395 396 397 398 399 400
for @link msg_s struct msg_s @endlink in <sofia-sip/msg.h>, but the actual
structure is defined in "msg_internal.h". Programs outside @b msg module
does not have access to the @link msg_s struct msg_s @endlink, but they have
to to access the #msg_t object through method functions provided in
<sofia-sip/msg.h>. The @b msg implementation is also free to change the
internal layout of the structure, only keeping the function interface
unmodified.
Pekka Pessi's avatar
Pekka Pessi committed
401 402 403

@subsection oo_interface Interfaces

404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420
Abstract interface is another object-oriented practice used in Sofia. Parser
headers, defined in <sofia-sip/msg_types.h>, is a good example of abstract
interface. The type for message headers, #msg_header_t, is defined using two
C structures @link msg_common_s struct msg_common_s @endlink
(#msg_common_t), and @link msg_hclass_s struct msg_hclass_s @endlink
(#msg_hclass_t).

Abstract interface is achieved using virtual function table in #msg_hclass_t
structure, bit like C++ typically implements abstract classes and virtual
functions. For implemenation of each header, the function table is
initialized with functions responsible for decoding, encoding and
manipulating the header structure. Unlike C++, the class of the object
(#msg_hclass_t) is represented by a real data structure which also contains
header-specific data, like header name.

@dontinclude sip_basic.c
@skipline msg_hclass_t sip_contact_class
421 422
@skip {{
@until }};
Pekka Pessi's avatar
Pekka Pessi committed
423 424 425

@subsection oo_derived Inheritance and Derived Objects

426
Inheritance is a object-oriented practice that has limited use in Sofia.
Pekka Pessi's avatar
Pekka Pessi committed
427 428
Most common example of inheritance is use of #su_home_t. Many objects are
derived from #su_home_t, which means that they can use the various
429
home-based memory management functions from <su_alloc.h>.
Pekka Pessi's avatar
Pekka Pessi committed
430 431 432 433 434 435

In this sence, inheritance means that a pointer to a derived object can be
casted as a pointer to a base object. In other words, the derived object
must have the base object at the beginning of its memory area:

@code
436
struct derived
Pekka Pessi's avatar
Pekka Pessi committed
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454
{
  struct base base[1];
  int         extra;
  char       *data;
};
@endcode

There are three alternatives to cast a pointer to derived to a pointer to
base:
@code
struct base *base1 = (struct base *)derived;
struct base *base2 = &derived->base;
struct base *base3 = derived->base;
@endcode
The third alternative works because base was used as a 1-element array.

@subsection oo_templates Templates

455
There are a few template types implemented as macros in Sofia libraries.
456 457 458
They include hash table, defined in <sofia-sip/htable.h>, which can be used
to define hash tables types and accessor functions for different object, and
red-black tree, defined in <sofia-sip/rbtree.h>.
Pekka Pessi's avatar
Pekka Pessi committed
459 460 461

@section memory Memory Management

462 463 464 465 466 467
The home-based memory management is useful when a lot of memory blocks are
allocated for given task. The allocations are done via the memory home,
which keeps a reference to each allocated memory block. When the memory
home is then freed, it will free all memory blocks to which it has
reference. This simplifies application logic because application code does
not need to keep track of the allocated memory and free every allocated block
Pekka Pessi's avatar
Pekka Pessi committed
468 469
separately.

470
See documentation of <sofia-sip/su_alloc.h> and @ref su_alloc "memory managment tutorial"
Pekka Pessi's avatar
Pekka Pessi committed
471 472 473 474 475
for more information of memory management services.

@subsection contextdata Memory management of context data

A typical example of use of a memory home is to have a memory home structure
476
(#su_home_t) as part of operation context information structure.
Pekka Pessi's avatar
Pekka Pessi committed
477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504

@code
  /* context info structure */
  struct context {
    su_home_t  ctx_home[1];      /* memory home */
    other_t   *ctx_other_stuff;  /* example of memory areas */
    ...
  };

  /* context pointer */
  struct context *ctx;

  /* Allocate memory for context structure and initialize memory home */
  ctx = su_home_clone(NULL, sizeof (struct context));

  /* Allocate memory and register it with memory home */
  ctx->ctx_other_stuff = su_zalloc(ctx->ctx_home, sizeof(other_t));

  ... processing and allocating more memory ...

  /* Release registered memory areas, home, and context structure */
  su_home_zap(ctx->ctx_home);

@endcode

@subsection combining Combining allocations

Another place where home-based memory management makes programmers
505 506
life easier is case where a sub-procedure makes multiple memory allocations
and, in case the sub-procedure fails, all the allocations must be released
Pekka Pessi's avatar
Pekka Pessi committed
507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524
and, in case the sub-procedure is succesfull, all allocations must be
controlled by upper level memory management.

@code
  /* example sub-procedure. top_home is upper-level memory home */
  int sub_procedure( su_home_t *top_home, ... )
  {
    su_home_t temphome[1] = { SU_HOME_INIT(temphome) };

    ... allocations and other processing ...

    /* was processing successfull ? */
    if (success) {
      /* ok -> move registered allocated memory to upper level memory home */
      su_home_move( top_home, temphome );
    }
    /* destroy temporary memory home (and registered allocations) */
    /* Note than in case processing was succesfull the memory     */
525
    /* registrations were already moved to upper level home.      */
Pekka Pessi's avatar
Pekka Pessi committed
526 527 528 529 530 531 532 533 534
    su_home_deinit(temphome);

    /* return ok/not-ok */
    return success;
  }
@endcode

@section testing Testing Your Code

535
See <sofia-sip/tstdef.h> for example of how to write module tests with macros provided
Pekka Pessi's avatar
Pekka Pessi committed
536 537 538 539 540 541 542 543 544
by Sofia.

Here are some ideas of what you should test:
- "Smoke test" \n
  See that the module compiles, links and executes.
- Module API functions should be tested with\n
  - valid args
  - not valid args
- Aim for 100% line coverage\n
545
  (If there is a line of code that you have not tested, you don't know
Pekka Pessi's avatar
Pekka Pessi committed
546
  if its working.) \n
547
  For selected part of code you should also aim for
548
  100% branch/path coverage.\n
Pekka Pessi's avatar
Pekka Pessi committed
549 550 551 552 553 554 555 556
  But be anyway reasonable with these because in practise complete
  coverage is next to impossible to achive (so 80% is ok in practise).
- Create test to check assumptions and/or tricks used in code.\n
  For example if you rely on some compiler feature, create a test that
  will fail with a compiler that does not have that feature.

@subsection check Running Module Tests

557
Automake, which is used to build Sofia SIP, has builtin
Pekka Pessi's avatar
Pekka Pessi committed
558 559 560 561 562
support for unit tests. To add an automatically run test to your module,
you just have to add the following few lines to your module's Makefile.am
(of course, you have to write the test programs, too):

@code
563
TESTS = test_foo test_bar
Pekka Pessi's avatar
Pekka Pessi committed
564

565
check_PROGRAMS = test_foo test_bar
Pekka Pessi's avatar
Pekka Pessi committed
566

567 568
test_foo_SOURCES = foo.c foo.h
test_foo_LDADD = -L. -lmy
Pekka Pessi's avatar
Pekka Pessi committed
569

570 571
test_bar_SOURCES = bar.c bar.h
test_foo_LDADD = -L. -lmy
Pekka Pessi's avatar
Pekka Pessi committed
572 573 574 575
@endcode

Each test program should either return zero for success or a non-zero
error code in its main function. Now when you run "make check",
576
@b my_test_foo and @b my_test_bar will be built and then run.
Pekka Pessi's avatar
Pekka Pessi committed
577
Make will print a
578 579
summary of how the tests went. As these tests are run from the build
system, the tests must be non-interactive (no questions asked) and not
580
rely on any files that are not in version control system.
Pekka Pessi's avatar
Pekka Pessi committed
581

582
Sofia SIP's top-level makefile contains a recursive check target, so
583
you can use "cd sofia-sip ; make check" to run all the existing tests
Pekka Pessi's avatar
Pekka Pessi committed
584 585 586 587
with a single command.

@section build Dealing with GNU Autotools

588 589 590
Sofia-SIP build system is based on the GNU tools automake, autoconf and
libtool. This toolset has become the de-facto way of building Linux
software. Because of this there is a lot of publicly available documentation
Pekka Pessi's avatar
Pekka Pessi committed
591 592 593 594 595 596
about these tools, and of course, lots and lots of examples.

A good introduction to these tools is available at
<a href="http://developer.gnome.org/doc/books/WGA/generating-makefiles.html">
developer.gnome.org</a>. <a href="http://sources.redhat.com/autobook">Autobook</a>
provides more detailed documentation for autoconf and automake.
597
The <a href="http://www.gnu.org/manual/make/">GNU make manual</a>
Pekka Pessi's avatar
Pekka Pessi committed
598 599
is also a good source of information.

600
@subsection autogen_sh autogen.sh
Pekka Pessi's avatar
Pekka Pessi committed
601

602 603 604 605
At top-level there is a shell script called @b autogen.sh. It calls a
convenient tool called @b autoreconf which will generate configure script
for you. It also fixes the mode bits: the mode bits are not stored in
<a href="http://darcs.net">darcs</a> version control system.
Pekka Pessi's avatar
Pekka Pessi committed
606

607 608 609 610
@code
$ sh autogen.sh
$ ./configure ... with your configure options ...
@endcode
Pekka Pessi's avatar
Pekka Pessi committed
611

612
@subsection configure_ac configure.ac
Pekka Pessi's avatar
Pekka Pessi committed
613

614 615
The @b configure.ac file (older autoconf versions used also @b configure.in)
contains the primary configuration for autoconf. configure.ac contains
Pekka Pessi's avatar
Pekka Pessi committed
616
checks for all external libraries, non-standard language and compiler
617
features that are needed to build the target module.
Pekka Pessi's avatar
Pekka Pessi committed
618 619 620 621 622 623

This file is created by the developer of the module.

@subsection sofia_m4 m4 files

Sofia-SIP's own autoconf macros are stored in the top-level direcry called @b
624
m4. These macros, along with all other macros used by @b configure.ac, are
Pekka Pessi's avatar
Pekka Pessi committed
625 626 627 628 629 630 631
copied into the module-specific @b aclocal.m4 file by an utility called
aclocal.

Contact Sofia-SIP development team, if you need changes to these files.

@subsection aclocal_m4 aclocal.m4

632
The aclocal.m4 contains the definitions of the autoconf macros used in
633
@b configure.ac.
Pekka Pessi's avatar
Pekka Pessi committed
634 635 636 637 638

This file is generated by aclocal command.

@subsection Makefile_am Makefile.am

639
Makefile.am is where you define what programs and libraries should
Pekka Pessi's avatar
Pekka Pessi committed
640 641 642 643 644 645 646
be built, and also what source files are needed to create them.
When you run automake, it creates the file Makefile.in.

This file is created by the developer of the module.

@subsection configure configure

647 648 649
When you run configure script, it performs all the checks defined in
@b configure.ac and then replaces all @b xxx.in files with equivalent
@b xxx files. All @c @@FOO@@ variables in the source @b *.in files are
Pekka Pessi's avatar
Pekka Pessi committed
650
replaced with values found during the configuration process. For instance
651 652
the variable @c @@srcdir@@ in @b Makefile.in is replaced in @b Makefile
with the source directory path (useful when compiling outside the main
Pekka Pessi's avatar
Pekka Pessi committed
653 654 655 656 657 658 659
source tree).

This file is generated by autoconf command.

@subsection config_status config.status

This script stores the last parameters given to configre command.
660
If necessary you can rerun the last given configure script (with given
661
parameters) by using command "./config.status -r" or
662
"./config.status --recheck".
Pekka Pessi's avatar
Pekka Pessi committed
663

664
This file is generated by configure script.
Pekka Pessi's avatar
Pekka Pessi committed
665 666 667

@subsection config_cache config.cache

668
This file contains results of the various checks that configure script
669 670
performed. In case the configure script failed, you might try to
delete this file and run the configure script again.
Pekka Pessi's avatar
Pekka Pessi committed
671

672
This file is generated by configure script.
Pekka Pessi's avatar
Pekka Pessi committed
673 674 675

@subsection Makefile Makefile

676 677
The @b Makefile contains the actual rules how to build the target
libraries and program. It is used by the @c make program. @b Makefile
Pekka Pessi's avatar
Pekka Pessi committed
678 679 680
is generated from @b Makefile.in when you run @c autoconf command.
Ensure that "make dist" and "make install" targets work.

681
This file is generated by config.status and configure scripts.
Pekka Pessi's avatar
Pekka Pessi committed
682 683 684 685 686

@subsection config_h config.h

This file contains C language defines of various confurable issues.

687 688 689 690 691 692 693 694
This file is generated by config.status and configure script.

@subsection sofia_sip_configure_h sofia-sip/su_configure.h

This file contains C language defines describing how the Sofia SIP UA
library is configured.

This file is generated by config.status and configure script.
Pekka Pessi's avatar
Pekka Pessi committed
695 696 697 698 699 700

*/

/**
@page debug_logs Debugging Logs

701 702 703 704 705
The Sofia-SIP components can output various debugging information. The
detail of the debugging output is determined by the debugging level. The
level is usually module-specific and it can be modified by module-specific
environment variable. There is also a default level for all modules,
controlled by environment variable #SOFIA_DEBUG.
Pekka Pessi's avatar
Pekka Pessi committed
706 707 708 709

The environment variables controlling the logging and other debug output are
as follows:
- #SOFIA_DEBUG	Default debug level (0..9)
710 711 712
- #NUA_DEBUG	User Agent engine (<a href="nua/index.html">nua</a>) debug level (0..9)
- #SOA_DEBUG	SDP Offer/Answer engine (<a href="soa/index.html">soa</a>) debug level (0..9)
- #NEA_DEBUG	Event engine (<a href="nea/index.html">nea</a>) debug level (0..9)
Pekka Pessi's avatar
Pekka Pessi committed
713 714 715
- #IPTSEC_DEBUG	HTTP/SIP autentication module debug level (0..9)
- #NTA_DEBUG	Transaction engine debug level (0..9)
- #TPORT_DEBUG	Transport event debug level (0..9)
716 717 718
  - #TPORT_LOG	If set, print out all parsed SIP messages on transport layer
  - #TPORT_DUMP	Filename for dumping unparsed messages from transport
- #SU_DEBUG	<a href="nea/index.html">su</a> module debug level (0..9)
Pekka Pessi's avatar
Pekka Pessi committed
719 720

The defined debug output levels are:
721 722 723 724 725 726 727 728
- 0 SU_DEBUG_0() - fatal errors, panic
- 1 SU_DEBUG_1() - critical errors, minimal progress at subsystem level
- 2 SU_DEBUG_2() - non-critical errors
- 3 SU_DEBUG_3() - warnings, progress messages
- 5 SU_DEBUG_5() - signaling protocol actions (incoming packets, ...)
- 7 SU_DEBUG_7() - media protocol actions (incoming packets, ...)
- 9 SU_DEBUG_9() - entering/exiting functions, very verbatim progress

729
In addition to the macros mentioned above, there is also functions for
730 731 732 733 734 735 736 737 738 739
printing logging messages:
- su_llog(), su_vllog()
- su_perror(), su_perror2()

The log level can be set (to a level defined in a configuration file, for
instance) with following functions
- su_log_set_level(), su_log_soft_set_level()

The log output can be redirected to, e.g., system log or loggin server, with
su_log_redirect().
Pekka Pessi's avatar
Pekka Pessi committed
740 741

*/