Installation on OS X 10.6 Snow Leopard

From FreeSWITCH Wiki
Revision as of 17:49, 28 April 2014 by Mario G (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search




This page has been updated and converted to Confluence April 28 2014, it will no longer be updated but is still accurate. It is located at: https://confluence.freeswitch.org/display/FREESWITCH/Installation+on+OS+X+10.6+Snow+Leopard


Contents


Introduction

Description

This is part of the Installation and Setup on OS X guide for installing and running FreeSWITCH™. This page describes the installation of FreeSWITCH™ using the following components downloaded and/or installed as of April 26, 2014:

  • OS X Snow Leopard 10.6.8 (10.6 built clean, not upgraded from a prior OS X release)
  • GCC compiler, Homebrew and other prerequisites
  • FreeSWITCH™ 1.5.12b+git~20140426 development version


Warning

As of April 9 2014 the FreeSwitch module mod_v8 which provides Javascript support does not compile on OSX 10.6.8. Most likely, this module will never be supported on OSX 10.6.8. If you need this support upgrade OSX to at least 10.8.5. Instructions for removal are below.

As of March 10 2014 A fresh installation of OSX 10.6.8 was used to test these instructions without Xcode. Installing prerequisites using methods other than Homebrew were unsuccessful.

 

Getting Help

If you encounter problems search the web first, if you can't find an answer join and post to the FreeSWITCH-users mailing list.

A Word About Security

Although it's possible to log into root on OS X and perform the installation under root, it is not recommended. This procedure uses root minimally. That resulted in a few extra Unix permission commands but also a safer system.


Preparation

Backup

Even though it's easy to remove FreeSWITCH™ and it's prerequisites, removing Apple supplied tools is very difficult. If you decide to remove everything it's best to backup before starting this procedure.

Terminal Application Preferences

We'll use the Terminal application extensively during installation and to start FreeSWITCH™ initially. You should make the following changes to save time during this procedure:

  1. Copy Terminal in the Applications/Utilities folder into the Dock for quick access.
  2. Start the Terminal application by clicking it in the dock. Then open its preferences panel.
  3. In Settings–>Window change the Window Size to larger values such as 140x48 to reduce having to resize the window often.
  4. In Settings–>Window change Scrollback to Unlimit or a larger number. A lot of messages are produced that you may need to view.
  5. In Settings–>Shell change Prompt before closing to "Only if there are processes other than:". This prevents the Terminal window from closing when FreeSWITCH™ is shutdown if it started automatically, which would result in the loss of all messages in the window. This is useful during debugging. If FreeSWITCH™ started manually the window does not close.


OS X Developer Tools

Determine Xcode Status

If Xcode AND the Command Lines Tools are installed skip to Create /usr Subdirectories.
If Xcode is NOT installed continue with Install the OS X GCC Compiler.
If Xcode is installed but the Command Lines Tools are NOT inistalled remove Xcode first then continue with Install the OS X GCC Compiler.

Informational Tip

Xcode 4.2, the last available for 10.6, is no longer required for FreeSwitch installation on OSX 10.6. This is due to Apple removing Xcode 4.2 Command Line Tools for download. The following is for information only:
The Xcode OS X Software Developer Kit for Snow Leopard can be obtained from the OS X Developer site which requires a (free+) membership (NOTE: Apple may require a paid membership to access old versions such as 4.2). Sign on and select "View all downloads" to locate Xcode 4.2 for Snow Leopard, it provides tools required to generate FreeSWITCH™ and its prerequisites. The Xcode install is simple but large so it takes a while download and install. You can perform all editing using Textedit, however, Xcode provides an editor you should become familiar with. Its advantage is that it displays XML code colorized so you can find syntax errors quickly. This is ideal for editing FreeSWITCH™ XML configuration files.


 

Install the OS X GCC Compiler

The GCC compiler and additional tools for Snow Leopard (known as Command Line Tools) have been removed as an Apple Developer download. A version for OS X 10.6 can be downloaded from GitHub to provide the compiler and additional tools required to generate FreeSWITCH™ and its prerequisites. Scroll down to the prebuilt binaries for OS X 10.6, download and install the package.


Setup Installation Directories

OS X contains the directory /usr, to allow easy removal of FreeSWITCH™ and its prerequisites, everything "not from Apple" is installed into a new local directory you will create in /usr. This keeps non-Apple code out of OS X libraries. All prerequisites and FreeSWITCH™ source and runtimes are placed into /usr/local.

Show Invisible Files and Directories in the Finder

OS X hides many Unix directories and files from the Finder including the directories created by this procedure. These files and directories can be viewed by opening the Terminal application and run each line below. All hidden files will appear on the desktop, Finder windows and file dialogs. Additional information and scripts for showing invisible files are in the Installation and Setup on OS X guide.

     defaults write com.apple.finder AppleShowAllFiles YES
     killall Finder

Create /usr Subdirectories

The owner and group id of /usr/local and it's subdirectories must match the ones FreeSWITCH™ will run under. This is typically the main user ID of the Mac.
To find your information launch the Terminal application and issue the following command to display yourid and yourgroup:

   ls -l ~/

Create the /usr/local directory and change the owner and group of /usr/local to yourid and yourgroup obtained from the previous command:

   cd /usr
   sudo mkdir local
   sudo chown -R yourid:yourgroup local

Create the /usr/local/src directory FreeSWITCH™ source will be downloaded into:

   mkdir local/src

Prerequisites

A few prerequisite programs are required to generate and run FreeSWITCH™. This procedure is simplified by using a package manager that provides a repository of products that are easy to install, in this case, Homebrew. If you don't want to use Homebrew and want to install them manually see Install Individual Packages for OSX 10.6 below.

Install Homebrew

Homebrew is a packager manager for OS X that uses a Git repository maintained by volunteers. It drastically simplifies installation of Linux packages that run on OS X. Homebrew installation is simple, the command can be run from any directory:

  1. Go to the bottom of the Homebrew page and copy the ruby command.
  2. Open terminal if not already opened, paste and run the command
  3. Run the command "brew doctor" to make sure it all works, this command could take a couple of minutes.

There is an uninstall command to allow easy removal of all or some packages.

Install Required Packages

There are 11 packages required for a basic FreeSWITCH™ installation. The OS X SDK provides autoconf but it must be updated since the Snow Leopard versions are too old for FreeSWITCH™ installation. Enter the following command in Terminal to install all prerequisites, the command can be run from any directory:

   brew install git autoconf automake curl jpeg libtool openssl pcre pkg-config speex sqlite

If there were messages indicating that autoconf and automake were found to exist from Xcode 4.2 and were installed keg-only, you must run the following command, or ./bootstrap.sh (below) will fail:

   brew link --force autoconf automake

If there is a problem with any prerequisite it must be resolved before continuing.


Download FreeSWITCH™

After the previous steps are successful you are ready to continue. Downloading and updating are very easy.

Selecting a Version

There are two versions of FreeSWITCH™ that can be downloaded: development and stable. The development version is illustrated here because if you run into problems, the developers will want you to use that version to diagnose. The developer version is almost always stable and usable for normal operations. If you decide later to use the stable version, more information can be found at Which version should I use.

Download Using Git Clone

To install the most up-to-date development version switch to the new local/src directory and use Git to download the latest FreeSWITCH™, Git will create a freeswitch directory in src and start to download. Enter the following commands:

   cd /usr/local/src
   git clone git://git.freeswitch.org/freeswitch.git


Install FreeSWITCH™

Generate Installation and Configuration Files

This step creates the modules.conf file that can be edited to add modules to the compilation. ./bootstrap.sh creates many files including modules.conf and ./configure sets compilation options. Enter the following commands:

   cd freeswitch    <- the new freeswitch directory created by the git clone process
   ./bootstrap.sh
   ./configure

Edit modules.conf for Additional Modules to Compile

Optional functions are added to the compilation by editing the modules.conf file. At a minimum, FLITE should be added to provide Text To Speech functionality. As your FreeSWITCH™ configuration becomes more complex additional modules may be required.

  1. Use the Finder to launch Textedit, or try Xcode located in the Developer/Applications folder if it's installed.
  2. Use the File/Open… menu
  3. While the file window is open press command+shift+.(period) to view hidden files.
  4. Navigate to and edit /usr/local/src/freeswitch/modules.conf
  5. Search for "flite" and remove the # to uncomment.
  6. Save the file.
Warning

If this is your first experience with FreeSWITCH™ don't add more than FLITE. Adding functions may result in additional prerequisites that must be installed. For instance, if you want mp3 instead of aiff for emails search for shout and remove #, but you may need to install LIBVORBIS for OS X.

 

Warning

The mod_v8 module which provides Javascript support does not compile on OSX 10.6.8, if make below fails in mod_v8 edit modules.conf, locate the line containing "mod_v8" and insert "#" as the first character on the line then save the file. Otherwise the next step will fail.

 

Compile, Create Additional Source Directories and Check for Errors

This step compiles the programs and creates additional directories and files based on modules.conf. While still in /usr/local/src/freeswitch compile FreeSWITCH™:

   make

If there are no errors proceed, otherwise seek assistance from the FreeSWITCH-users mailing list

Generate FreeSWITCH™ Runtime

This creates the final runtime binary modules which are placed into /usr/local/freeswitch.

   make install

Download and Install Sounds

There are mandatory sound prompts and optional music on hold files. All must be compiled to run the sample IVR. There are four versions available:

  • sounds-install moh-install (8 kHz)
  • hd-sounds-install hd-moh-install (16 kHz)
  • uhd-sounds-install uhd-moh-install (32 kHz)
  • cd-sounds-install cd-moh-install (48 kHz)

The cd sounds are recommended since all the sampling rates are provided resulting in fewer problems. Invoke the following command:

   make cd-sounds-install cd-moh-install

Cleanup

This optional step can be performed to save space by removing the temporary files created by make:

   make clean

Installation is Complete!

Continue at Installation is Complete in the Installation and Setup on OS X guide.


Updating FreeSWITCH™

FreeSWITCH™ may occasionally require updating due to new features, fixes, etc. You can download the latest updates, compile FreeSWITCH™ and create updated runtime binaries with the following two commands:

   cd /usr/local/src/freeswitch
   git pull && make current


Install Individual Packages for OS X 10.6

This section is from 2010 and there are no plans to update it, it is for illustration only and is not recommend. Using this technique requires many more commands and knowledge of system configuration. It places programs in directories that are much harder to remove from and update.
This section illustrates how to install packages individually using Linux commands. If there are multiple file extensions in each of the download directories, use files ending in tar.gz if available.

Install autoconf

Building FreeSWITCH™ requires the gnu autoconf utility. Starting with Lion Apple no longer ships autoconf with XCODE 4.3.

  1. Download a recent autoconf (the one ending in .gz), by default it is placed into your Downloads folder.
  2. Open Downloads and click the file to uncompress it.
  3. Launch the Terminal application if not already running and issue these commands to move the source to the src directory, build and install:
   mv ~/Downloads/autoconf-2.69 /usr/local/src
   cd /usr/local/src/autoconf-2.69
   ./configure
   make
   make install	<– binaries are loaded into /usr/local/bin
   make clean	<– optional - removes temp make files, saves space

Install automake

Building FreeSWITCH™ requires the gnu automake utility. Starting with Lion Apple no longer ships automake with XCODE 4.3.

  1. Download a recent automake (the one ending in .gz), by default it is placed into your Downloads folder.
  2. Open Downloads and click the file to uncompress it.
  3. Launch the Terminal application if not already running and issue these commands to move the source to the src directory, build and install:
   mv ~/Downloads/automake-1.12 /usr/local/src
   cd /usr/local/src/automake-1.12
   ./configure
   make
   make install	<– binaries are loaded into /usr/local/bin
   make clean	<– optional - removes temp make files, saves space

Install libtool

Building FreeSWITCH™ requires the gnu libtool utility. Starting with Lion Apple no longer ships lib tool with XCODE 4.3.

  1. Download a recent libtool (the one ending in .gz)], by default it is placed into your Downloads folder.
  2. Open Downloads and click the file to uncompress it.
  3. Launch the Terminal application if not already running and issue these commands to move the source to the src directory, build and install:
   mv ~/Downloads/libtool-2.4.2 /usr/local/src
   cd /usr/local/src/libtool-2.4.2
   ./configure
   make
   make install	<– binaries are loaded into /usr/local/bin
   make clean	<– optional - removes temp make files, saves space

