release/src/router/php/README.UNIX-BUILD-SYSTEM

   1 PHP Build System V5 Overview
   2
   3 - supports Makefile.ins during transition phase
   4 - not-really-portable Makefile includes have been eliminated
   5 - supports separate build directories without VPATH by using
   6   explicit rules only
   7 - does not waste disk-space/CPU-time for building temporary libraries
   8   => especially noticeable on slower systems
   9 - slow recursive make replaced with one global Makefile
  10 - eases integration of proper dependencies
  11 - adds PHP_DEFINE(what[, value]) which creates a single include-file
  12   per what.  This will allow more fine-grained dependencies.
  13 - abandoning the "one library per directory" concept
  14 - improved integration of the CLI
  15 - several new targets
  16   build-modules: builds and copies dynamic modules into modules/
  17   install-cli: installs the CLI only, so that the install-sapi
  18                target does only what its name says
  19 - finally abandoned automake (still requires aclocal at this time)
  20 - changed some configure-time constructs to run at buildconf-time
  21 - upgraded shtool to 1.5.4
  22 - removed $(moduledir) (use EXTENSION_DIR)
  23
  24 The Reason For a New System
  25
  26 It became more and more apparent that there is a severe need
  27 for addressing the portability concerns and improving the chance
  28 that your build is correct (how often have you been told to
  29 "make clean"? When this is done, you won't need to anymore).
  30
  31
  32 If You Build PHP on a Unix System
  33
  34
  35 You, as a user of PHP, will notice no changes.  Of course, the build
  36 system will be faster, look better and work smarter.
  37
  38
  39
  40 If You Are Developing PHP
  41
  42
  43
  44
  45 Extension developers:
  46
  47 Makefile.ins are abandoned.  The files which are to be compiled
  48 are specified in the config.m4 now using the following macro:
  49
  50 PHP_NEW_EXTENSION(foo, foo.c bar.c baz.cpp, $ext_shared)
  51
  52 E.g. this enables the extension foo which consists of three source-code
  53 modules, two in C and one in C++.  And, depending on the user's wishes,
  54 the extension will even be built as a dynamic module.
  55
  56 The full syntax:
  57
  58 PHP_NEW_EXTENSION(extname, sources [, shared [,sapi_class[, extra-cflags]]])
  59
  60 Please have a look at acinclude.m4 for the gory details and meanings
  61 of the other parameters.
  62
  63 And that's basically it for the extension side.
  64
  65 If you previously built sub-libraries for this module, add
  66 the source-code files here as well.  If you need to specify
  67 separate include directories, do it this way:
  68
  69 PHP_NEW_EXTENSION(foo, foo.c mylib/bar.c mylib/gregor.c,,,-I@ext_srcdir@/lib)
  70
  71 E.g. this builds the three files which are located relative to the
  72 extension source directory and compiles all three files with the
  73 special include directive (@ext_srcdir@ is automatically replaced).
  74
  75 Now, you need to tell the build system that you want to build files
  76 in a directory called $ext_builddir/lib:
  77
  78 PHP_ADD_BUILD_DIR($ext_builddir/lib)
  79
  80 Make sure to call this after PHP_NEW_EXTENSION, because $ext_builddir
  81 is only set by the latter.
  82
  83 If you have a complex extension, you might to need add special
  84 Make rules.  You can do this by calling PHP_ADD_MAKEFILE_FRAGMENT
  85 in your config.m4 after PHP_NEW_EXTENSION.
  86
  87 This will read a file in the source-dir of your extension called
  88 Makefile.frag.  In this file, $(builddir) and $(srcdir) will be
  89 replaced by the values which are correct for your extension
  90 and which are again determined by the PHP_NEW_EXTENSION macro.
  91
  92 Make sure to prefix *all* relative paths correctly with either
  93 $(builddir) or $(srcdir).  Because the build system does not
  94 change the working directory anymore, we must use either
  95 absolute paths or relative ones to the top build-directory.
  96 Correct prefixing ensures that.
  97
  98
  99 SAPI developers:
 100
 101 Instead of using PHP_SAPI=foo/PHP_BUILD_XYZ, you will need to type
 102
 103 PHP_SELECT_SAPI(name, type, sources.c)
 104
 105 I.e. specify the source-code files as above and also pass the
 106 information regarding how PHP is supposed to be built (shared
 107 module, program, etc).
 108
 109 For example for APXS:
 110
 111 PHP_SELECT_SAPI(apache, shared, sapi_apache.c mod_php5.c php_apache.c)
 112
 113
 114
 115 General info
 116
 117 The foundation for the new system is the flexible handling of
 118 sources and their contexts.  With the help of macros you
 119 can define special flags for each source-file, where it is
 120 located, in which target context it can work, etc.
 121
 122 Have a look at the well documented macros
 123 PHP_ADD_SOURCES(_X) in acinclude.m4.