This page is still a work in progress. There are still some bugs with this setup that I'm working on ironing out. Hopefully it will be ready for others to try out soon. Until then, caveat emptor!
This page is a step-by-step set of instructions for setting up a CiviCRM dev environment on Mac OS X using MacPorts. Once complete, you'll be able to run the testing suite and debug the source code. This puts you in a much better position to start making changes to CiviCRM vs. the hack-and-pray model.
- If you don't already have MacPorts installed, skip to the next step. If you do have it installed already, make sure it's up to date. I'm assuming you have MacPorts 1.8.0 with a recent ports tree, which is a very recent release as of this writing (it came out in late August, 2009). Here's how you update your MacPorts installation:
Now you can skip to the next section, "Install the AMP stack."
- MacPorts requires that you have the Apple Developer Tools installed on your Mac. This is an "Optional Install" on the Mac OS X installation DVD, or you can download them from the Apple Developer Connection website. After you login with your Apple ID, the Downloads link will become active. Click that and then grab the appropriate Xcode download for your version of OS X.
- Go here: http://www.macports.org/install.php and download the appropriate MacPorts .dmg disk image for your version of OS X (i.e. 10.6/Snow Leopard, 10.5/Leopard, or 10.4/Tiger; earlier versions are not supported, sorry).
- Install MacPorts from the disk image. This works just like installing any other piece of software on your Mac. I'm going to assume you can handle that.
- Make sure it's working by launching a Terminal (or iTerm, which is way cooler, IMO) window and running "port search php5". If you get "bash: port: command not found" instead of a list of PHP-related ports, then something went wrong with your MacPorts installation. Look into the help resources available on their website.
|Is your port command hiding?|
One common error is to have a Terminal/iTerm window open while you run the MacPorts installer. The shell in that terminal session won't yet have had a chance to grab the new PATH setting, so it will act like the port command isn't there. Try running this to see if that's the case:
If that works, just quit and re-launch your terminal app.
Install the AMP stack
- AMP refers to Apache, MySQL, and PHP. When you run it on Linux, you have a LAMP server. When you run it on Mac, it's called MAMP (which is less fun to say).
- Run the command below. It will take awhile to complete.
- Now let's enable PHP in our Apache configuration.
- Setup MySQL
- the last command creates a my.cnf file you can edit and that will be loaded when you start mysql. This is particularly important because the default max_packet_size setting is 1M, which is quite low. You can also copy the my-huge.cnf, my-medium.cnf, my-small.cnf or my-innodb-heavy-4G.cnf depending on your set-up (read the individual file's comment to decide what's best for your machine).
- I've set this all up to not start automatically on boot, because I don't want a full AMP stack running in the background when I'm watching Buffy the Vampire Slayer on DVD. If you like mixing your vamps with your open-source web app platforms, then MacPorts provides facilities for getting these to start on their own. For the rest of us, here's what you run to start this up on a subsequent reboot:
# You may want to put that into a handy script in your home directory:
Then you can just do:
# Go ahead and (re)start Apache and MySQL at this point using one of the suggestions above.
- Phing is a project build utility that is based on Apache Ant. CiviCRM's test suite uses it to generate fun things like fancy test result & code coverage reports. You can view the official reports http://tests.dev.civicrm.org/results/ and http://tests.dev.civicrm.org/coverage/, so if you don't want to generate your own, you can skip this section. It's quick and easy though, and you know you want to increase your killing code coverage chart generating power.
- Still here? Excellent. Just run these commands for Phing-y goodness:
h3. Install CiviCRM from Subversion
- You may already have a full checkout of the CiviCRM source from Subversion. If that's the case, give yourself a gold star and skip to the next section.
- Don't have an SVN checkout? That's OK, let's snag you one. Mac OS X comes with Subversion, but sometimes it's old and busted. Let's start by getting some new hotness:
# Checkout the CiviCRM source and get it up and running. You can follow the existing instructions for that here.
|Some important file locations for your CiviCRM installation|
In a typical MacPorts installation of MySQL, your MySQL socket file will live here:
And your mysql path will be:
- NetBeans is a handy IDE (integrated development environment) for CiviCRM because it works so well with the Xdebug PHP extension. This lets you do things like set breakpoints and step through your code. You can then inspect the value of any in-scope variables as you step through the code and determine exactly where, when, and hopefully why something is not working the way you expect. The amount of time this will save you when hunting down bugs in CiviCRM code is immeasurable. I highly recommend taking the time to become familiar with this or another PHP debugging setup if you want to work on custom CiviCRM code.
- Go here: http://www.netbeans.org/downloads/index.html and download the PHP version (you can add the PHP components later if you get a different version).
- Run the NetBeans installer. Again, nothing out of the ordinary here. Just the standard Mac installation humdrum. Don't worry, we'll have some exciting times soon.
- Run NetBeans and open your CiviCRM source directory as a new project with existing sources. Open a couple PHP files in the CiviCRM source and notice the pretty syntax highlighting NetBeans is doing. Schmancy!
- If you don't like NetBeans as a code editor, you can continue using whatever else you prefer. NetBeans will still happily debug your code even though you stood it up at the text editing prom. It won't even cry.
An alternate debugger for the OS X platform is MacGDBp. Its lightweight as its just a debugger, and pretty much works without any additional configuration.
- Xdebug is a PHP debugging & profiling extension. It forms one half of your PHP debugging & profiling environment (NetBeans & Webgrind are the other halves, respectively). When you start a debugging session in NetBeans, it will launch a web browser to access your CiviCRM installation via the local AMP stack we installed earlier. It will pass a query parameter that tells Xdebug to call it back when it's ready. NetBeans then listens for that connection from Xdebug. All that buck-passing can make it hard to get NetBeans & Xdebug playing nicely together, so let's make sure it's all setup to run when we tell NetBeans to debug some PHP code.
- Run these commands:
You might also try replacing the debug.remote_enable statement value with '1' instead of 'on'.
- Webgrind is a profiling tool to see how your code is performing. It shows you what parts of the CiviCRM codebase are getting called most often, as well as which parts take the longest time to execute. For any given workflow, you can see what sections of the code the system is spending most of its time in and thus have a very good idea of how you should prioritize your optimization efforts. A good code profiler is an indispensable tool in any programmer's toolbox.
- Webgrind is relatively new (as of Sept. 16, 2009 it's at version 1.0), so some features may be missing or incomplete compared to more mature offerings such as kcachegrind (which can be installed via MacPorts). But Webgrind looks great, is dead simple, and runs in your web browser. I kind of <3 it.
- Holy crap let's install this thing already! Download the latest version from here: http://code.google.com/p/webgrind/
- Extract it to your local CiviCRM installation. You can put it in the tools/ directory to keep things tidy.
- Then browse to your CiviCRM instance with the following query parameter tacked onto the URL: XDEBUG_PROFILE. So if you access the dashboard page on a standalone install, you'd want something like the following:
- Now access your Webgrind installation via another tab in your web browser. For the same standalone example above, that might be something like this: http://localhost/civicrm/tools/webgrind/
- That's it! You should now see the profile of the execution that rendered the dashboard.
- Probably you want to profile more interesting things. Just execute whatever workflow you're interested in profiling in CiviCRM like you normally would but make sure that "XDEBUG_PROFILE" query parameter stays on there. When you're ready to see the results, go back to your Webgrind tab in your browser and click the Update button in the upper-right corner of the page.