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

[Howard Butler]

On May 20, 2012, at 12:23 PM, Even Rouault wrote:
> Up to now, the signature of functions added in the GDAL/OGR C API has never 
> changed, once they have been added.

This fact has at once been GDAL's strongest strength and its greatest weakness. GDAL's ability to innovate has been hampered by the fact that we seem to be contractually obligated to our users to never change the C API once we publish new methods. On the contrary, GDAL's ease of integration and ongoing inclusion in both proprietary and open source projects is predicated on the fact that once users implement GDAL's API, they practically never have to touch their code that interacts with GDAL ever again.

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. 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.  

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?  

> -------------------------------------------------
> Syntax of command line utilities
> -------------------------------------------------

I'd like to see some normalization of the arguments, arrangement, and help for the utilities. I'm also unsure how to do so without disrupting everyone.

Howard