1. Overview.

This document is intended for Linux developers. If you notice mistakes, write to: oldcoder@yahoo.com

Gearman is a message queue framework that makes it easier for an application to implement distributed processing. The framework is believed to be reasonably stable. As a related note, it has been used by large ventures such as Digg, LiveJournal, and Yahoo.

This document explains how I got Gearman to work on a Debian (Ubuntu) system. Note: All steps were done as superuser except where otherwise indicated.

The procedure used may or may not work for newer releases of Debian and/or Ubuntu. However, it's discussed here in the hope that it may be useful.





2. Building Gearman core.

2.1. I started with a Debian (Ubuntu) machine that I'd configured as a development system previously.

For the Debian setup steps that I used, or reasonably compatible steps, click here.

I wasn't able to get prebuilt copies of Gearman to work. So I built the framework myself.

2.2. I removed all traces of existing copies of Gearman from the system. The procedure used for this step is beyond the scope of this discussion.

2.3. I installed some standard Ubuntu packages:


apt-get install libboost-dev
apt-get install libboost-thread-dev
apt-get install libboost-program-options-dev
apt-get install libcloog-ppl0

2.4. I went to a downloads directory and downloaded a current Gearman core source tarball using the link below. This copy of the link goes to a local copy of the tarball. Therefore it should work:

https://launchpad.net/gearmand/1.2/1.1.3/\
+download/gearmand-1.1.3.tar.gz

2.5. I unpacked the source tarball and entered the top-level source directory:


tar zxf gearmand-1.1.3.tar.gz
cd      gearmand-1.1.3

2.6. I found that a patch was necessary. So I created and applied one. The patch file is provided below:

gearmand-configmake-opt.txt

2.7. I configured, built, and installed the associated software:


sh ./configure \
    --prefix=/opt \
    --disable-libpq \
    --enable-shared=yes \
    --enable-static=no \
    --mandir=/opt/man

make && make install

2.8. I started the gearmand daemon, verified that startup was successful, and terminated the daemon:


/opt/sbin/gearmand -d --verbose INFO
tail /opt/var/log/gearmand.log 
killall -SIGTERM gearmand

2.9. I edited the file /etc/rc.local (which already existed) and inserted the following code before the exit 0 line that I found there:


/opt/sbin/gearmand -d

2.10. I made sure that /etc/rc.local was executable, rebooted the system, and verified that the new daemon was running:


chmod 755 /etc/rc.local
shutdown -r now
# System should reboot at this point
ps ax | grep gearmand

At this point, installation of the Gearman core was believed to be completed.





3. Building Gearman PECL extension.

The next goal was to build a Gearman PECL extension. This was a software component from a repository known as PECL that added support for Gearman to both CGI and CLI versions of PHP.

3.1. I went to a downloads directory and downloaded a current Gearman PECL source tarball using the link below. This copy of the link goes to a local copy of the tarball. Therefore it should work:

http://pecl.php.net/get/gearman-1.1.0.tgz

3.2. I unpacked the source tarball and entered the top-level source directory:


tar zxf gearman-1.1.0.tgz
cd      gearman-1.1.0

3.3. I executed the following PECL-related configuration command:


phpize

3.4. I found that a patch was necessary. So I created and applied one. The patch file is provided below:

gearman-pecl-configure.txt

3.5. I configured, built, and installed the associated software:


./configure
make && make install

3.6. I edited the following two PHP configuration files:


/etc/php5/cgi/php.ini
/etc/php5/cli/php.ini

and added this line to each file at the appropriate location:


extension=gearman.so

At this point, Gearman PECL installation was believed to be completed.





4. Testing the PECL extension.

The next goal was to test the Gearman PECL extension.

4.1. I created a PHP script named testgearpecl.php that contained the following code:


<?php print gearman_version() . "\n"; ?>

4.2. I executed the script using: php testgearpecl.php

testgearpecl.php printed a release number, 1.1.3 in this case. This confirmed that the PECL interface to Gearman was working.

4.3. I created a PHP script named testgearworker.php that contained the following code:


<?php
$worker= new GearmanWorker();
$worker->addServer();
$worker->addFunction ("reverse", "mytest");
while ($worker->work()) {}
function mytest ($job) { return strrev ($job->workload()); }
?>

4.4. I created a PHP script named testgearclient.php that contained the following code:


<?php
$client = new GearmanClient();
$client->addServer();
print $client->do ("reverse", "Hello World!") . "\n";
?>

4.5. I started testgearworker.php as a background job and ran testgearclient.php in the foreground:


php testgearworker.php < /dev/null &
php testgearclient.php

testgearclient.php printed: !dlroW olleH

This tested PHP support for Gearman further. The !dlroW olleH output confirmed that things were working.

Note: The /dev/null redirection shown here was needed for background operation to work correctly.





5. Gearman MySQL UDF.

The next goal was to build the Gearman MySQL UDF (User Defined Functions) library. It “allows you to run Gearman client jobs from within MySQL”. The library is needed by Shard Query, a sharding framework that leverages both MySQL Proxy and Gearman, but not much information is available about it.

5.1. I started with a Debian (Ubuntu) machine that I'd configured as a development system previously.

For the Debian setup steps that I used, or reasonably compatible steps, click here.

5.2. I went to a downloads directory and downloaded a current Gearman MySQL UDF source tarball using the link below. This copy of the link goes to a local copy of the tarball. Therefore it should work:

https://launchpad.net/gearman-mysql-udf/trunk/0.6/\
+download/gearman-mysql-udf-0.6.tar.gz

5.3. I unpacked the source tarball and entered the top-level source directory:


tar zxf gearman-mysql-udf-0.6.tar.gz
cd      gearman-mysql-udf-0.6

5.4. I configured, built, and installed the associated software:


sh ./configure \
    --prefix=/opt \
    --enable-shared=yes \
    --enable-static=no \
    --mandir=/opt/man

make && make install

At this point, installation of Gearman MySQL UDF was believed to be completed.





6. Adding Gearman PEAR extension.

The next goal was to add a Gearman PEAR extension. This was a software component from a repository known as PEAR that added more support for Gearman to both CGI and CLI versions of PHP.

6.1. I went to a downloads directory and downloaded a current Gearman PEAR source tarball using the link below. This copy of the link goes to a local copy of the tarball. Therefore it should work:

http://download.pear.php.net/package/Net_Gearman-0.2.3.tgz

6.2. I unpacked the source tarball and entered the top-level source directory:


tar zxf Net_Gearman-0.2.3.tgz
cd      Net_Gearman-0.2.3

6.3. I copied one of the directory trees provided into place on the system:


mkdir -p    /usr/share/php/Net
cp -a Net/* /usr/share/php/Net/

At this point, installation of the extension was believed to be completed.





For acknowledgments related to CSS and other code used, click here.

Linked or embedded works (software, books, articles, etc.) are presented under their own licenses.

Other unique content on this page, excluding screenshots, is distributed under the following license: C.C. Attribution NonCommercial ShareAlike 3.0. In some cases, screenshots are distributed under the same license. In other cases, the associated program's license applies.

image Valid XHTML 1.0