Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

168 lines (101 sloc) 4.742 kb
<h2>How to add new extension functions/classes</h2>
There are 2 types of extensions: separable extensions and non-separable
extensions. Most of existing extensions were written in a way that's not quite
easy to remove/detach/separate from the runtime. Separable extension is a new
framework that's just added to allow people to work in its own directory
without any modifications to main project files, thus easy to add/remove an
extension from the core runtime.
<h2>How to add new separable extension functions/classes</h2>
1. Find the right extension name
Find a unique extension name, for example, "mhash". Use the name to create a
directory. For example, runtime/ext/sep/mhash. This would be home directory
of the extension, and all new files will be created under this directory.
2. Create a new IDL
For example, mhash.idl.php. Add function/class prototypes to the IDL file.
Follow existing ones for formats. Most of them are straightforward. Possible
types are listed in idl/base.php.
3. Auto-generate files from IDL
Create a Makefile like runtime/ext/sep/mhash/Makefile, by specifying
PROJECT_ROOT and including runtime/ext/sep/rules.mk.
If it is a new IDL file, run
make create
Otherwise, run
make update
4. Manual editing
Modify these files to implement the extension.
ext_[name].h
ext_[name].cpp
5. Unit tests
Modify these files to add unit tests.
test_ext_[name].h
test_ext_[name].cpp
6. Create the extension and unit test program.
make
7. Provide the extension to the compiler.
The compiler needs to know about these new functions/classes, while compiling
PHP code. To do this, prepare a configuration HDF file like this,
SepExtensions {
mhash {
# optional: default to lib[name].so
soname = libmhash.so
# optional: default to $(PROJECT_ROOT)/src/runtime/ext/sep/[name]
include = /var/users/hzhao/hphp2/src/runtime/ext/sep/mhash
# optional: default to use LD_LIBRARY_PATH or ldconfig to locate the .so
libpath = /var/users/hzhao/hphp2/src/runtime/ext/sep/mhash
# optional: default to "false", using static libraries for linking
shared = true
}
}
Then give this file to the compiler like this,
hphp/hphp test.php -c config.hdf
The compiler will extract extension symbols from the .so file.
8. Run compiled program with the new extension.
Newly compiled program will depend on the new extension's .a or .so (depending
on config's "shared" setting. If static linking is used, the compiler will
locate the .a file automatically and link with it. No more runtime setup is
needed. Otherwise, the .so file becomes a runtime dependency and it has to
be located by the compiled program at runtime, perhaps with ldconfig or any
other ways.
<h2>How to add new non-separable extension functions/classes</h2>
All commands and directories are from src/ in this guide.
1. Find the right extension name
Find the best "extension" under idl/*.idl.php to add your function(s) to.
runtime/ext/README has a good list of categorized extension names. If nothing
fits, create a new IDL file with a good name.
2. Update IDL
Add function/class prototypes to the IDL file. Follow existing ones for
formats. Most of them are straightforward. Possible types are listed in
idl/base.php.
3. Auto-generate files from IDL
If it is a new IDL file, run
EXT=[new extension name] make -C idl install
For example,
EXT=my_extension make -C idl install
This will add several files to different places.
Otherwise, run
EXT=[existing extension name] make -C idl update
For example,
EXT=string make -C idl update
This will modify several files with the new function/classes.
4. Manual editing
Some files are not automatically updated, including
runtime/ext/ext_[name].h
runtime/ext/ext_[name].cpp
They are created under idl/ to serve as templates that one can copy portions
of them manually. These are the two files that you will add implementation to.
5. Unit tests
The "EXT=name make update" does the following for test files:
creates test/test_ext_[name].h -- entry points for this unit test, don't modify
updates test/test_ext.inc -- to invoke the test, don't modify
creates idl/test_ext_[name].cpp -- A template to be modified.
You will have to add new unit tests to
test/test_ext_[name].cpp
into both the list of RUN_TEST() at top portion of the file and a real
unit test function like this,
void TestExt[Name]::test_ext_[function] () { ... }
6. How to modify existing extension functions/classes
Modify the IDL file. Then run
EXT=existing make -C idl update
Follow all steps after step 3 at above.
7. After compiling once, do this to update compiler with the latest functions:
make -C system
Jump to Line
Something went wrong with that request. Please try again.