Skip to main content

macOS Homebrew Installation

About​

This page describes the process of installing, updating and removing FreeSWITCH™ and its prerequisites on macOS using Homebrew. This page is part of the FreeSWITCH™ macOS documentation.
---

Knowledge​

What You Should Already Know You must know your way around the macOS Finder, Dock and Textedit. You should also be familiar with the standard macOS folders (directories) such as Applications, Utilities, Downloads, Users, etc.

New To You
A new folder (directory) named /usr/local, it's part of the Linux/UNIX standard directories. We'll also use the Linux/Unix commands: cd, mkdir, ls, cp, mv,chmod, chown, and sudo. You don't need to learn about them unless you change the steps or directories used in this document.

Overview​

The manual installation steps below involve downloading and installing the following software:

It takes about one hour to have the sample FreeSWITCH™ configuration running on macOS.

Preparation​

Backup​

All of the software this procedure installs can be removed easily. However, to restore to a point where nothing was added or changed, a backup is required.

Terminal Application Preferences​

The Terminal application is used extensively during installation. The following changes are highly recommended:

  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–>Profiles–>Window change the Window Size to larger values such as 140x48 to reduce having to resize the window often.

Show Invisible Files and Directories in the Finder​

macOS hides many Unix directories and files from the Finder including the directories created by this procedure. These files and directories must be unhidden so they appear on the desktop, Finder windows and file dialogs. Additional information and scripts for showing invisible files are in the macOS Customization guide. View hidden files by running the lines below in Terminal:

defaults write com.apple.finder AppleShowAllFiles YES
killall Finder

Installation Directories​

Homebrew FreeSWITCH Directories​

All FreeSWITCH™ and prerequisite files are placed into the macOS provided /usr/local directory which is normally empty and intended for additional software such as FreeSWITCH™. This single location allows easy removal. The Homebrew version of FreeSWITCH is placed into the following directories:

  • Homebrew and prerequisites runtime located in /usr/local
  • FreeSWITCH™ runtime located in /usr/local/opt/freeswitch
  • FreeSWITCH™ configuration located in /usr/local/opt/freeswitch/etc/freeswitch
  • FreeSWITCH™ prerequisite source and runtime directories in /usr/local

Non-Homebrew FreeSWITCH Directories​

Throughout the FreeSWITCH macOS wiki, the directories are identified differently due to the manual installation process. You will need to adjust any wiki commands you copy/paste from this wiki:

  • FreeSWITCH™ source located in /usr/local/src
  • FreeSWITCH™ runtime located in /usr/local/freeswitch
  • FreeSWITCH™ configuration located in /usr/local/freeswitch/conf
  • FreeSWITCH™ prerequisite source and runtime directories in /usr/local

The /usr/local directory is protected by System Integrity Protection (aka rootless) and cannot be removed or changed. Subdirectores of /usr/local can be added or removed using administrator authority. The subdirectories can then have their security changed so that non-administrators can modify them.

If you would like to see the ownership and permissions of directories and files use the "ls -l" command in Terminal.

Since /usr/local is accessed often, it should be placed in the Finder "FAVORITES" sidebar for quick access. Use the Finder to navigate to the /usr/local folder and drag it under "FAVORITES".

Extra info: /usr/local/bin is defined in the default macOS 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​

Additional programs are required to generate and run FreeSWITCH™. They are installedusing Homebrew, a package manager and its repository of products for macOS. Homebrew saves time since there is no need to locate packages and determine the version required for each macOS release. Homebrew's Git repository is maintained by volunteers.

macOS Developer Tools​

Generation of FreeSWITCH™ and its prerequisites require the macOS Developer Command Line Tools that provide LLVM, Clang, Git and other tools required to generate non-GUI applications. The Xcode Software Developer Kit used to develop macOS GUI applications already includes the CLT. This is not something you need to worry about because if:

  1. Xcode and CLT are not already installed Homebrew will download and install the Command Line Tools during Homebrew installation.
  2. You are using the latest macOS and Xcode is installed, the correct CLT is already installed.
  3. You are using a macOS prior to the latest release and Xcode is installed you may have the wrong CLT. That's because when Apple upgrades Xcode, only the latest release of macOS CLT are usually supplied. If macOS is not the latest release, the CLT may not match. Homebrew will determine if the correct Command Line Tools are already installed. If not, it will download and install them during Homebrew installation.

Install the Homebrew Package Manager​

Homebrew installation is simple, the install command is found at the Homebrew home page and is listed below. The Homebrew package manager takes several minutes to install.

  1. Open Terminal if not already opened, paste and run the first command from any directory.
  2. Run the command "brew doctor" to verify homebrew works, this command could take a couple of minutes.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew doctor

Already had some prerequisites installed?

If non-Apple compilers are installed, or prerequisites were installed without homebrew, there may be problems.

Install FreeSWITCH™ and Prerequisites​

macOS is now ready to download and install the Current public release of FreeSWITCH™ and all prerequisites. FreeSWITCH and its prerequisites takes several minutes to install. Use the following command:

brew install freeswitch

Ignore any keg-only messages, they mean an alias (link) for the package was not placed into /usr/local/bin because brew found that macOS has another version installed. This is not a problem because the FreeSWITCH™ installation process searches Homebrew directories to find prerequisite packages.

Test FreeSWITCH™!​

The time has come to start and test FreeSWITCH™ using the macOS Testing and Diagnostics instructions.

Updating FreeSWITCH™​

Homebrew, FreeSWITCH™ public release and its prerequisites are updated by the following two commands:

brew update
brew upgrade

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​

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:

brew uninstall freeswitch

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:

rm -rf /usr/local/Cellar /usr/local/.git && brew cleanup
sudo rm -r /Library/Caches/Homebrew   # (macOS prompts for the administrator password)

Remove the Command Line Tools​

  1. Move the /Library/Developer directory to the trash. Or delete it in Terminal (macOS prompts for the administrator password):
  sudo rm -r /Library/Developer

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:

  1. Drag everything in the /usr/local directory to the trash. Or delete it in Terminal (macOS prompts for the administrator password):
sudo rm -r /usr/local/*

The /usr/local directory can't be deleted due to System Integrity Protection (aka rootless) security.

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