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