INSTALL

   1 Installation Instructions for APC
   2 ---------------------------------
   3
   4 This version of APC should work on PHP 4.3.0 - 4.4.x and
   5 5.1.0 - 5.2.x.  Yes, that means PHP 5.0.x is no longer
   6 supported.  Upgrade to PHP 5.1.x or 5.2.x and you will
   7 notice all sorts of performance increases.
   8
   9 CVS Instructions
  10 ----------------
  11 Building from CVS can be done like this:
  12
  13   cvs -d :pserver:cvsread@cvs.php.net:/repository login
  14   Password: phpfi
  15   cvs -d :pserver:cvsread@cvs.php.net:/repository co pecl/apc
  16   cd pecl/apc
  17   phpize
  18   ./configure --enable-apc-mmap --with-apxs --with-php-config=/usr/local/php/bin/php-config
  19   make
  20   make install
  21
  22 Suggested Configuration (in your php.ini file)
  23 ----------------------------------------------
  24   extension=apc.so
  25   apc.enabled=1
  26   apc.shm_segments=1
  27   apc.shm_size=128
  28   apc.ttl=7200
  29   apc.user_ttl=7200
  30   apc.num_files_hint=1024
  31   apc.mmap_file_mask=/tmp/apc.XXXXXX
  32   apc.enable_cli=1
  33
  34 These are fully described at the bottom of this file.
  35
  36 PHP 4 Optimization
  37 ------------------
  38 If you are trying to get every little bit of speed out of PHP4+APC, you need
  39 to tell APC where to find your httpd.h file and also add -DAPC_PHP4_STAT to
  40 your CPPFLAGS.  (if you don't have httpd.h, install the apache_dev package
  41 for your OS) and do:
  42   export CPPFLAGS="-I/usr/include/apache-1.3 -DAPC_PHP4_STAT" (for bash on Debian)
  43   setenv CPPFLAGS "-I/usr/include/apache-1.3 -DAPC_PHP4_STAT" (for tsch on Debian)
  44 and then re-run your configure script.
  45
  46 This optimization saves a stat syscall on the main script file.  In PHP5 this
  47 optimization is automatic and doesn't need any special build flags.
  48
  49 The second thing you are going to want to do to save another syscall is to
  50 compile using the --with-apxs configure switch.  This should work for both
  51 Apache1 and Apache2.  Point it directly at your apxs2 script for Apache2.
  52 eg. --with-apxs=/usr/local/bin/apxs2
  53
  54 +---------------------+
  55 | QUICK INSTALL (DSO) |
  56 +---------------------+
  57
  58 These instructions assume your PHP installation is located in /usr/local/php and you
  59 want Apache optimizations (--with-apxs).
  60
  61 $ gunzip -c apc_x.y.tar.gz | tar xf -
  62 $ cd apc_x.y
  63 $ /usr/local/php/bin/phpize
  64 $ ./configure --enable-apc --enable-apc-mmap --with-apxs --with-php-config=/usr/local/php/bin/php-config
  65 $ make
  66 $ make install
  67
  68 You will probably need to run the final command (make install) as root.
  69
  70 The above sequence of commands will install a .so file in your PHP
  71 installation extension directory. The output of make install should display
  72 that path to the screen.
  73
  74 Next you must edit your php.ini file, which is normally located in
  75 /usr/local/php/lib/php.ini, and add the following line:
  76
  77     extension="apc.so"
  78
  79 Replace "/path/to/php/extensions" with whatever path was displayed when you
  80 ran make install above.
  81
  82 Then restart your web server and consult the output of phpinfo(). If there is
  83 an informational section for APC, the installation was successful.
  84
  85 +------------------------+
  86 | QUICK INSTALL (Static) |
  87 +------------------------+
  88
  89 APC will not successfully compile on all systems as a DSO. If you run into
  90 problems using the DSO quick install, you can try to compile it statically
  91 into PHP. (The DSO install is recommended, though.)
  92
  93 These instructions assume the current directory is the root of the PHP source
  94 tree, and that you have already configured PHP by running its bundled
  95 configure script.
  96
  97 $ cd ext
  98 $ gunzip -c apc_x.y.tar.gz | tar xf -
  99 $ cd ..
 100 $ ./buildconf
 101 $ ./config.nice
 102 $ make
 103 $ make install
 104
 105 Once this is complete, simply restart your web server. You do not need to
 106 modify your php.ini file to enable APC.
 107
 108 +-----------------+
 109 | VERBOSE INSTALL |
 110 +-----------------+
 111
 112 These instructions assume your PHP installation is located in /usr/local/php.
 113
 114 1.  Unpack your distribution file.
 115
 116     You will have downloaded a file named something like apc_x.y.tar.gz.
 117     Unzip this file with a command like
 118
 119         gunzip apc_x.y.tar.gz
 120
 121     Next you have to untar it with
 122
 123         tar xvf apc_x.y.tar
 124
 125     This will create an apc_x.y directory. cd into this new directory:
 126
 127         cd apc_x.y
 128
 129 2.  Run phpize.
 130
 131     phpize is a script that should have been installed with PHP, and is
 132     normally located in /usr/local/php/bin assuming you installed PHP in
 133     /usr/local/php. (If you do not have the phpize script, you must reinstall
 134     PHP and be sure not to disable PEAR.)
 135
 136     Run the phpize command:
 137
 138         /usr/local/php/bin/phpize
 139
 140     Its output should resemble this:
 141
 142         autoheader: `config.h.in' is created
 143         You should update your `aclocal.m4' by running aclocal.
 144         Configuring for:
 145           PHP Api Version:   20020918
 146           Zend Module Api No:   20020429
 147           Zend Extension Api No:   20021010
 148
 149     phpize should create a configure script in the current directory. If you
 150     get errors instead, you might be missing some required development tools,
 151     such as autoconf or libtool. You can try downloading the latest versions
 152     of those tools and running phpize again.
 153
 154 3.  Run the configure script.
 155
 156     phpize creates a configure script. The only option you need to specify is
 157     the location of your php-config script:
 158
 159         ./configure --enable-apc
 160
 161     php-config should be located in the same directory as phpize.
 162
 163     If you prefer to use mmap instead of the default IPC shared memory support,
 164     add --enable-apc-mmap to your configure line.
 165
 166         If you prefer to use sysv IPC semaphores over the safer fcntl() locks, add
 167         --enable-sem to your configure line.  If you don't have a problem
 168         with your server segaulting, or any other unnatural accumulation of
 169         semaphores on your system, the semaphore based locking is slightly faster.
 170
 171 4.  Compile and install the files. Simply type: make install
 172
 173     (You may need to be root in order to install)
 174
 175     If you encounter errors from libtool or gcc during this step, please
 176     contact the project maintainer (dcowgill@php.net).
 177
 178 5.  Edit your php.ini
 179
 180     make install should have printed a line resembling the following:
 181
 182         Installing shared extensions: /path/to/extension/
 183
 184     Copy the path /path/to/extension/ and add the following line to your
 185     php.ini file (normally located in /usr/local/php/lib/php.ini):
 186
 187         extension="apc.so"
 188
 189     If you don't have a php.ini file in that location, you can create it now.
 190
 191 6.  Restart the web server and test the installation.
 192
 193     Restart your web server now (for apache, it's apachectl restart) and
 194     create a small test PHP file in your document root. The file should
 195     contain just the following line:
 196
 197         <?php phpinfo() ?>
 198
 199     Request that file in a web browser. If there is an entry for APC in the
 200     list of installed modules, the installation was successful.
 201
 202     If APC is not listed, consult your web server error log. If it contains an
 203     error message saying that it can't load the APC extension, your system
 204     might not be able to load shared libraries created with PHP's build
 205     system. One alternative would be to compile APC statically into PHP. See
 206     the Quick Install (Static) instructions above.
 207
 208     You should consult your error log anyway to see if APC generated any
 209     errors. On BSD-based platforms, it is typical for APC to be unable to
 210     allocate the default-sized shared memory segment. See below for hints on
 211     raising your system's shared memory limitations.
 212
 213 +-----------------+
 214 | CONFIGURING APC |
 215 +-----------------+
 216
 217 Although the default APC settings are fine for many installations, serious
 218 users should consider tuning the following parameters:
 219
 220     OPTION                  DESCRIPTION
 221     ------------------      --------------------------------------------------
 222     apc.enabled             This can be set to 0 to disable APC. This is
 223                             primarily useful when APC is statically compiled
 224                             into PHP, since there is no other way to disable
 225                             it (when compiled as a DSO, the zend_extension
 226                             line can just be commented-out).
 227                             (Default: 1)
 228
 229     apc.shm_segments        The number of shared memory segments to allocate
 230                             for the compiler cache. If APC is running out of
 231                             shared memory but you have already set
 232                             apc.shm_size as high as your system allows, you
 233                             can try raising this value.  Setting this to a
 234                             value other than 1 has no effect in mmap mode
 235                             since mmap'ed shm segments don't have size limits.
 236                             (Default: 1)
 237
 238     apc.shm_size            The size of each shared memory segment in MB.
 239                             By default, some systems (including most BSD
 240                             variants) have very low limits on the size of a
 241                             shared memory segment.
 242                             (Default: 30)
 243
 244     apc.optimization        This option has been deprecated.
 245                             (Default: 0)
 246
 247     apc.num_files_hint      A "hint" about the number of distinct source files
 248                             that will be included or requested on your web
 249                             server. Set to zero or omit if you're not sure;
 250                             this setting is mainly useful for sites that have
 251                             many thousands of source files.
 252                             (Default: 1000)
 253
 254     apc.user_entries_hint   Just like num_files_hint, a "hint" about the number
 255                             of distinct user cache variables to store.
 256                             Set to zero or omit if you're not sure;
 257                             (Default: 4096)
 258
 259     apc.ttl                 The number of seconds a cache entry is allowed to
 260                             idle in a slot in case this cache entry slot is
 261                             needed by another entry.  Leaving this at zero
 262                             means that your cache could potentially fill up
 263                             with stale entries while newer entries won't be
 264                             cached.
 265                             (Default: 0)
 266
 267     apc.user_ttl            The number of seconds a user cache entry is allowed
 268                             to idle in a slot in case this cache entry slot is
 269                             needed by another entry.  Leaving this at zero
 270                             means that your cache could potentially fill up
 271                             with stale entries while newer entries won't be
 272                             cached.
 273                             (Default: 0)
 274
 275
 276     apc.gc_ttl              The number of seconds that a cache entry may
 277                             remain on the garbage-collection list. This value
 278                             provides a failsafe in the event that a server
 279                             process dies while executing a cached source file;
 280                             if that source file is modified, the memory
 281                             allocated for the old version will not be
 282                             reclaimed until this TTL reached. Set to zero to
 283                             disable this feature.
 284                             (Default: 3600)
 285
 286     apc.cache_by_default    On by default, but can be set to off and used in
 287                             conjunction with positive apc.filters so that files
 288                             are only cached if matched by a positive filter.
 289                             (Default: On)
 290
 291     apc.filters             A comma-separated list of POSIX extended regular
 292                             expressions. If any pattern matches the source
 293                             filename, the file will not be cached. Note that
 294                             the filename used for matching is the one passed
 295                             to include/require, not the absolute path.  If the
 296                             first character of the expression is a + then the
 297                             expression will be additive in the sense that any
 298                             files matched by the expression will be cached, and
 299                             if the first character is a - then anything matched
 300                             will not be cached.  The - case is the default, so
 301                             it can be left off.
 302                             (Default: "")
 303
 304     apc.mmap_file_mask      If compiled with MMAP support by using --enable-mmap
 305                             this is the mktemp-style file_mask to pass to the
 306                             mmap module for determing whether your mmap'ed memory
 307                             region is going to be file-backed or shared memory
 308                             backed.  For straight file-backed mmap, set it to
 309                             something like /tmp/apc.XXXXXX (exactly 6 X's).
 310                             To use POSIX-style shm_open/mmap put a ".shm"
 311                             somewhere in your mask.  eg.  "/apc.shm.XXXXXX"
 312                             You can also set it to "/dev/zero" to use your
 313                             kernel's /dev/zero interface to anonymous mmap'ed
 314                             memory.  Leaving it undefined will force an
 315                             anonymous mmap.
 316                             (Default: "")
 317
 318     apc.slam_defense        ** DEPRECATED - Use apc.write_lock instead **
 319                             On very busy servers whenever you start the server or
 320                             modify files you can create a race of many processes
 321                             all trying to cache the same file at the same time.
 322                             This option sets the percentage of processes that will
 323                             skip trying to cache an uncached file.  Or think of it
 324                             as the probability of a single process to skip caching.
 325                             For example, setting this to 75 would mean that there is
 326                             a 75% chance that the process will not cache an uncached
 327                             file.  So the higher the setting the greater the defense
 328                             against cache slams.  Setting this to 0 disables this
 329                             feature.
 330                             (Default: 0)
 331
 332     apc.file_update_protection
 333                             When you modify a file on a live web server you really
 334                             should do so in an atomic manner.  That is, write to a
 335                             temporary file and rename (mv) the file into its permanent
 336                             position when it is ready.  Many text editors, cp, tar and
 337                             other such programs don't do this.  This means that there
 338                             is a chance that a file is accessed (and cached) while it
 339                             is still being written to.  This file_update_protection
 340                             setting puts a delay on caching brand new files.  The
 341                             default is 2 seconds which means that if the modification
 342                             timestamp (mtime) on a file shows that it is less than 2
 343                             seconds old when it is accessed, it will not be cached.
 344                             The unfortunate person who accessed this half-written file
 345                             will still see weirdness, but at least it won't persist.
 346                             If you are certain you always atomically update your files
 347                             by using something like rsync which does this correctly, you
 348                             can turn this protection off by setting it to 0.  If you
 349                             have a system that is flooded with io causing some update
 350                             procedure to take longer than 2 seconds, you may want to
 351                             increase this a bit.
 352                             (Default: 2)
 353
 354     apc.enable_cli          Mostly for testing and debugging.  Setting this enables APC
 355                             for the CLI version of PHP.  Normally you wouldn't want to
 356                             create, populate and tear down the APC cache on every CLI
 357                             request, but for various test scenarios it is handy to be
 358                             able to enable APC for the CLI version of APC easily.
 359                             (Default: 0)
 360
 361     apc.max_file_size       Prevents large files from being cached.
 362                             (Default: 1M)
 363
 364     apc.stat                Whether to stat the main script file and the fullpath
 365                             includes.  If you turn this off you will need to restart
 366                             your server in order to update scripts.
 367                             (Default: 1)
 368
 369     apc.write_lock          On busy servers when you first start up the server, or when
 370                             many files are modified, you can end up with all your processes
 371                             trying to compile and cache the same files.  With write_lock
 372                             enabled, only one process at a time will try to compile an
 373                             uncached script while the other processes will run uncached
 374                             instead of sitting around waiting on a lock.
 375                             (Default: 1)
 376
 377     apc.report_autofilter   Logs any scripts that were automatically excluded from being
 378                             cached due to early/late binding issues.
 379                             (Default: 0)
 380
 381     apc.rfc1867             RFC1867 File Upload Progress hook handler is only available
 382                             if you compiled APC against PHP 5.2.0 or later.  When enabled
 383                             any file uploads which includes a field called
 384                             APC_UPLOAD_PROGRESS before the file field in an upload form
 385                             will cause APC to automatically create an upload_<key>
 386                             user cache entry where <key> is the value of the
 387                             APC_UPLOAD_PROGRESS form entry.
 388
 389                             Note that the file upload tracking is not threadsafe at this
 390                             point, so new uploads that happen while a previous one is
 391                             still going will disable the tracking for the previous.
 392                             (Default: 0)
 393
 394     apc.rfc1867_prefix      Key prefix to use for the user cache entry generated by
 395                             rfc1867 upload progress functionality.
 396                             (Default: "upload_")
 397
 398     apc.rfc1867_name        Specify the hidden form entry name that activates APC upload
 399                             progress and specifies the user cache key suffix.
 400                             (Default: "APC_UPLOAD_PROGRESS")
 401
 402     apc.rfc1867_freq        The frequency that updates should be made to the user cache
 403                             entry for upload progress.  This can take the form of a
 404                             percentage of the total file size or a size in bytes
 405                             optionally suffixed with 'k', 'm', or 'g' for kilobytes,
 406                             megabytes, or gigabytes respectively (case insensitive).
 407                             A setting of 0 updates as often as possible, which may cause
 408                             slower uploads.
 409                             (Default: 0)
 410
 411     apc.localcache         ** REMOVED
 412     apc.localcache.size    ** REMOVED
 413
 414     apc.include_once_override
 415                             Optimize include_once and require_once calls and avoid the
 416                             expensive system calls used.
 417                             (Default: 0)