[gdal-dev] Policy for C/C++ API for GDAL 2.0 ?

Even Rouault even.rouault at mines-paris.org
Mon May 21 15:50:04 EDT 2012


> 
> A gold-plated GDAL 2.0 exists as something for us the developers, at least
> as it appears right now, to marvel at rather than provide real world
> improvements in functionality.

I think that the justification of the 2.0 in GDAL 2.0 should be mostly drived 
by the need of implementing new real world functionnality that cannot be 
solved with GDAL 1.X. Personnaly, I think that the reorganization of header 
files, const-correctness changes, or other changes only justified to make things 
look cleaner internally are bonus, but should not be the main motivation.

> We want cleaner and more coherent internal
> APIs, cleaner abstractions, a unified GDAL/OGR driver interface, and so
> on. None of these would seem to impact what users of GDAL who've
> implemented the software in their own projects are doing Right Now. As
> such, our 2.0 developments should take care not to break things for these
> users, but the question is how to do it.
> 
> Our contract has been with the C API users, not the C++ ones, and
> accordingly, I think we have carte blanche permission to do whatever we
> want with the C++ API.  I for one hope this includes organizing our
> include file and installation layout. For the C API, however, I think we
> should "fork" the old C API from a new one, and leave the old one alone to
> the extent that we can. Maybe this means changing its include path and
> requiring some sort of version-dependent #ifdef for users to point to the
> new location for 2.0 support, but I hope the changes implementers would
> have to make would be limited to that. It's not as if GDAL/OGR's internals
> are going to change so much in 2.0 that the existing C API facade,
> imperfect as it is, is unable to be continued.

Yes I agree that there's no reason to ditch out the existing C API. I'm not 
sure to understand how you would see the 2 API coexisting though. Would that 
be 2 libraries (like a libgdal1capi.so with its own include files and 
libgdal2capi.so with its own include files, that would both link to a 
libgdalc++.so) ?

> 
> I agree that this strategy is development burden on us, but it also
> provides us benefits in the form of allowing us to gradually migrate
> things like the command-line utilities and SWIG bindings from the old C
> API to a/the new C API. We eat our own dogfood and incur the
> implementation problems of a new API ourselves as we update utilities. As
> development continues, we should not add new functionality to the old C
> API.  Users should be required to update their codebases to use GDAL 2.0
> if they want new functionality (presumably this is mostly related to OGR).
> 
> Using the analogy of a house remodel, how far are we planning to take GDAL
> 2.0? Strip the internals down to the studs, re-plumb and re-wire
> everything, and build it back up? Slap another layer of shingles on the
> roof and caulk the holes where it's leaking and leave it at that?

The reason for initiating this discussion was to know which constraints we 
should impose on yourselves, a priori. It does not imply that major breaking 
changes will actually occur (at that time, I have no idea of what they could 
be anyway). I'm not sure there's the manpower and/or justification to make 
breaking changes happen. Let be realistic : given the large numbers of 
existing drivers, changing even internal interfaces might have prohibitive 
costs that can refrain enthousiasm.


Thinking out loud (half-convinced myself, but oh well, I take the risk to 
share even half-baked ideas) :

Looking at http://trac.osgeo.org/gdal/wiki/GDAL20Changes , I'm also wondering 
if 2.0 should not be the time to anticipate for later possible evolutions, and 
do the change in the API that would be needed, but not actually implement them 
if time does not permit it. For example, add progress callback arguments in 
some places, or add char** papszOptions as a provision for later extensions, 
or extend OGRField structure to add sub-second accuarcy (well, a wiser 
decision might be to just hide this structure from the public API !), or 
increase to 64bit data types some parameters. Or, for example, for  
http://trac.osgeo.org/gdal/wiki/rfc31_ogr_64, just do the API evolutions even 
if no drivers actually use them yet (but that's going to be frustrating !)

RFC31 is an interesting case actually when thinking again about the above idea 
of 2 versionso of the C API, one of them being the compatibility layer for 
GDAL 1. If we add a OFTInteger64 data type, even users of the old C API could 
have to deal with that data type as soon as drivers will use them. But not 
having any of the new API to deal with that 64bit data type, they will be 
stuck.

Best regards,

Even


More information about the gdal-dev mailing list