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

[Frank Warmerdam]

On Sun, May 20, 2012 at 10:23 AM, Even Rouault
<even.rouault at mines-paris.org> wrote:
> I think it is good time to discuss now what we want to allow, or not, for GDAL
> 2.0, as far as the C/C++ API is concerned.

Even,

My brief thoughts are:

 * My objectives for GDAL/OGR 2.0 primarily revolve around
restructuring OGR to be close alignment with the GDAL API.  That means
moving to a unified driver model, and GDAL style creation option and
capabilities mechanisms.  I want to end up with a GDALDataset that can
have vector layers as well as bands.

 * To that end, I imagine non-trivial changes in the OGRDriver,
OGRDataSource and OGRLayer classes which will non-trivially their API.
 OGRFeature and OGRGeometry will hopefully not be very adversely
affected.

 * My goal then is to minimize disruption in the GDAL C++ API, and C
API with the C API hopefully being nearly entirely backward compatible
while the OGR C++ and C API will be signifcantly disrupted though I'm
hoping via some aliasing mechanisms we might be able to provide some
amount of compatability.

 * I hadn't considered big changes in the utilities myself but if ever
it was to be done now would be the time.

Best regards,
Frank

>
> ---------
> C API
> ---------
>
> Up to now, the signature of functions added in the GDAL/OGR C API has never
> changed, once they have been added.
>
> What should be the rule for GDAL 2.0 ?
>
> 1) do not change the signature of any function already present in the C API.
> If breaking changes are necessary, then introduce "FooEx", or "Foo2" versions
> of those functions as done in the past. The drawback of that approach is that
> the API becomes cluttered.
>
> 2) do not change the signature of any commonly used functions, but allow
> changes in marginally used functions. The definition of commonly functions
> w.r.t marginally used ones is a bit arbitrary. Looking at the symbols used by
> popular Open Source software using GDAL C API could give a clue in case of
> doubt (MapServer, QGIS, GRASS, PostGIS, or in-tree GDAL utilities using C API
> ...).
>
> 3) allow changes even in commonly used functions.
>
> Options 2) or 3) would likely require other projects to have #if GDAL_VERSION
>>= 2000 in some places if they plan to support older GDAL versions. Unless
> they plan to update their dependency requirements when they release a newer
> version of their project (Project XX version < 1.Y depends on GDAL < 2.0.
> Version >= 1.Y depends on GDAL >= 2.0).
>
> -------------
> C++ API
> -------------
>
> As far as the C++ API is concerned, the policy up to now was that minor
> changes between GDAL 1.X version and GDAL 1.(X+1) were OK. Generally, the
> changes have been the addition of new optional arguments, that only required
> recompilation to solve the change of ABI, but did not require code changes.
>
> For GDAL 2.0, I believe that most major changes could occur, especially if the
> OGR "grand unification" occurs, but for now, I don't know the impact that that
> might cause.
>
> -------------------------------------------------
> Syntax of command line utilities
> -------------------------------------------------
>
> A bit out of topic, since it is about UI and not API. But a lot of scripts in
> the wild call popular GDAL command line utilities. Changes in their syntax
> would cause potentially more headaches, given the larger number of users
> w.r.t. developers using GDAL ;-) The page at
> http://trac.osgeo.org/gdal/wiki/GDAL20Changes lists a few changes that have
> been proposed (just as a reminder : nothing listed there is officially vetted).
>
> The same question also arise with the API of the various bindings languages.
>
> Feedback welcome !
>
> Best regards,
>
> Even
>
> _______________________________________________
> gdal-dev mailing list
> gdal-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/gdal-dev



-- 
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up   | Frank Warmerdam, warmerdam at pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush    | Geospatial Software Developer