==============================================================================
               I N S T A L L A T I O N   I N S T R U C T I O N S
==============================================================================

This document describes how to build and install sipXezPhone from source. 
This process is somewhat complicated and requires a number of 3rd party
software packages and manual steps.

If you have questions or problems, please consult the latest version of this
document and the sipX dev mailing list.  The sipX-dev mailing list is
searchable - please search before posting your question.

  http://scm.sipfoundry.org/rep/sipX/branches/sipXtapi/sipXcallLib/examples/sipXezPhone/INSTALL
  http://www.sipfoundry.org/sipXcallLib/
  http://list.sipfoundry.org/mailman/listinfo/sipx-dev

Contents:

  Windows instructions
    Getting the source code
    Installing 3rd party components
    Building C++ code
    Updating environment variables
    Launching the softphone
        Troubleshooting: Build problems
  Linux instructions
  Please help!

====================
Windows instructions
====================

The sipXezPhone depends on other SIPFoundry projects:
  sipXportLib, sipXtackLib, sipXmediaLib, and sipXcallLib.

For more information, please see the build and install documentation
for those projects. The top-level sipXezPhone.sln will configure and build
all of the dependant projects.

-------------------------------
Getting the Source Code
-------------------------------

Make a new directory which will be home to your SIPFoundry projects.

For example, create a "c:\sipfoundry" directory.

Using subversion from the command line, get the needed SIPFoundry projects by
running the following from the command line.

For example:
  cd \sipfoundry
  svn checkout https://scm.sipfoundry.org/rep/sipX/branches/sipXtapi sipXtapi
  
The sipXezPhone code and the Visual Studio project files are located in the
"sipXcallLib\examples\sipXezPhone" directory.

-------------------------------
Installing 3rd party components
-------------------------------

Required Software
-----------------
MSVC      - Microsoft Visual Studio.NET 2003 (or greater).
PCRE      - Perl Compatible Regular Expression Library
wxWidgets - Open-source, platform independent GUI library

Optional Software
-----------------
cppunit   - Unit test framework.  This required to build to sipXtapi unit 
            tests framework.

In MSVC, select "Options" from the "Tools" menu, select the "Projects"
folder, select "VC++ Directories", and then select either "Include files" or
"Library files" from the right-aligned dropdown list.

Installing PCRE
---------------
Latest tested version: 4.4

You will need the following PCRE packages/files:
  pcre-4.4-bin.exe : PCRE runtime environment
  pcre-4.4-lib.exe : PCRE development package

You can download the directly from gnuwin32 or from SIPfoundry:
  http://gnuwin32.sourceforge.net/packages/pcre.htm
  http://www.sipfoundry.org/pub/sipXphone/depends/win32/

Install both packages.  Order may not matter, however, installating the runtime
environment first is known to work.

Next add the PCRE paths to your MSVC environment (assuming installation into
C:\Program Files\GnuWin32):

Additional "Include files":
   C:\Program Files\GnuWin32\include

Additional "Library files":
   C:\Program Files\GnuWin32\lib

In MSVC, select "Options" from the "Tools" menu, select the "Projects"
folder, select "VC++ Directories", and then select either "Include files" or
"Library files" from the right-aligned dropdown list.

Installing wxWidgets
--------------------
The wxWidgets library can be downloaded from http://www.wxwidgets.org/.
sipXezPhone uses version 2.6.3 of wxWidgets.  Please follow the instructions
and build wxWidgets.  You will need to add the following paths to your 
MSVC environment (assuming installation info c:\wxWidgets-2.6.3):

Additional "Include files":
  C:\wxWidgets-2.6.3\include
  C:\wxWidgets-2.6.3\include\msvc

Additional "Library Files":
  C:\wxWidgets-2.6.3\lib\vc_lib

Installing cppunit
------------------

Download cppunit from the following URL (1.10.2 is known to work):
  http://sourceforge.net/projects/cppunit

Follow the cppunit build instructions to build cppunit.  You will need to add
the following paths to your MSVC environment (assuming installation into 
C:\cppunit-1.10.2):

Additional "Include files":
  C:\cppunit-1.10.2\include

Additional "Library Files":
  C:\cppunit-1.10.2\src\cppunit\Debug
  C:\cppunit-1.10.2\src\cppunit\Release


-----------------
Building C++ Code
-----------------

Open "sipXezPhone.sln" in MSVC, verify that "sipXezPhone" is the default 
project and build.  You should end up building "sipXezPhone.exe", 
"sipXtapi.dll" and the dependent .libs.

NOTE - there is currently and issue where the projects in the sipXezPhone 
solution may attempt to build in the WRONG order!!  If this happens, just 
build (dont re-build) a second time.  The second pass should build attempt 
should succeed.

-----------------------
Launching the sipXezPhone
-----------------------

After a build, sipXezPhone.exe will be created in the 
sipXcallLib\examples\sipXezPhone directory.  The working directory for 
sipXezPhone must have in it the sipXtapi.dll.  Either copy the sipXtapi.dll 
to the directory containing sipXezPhone.exe, or point your working directory 
to sipXtapi's build directory.

NOTE: Post-build commands have been added to automatically copy the 
sipXtapi[d].dll into the sipXezPhone build target directory.

-------------------------------
Troubleshooting: Build Problems
-------------------------------

RTTI must be enabled
--------------------
Many of the projects are starting to use the dynamic_cast<>()  mechanism to
provide runtime type checking.  RTTI must be enabled on all projects using
dynamic_cast<>() and related functionality.  By default, almost all of the
sipX WIN32 projects now enable RTTI.

Failing to enable RTTI results in odd crashes/exceptions.  Generally "rtti"
or "RTDynamicCast" is found in stack trace.

wxWidgets Unresolved Externals and MSVC 6.0
--------------------------------------------
If your wxWidgets library was not compiled with the /MT compile flag (multi-threaded),
may experience 'unresoved external' link errors such as:

unresolved external symbol __ftol2

Rebuild wxWidgets with the following command lines
 nmake -f makefile.vc clean FINAL=1
 nmake -f makefile.vc FINAL=1 CRTFLAG=/MD    (for the multithreaded DLL)

-------------------------------
Troubleshooting: Runtime Problems
-------------------------------

A STATUS_DLL_NOT_FOUND failure at start-up can be caused
if the application cannot find sipXtapi.dll or sipXtapid.dll (for debug).

You can:
1.  Set the working directory of sipXezPhone to the folder containing the 
    sipXtapi.dll or sipXtapid.dll.
2.  Copy the sipXtapi.dll or sipXtapid.dll to the same folder as the sipXezPhone.exe
3.  Add the folder containing sipXtapid.dll and/or sipXtapi.dll to your path.

==================
Linux instructions
==================

[Coming soon.]

As usual, run "autoreconf --install --force" and "./configure" in the
sipXcallLib directory.

Then, in this directory, run "make".


============
Please help!
============

Find a problem in these docs?  Have suggestions ... better yet a patch with
changes?  Please email sipX-dev AT sipfoundry.org or mcohen AT pingtel.com.
