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

[Peter Halls]

As a programmer using GDAL/OGR, I do not think I mind if there are API
changes at major releases - especially, as with GDAL, where these are
infrequent - but might be annoyed during point releases.  It is reasonable
to expect major new features and rationalisation at major releases, so the
burden of having to edit code is acceptable.  Obviously, if there are no
changes, that is great ... but then it would hardly classify as a major
release.

For my part, I have an interface library to edit - rather like a language
binding for Java or Python, so I have probably only one place that will
need work.

It says a great deal for the original design of GDAL/OGR that this
discussion is only happening now, after several years and many point
releases.  Thank you, Frank.

Peter

On 20 May 2012 18:23, Even Rouault <even.rouault at mines-paris.org> wrote:

> Hi GDAL developers and users (actually, developers of other projects using
> GDAL ;-)),
>
> This issue was raised incidently in the "[gdal-dev] VRTComplexSource with a
> LUT, proposal" thread at http://lists.osgeo.org/pipermail/gdal-dev/2012-
> May/032872.html .
>
> 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.
>
> ---------
> 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
>



-- 
----------------------------------------------------------------------------------------------------------------
Peter J Halls, GIS Advisor & Team Leader Applications Support and Training,
               Information Directorate, University of York
Telephone: 01904 323806     Fax: 01904 323740
Snail mail: Harry Fairhurst Building, University of York,
                Heslington, York YO10 5DD
This message has the status of a private and personal communication
----------------------------------------------------------------------------------------------------------------
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/gdal-dev/attachments/20120521/49ea8423/attachment-0001.html