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.

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.

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​

You'll reference folders (directories) similar to Linux/UNIX standard directories. We'll also use the 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.

Apple Silicon vs Intel x86​

The directories used are different between Apple Silicon and x86 machines:

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 directories below which are 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 runtime located in /opt/homebrew OR /usr/local/homebrew
  • FreeSWITCH™ prerequisites runtime and source located in /opt/homebrew OR /usr/local
  • FreeSWITCH™ runtime located in /opt/homebrew/opt/freeswitch OR /usr/local/opt/freeswitch
  • FreeSWITCH™ configuration located in /opt/homebrew/opt/freeswitch/etc/freeswitch OR /usr/local/opt/freeswitch/etc/freeswitch

Subdirectores of /opt OR /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. The /usr/local directory is protected by System Integrity Protection (aka rootless) and cannot be removed or changed.

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

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

Various /opt directories are added to the default search path by Homebrew installation. /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 freeswitch directories from /opt and /opt/src OR /usr/local and /usr/local/src 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 /opt/homebrew/Cellar /opt/homebrew/.git && brew cleanup
or
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 /opt OR /usr/local directory were empty prior to using this procedure then the entire contents are deletable. Everything can be removed to restore the system prior to using this procedure by performing these steps:

  1. Drag everything in the /opt OR /usr/local directory to the trash. Or delete it in Terminal (macOS prompts for the administrator password):
sudo rm -r /opt/*
  or
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