PHP Policy Draft: API version

[Olly Betts]

I'm putting together (currently unofficial) packages for a PHP extension.
There's nothing in policy that's PHP specific, but google found me the PHP
Policy Draft which has this list listed as author:

http://webapps-common.alioth.debian.org/draft-php/html/index.html

Although it's only a draft currently, it seems best to try to adhere to it.

Section 5.2 says:

| Precompiled binary modules for PHP must be located in
| /usr/lib/phpPHPVERSION/PHP_API_VERSION. PHPVERSION is the numeric major
| version number (such as 3, 4, or 5), and PHP_API_VERSION is the version
| against which the module was compiled. The latter is defined at build-time#
| in /usr/include/phpPHPVERSION/main/php.h.
|
| The following sed command can extract the value of PHP_API_VERSION for php4:
|
| sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php4/main/php.h

However, looking at the php4-dev and php5-dev packages in unstable:

$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php4/main/php.h
20020918
$ php-config4 --extension-dir
/usr/lib/php4/20050606
$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php5/main/php.h
20041225
$ php-config5 --extension-dir
/usr/lib/php5/20051025

And the existing packaged PHP modules seem to match the API version returned
by --extension-dir rather than that in php.h. Is this a bug in the draft
PHP policy, in the packaging of those modules, or in the php[45]-dev packages?
Or have I misunderstood something?

Cheers,
Olly

[sean finney]

hey olly,

Post by Olly Betts
$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php4/main/php.h
20020918
$ php-config4 --extension-dir
/usr/lib/php4/20050606
$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php5/main/php.h
20041225
$ php-config5 --extension-dir
/usr/lib/php5/20051025
And the existing packaged PHP modules seem to match the API version returned
by --extension-dir rather than that in php.h. Is this a bug in the draft
PHP policy, in the packaging of those modules, or in the php[45]-dev packages?
Or have I misunderstood something?

my impression is that you're correct. this seems like a much cleaner
method to recommend as well... any seconds to change the draft?


sean

[Neil McGovern]

Post by sean finney
hey olly,

Post by Olly Betts
$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php4/main/php.h
20020918
$ php-config4 --extension-dir
/usr/lib/php4/20050606
$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php5/main/php.h
20041225
$ php-config5 --extension-dir
/usr/lib/php5/20051025
And the existing packaged PHP modules seem to match the API version returned
by --extension-dir rather than that in php.h. Is this a bug in the draft
PHP policy, in the packaging of those modules, or in the php[45]-dev packages?
Or have I misunderstood something?

my impression is that you're correct. this seems like a much cleaner
method to recommend as well... any seconds to change the draft?

Seconded :)

Neil

[Olly Betts]

Post by sean finney
my impression is that you're correct. this seems like a much cleaner
method to recommend as well... any seconds to change the draft?

I think I've discovered why the versions mismatch:

$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php4/main/php.h
20020918
$ php-config4 --extension-dir
/usr/lib/php4/20050606
$ phpize4 -v
Configuring for:
PHP Api Version: 20020918
Zend Module Api No: 20020429
Zend Extension Api No: 20050606
$ sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php5/main/php.h
20041225
$ php-config5 --extension-dir
/usr/lib/php5/20051025
$ phpize5 -v Configuring for:
PHP Api Version: 20041225
Zend Module Api No: 20050922
Zend Extension Api No: 220051025

So PHP_API_VERSION is the "PHP Api Version" (unsuprisingly). The
version number on the directory is the Zend Extension Api No (minus
the leading 2 in PHP5 - I guess that's to differentiate between PHP4 and
PHP5 and so isn't needed on the extension dir as that's in the
/usr/lib/phpN prefix.)

So I think the current draft is confused as to which API is relevant
here and should indeed use "php-configN --extension-dir".

While I'm here, is there an existing PHP binary module whose packaging
conforms to current "best practice" which I can use as a guide? If
there's a better place to ask, please point me there...

Cheers,
Olly

[Pierre Habouzit]

Post by Olly Betts
While I'm here, is there an existing PHP binary module whose
packaging conforms to current "best practice" which I can use as a
guide? If there's a better place to ask, please point me there...
Cheers,
Olly

php-json-ext that I maintain, should respect the best practices. but I
*may* be wrong, and will be happy to fix it the right way.

[Olly Betts]

Post by Pierre Habouzit
php-json-ext that I maintain, should respect the best practices. but I
*may* be wrong, and will be happy to fix it the right way.

I have one question - why do you set:

Depends: phpapi-XXXXXXXX, phpN-common

Where XXXXXXXX is the api version and N is the PHP major version (i.e.
4 or 5). It doesn't appear that you directly need phpN-common, and
anything which provides phpapi-XXXXXXXX should depend on it if it
needs it, shouldn't it?

I'm not saying you're wrong (especially since the majority of PHP
modules seem to set their dependencies like this), just wondering why
it is done this way.

