Return to README.UNIX-BUILD-SYSTEM CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

Annotation of embedaddon/php/README.UNIX-BUILD-SYSTEM, revision 1.1.1.1

1.1       misho       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.