[Proj] Time for a new release?

Kristian Evers kreve at sdfe.dk
Mon Nov 13 12:38:13 EST 2017


you said most of what I had in mind, so I’ll just add that almost all functions in the library today is part of the public API. Either through projects.h or proj_api.h. That doesn’t leave much room for refactoring in general. I recently touched the gridshifting code, but had to stay within the boundaries of the current functions in order to not break the API. I could have come up with better implementations if I had been able to change things at a deeper level. The biggest offender is projects.h which absolutely should be a private header.


I think it is possible to make a compatibility layer as you suggest. Most of what is needed is in place already. I understand your reasoning, though I am not too keen on taking on this task myself. Your alternative plan sounds better to me, although we would then introduce a breaking change at the 5.1.0 version, which kind of goes against the semantic versioning scheme that we ought to follow. It can easily be solved by changing your proposed error message to I_AM_M_AWARE_PROJ_API_H_WILL_BE_REMOVED_IN_PROJ_6_0 and then release version 6 a year after version 5. It should also be added to projects.h.

Anyway, I don’t want to restart the discussion we had a few months ago, I just wanted to take the temperature on this with the clear decision about going to version 5 in the next release.


On 13 Nov 2017, at 16:43, Thomas Knudsen <knudsen.thomas at gmail.com<mailto:knudsen.thomas at gmail.com>> wrote:

Even, regarding simplification by elimination:

Obviously Kristian will want to answer this himself, but I would like to mention at least one thing (or perhaps rather aspect) that will buy us simplification by eliminating projects.h and proj_api.h:

We would get rid of the type-punning-by-preprocessor-defs that destroyed Gerald's classic PROJ.4 core API, (pj_init, pj_fwd, pj_inv, and pj_free), by turning XY and LP into UV behind the back of the user, such that XY xy is no longer adressed xy.x and xy.y, but xy.u and xy.v

We would also get rid of the half baked namespacing-and-information-hiding-by-misleading-typedef, implemented by e.g.
typedef void *projPJ, and typedef void *projCtx, rather than by forward declarations.

This kind of stuff has been hell to work around (see the text in the top of proj.h for rationale for the work). This is not said to belittle Frank's work, which has been of immense value for PROJ.4, and has kept it afloat and in constant evolution, for more than 15 years: His work is admirable, but has, naturally, been focused on whatever (or whom-ever) paid the bills.

This has given us support for vertical datums, support for NTv2, support for a "failrly accurate for the needs when it was introduced 15 years ago" interface function as pj_transform, which to a large degree succeeds in "giving the user what (s)he wants without asking too many annoying geodetic questions".

It has, however, also given us the, largely superfluous contexts, and the  fileapi, which, apart form missing a fgetc- style function, also in general suffer from a feeling of "work made for hire" for a specific customer, using it for in house stuff (only since it is largely unknown by search engines) - but now we have to maintain this stuff,without even knowing what the rationale behind was.

So yes - we could certainly benefit from skipping projects.h and proj_api.h : It will buy us some simplifications -  I'm just not sure that this is the right way to do things. More about this later.

2017-11-11 20:06 GMT+01:00 Even Rouault <even.rouault at spatialys.com<mailto:even.rouault at spatialys.com>>:
On samedi 11 novembre 2017 17:32:05 CET Kristian Evers wrote:
> PROJ v. 5.0.0 is also good with me. It also brings us into "braking changes
> territory". With this in mind I think we should consider only supporting
> the new API in proj.h and dropping the other APIs. This will allow us to
> simplify the code immensely.

Can you sketch a bit what would be simplified in doing so ?

> At the moment we jump through a bunch of hoops
> to keep backwards compatibility. We'd probably still do that for the next
> release, but not having projects.h and proj_api.h as part of the public API
> we can change things behind the scenes in future releases.

If I remember the analysis of Debian packages, while dropping projects.h would have a moderate impact, dropping proj_api.h would cause massive breakage. This would likely cause proj 5 to take months to years before being available in distributions due to many packages not being ready for it (and the proj_api.h -> proj.h port is the kind of change that needs to be done by upstream projects. not a quick&dirty hack that the packager can do)
Thus in this context of software distributions, applications that would be adapted to use the new API wouldn't be able to use it in practice for a long time. Worse, applications that would do the changes to support proj >= 5 would still to have to support both proj < 5 and proj >= 5 in a transition period if they want their new releases to be packaged. To make their life easier by avoiding to have them to support both API, a proj 5 should be available as packaged as fast as possible.

I'm wondering if there wouldn't be a way of having a proj_api.c compatibiliy layer that would use the new API behind the scene ? The projPJ struct could be something different than the PJ one, for example just storing the text. And when doing pj_transform() you would build a pipeline from the src and dest projPJ. Things like that. I believe the cost of creating this compatibility layer (assuming this is possible) would be worth it

Or alternate plan :

- for proj 5.0, add at top of proj_api.h

#error "proj_api.h will be removed in proj 5.1. You can still use it for now by defining I_AM_AWARE_PROJ_API_H_WILL_BE_REMOVED_IN_PROJ_5_1, but you should strongly consider using proj.h now"

Perhaps do the same for projects.h, if we really want proj 5 to be a no-brainer for packagers

- for proj 5.1, remove proj_api.h (and projects.h)

* this would make proj 5 easy to be packaged, by avoiding a flag day
* applications would be clearly warned they have to do something, and have time to do the changes
* after proj 5.0 release, proj master could benefit from the needed cleanups.


Spatialys - Geospatial professional services

Proj mailing list
Proj at lists.maptools.org<mailto:Proj at lists.maptools.org>

Proj mailing list
Proj at lists.maptools.org<mailto:Proj at lists.maptools.org>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.maptools.org/pipermail/proj/attachments/20171113/79692b1d/attachment.htm 

More information about the Proj mailing list