Askeet! Diary - Day 1
December 18th, 2005
Lets do this tutorial on a Mac
Getting Started
The tutorial assumes that we have Apache, MySQL and PHP 5 installed. Apple installs Apache with the default Mac OS X installation, so we don’t need to do anything except turn it on. You can do this by starting “Personal Web Sharing” in the “Sharing” System Preference window. Day 1 of the tutorial doesn’t use MySQL, so let’s skip it for now and deal with it later.
Install PHP 5
Apple ships PHP 4 with the default installation, and it’s not even turned on by default. We’ll need to install PHP 5. The easy thing to do here is get the pre-compiled package from Marc Liyanage from this page. [As a small aside, Marc has done absolutely fabulous job of maintaining and distributing PHP for Mac OS X for quite some time now. Thank You Marc.] I downloaded version 5.0.4 release 1, mounted the disk image, and installed the package. The installer make the necessary modification to the Apache configuration, so you don’t need to do anything extra to get it to run under Apache. However, the installer does the smart and safe thing by not deleting any PHP 4 files just in case you need to reinstate them later. While this is the smart and safe thing to do, it poses a few obstacles for us.
Setup PEAR
The first step of the tutorial asks us to upgrade PEAR. [PEAR is a set of extensions to PHP. It's become so useful that it has been included with PHP 5 and later versions of 4. You can read more about PEAR here.] Upgrading PEAR makes use of the PHP command line binary, and needs version 5 to upgrade to the latest version of PEAR, the problem here is that we actually have 2 instances of PHP installed and the the PHP 5 version is not installed in the default location the PEAR expects it to be in. We need to do a few things to get everything in place.
First lets get the PHP 5 CLI in place. The default binary is at /usr/bin/php. Go ahead and move the PHP 4 CLI. Don’t forget to root up first.
$ sudo -s
$ mv /usr/bin/php /usr/bin/php4
$ ln -s /usr/local/php5/bin/php /usr/bin/php
This moves the old PHP 4 CLI and then makes a symbolic link to the new PHP 5 version. The symbolic link allows any program or user that invokes the php tool from the terminal to use the new version.
Before we can upgrade PEAR, we need to modify the PEAR configuration. You see, PEAR installs a bunch of libraries and components to your hard drive and makes them available to PHP, but since we have two instances of PHP with version 5 being installed in the non default location, upgrading PEAR now will upgrade the PEAR files for the PHP 4 installation, and not the PHP 5 installation. The PHP 5 files are located at /usr/local/php5/ instead of /usr/lib/php. Feel free to inspect your current PEAR configuration with $ pear config-show.
Let’s set the new configuration parameters.
$ pear config-set bin_dir /usr/local/php5/bin/
$ pear config-set doc_dir /usr/local/php5/lib/php/doc/
$ pear config-set php_dir /usr/local/php5/lib/php/
$ pear config-set data_dir /usr/local/php5/lib/php/data
$ pear config-set php_bin /usr/local/php5/bin/php
$ pear config-set test_dir /usr/local/php5/lib/php/test
OK, your ready to upgrade PEAR. Do a $ pear upgrade pear. Did you get an error message? All that means is that in order to upgrade pear you first need to upgrade the required package. You might be asking “What package? Where do I get it from?” PEAR is pretty much self updating and self sustaining. Remember how you just told PEAR to upgrade itself? Just tell PEAR to upgrade to the required package.
$ pear upgrade Archive_Tar
Upgrade PEAR and you should see something like this:
$ pear upgrade pear
downloading PEAR-1.4.5.tgz ...
Starting to download PEAR-1.4.5.tgz (277,491 bytes)
.........................................................done: 277,491 bytes
Optional dependencies:
package `XML_RPC' version >= 1.4.0 is recommended to utilize some features. Installed version is 1.2.2
package `PEAR_Frontend_Web' version >= 0.5.0 is recommended to utilize some features.
package `PEAR_Frontend_Gtk' version >= 0.4.0 is recommended to utilize some features.
upgrade ok: PEAR 1.4.5
PEAR upgraded to version 1.4.5 OK. Those optional dependancies might be worth upgrading too, but we’ve covered PEAR enough for now, so let’s skip it and move on. [I did $ pear upgrade XML_RPC though. XML_RPC is pretty heavily used these days, and it's probably a wise choice to have that around too. I skipped the other two packages because since they are just alternative interfaces to PEAR package management, and they have there own dependancies and complications. We can always install them later if we need/want.]
[The funny thing is now you have 2 instances of PEAR installed. One at the default location of /usr/bin and the new one in /usr/local/php5/bin/. Check it out. $ pear info pear shows you the version installed is 1.3.5, but you just successfully upgraded to 1.4.5. Maybe you didn't. Trying to upgrade PEAR again fails and tells you you already the most recent version. Honestly, don't worry about it, just be aware of it in case it comes back to haunt us.]
Moving on with the actual tutorial
Install Symfony
like the tutorial says:
$ pear channel-discover pear.symfony-project.com
$ pear install symfony/symfony-beta
$ pear install http://phing.info/pear/phing-current.tgz
All run without a hitch.
$ symfony -V gives us an error because the command line has no idea that we’ve stuck a bunch programs in /usr/local/php5/bin/.
A Quick Fix
You just need to add /usr/local/php5/bin/ to the $PATH variable. There’s plenty of info on how to do this on the Web, but in case you have no idea what I’m talking about, just do the following:
$ pico ~/.profile opens your profile configuration file in a terminal based text editor. On the line that reads “PATH=$PATH:/usr/local/bin” add “:/usr/local/php5/bin” without the quotes. Hit ctr+x, hit y to save the modified file, and then hit enter to save the modified version of the file in the same place as it was in. Close out of the terminal and open a new shell window. $ symfony -V should now give you its version number.
Project Setup
Move on with the tutorial, but feel free to put your version on the project somewhere other than /home/sfprojects/askeet. [I put mine in /Users/username/Projects/webDevelopment/askeet, maybe a better place would be /Library/WebServer/askeet, but it’s really up to you and your preferences. Just remember to use the path you chose instead of /home/sfprojects/askeet whenever the example does.
Web service setup
For this section , you only need to do 2 things differently than in the tutorial.
1. Don’t forget to use the path you chose instead of /home/sfprojects/askeet.
2. When editing httpd.conf we have to use Alias /sf /usr/local/php5/lib/php/data/symfony/web/sf since our Symfony installation is not in the same place as theirs.
Subversion
WHAT? That damn tutorial never said anything about Subversion. Now they just assume I have it installed or access to it or even that I know how to use it. Source control is like seat belts, you’re probably OK never using it, but that one time you need it, it will save your life. I was tempted to just blow this off, but I know it’s important, and in the spirit of learning let’s go for it.
We’ve covered a lot of ground so far, and this was only supposed to take an hour. Now would be a good time to take a break before we tackle the topic of Subversion.
What is Source Control?
Quite simply source control is a way to keep track of different version of files. For example you’re working on project and modify a file. Three days later you you make some more changes. The next day you decide the work you did was crap, and you want to undo all that work, but you you don’t have a copy of that file. You could manually copy files into folders and date them and try to do this all by yourself, but that’s really a waste of time. Besides what happens when 2 or more people are working on the same project, and they both end up making changes to the same file? Something like Subversion, CVS, or even Source Safe really helps manage this problem. Some basic source control commands are make new project, get project files, submit my changes, and compare the differences between my local copy and the remote master copy.
Installing Subversion
Apple doesn’t ship subversion with Mac OS X, and like PPH & PEAR, we could download the source and compile it ourself using the compliers that come with Xcode. But why go through all that when you can just download a package and install it. You can get a package from this page. I downloaded version 1.2.3.
The first Subversion command in the askeet! tutorial is to create a new project.
$ svnadmin create $SVNREP_DIR/askeet
They use $SVNREP_DIR environment variable. Much like $PATH that we discussed earlier, every time you use $SVNREP_DIR it would point you to the root Subversion folder. By default Mac OS X doesn’t have a $SVNREP_DIR variable set. You could either set up a $SVNREP_DIR value just for yourself, or for all users of the workstation. Just add “SVNREP_DIR=/PathToSubversionDirectory” to either ~/.profile or /etc/profile. A good place for the folder is /SVN. Once again, after setting the value, close out of terminal windows and start New Shell window to use the new variable.
Setup the Repository for askeet!
Create a new repository for the askeet project just as the tutorial states.
$ svnadmin create $SVNREP_DIR/askeet
$ svn mkdir -m "layout creation" file:///$SVNREP_DIR/askeet/trunk file:///$SVNREP_DIR/askeet/tags file:///$SVNREP_DIR/askeet/branches
On the next step, remember to go to the directory you used for you project, and not the one the tutorial shows.
The tricky part here is when you get to the part instructing Subversion to ignore the cache and log directories.
$ svn propedit svn:ignore cache opens the default text editor configured for SVN. The default text editor is VIM. I’ve never used VIM before so I had no idea what I was doing. Here’s the 30 second tutorial. You’re in command mode. Hit i to enter editing mode. Type *. Hit esc to go back to command mode. Hit ZZ (that’s shift+z twice) to save the file and quit. You’ll have to do this twice. Once for cache and again for log.
That’s pretty much it. Everything else in the tutorial should work as is.
OK PENCILS DOWN!
The tutorial took me about 3 hours to complete instead of 1. If you followed along, I probably saved you about an hour or more.
All in all, I’ve learned a lot. I was exposed to a few UNIX concepts, a few PEAR concepts, some Apache configuration, some basic Subversion commands, and I even had to use the intimidating VIM for the first time. If your anywhere as overwhelmed as I am by all this you probably need a day or two off from this to let it all sink in.
a little thank you
I’d like to say thanks to Brian Ibbott of Coverville and Michael Butler of The Rock and Roll Geek Show for providing me with some tunes while I was working.