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