xref: /PHP-5.5/README.UNIX-BUILD-SYSTEM (revision 9b31c51d)
1171b8642SSascha SchumannPHP Build System V5 Overview
2171b8642SSascha Schumann
3171b8642SSascha Schumann- supports Makefile.ins during transition phase
4171b8642SSascha Schumann- not-really-portable Makefile includes have been eliminated
552641b41SJon Parise- supports separate build directories without VPATH by using
6171b8642SSascha Schumann  explicit rules only
7171b8642SSascha Schumann- does not waste disk-space/CPU-time for building temporary libraries
8171b8642SSascha Schumann  => especially noticeable on slower systems
9171b8642SSascha Schumann- slow recursive make replaced with one global Makefile
10171b8642SSascha Schumann- eases integration of proper dependencies
11171b8642SSascha Schumann- adds PHP_DEFINE(what[, value]) which creates a single include-file
12171b8642SSascha Schumann  per what.  This will allow more fine-grained dependencies.
13171b8642SSascha Schumann- abandoning the "one library per directory" concept
14171b8642SSascha Schumann- improved integration of the CLI
15171b8642SSascha Schumann- several new targets
16171b8642SSascha Schumann  build-modules: builds and copies dynamic modules into modules/
17171b8642SSascha Schumann  install-cli: installs the CLI only, so that the install-sapi
18171b8642SSascha Schumann               target does only what its name says
19171b8642SSascha Schumann- finally abandoned automake (still requires aclocal at this time)
20171b8642SSascha Schumann- changed some configure-time constructs to run at buildconf-time
21171b8642SSascha Schumann- upgraded shtool to 1.5.4
22171b8642SSascha Schumann- removed $(moduledir) (use EXTENSION_DIR)
23171b8642SSascha Schumann
24171b8642SSascha SchumannThe Reason For a New System
25171b8642SSascha Schumann
26171b8642SSascha SchumannIt became more and more apparent that there is a severe need
27171b8642SSascha Schumannfor addressing the portability concerns and improving the chance
28171b8642SSascha Schumannthat your build is correct (how often have you been told to
29171b8642SSascha Schumann"make clean"? When this is done, you won't need to anymore).
30171b8642SSascha Schumann
31171b8642SSascha Schumann
32171b8642SSascha SchumannIf You Build PHP on a Unix System
33171b8642SSascha Schumann
34171b8642SSascha Schumann
35171b8642SSascha SchumannYou, as a user of PHP, will notice no changes.  Of course, the build
36171b8642SSascha Schumannsystem will be faster, look better and work smarter.
37171b8642SSascha Schumann
38171b8642SSascha Schumann
39171b8642SSascha Schumann
40171b8642SSascha SchumannIf You Are Developing PHP
41171b8642SSascha Schumann
42171b8642SSascha Schumann
43171b8642SSascha Schumann
44171b8642SSascha Schumann
45171b8642SSascha SchumannExtension developers:
46171b8642SSascha Schumann
47171b8642SSascha SchumannMakefile.ins are abandoned.  The files which are to be compiled
48171b8642SSascha Schumannare specified in the config.m4 now using the following macro:
49171b8642SSascha Schumann
50171b8642SSascha SchumannPHP_NEW_EXTENSION(foo, foo.c bar.c baz.cpp, $ext_shared)
51171b8642SSascha Schumann
52171b8642SSascha SchumannE.g. this enables the extension foo which consists of three source-code
5352641b41SJon Parisemodules, two in C and one in C++.  And, depending on the user's wishes,
5452641b41SJon Parisethe extension will even be built as a dynamic module.
55171b8642SSascha Schumann
56171b8642SSascha SchumannThe full syntax:
57171b8642SSascha Schumann
58171b8642SSascha SchumannPHP_NEW_EXTENSION(extname, sources [, shared [,sapi_class[, extra-cflags]]])
59171b8642SSascha Schumann
60171b8642SSascha SchumannPlease have a look at acinclude.m4 for the gory details and meanings
61171b8642SSascha Schumannof the other parameters.
62171b8642SSascha Schumann
63171b8642SSascha SchumannAnd that's basically it for the extension side.
64171b8642SSascha Schumann
65171b8642SSascha SchumannIf you previously built sub-libraries for this module, add
66171b8642SSascha Schumannthe source-code files here as well.  If you need to specify
67171b8642SSascha Schumannseparate include directories, do it this way:
68171b8642SSascha Schumann
69171b8642SSascha SchumannPHP_NEW_EXTENSION(foo, foo.c mylib/bar.c mylib/gregor.c,,,-I@ext_srcdir@/lib)
70171b8642SSascha Schumann
71171b8642SSascha SchumannE.g. this builds the three files which are located relative to the
72171b8642SSascha Schumannextension source directory and compiles all three files with the
73171b8642SSascha Schumannspecial include directive (@ext_srcdir@ is automatically replaced).
74171b8642SSascha Schumann
75171b8642SSascha SchumannNow, you need to tell the build system that you want to build files
76171b8642SSascha Schumannin a directory called $ext_builddir/lib:
77171b8642SSascha Schumann
78171b8642SSascha SchumannPHP_ADD_BUILD_DIR($ext_builddir/lib)
79171b8642SSascha Schumann
80171b8642SSascha SchumannMake sure to call this after PHP_NEW_EXTENSION, because $ext_builddir
81171b8642SSascha Schumannis only set by the latter.
82171b8642SSascha Schumann
83171b8642SSascha SchumannIf you have a complex extension, you might to need add special
84171b8642SSascha SchumannMake rules.  You can do this by calling PHP_ADD_MAKEFILE_FRAGMENT
85171b8642SSascha Schumannin your config.m4 after PHP_NEW_EXTENSION.
86171b8642SSascha Schumann
87171b8642SSascha SchumannThis will read a file in the source-dir of your extension called
88171b8642SSascha SchumannMakefile.frag.  In this file, $(builddir) and $(srcdir) will be
89171b8642SSascha Schumannreplaced by the values which are correct for your extension
90171b8642SSascha Schumannand which are again determined by the PHP_NEW_EXTENSION macro.
91171b8642SSascha Schumann
92171b8642SSascha SchumannMake sure to prefix *all* relative paths correctly with either
9349679a72SSander Roobol$(builddir) or $(srcdir).  Because the build system does not
94171b8642SSascha Schumannchange the working directory anymore, we must use either
95171b8642SSascha Schumannabsolute paths or relative ones to the top build-directory.
96171b8642SSascha SchumannCorrect prefixing ensures that.
97171b8642SSascha Schumann
98171b8642SSascha Schumann
99171b8642SSascha SchumannSAPI developers:
100171b8642SSascha Schumann
101171b8642SSascha SchumannInstead of using PHP_SAPI=foo/PHP_BUILD_XYZ, you will need to type
102171b8642SSascha Schumann
103171b8642SSascha SchumannPHP_SELECT_SAPI(name, type, sources.c)
104171b8642SSascha Schumann
105171b8642SSascha SchumannI.e. specify the source-code files as above and also pass the
106171b8642SSascha Schumanninformation regarding how PHP is supposed to be built (shared
107171b8642SSascha Schumannmodule, program, etc).
108171b8642SSascha Schumann
109171b8642SSascha SchumannFor example for APXS:
110171b8642SSascha Schumann
111*9b31c51dSJon ParisePHP_SELECT_SAPI(apache, shared, sapi_apache.c mod_php5.c php_apache.c)
112171b8642SSascha Schumann
113171b8642SSascha Schumann
114171b8642SSascha Schumann
115171b8642SSascha SchumannGeneral info
116171b8642SSascha Schumann
117171b8642SSascha SchumannThe foundation for the new system is the flexible handling of
118171b8642SSascha Schumannsources and their contexts.  With the help of macros you
119171b8642SSascha Schumanncan define special flags for each source-file, where it is
120171b8642SSascha Schumannlocated, in which target context it can work, etc.
121171b8642SSascha Schumann
122171b8642SSascha SchumannHave a look at the well documented macros
123171b8642SSascha SchumannPHP_ADD_SOURCES(_X) in acinclude.m4.
124