Skip to content

Instantly share code, notes, and snippets.

@Sarfarazsajjad

Sarfarazsajjad/installing-xdebug-on-catalina.md

Created July 9, 2020 09:30
Show Gist options
  • Save Sarfarazsajjad/3c04592a0403299297665979e68918cd to your computer and use it in GitHub Desktop.
Save Sarfarazsajjad/3c04592a0403299297665979e68918cd to your computer and use it in GitHub Desktop.
Download ZIP
Raw
installing-xdebug-on-catalina.md

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

include <tsrm_config.h>

      ^~~~~~~~~~~~~~~
      "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

Variable declaration

+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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment