How to install Xdebug on MacOS 10.15 Catalina (Xcode 11) When you try to build xdebug on macOS Catalina you will get errors like these:
phpize
grep: /usr/include/php/main/php.h: No such file or directory
grep: /usr/include/php/Zend/zend_modules.h: No such file or directory
grep: /usr/include/php/Zend/zend_extensions.h: No such file or directory
Configuring for:
PHP Api Version:
Zend Module Api No:
Zend Extension Api No:
xdebug-2.9.0/xdebug.c:25:10: fatal error: 'php.h' file not found #include "php.h" ^~~~~~~ 1 error generated. make: *** [xdebug.lo] Error 1
/usr/include/php/main/php.h:33:10: fatal error: 'zend.h' file not found #include "zend.h" ^~~~~~~~ 1 error generated. make: *** [xdebug.lo] Error 1
/usr/include/php/Zend/../TSRM/TSRM.h:20:11: error: 'tsrm_config.h' file not found with include; use "quotes" instead
^~~~~~~~~~~~~~~
"tsrm_config.h"
.... /usr/include/php/Zend/zend_virtual_cwd.h:24:10: fatal error: 'TSRM.h' file not found #include "TSRM.h" ^~~~~~~~ 2 errors generated. make: *** [xdebug.lo] Error 1
Configure and build xdebug on macOS Catalina The reason for these errors is that the /usr/include folder is missing because Apple removed it when they released Xcode 11.
But, you can work around this problem. Here is how:
First, you need to make sure that Xcode and the command line tools installed. Open a terminal window and run the following command to display the SDK path:
xcrun --show-sdk-path
This command should output something like this:
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
If not, install the command-line tools with executing:
xcode-select --install
and follow the instructions. After the installation is finished, start Xcode App to make sure the installation is done.
Now try to display the SDK-Path again:
xcrun --show-sdk-path
The php tools needed to compile an extension try to use this missing include folder. We will create a modified version of phpize and php-config which will use the includes from the macOS SDK. First we will copy phpize and php-config and then we will modify these copies with a patch.
We create a new folder in your home directory under /Users/YOUR-USERNAME with the name "php-private"..
mkdir ~/php-private/
Now copy phpize and php-config to php-private
cp /usr/bin/phpize ~/php-private/ cp /usr/bin/php-config ~/php-private/
Now determine which PHP version is installed on your system by executing
grep version= ~/php-private/php-config
You should get something like this
version="7.3.11"
I have prepared two patches to simplify the process. Download the two files and save them in your Downloads folder.
Download the phpize patch phpize-catalina.patch.zip and save it. The contents of the patch file for reference:
--- /usr/bin/phpize 2019-09-11 02:46:18.000000000 +0200 +++ ./phpize 2019-12-26 23:10:32.000000000 +0100 @@ -1,11 +1,12 @@ #!/bin/sh
+XCODE_SDK_ROOT=$(/usr/bin/xcrun --show-sdk-path)
prefix='/usr'
datarootdir='/usr/php'
exec_prefix="eval echo ${prefix}"
phpdir="eval echo ${exec_prefix}/lib/php/build"
-includedir="eval echo ${prefix}/include/php"
+includedir="eval echo ${XCODE_SDK_ROOT}${prefix}/include/php"
builddir="pwd"
SED="/usr/bin/sed"
For PHP 7.3.9 Download the php-config patch php-config-7.3.9-catalina.patch.zip and save it.
For PHP 7.3.11 Download the php-config patch php-config-7.3.11-catalina.patch.zip and save it.
The contents of the patch file for reference:
--- /usr/bin/php-config 2019-09-11 02:48:43.000000000 +0200 +++ ./php-config 2019-12-26 23:10:19.000000000 +0100 @@ -1,12 +1,14 @@ #! /bin/sh
+XCODE_SDK_ROOT=$(/usr/bin/xcrun --show-sdk-path) + SED="/usr/bin/sed" prefix="/usr" datarootdir="/usr/php" exec_prefix="${prefix}" version="7.3.9" vernum="70309" -include_dir="${prefix}/include/php" +include_dir="${XCODE_SDK_ROOT}${prefix}/include/php" includes="-I$include_dir -I$include_dir/main -I$include_dir/TSRM -I$include_dir/Zend -I$include_dir/ext -I$include_dir/ext/date/lib" ldflags=" -L$SDKROOT/usr/lib -L$SDKROOT/usr/local/libressl/lib -L/usr/local/lib" libs="-lresolv -lcrypto -lssl -lcrypto -lexslt -ltidy -lresolv -ledit -lncurses -lpq -lpq -lldap -llber -liconv -liconv -lpng -lz -ljpeg -lcrypto -lssl -lcrypto -lbz2 -lz -lcrypto -lssl -lcrypto -lm -lxml2 -lz -licucore -lm -lkrb5 -lcurl -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lnetsnmp -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxml2 -lz -licucore -lm -lxslt -lxml2 -lz -licucore -lm "
Extract the compressed patch files.
PHP 7.3.9:
unzip ~/Downloads/phpize-catalina.patch.zip -d ~/Downloads/ unzip ~/Downloads/php-config-7.3.9-catalina.patch.zip -d ~/Downloads/
PHP 7.3.11:
unzip ~/Downloads/phpize-catalina.patch.zip -d ~/Downloads/ unzip ~/Downloads/php-config-7.3.11-catalina.patch.zip -d ~/Downloads/
Now we patching our copy of phpize and php-config
PHP 7.3.9:
patch ~/php-private/phpize < ~/Downloads/phpize-catalina.patch patch ~/php-private/php-config < ~/Downloads/php-config-7.3.9-catalina.patch
PHP 7.3.11:
patch ~/php-private/phpize < ~/Downloads/phpize-catalina.patch patch ~/php-private/php-config < ~/Downloads/php-config-7.3.11-catalina.patch
We are ready to compile xdebug
Create a working directory in your home folder. We will build xdebug here
mkdir ~/xdebug-install
Download xdebug from Xdebug.org and save in under Downloads.
Copy the archive to the working directory and extract it.
cp ~/Downloads/xdebug-2.9.0.tgz ~/xdebug-install cd ~/xdebug-install tar -xvzf xdebug-2.9.0.tgz cd xdebug-2.9.0
Now, we run our patched phpize in the xdebug folder.
~/php-private/phpize
When everything went good, you get something like this:
Configuring for: PHP Api Version: 20180731 Zend Module Api No: 20180731 Zend Extension Api No: 320180731
If so, you can skip the next part and continue with configuring and installing Xdebug.
Errors like these means, you need to install some requirements.
Configuring for: PHP Api Version: 20180731 Zend Module Api No: 20180731 Zend Extension Api No: 320180731 Cannot find autoconf. Please check your autoconf installation and the $PHP_AUTOCONF environment variable. Then, rerun this script.
If phpize prints lines like these, you need to install autoconf:
Cannot find autoconf. Please check your autoconf installation and the $PHP_AUTOCONF environment variable. Then, rerun this script.
To install autoconf, execute the following commands:
#change back to our working directory cd ~/xdebug-install
#dowload autoconf curl -OL http://ftpmirror.gnu.org/autoconf/autoconf-2.69.tar.gz
#extract it, and change into the folder tar xzf autoconf-2.69.tar.gz cd autoconf-2.69
#now build and install it ./configure --prefix=/usr/local make sudo make install
#change back to the xdebug folder cd .. cd xdebug-2.9.0
Now run our patched phpize in the xdebug folder again.
~/php-private/phpize
Check the output, and if everything went good, continue.
Configuring for: PHP Api Version: 20180731 Zend Module Api No: 20180731 Zend Extension Api No: 320180731
Configure and build xdebug: Now we will find the full path to our patched php-config. This can be done like this:
echo ~/php-private/php-config
The output will something like:
/Users/YOUR-USERNAME/php-private/php-config
Replace "/Users/YOUR-USERNAME/php-private/php-config" with the output of the above command and configure xdebug by executing:
./configure --enable-xdebug --with-php-config=/Users/YOUR-USERNAME/php-private/php-config
In the output of configure you will see that the SDK path is being used:
... checking for PHP prefix... /usr checking for PHP includes... -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/main -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/TSRM -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/Zend -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/ext -I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php/ext/date/lib checking for PHP extension directory... /usr/lib/php/extensions/no-debug-non-zts-20180731 checking for PHP installed headers prefix... /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/php checking if debug is enabled... no ...
Now build the extension
make
We don't executing "make install" to install xdebug.so because the macOS System Integrity Protection (SIP) will not allow us to install xdebug to the /usr/lib/extensions folder. To workaround this, we install the extension under the /usr/local folder.
sudo mkdir -p /usr/local/php/extensions sudo cp modules/xdebug.so /usr/local/php/extensions
Now edit your php.ini (usually under /etc/php.ini) to load the right xdebug. PHP searches for extensions in its default extension directory. Our xdebug resides outside of this directory, so we have to specify the full path:
zend_extension=/usr/local/php/extensions/xdebug.so
To test it, execute:
php -i | grep xdebug
The output should begin like this:
xdebug xdebug support => enabled ....
Restart your apache web server to activate your changes
sudo apachectl restart