Difference between revisions of "Installation on OS X 10.9 Mavericks"

From FreeSWITCH Wiki
Jump to: navigation, search
(Add more removal info, add show invisible files, rearrange to prepare for script)
(Lots of minor rewrites, added more info to removal)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
 
===Description===
 
===Description===
This is a part of the  [http://wiki.freeswitch.org/wiki/Installation_and_Setup_on_OS_X Installation and Setup on OS X] guide for installing and running FreeSWITCH™. This page describes the installation of FreeSWITCH™ using the following components <span style="color:#FFFF00; background:#0000FF">&nbsp;Installed and tested March 26, 2014:&nbsp;</span><br/>
+
This is a part of the  [http://wiki.freeswitch.org/wiki/Installation_and_Setup_on_OS_X Installation and Setup on OS X] guide for installing and running FreeSWITCH™. This page describes the installation of FreeSWITCH™ using the following components <span style="color:#FFFF00; background:#0000FF">&nbsp;Installed and tested March 29, 2014:&nbsp;</span><br/>
 
* OS X Mavericks 10.9.2 (10.9 built clean, not upgraded from a prior OS X release)
 
* OS X Mavericks 10.9.2 (10.9 built clean, not upgraded from a prior OS X release)
 
* Xcode 5.1 and its Command Line Utilities
 
* Xcode 5.1 and its Command Line Utilities
 
* Homebrew and other prerequisites
 
* Homebrew and other prerequisites
* FreeSWITCH™ 1.5.12b+git~20140326 development version
+
* FreeSWITCH™ 1.5.12b+git~20140328 development version
 
<br>
 
<br>
There is information on this page for people who want a little more than others. ''If you're not too technical don't let the explanations intimidate you.'' Just follow the steps and FreeSWITCH™ should be installed in about an hour.
+
Some information on this page is for people who want a little more than others. ''If you're not too technical don't let the explanations intimidate you.'' Just follow the steps and FreeSWITCH™ should be installed in about an hour.
  
 
===Getting Help===
 
===Getting Help===
If you encounter problems search the web first, if you can't find an answer join and post to the [http://lists.freeswitch.org FreeSWITCH-users mailing list].
+
If you encounter problems search the web, if you can't find an answer join and post to the [http://lists.freeswitch.org FreeSWITCH-users mailing list].
  
 
===A Word About Security===
 
===A Word About Security===
It is ''not recommended'' to perform the installation while logged on as root on OS X. This procedure uses root minimally which results in a few extra Unix permission commands and a safer system.
+
It is ''not recommended'' to perform this procedure while logged on as root. The administrator password is required minimally, resulting in a couple of extra prompts and a safer system.
 +
 
  
 
==Install OS X Xcode==
 
==Install OS X Xcode==
Line 27: Line 28:
 
OS X provides the /usr directory which contains subdirectories. This procedure adds the directory '''local''' to /usr as /usr/local where FreeSWITCH™ and its prerequisite source and runtime files are placed. These files are kept out of OS X supplied directories to allow easy removal of FreeSWITCH™ and its prerequisites.
 
OS X provides the /usr directory which contains subdirectories. This procedure adds the directory '''local''' to /usr as /usr/local where FreeSWITCH™ and its prerequisite source and runtime files are placed. These files are kept out of OS X supplied directories to allow easy removal of FreeSWITCH™ and its prerequisites.
 
===Show Invisible Files and Directories in the Finder===
 
===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  [http://wiki.freeswitch.org/wiki/Installation_and_Setup_on_OS_X Installation and Setup on OS X] guide.
+
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  [http://wiki.freeswitch.org/wiki/Installation_and_Setup_on_OS_X#Invisible_Files_and_Directories Installation and Setup on OS X] guide.
 
       defaults write com.apple.finder AppleShowAllFiles YES
 
       defaults write com.apple.finder AppleShowAllFiles YES
 
       killall Finder
 
       killall Finder
  
 
===Create /usr Subdirectories===
 
===Create /usr Subdirectories===
The user name (owner) and group name of /usr/local and it's subdirectories must match the user and group FreeSWITCH™ will run under. This is typically the main user name of the Mac. To find your information launch the Terminal application and issue the following command to display yourname and yourgroup:
+
The user name (owner) and group name of /usr/local and it's subdirectories must match the user and group FreeSWITCH™ will run under. This is typically the main user name of the Mac. View this information (yourname and yourgroup) by running the following command in Terminal:
     ls -l
+
     ls -l ~/
Create the /usr/local directory and change the owner and group of /usr/local to yourname and yourgroup obtained from the previous command:
+
The user name and group appear in the third and fourth columns. Create the /usr/local directory and change the owner and group of /usr/local, replace yourname and yourgroup with the ones obtained from the previous command:
 
     cd /usr
 
     cd /usr
 
     sudo mkdir local
 
     sudo mkdir local
Line 45: Line 46:
 
==Prerequisites==
 
==Prerequisites==
 
===Prerequisite Installation Options===
 
===Prerequisite Installation Options===
Additional programs are required to generate and run FreeSWITCH™. It is ''strongly recommended to follow the procedure on this page using the Homebrew [http://en.wikipedia.org/wiki/Package_management_system package manager]'' for OS X that provides a [http://en.wikipedia.org/wiki/Software_repository repository] of products that are easy to install and remove. Homebrew uses a [http://en.wikipedia.org/wiki/Git_(software) Git] repository maintained by volunteers. Using Homebrew saves time since you don’t have to locate each package and determine the version required for your OS X release.
+
Additional programs are required to generate and run FreeSWITCH™. It is ''strongly recommended to follow the procedure on this page using the Homebrew [http://en.wikipedia.org/wiki/Package_management_system package manager]'' for OS X that provides a [http://en.wikipedia.org/wiki/Software_repository repository] of products that are easy to install and remove. Homebrew uses a [http://en.wikipedia.org/wiki/Git_(software) Git] repository maintained by volunteers. Homebrew saves time since there is no need to locate packages and determine the version required for each OS X release.
 
{{info|content=Alternatively, other techniques for installing prerequisites and FreeSWITCH™ can be viewed on the [http://wiki.freeswitch.org/wiki/Installation_on_OS_X_Alternatives Installation on OS X Alternatives] documentation.<br>
 
{{info|content=Alternatively, other techniques for installing prerequisites and FreeSWITCH™ can be viewed on the [http://wiki.freeswitch.org/wiki/Installation_on_OS_X_Alternatives Installation on OS X Alternatives] documentation.<br>
 
This is discouraged but is made available for those who don’t want to use Homebrew.}}
 
This is discouraged but is made available for those who don’t want to use Homebrew.}}
Line 55: Line 56:
 
# Go to the bottom of the [http://mxcl.github.com/homebrew Homebrew] page and copy the ruby command.
 
# Go to the bottom of the [http://mxcl.github.com/homebrew Homebrew] page and copy the ruby command.
 
# Open terminal if not already opened, paste and run the command
 
# Open terminal if not already opened, paste and run the command
# Run the command "brew doctor" to make sure it all works, this command could take a couple of minutes.
+
# Run the command "brew doctor" to verify homebrew works, this command could take a couple of minutes.
  
 
====Install Required Packages====
 
====Install Required Packages====
Line 78: Line 79:
 
==Install FreeSWITCH™==
 
==Install FreeSWITCH™==
 
===Generate Installation and Configuration Files===
 
===Generate Installation and Configuration Files===
This step creates installation files based on the operating system and installed packages. ./bootstrap.sh creates many files such as modules.conf used to add modules to the compilation while ./configure sets compilation options. Enter the following commands (each will run several minutes):
+
This step creates installation files based on the operating system and installed packages. ./bootstrap.sh creates many files such as modules.conf used to add optional functionality to FreeSWITCH™, while ./configure sets [http://en.wikipedia.org/wiki/GNU_Compiler_Collection compilation] options. Enter the following commands (each will run several minutes):
 
     cd freeswitch  &nbsp;&nbsp;<- the new freeswitch directory created by the git clone process
 
     cd freeswitch  &nbsp;&nbsp;<- the new freeswitch directory created by the git clone process
 
     ./bootstrap.sh
 
     ./bootstrap.sh
Line 84: Line 85:
  
 
===Add Text To Speech Module===
 
===Add Text To Speech Module===
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.
+
Optional functions are added to FreeSWITCH™ by editing the modules.conf file. Although not required the Text To Speech functionality is recommended by adding the FLITE module. The easiest way to add the module is to paste and run the following line into Terminal:
 +
    perl -pi -e 's{#asr_tts/mod_flite}{asr_tts/mod_flite}' /usr/local/src/freeswitch/modules.conf
 +
 
 +
If you prefer to manually edit the modules.conf file use this procedure:
 
# Use the Finder to navigate to the /usr/local/src/freeswitch directory.
 
# Use the Finder to navigate to the /usr/local/src/freeswitch directory.
 
# Scroll to and double-click modules.conf in the freeswitch directory, the first time requires application selection, Textedit should be used.
 
# Scroll to and double-click modules.conf in the freeswitch directory, the first time requires application selection, Textedit should be used.
 
# Search for "flite" and remove the # to uncomment.
 
# Search for "flite" and remove the # to uncomment.
 
# Save the file.
 
# Save the file.
{{warning|content=''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|content=As your FreeSWITCH™ configuration becomes more complex additional modules may be required. ''If this is your first FreeSWITCH™ don't add more than the FLITE module. Some modules may have prerequisites in addition to what is listed in this procedure.''}}
 
===Compile, Create Additional Source Directories and Check for Errors===
 
===Compile, Create Additional Source Directories and Check for Errors===
 
This step compiles the programs and creates additional directories and files based on modules.conf. It can run longer than 10 minutes. While still in /usr/local/src/freeswitch compile FreeSWITCH™ with the following command:
 
This step compiles the programs and creates additional directories and files based on modules.conf. It can run longer than 10 minutes. While still in /usr/local/src/freeswitch compile FreeSWITCH™ with the following command:
Line 123: Line 127:
  
 
===Updating Prerequisites===
 
===Updating Prerequisites===
To upgrade everything installed by Homebrew run "brew update" then "brew upgrade". To update a single package add the package name to the brew upgrade command.
+
To update Homebrew and its formulas run "brew update" in Terminal, this should be run prior to upgrading packages. To upgrade all packages, run "brew upgrade", or to upgrade a single package run "brew upgrade ''package-name''" command.
 +
 
  
 
==Removal==
 
==Removal==
 +
===Remove Everything===
 +
If the /usr/local directory existed prior to using this procedure it has to be examined to determine if the contents are deletable. If the instructions on this page were followed, '''''and the /usr/local directory was created during this procedure''''', everything can be removed to roll back the system prior to using this procedure by performing these steps:
 +
 +
# Move the Xcode application to the trash and empty the Trash
 +
# Drag directories /usr/local and /Library/Caches/Homebrew to the trash. Or delete them in Terminal (OS X prompts for the administrator password):
 +
    sudo rm -r /usr/local
 +
    sudo rm -r /Library/Caches/Homebrew
 +
 
===Removing FreeSWITCH™===
 
===Removing FreeSWITCH™===
Save any configuration files you created and don't want to lose! FreeSWITCH™ can be removed simply by deleting the /usr/local/freeswitch and /usr/local/src/freeswitch directories using the Finder (drag to trash) or in Terminal: "rm -r /usr/local/freeswitch" and "rm -r /usr/local/src/freeswitch" commands.
+
Consider backing up modified or new configuration files you created! FreeSWITCH™ is completely removed by deleting the /usr/local/freeswitch and /usr/local/src/freeswitch directories using the Finder (drag to trash) or in Terminal:
 +
    rm -r /usr/local/freeswitch
 +
    rm -r /usr/local/src/freeswitch
  
 
===Remove Prerequisites===
 
===Remove Prerequisites===
Line 134: Line 149:
 
===Remove Xcode===
 
===Remove Xcode===
 
Xcode is installed as an OS X package (directory) that looks like a single application file. It is removed by moving the Xcode application to the trash and emptying it.
 
Xcode is installed as an OS X package (directory) that looks like a single application file. It is removed by moving the Xcode application to the trash and emptying it.
 
===Remove Everything===
 
If the instructions on this page are followed, '''''and the /usr/local directory was created during this procedure''''', everything that is installed can be removed to roll back the system prior to installing FreeSWITCH™ and its prerequisites by performing these steps:
 
 
# Delete (drag to trash) all files and directories located in /usr/local or in Terminal: "rm -r /usr/local".
 
# Move the Xcode application to the trash and empty the Trash
 
 
If there was a /usr/local directory prior to using this procedure it has to be examined to determine if the contents are deletable.
 
  
 
===Hide Invisible Files and Directories in the Finder===
 
===Hide Invisible Files and Directories in the Finder===
To reverse the show hidden files step above, open the Terminal application and run each line below. All hidden files will disappear from the desktop, Finder and file dialogs.   
+
To reverse the show hidden files step, open the Terminal application and run each line below. All hidden files will disappear from the desktop, Finder and file dialogs.   
 
       defaults write com.apple.finder AppleShowAllFiles NO
 
       defaults write com.apple.finder AppleShowAllFiles NO
 
       killall Finder
 
       killall Finder

Revision as of 21:25, 29 March 2014

Contents

Introduction

Description

This is a 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  Installed and tested March 29, 2014: 

  • OS X Mavericks 10.9.2 (10.9 built clean, not upgraded from a prior OS X release)
  • Xcode 5.1 and its Command Line Utilities
  • Homebrew and other prerequisites
  • FreeSWITCH™ 1.5.12b+git~20140328 development version


Some information on this page is for people who want a little more than others. If you're not too technical don't let the explanations intimidate you. Just follow the steps and FreeSWITCH™ should be installed in about an hour.

Getting Help

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

A Word About Security

It is not recommended to perform this procedure while logged on as root. The administrator password is required minimally, resulting in a couple of extra prompts and a safer system.


Install OS X Xcode

Xcode is the OS X Software Developer Kit for Mavericks that provides Git and other tools required to generate FreeSWITCH™ and its prerequisites. Xcode should be installed using the OS X App Store application. It can also be downloaded from the OS X Developer site which requires a minimum of a free membership. Xcode is large so it takes a while to download and install. Xcode is installed into the Applications folder (/Applications directory).

After Xcode is installed the compiler and command line tools must be installed. WARNING: Starting with OS X 10.9 Mavericks, the Command Line Tools can be installed without Xcode. DO NOT install without first installing Xcode, otherwise the tools are placed into directory paths that contain spaces which cause FreeSWITCH™ installation to fail. Install the tools as follows:

  1. Open a Terminal session.
  2. Type “xcode-select --install” (without quotes), press Enter
  3. When the pop-up window displays click “Install”. The Command Line Tools will download and install in a few minutes.


Informational Tip

You can perform all editing using Textedit, however, you should become familiar with the Xcode editor. 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.


 

Setup Installation Directories

OS X provides the /usr directory which contains subdirectories. This procedure adds the directory local to /usr as /usr/local where FreeSWITCH™ and its prerequisite source and runtime files are placed. These files are kept out of OS X supplied directories to allow easy removal of FreeSWITCH™ and its prerequisites.

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 user name (owner) and group name of /usr/local and it's subdirectories must match the user and group FreeSWITCH™ will run under. This is typically the main user name of the Mac. View this information (yourname and yourgroup) by running the following command in Terminal:

   ls -l ~/

The user name and group appear in the third and fourth columns. Create the /usr/local directory and change the owner and group of /usr/local, replace yourname and yourgroup with the ones obtained from the previous command:

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

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

   mkdir local/src
Informational Tip

You will access /usr/local quite often, it is recommended that you navigate to it in the Finder, then drag the local folder to the Finder window sidebar under "FAVORITES" so it can be accessed quickly.

If you're interested: Even though OS X did not contain the /usr/local directory, /usr/local/bin is defined at the end of the default OS X path. The path is viewed by running "echo $PATH" in Terminal. If you don't understand this, don't worry, it doesn't affect anything.


 

Prerequisites

Prerequisite Installation Options

Additional programs are required to generate and run FreeSWITCH™. It is strongly recommended to follow the procedure on this page using the Homebrew package manager for OS X that provides a repository of products that are easy to install and remove. Homebrew uses a Git repository maintained by volunteers. Homebrew saves time since there is no need to locate packages and determine the version required for each OS X release.

Informational Tip

Alternatively, other techniques for installing prerequisites and FreeSWITCH™ can be viewed on the Installation on OS X Alternatives documentation.
This is discouraged but is made available for those who don’t want to use Homebrew.


 

Install Package Manager and Prerequisites

Using the commands below the package manager and prerequisites install in under 10 minutes.

Install Homebrew

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 verify homebrew works, this command could take a couple of minutes.

Install Required Packages

The basic FreeSWITCH™ prerequisite packages are installed by running the following command in Terminal from any directory:

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

Some packages produce keg-only messages which can be ignored. It means an alias (link) for the package was not placed into /usr/local/bin because brew found that OS X has another version installed. This is not a problem because the FreeSWITCH™ installation process searches Homebrew directories to find packages.
Homebrew has never failed in all tests but if any prerequisite fails to install it must be resolved before continuing. First, check if you are using an OS X or Xcode that was upgraded, if so read the warnings at the top of the Installation on OS X Alternatives page.

 

Download FreeSWITCH™

OS X is now ready to download and install FreeSWITCH™. This takes about 20 minutes.

Selecting a Version

There are two versions of FreeSWITCH™ that can be downloaded: development and stable. The development version is used here because if there are problems the developers will request to diagnose using the development version. The development version is almost always stable and usable for normal operations. Information for the stable version is found at Which version should I use.

Download Using Git Clone

To install the most up-to-date development version, switch to the new src directory and use git to download the latest FreeSWITCH™, git will create the freeswitch directory in src and download the FreeSWITCH™ source files. 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 installation files based on the operating system and installed packages. ./bootstrap.sh creates many files such as modules.conf used to add optional functionality to FreeSWITCH™, while ./configure sets compilation options. Enter the following commands (each will run several minutes):

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

Add Text To Speech Module

Optional functions are added to FreeSWITCH™ by editing the modules.conf file. Although not required the Text To Speech functionality is recommended by adding the FLITE module. The easiest way to add the module is to paste and run the following line into Terminal:

   perl -pi -e 's{#asr_tts/mod_flite}{asr_tts/mod_flite}' /usr/local/src/freeswitch/modules.conf

If you prefer to manually edit the modules.conf file use this procedure:

  1. Use the Finder to navigate to the /usr/local/src/freeswitch directory.
  2. Scroll to and double-click modules.conf in the freeswitch directory, the first time requires application selection, Textedit should be used.
  3. Search for "flite" and remove the # to uncomment.
  4. Save the file.
Warning

As your FreeSWITCH™ configuration becomes more complex additional modules may be required. If this is your first FreeSWITCH™ don't add more than the FLITE module. Some modules may have prerequisites in addition to what is listed in this procedure.

 

Compile, Create Additional Source Directories and Check for Errors

This step compiles the programs and creates additional directories and files based on modules.conf. It can run longer than 10 minutes. While still in /usr/local/src/freeswitch compile FreeSWITCH™ with the following command:

   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

Updating FreeSWITCH™

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

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

Updating Prerequisites

To update Homebrew and its formulas run "brew update" in Terminal, this should be run prior to upgrading packages. To upgrade all packages, run "brew upgrade", or to upgrade a single package run "brew upgrade package-name" command.


Removal

Remove Everything

If the /usr/local directory existed prior to using this procedure it has to be examined to determine if the contents are deletable. If the instructions on this page were followed, and the /usr/local directory was created during this procedure, everything can be removed to roll back the system prior to using this procedure by performing these steps:

  1. Move the Xcode application to the trash and empty the Trash
  2. Drag directories /usr/local and /Library/Caches/Homebrew to the trash. Or delete them in Terminal (OS X prompts for the administrator password):
   sudo rm -r /usr/local
   sudo rm -r /Library/Caches/Homebrew

Removing FreeSWITCH™

Consider backing up modified or new configuration files you created! FreeSWITCH™ is completely removed by deleting the /usr/local/freeswitch and /usr/local/src/freeswitch directories using the Finder (drag to trash) or in Terminal:

   rm -r /usr/local/freeswitch
   rm -r /usr/local/src/freeswitch

Remove Prerequisites

Packages installed by Homebrew are listed using the "brew list" command. They are removed using the "brew uninstall package-name" command.

Remove Xcode

Xcode is installed as an OS X package (directory) that looks like a single application file. It is removed by moving the Xcode application to the trash and emptying it.

Hide Invisible Files and Directories in the Finder

To reverse the show hidden files step, open the Terminal application and run each line below. All hidden files will disappear from the desktop, Finder and file dialogs.

     defaults write com.apple.finder AppleShowAllFiles NO
     killall Finder