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     ! 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.