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