httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Sutton <>
Subject HIDE summary
Date Wed, 01 Apr 1998 10:13:03 GMT
Hey this has really livened up this list! 

We want the Apache core to work well with third party modules. We aren't
going to make many module-author friends if we keep changing the API. So
we eventually need a documented API at the source level. We also want to
make binary modules work between version if at all possible, since it
makes so many things so much more attractive. I don't think it is
unreasonable to attempt to make upgrades from 1.3.0 binary compatibile
with 1.3.0. The current beta phase is to time to put things into place to
make that compatibility help. We can't just put it of now because the
decision is difficult and say we'll do it for 1.3.0 to 1.3.1 (or whatever) 
since that will guarantee breakages of modules during a stable product
sequence. Not nice to module authors.

As far as I can see the HIDE=yes code makes no difference to source
compatibility. There are already changes in the API for other reasons, so
we do not have binary compatibility. So modules authors or users will have
to recompile. If they do recompile it will not matter to them whether
HIDE=no or HIDE=yes is on, since the symbols in the module being compiled
will be mapped to the correct exported symbols when HIDE=yes. 

For the 1.3beta to 1.3 change:

  -- with HIDE=no module authors will have to recompile 
  -- with HIDE=yes module authors will have to recompile

So there is no difference at this stage (1.3beta to 1.3) between using
HIDE=no and HIDE=yes.

There may be issues regarding debugging, profiling, and source browsing
which make HIDE=yes undesirable, though. The advantage of HIDE=yes is that
it avoids name space clashes.

Now in the future we would like to provided better binary module upgrade
support. This will necessitate some kind of back-compatibility layer. If
we use HIDE=no as the default, this means we will have to provide symbols
with _unhidden_ names, such as palloc(), which are wrappers for the
(renamed) ap_palloc() type functions. But if we use HIDE=yes, our wrappers
will be of the form AP_palloc. Assuming that unhidden names may conflict
with third-party libraries, using HIDE=no now means in order to get binary
compatibility between 1.3.0 the next release with renamed symbols means we
will have to continue to export conflicting names, or break compatibility
again in the renamed release.

So, for a future release where we rename symbols to avoid conflicts (e.g. 
1.3.0 to 1.3.1): 

  -- if 1.3 used HIDE=no, we will have to either break binary
     compatibility and remove palloc(), OR map palloc() to ap_palloc()
     and continue to get conflicts

  -- if 1.3 used HIDE=yes, we can provide a mapping from AP_palloc() 
     to ap_palloc() at binary and source levels, so not breaking
     modules and not conflicting with external libraryies

So it seems to me that we should use HIDE=yes as an enforced setting in
1.3.0. We can then provide forward binary and source compatibility. Using
HIDE=no for 1.3.0 means we must break binary compatibility in the renamed

For 1.3.* we can continue to supply a hide.h which maps to the correct
exported function. In 1.3.0 this will map palloc() -> AP_palloc(). In
1.3.1 it will map palloc() -> ap_palloc(). For 1.3.0 we document to module
authors that they must not use AP_* names -- they are transitionary names.
>From 1.3.1 onwards we can document the correct names, such as ap_palloc().
This provides a clean development path with minimum distruptions to module
authors after they've upgraded their modules to work with 1.3.0.

The _only_ alternate to HIDE=yes for 1.3 is that we quickly decide on the
final API names for all public functions, and make hide.h or the source
code itself use the correct final names. These eliminates the
transitionary use of AP_* names, at lets module authors start using the
final names for their 1.3.0 modules straight away. 


View raw message