The PHP Policy Draft doesn't seem to cover this at all, but I think it
should...

Cheers,
Olly

[Pierre Habouzit]

Post by Olly Betts

Post by Pierre Habouzit
php-json-ext that I maintain, should respect the best practices.
but I *may* be wrong, and will be happy to fix it the right way.

Depends: phpapi-XXXXXXXX, phpN-common
Where XXXXXXXX is the api version and N is the PHP major version
(i.e. 4 or 5). It doesn't appear that you directly need phpN-common,
and anything which provides phpapi-XXXXXXXX should depend on it if it
needs it, shouldn't it?
I'm not saying you're wrong (especially since the majority of PHP
modules seem to set their dependencies like this), just wondering why
it is done this way.
The PHP Policy Draft doesn't seem to cover this at all, but I think
it should...

because it's a binary module, and yes policy should mention that for php
binary modules if not already stated.

[Olly Betts]

Post by Pierre Habouzit

Post by Olly Betts
Depends: phpapi-XXXXXXXX, phpN-common
[...]

because it's a binary module

Sorry, I'm still rather in the dark.

Is the logic that the "phpapi" number describes source level
compatibility, and that two PHP major versions could theoretically
support the same "phpapi" version but not be binary compatible?

Cheers,
Olly

[Pierre Habouzit]

Post by Olly Betts

Post by Pierre Habouzit

Post by Olly Betts
Depends: phpapi-XXXXXXXX, phpN-common
[...]

because it's a binary module

Sorry, I'm still rather in the dark.
Is the logic that the "phpapi" number describes source level
compatibility, and that two PHP major versions could theoretically
support the same "phpapi" version but not be binary compatible?

Not really, phpapi-XXXXXX is the ABI the module has been built against.
and when a php release change its phpapi version, every single binary
module has to be rebuilt.

when phpapi changes there is problems at least with:
* the ABI (I suppose)
* the path (php modules live in /usr/lib/php?/XXXXXXX)

hence the strict depends, because when the phpapi changes, the new php
does not even look in the old path (which is rather sane if ABI changed
enough ;p)

[Olly Betts]

Post by Pierre Habouzit
Not really, phpapi-XXXXXX is the ABI the module has been built against.
and when a php release change its phpapi version, every single binary
module has to be rebuilt.
* the ABI (I suppose)
* the path (php modules live in /usr/lib/php?/XXXXXXX)
hence the strict depends, because when the phpapi changes, the new php
does not even look in the old path (which is rather sane if ABI changed
enough ;p)

Indeed, but the new PHP package will now provide phpapi-YYYYYYYY instead
of phpapi-XXXXXXXX so a user wouldn't be able to upgrade PHP without
upgrading (or uninstalling) the module because that would leave the
module with unsatisfied dependencies (i.e. phpapi-XXXXXXXX). The
phpN-common dependency doesn't seem to make a difference...

Cheers,
Olly

[sean finney]

hi olly,
aha, very informative, thanks :)

Post by Olly Betts
So PHP_API_VERSION is the "PHP Api Version" (unsuprisingly). The
version number on the directory is the Zend Extension Api No (minus
the leading 2 in PHP5 - I guess that's to differentiate between PHP4 and
PHP5 and so isn't needed on the extension dir as that's in the
/usr/lib/phpN prefix.)
So I think the current draft is confused as to which API is relevant
here and should indeed use "php-configN --extension-dir".

yes, perhaps we should add something to clarify this. in the meantime
i've at least changed the specific section to mention using
php-configN instead of the ugly sed stuff.

Post by Olly Betts
While I'm here, is there an existing PHP binary module whose packaging
conforms to current "best practice" which I can use as a guide? If
there's a better place to ask, please point me there...

i think this question may have been answered for you already, but i'd
just like to add a suggestion that in addition to attempting to
follow the draft and other peoples' packages, you also keep
a critical eye to what you and others are doing (as well as what the
draft says), and if you see anything that doesn't seem right, bring it
up here.


sean

[Olly Betts]

Post by sean finney
yes, perhaps we should add something to clarify this. in the meantime
i've at least changed the specific section to mention using
php-configN instead of the ugly sed stuff.

I've made another discovery:

php-configN --phpapi

Returns just the module api version (and confusingly not the same as
PHP_API_VERSION in php.h), which is exactly what you need for creating
the dependency. An example:

$ php-config5 --extension-dir
/usr/lib/php5/20051025
$ php-config5 --phpapi
20051025

Post by sean finney

Post by Olly Betts
While I'm here, is there an existing PHP binary module whose packaging
conforms to current "best practice" which I can use as a guide? If
there's a better place to ask, please point me there...

i think this question may have been answered for you already, but i'd
just like to add a suggestion that in addition to attempting to
follow the draft and other peoples' packages, you also keep
a critical eye to what you and others are doing (as well as what the
draft says), and if you see anything that doesn't seem right, bring it
up here.

Will do.

Cheers,
Olly