docs/compile-svn.txt

   1 SVN 0.2 PECL Extension for PHP        <http://pecl.php.net/package/svn/0.2>
   2 ---------------------------------------------------------------------------
   3
   4 It took me two days to figure out how to compile the PECL extension
   5 'svn' for PHP5 on Dreamhost. It's not difficult, but it's not a walk
   6 in the park. There are lots of dependencies.
   7
   8 These instructions can be applied to other hosting environments where
   9 shell is allowed, although the dependencies will change. Be sure to
  10 do the necessary research before plowing ahead. The instructions here
  11 are specific to Dreamhost's server configurations.
  12
  13 == Dependencies ==
  14
  15 Before you embark, you'll want to add $HOME/bin to your $PATH variable
  16 in .bash_profile:
  17
  18     PATH=$HOME/bin:$PATH
  19
  20 If you've previously installed your own libraries or executables, this
  21 step may have already been done. You may also want to consider using
  22 a prefix directory that is not your $HOME directory, in that case,
  23 specify the directory in some other variable and replace all instances
  24 of $HOME below with that variable.
  25
  26 === Autoconf (2.61) ===
  27
  28 A very useful tool, and also one that Dreamhost doesn't have. This
  29 particular PECL package will need it, so download the source
  30 code from GNU's website, unpack it, and then install.
  31
  32     wget http://mirrors.kernel.org/gnu/autoconf/autoconf-2.61.tar.gz
  33     tar -xzf autoconf-2.61.tar.gz
  34     cd autoconf-2.61
  35     ./configure --prefix=$HOME
  36     make
  37     make install
  38
  39 === Subversion (1.4.3) ===
  40
  41 Dreamhost comes with `svn` installed, however, it does not provide the
  42 necessary includes and headers necessary to compile our extension. Best
  43 to install your own version.
  44
  45 Subversion, itself, has oodles of dependencies, but the Subversion
  46 developers have been so kind to provide an subversion-deps-x.y.z.tar.gz
  47 file on the downloads page. Download this file and the main source
  48 code file. Run in the newly created subversion-x.y.z/ directory:
  49
  50     wget http://subversion.tigris.org/downloads/subversion-1.4.3.tar.gz
  51     wget http://subversion.tigris.org/downloads/subversion-deps-1.4.3.tar.gz
  52     tar -xzf subversion-1.4.3.tar.gz
  53     tar -xzf subversion-deps-1.4.3.tar.gz
  54     cd subversion-1.4.3
  55     ./configure --prefix=$HOME
  56     make
  57     make install
  58
  59 This should do the installation, with all the dependencies. Subversion
  60 will recursively configure and make all of Subversion's dependencies.
  61
  62 == PHP (5.2.1) ===
  63
  64 Once again, Dreamhost comes with `php` installed. It even has `php5`
  65 installed. However, the `phpize` it has installed is out-of-date and
  66 will not work for PHP5 websites, so you'll need to install your own
  67 local copy. (If you're using PHP4, using the default may work).
  68
  69 Download the PHP source code that synchronizes with the version
  70 Dreamhost is running (for my case, it was 5.2.1, you can check using
  71 `php -v` or `php5 -v`). Do the standard kaboodle:
  72
  73     wget http://us3.php.net/get/php-5.2.1.tar.gz/from/this/mirror
  74     tar -xzf php-5.2.1.tar.gz
  75     cd php-5.2.1
  76     mkdir $HOME/local-php
  77     ./configure --prefix=$HOME/local-php
  78     make
  79     make install
  80
  81 We don't care about compiling the extensions because all we're after is
  82 phpize. Furthermore, we're not installing it into a directory that's
  83 in our path ($HOME/bin v. $HOME/local-php/bin) because we don't want
  84 this installation to supplant Dreamhost's own version of PHP (you may
  85 have command line scripts that rely on Dreamhost's specific version.)
  86 If you're using an alias:
  87
  88     alias php="/usr/local/dh/cgi-system/php5.cgi"
  89
  90 In order to overload calls to `php` with the PHP5 binary, this procedure
  91 is not strictly necessary, but it doesn't hurt to play it safe.
  92
  93 == Installation ==
  94
  95 Finally, we can install the PECL extension. We will download the source
  96 code, set up the environment with phpize, run autoconf to set up the
  97 configuration, and then do the standard configuration kaboodle, but
  98 without `make install`. Sound confusing? It is.
  99
 100     wget http://pecl.php.net/get/svn-0.2.tgz
 101     tar -xzf svn-0.2.tgz
 102     cd svn-0.2
 103
 104 Standard procedures. No surprises here.
 105
 106     autoconf
 107
 108 The developers of svn have been so kind not to provide a configure.sh
 109 script. So we'll use autoconf to generate it. `phpize` also seems to
 110 have trouble finding the autoconf binary, so lets make life easy for
 111 them.
 112
 113     $HOME/local-php/bin/phpize
 114
 115 Alright, we're calling phpize to setup the environment. However, you'll
 116 notice that we didn't call `phpize`, but we called the full path. This
 117 is essential to make sure we're calling the *right* binary. For PHP 5.2.1,
 118 you should see this in the output:
 119
 120 Configuring for:
 121 PHP Api Version:         20041225
 122 Zend Module Api No:      20060613
 123 Zend Extension Api No:   220060519
 124
 125 If you went against my advice and added $HOME/local-php/bin to the path,
 126 you might be able to get away with calling only `phpize`. Be sure to
 127 check the numbers though.
 128
 129     ./configure --with-svn=$HOME
 130
 131 This little gem took me two hours to figure out. Accept my hard-earned
 132 knowledge gratefully! The config.m4 file will not check your PATH for
 133 the necessary Subversion includes, so you will need to tell the configure
 134 script explicitly where to find your locally installed copy of Subversion
 135 (remember, Dreamhost's version does not contain the proper includes!)
 136 Also, although config.m4 seems to check the $PHP_SVN environment variable,
 137 it really doesn't. So don't try to use it.
 138
 139 Note that we didn't specify a prefix, that's because we're not going
 140 to make install.
 141
 142     make
 143
 144 Compile the extension. The prized 'svn.so' file will be in a newly
 145 created modules folder. Copy it over to somewhere easily accessible.
 146 You can now use your extension via:
 147
 148     dl('/path/to/svn.so');
 149
 150 That's it!
 151
 152 == And now... ==
 153
 154 Documentation for the SVN extension is woefully lame. Try these
 155 resources:
 156
 157 * http://www.edoceo.com/intmain/20060808-pecl-svn-package.php - lists
 158   the available functions, and some usage info.
 159 * http://cvs.php.net/viewvc.cgi/pecl/svn/svn.php?view=markup - test script
 160   for the extension, it offers some concrete usage examples. Don't run it
 161   though!
 162 * http://cvs.php.net/viewvc.cgi/pecl/svn/examples/ - more example scripts
 163 * http://svnbook.red-bean.com/en/1.2/svn.developer.usingapi.html -
 164   The Subversion Book's explanations of the APIs. Not PHP specific, but
 165   should give you some ideas for experimentation.
 166
 167 Some common pitfalls:
 168
 169 * To specify a repository URL on a local filesystem, you'll need to use
 170   the file:// schema.
 171 * If the SVN extension errors out, it will often result in an internal
 172   server error. I suspect the developers will want to rectify this sometime.
 173
 174 Cool stuff:
 175
 176 * http://www.akbkhome.com/blog.php/View/86/FlexySvn_A_subversion_browser_using_the_php_svn_bindings.html -
 177   The authors of the SVN extension also have hacked together FlexySVN,
 178   which is an XUL/Javascript/PHP based Subversion repository browser.
 179
 180 Credits (won't help you, but certainly helped me):
 181
 182 * http://livedocs.phpdoc.info/index.php?l=en&q=install.pecl - Contains
 183   instructions on how to install PECL extensions manually. I suppose
 184   this could have all been automated using `pecl`, but I didn't want
 185   to install it. :-P
 186 * http://svn.haxx.se/users/archive-2005-06/0383.shtml - The mailing list
 187   post that got things working for me.
 188
 189 I'll be working on more indepth documentation for the SVN extension as
 190 I stumble my way through it. Thanks for reading!