Install PKG-CONFIG Prerequisite

FreeSWITCH™ has many functions that invoke PKG-CONFIG. PKG-CONFIG source but not LIBJPEG source so must be downloaded and installed separately.

  1. Download the latest pkg-config, by default it is placed into your Downloads folder. Note: at the time of this writing OS X REQUIRED .25 due to glib2 dependencies. You can try a later version then install earlier ones until the install works.
  2. Open Downloads and click the file to uncompress it.
  3. Launch the Terminal application if not already running and issue these commands to move the source to the src directory, build and install:
   mv ~/Downloads/pkg-config-0.27 /usr/local/src
   cd /usr/local/src/pkg-config-0.27
   ./configure
   make install	<– binaries are loaded into /usr/local/bin
   make clean	<– optional - removes temp make files, saves space


Install LIBJPEG Prerequisite for SPANDSP

Some FreeSWITCH™ functions invoke SPANDSP, which then invokes LIBJPEG. FreeSWITCH™ provides SPANDSP source but not LIBJPEG source, so LIBJPEG must be downloaded and installed separately.

  1. Download libjpeg8d, by default it is placed into your Downloads folder.
  2. Open Downloads and double click the file to uncompress it.
  3. Launch the Terminal application if not already running and issue these commands to move the source to the src directory, build and install:
   mv ~/Downloads/jpeg-8d /usr/local/src
   cd /usr/local/src/jpeg-8d
   ./configure --enable-shared --enable-static
   make
   sudo make install	<– sudo is required because binaries are loaded into /usr/bin


Cleanup

Delete installers, compressed libjpeg, and other files no longer needed in the Downloads folder.


Category:Documentation]]