OS X Limited to FreeSWITCH 1.4 Until Further Notice
October 1 2015: Until further notice, FreeSWITCH™ versions beyond 1.4 cannot be built on OS X due to new extensive prerequisite requirements to support video functionality. The 1.4 Production version must be used until this issue is resolved. This page will be updated at that time.
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 Installed and tested October 3, 2015:
- OS X Mavericks 10.11.0 (10.11 built clean, not upgraded from a prior OS X release)
- Xcode 7.0.1 and its Command Line Utilities
- Homebrew and other prerequisites
- FreeSWITCH™ 1.4.23b+git~20151001 Production
The OS X FreeSWITCH™ Installer
The OS X FreeSWITCH™ Installer simplifies installation and saves time! Check it out at Installation on OS X using AppleScript.
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.
If you encounter problems search the web, if you can't find an answer join and post to the FreeSWITCH-users mailing list.
OS X System 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.
Even though it's easy to remove FreeSWITCH™ and it's prerequisites, removing the Apple Command Line Tools is difficult at this time. Although there is no problem leaving the CLT installed, If you want to remove them 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:
- Copy Terminal in the Applications/Utilities folder into the Dock for quick access.
- Start the Terminal application by clicking it in the dock. Then open its preferences panel.
- In Settings–>Profiles–>Window change the Window Size to larger values such as 140x48 to reduce having to resize the window often.
- In Settings–>Profiles–>Window set Scrollback to "Limit to Available Memory" or a larger number. Many messages are produced that may be needed for problem analysis.
- In Settings–>Profiles–>Shell set 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
The OS X Developer Tools are composed of two parts, the Xcode 7 OS X Software Developer Kit used to develop and test OS X GUI applications, and the Command Line Tools that provide LLVM, Clang, Git and other tools required to generate non-GUI applications such as FreeSWITCH™ and its prerequisites. The Command Line Tools are included and automatically installed with Xcode. The Apple Developer site offers the standalone CLT but it cannot be used because Homebrew will not install without the Xcode/CLT version.
Install Xcode using the OS X App Store application or download it from the OS X Developer site which requires a minimum of a free membership. Xcode takes a while to download and is placed into the Applications folder (/Applications directory) with the CLT in /Applications/Xcode.app/Contents/Developer. Once installed start Xcode to accept the license agreement.
All editing can be made using Textedit, however, you should try the Xcode editor. It has the advantage of displaying XML code colorized so that syntax errors can be found 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 unhidden so they 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. View hidden files by running the lines below in Terminal:
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:
The user name and group appear in the third and fourth columns. Now create the /usr/local and /usr/local/src directories, replace yourname and yourgroup with the ones obtained from the previous command:
You will access /usr/local often so it should be placed in the Finder "FAVORITES" sidebar for quick access. Navigate to the /usr/local folder in the Finder, then drag the local folder under "FAVORITES".
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.
Prerequisite Installation Options
Additional programs are required to generate and run FreeSWITCH™. It is strongly recommended to follow this procedure using the Homebrew package manager and its repository of products for OS X. Homebrew saves time since there is no need to locate packages and determine the version required for each OS X release. Homebrew's Git repository is maintained by volunteers.
Install Package Manager and Prerequisites
Using the commands below the package manager and prerequisites install in under 10 minutes.
Homebrew installation is simple, the command can be run from any directory:
- Go to the bottom of the Homebrew page and copy the ruby command.
- Open terminal if not already opened, paste and run the command
- 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:
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.
OS X is now ready to download and install FreeSWITCH™. This takes about 20 minutes.
Selecting a Version
There are two versions of FreeSWITCH™ to choose from: the current release version recommended for production systems, and master containing the latest fixes and features used during development. The current release version is recommended unless you need newer features or patches added since the current release of FreeSWITCH™. Additional Information is located at Source Options.
This documentation is tested with the master version to keep it as recent as possible and to provide feedback to the developers. If there are problems the developers may request that you install the master version for diagnosis.
Download Using Git Clone
Download FreeSWITCH™ by switching to the src directory and invoking one of the "git clone" commands below. The git command will create the freeswitch directory in src (/usr/local/src/freeswitch) and download the FreeSWITCH™ source 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 optional functionality to FreeSWITCH™, while ./configure sets compilation options. Enter the following commands (each will run several minutes):
Add Text To Speech Module
Optional functions are added to FreeSWITCH™ by editing the modules.conf file, this may be required as your FreeSWITCH™ configuration becomes more complex. Although not required, adding FLITE Text To Speech functionality is recommended. The easiest way to add the FLITE module is to paste and run the following line into Terminal:
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.
- 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.
- Save the file.
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:
If there are no errors proceed, otherwise seek assistance from the FreeSWITCH-users mailing list
Generate FreeSWITCH™ Runtime
This creates the /usr/local/freeswitch runtime library and executable programs.
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:
This optional step can be performed to save space by removing the temporary files created by make:
Installation is Complete!
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:
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.
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:
Remove Homebrew and Prerequisites
Packages installed by Homebrew are listed using the "brew list" command. They are removed using the "brew uninstall package-name" command. To remove packages and Homebrew run the following in Terminal:
Remove Xcode 7
Xcode is installed as an OS X package (directory) that looks like a single application file. To remove Xcode drag the application to the trash, empty it and restart OS X.
Remove Everything Else
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:
- Drag directory /usr/local to the trash. Or delete it in Terminal (OS X prompts for the administrator password):
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.