Re: [Evolution-hackers] Front-end header files for E-D-S libraries
On Tue, 2011-03-22 at 14:35 -0400, Matthew Barnes wrote: For 3.1, I would like to provide a top-level header file for each of the libraries in E-D-S and deprecate including individual header files. The benefits should be clear by now: more flexibility to change or rearrange header files without breaking the public API. Valid #include directives for E-D-S libraries will be: #include libebackend/libebackend.h #include libedataserver/libedataserver.h #include libedataserverui/libedataserverui.h #include libebook/libebook.h #include libecal/libecal.h I'm not bothering with the backend libraries just yet. They're less of an issue than the client-side libraries. To enforce this we'll use the same mechanism as in GLib and GTK+, except for now we'll issue a #warning instead of an #error: #warning Including libecal/e-cal.h directly is deprecated. #warning Please use #include libecal/libecal.h instead. We could also test for an EDS_DISABLE_SINGLE_INCLUDES definition which would issue an #error instead of a #warning. After maybe a year or two we'll crack down and issue #errors in some future 3.(odd).1 release. Since I've already broken E-D-S APIs across the board for 3.5.3, I'm following up on this as well. Same plan as what I originally sketched out, except I'm skipping the deprecation phase and moving straight to #error since there's no point drawing this out, and I _am_ bothering with the backend libraries. It turns out to be nice for backends to just have one #include. Matthew Barnes ___ evolution-hackers mailing list evolution-hackers@gnome.org To change your list options or unsubscribe, visit ... https://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] Front-end header files for E-D-S libraries
On Tue, 2011-03-22 at 14:35 -0400, Matthew Barnes wrote: For 3.1, I would like to provide a top-level header file for each of the libraries in E-D-S and deprecate including individual header files. The benefits should be clear by now: more flexibility to change or rearrange header files without breaking the public API. Hi, I never got why one wants this, I recall some Java guidelines which encourage the opposite, never include whole unit, but only pieces you actually use. It made more sense to me, to not get in things you never use (quicker parsing/compilation too, probably, to not openparse spare header files). Also, one does not rearrange code so often, I believe. Anyway, if you really think this change (which actually affects anyone using eds client API) worth the effort, then feel free to do it. Bye, Milan ___ evolution-hackers mailing list evolution-hackers@gnome.org To change your list options or unsubscribe, visit ... http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] Front-end header files for E-D-S libraries
On Di, 2011-03-22 at 14:35 -0400, Matthew Barnes wrote: For 3.1, I would like to provide a top-level header file for each of the libraries in E-D-S and deprecate including individual header files. The benefits should be clear by now: more flexibility to change or rearrange header files without breaking the public API. How much of a problem is that in practice? I have to deal with compatibility problems in all of the current releases already: * URI changes and data migration in 2.32 * account/config changes in 3.0 * and now header file changes in 3.1 If the header file change had been done such that a single = 3.0 check is enough I wouldn't mind, but it doesn't seem like 3.0 has a libebook.h (picking just one example). Is there a chance to add the headers to 3.0 before it gets released? If not, then I'd prefer to not make this change. -- Bye, Patrick Ohly -- patrick.o...@gmx.de http://www.estamos.de/ ___ evolution-hackers mailing list evolution-hackers@gnome.org To change your list options or unsubscribe, visit ... http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] Front-end header files for E-D-S libraries
On Wed, 2011-03-23 at 13:42 +0100, Patrick Ohly wrote: How much of a problem is that in practice? It's getting to be a problem. Seemingly innocent changes to header files break builds in unexpected ways. Here's a common scenario: - Header file foo.h includes bar.h. - A client program includes foo.h and uses things defined there. - Later, the client program starts using things defined in bar.h, but forgets to include it explicitly. It just happens to work because foo.h includes it. - Down the road, foo.h no longer includes bar.h for some reason or another. Maybe to resolve a cyclic dependency between the two. - The client program now fails to build, because bar.h was never explicitly included. Forcing the client program to include a front-end header file for the library, which itself includes both foo.h and bar.h, avoids this problem. This is why most other libraries already do it this way. Another scenario is when a pair of header/body files is getting to be overly bloated and complicated and developers would like to divide it into smaller files so it's easier to understand and maintain. Without a front-end header file for the library we don't have the flexibility to do this with without breaking the public API. Is there a chance to add the headers to 3.0 before it gets released? It's too late for 3.0.0. I can add it for 3.0.1 sans the preprocessor warnings if that would help. ___ evolution-hackers mailing list evolution-hackers@gnome.org To change your list options or unsubscribe, visit ... http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] Front-end header files for E-D-S libraries
On Mi, 2011-03-23 at 09:05 -0400, Matthew Barnes wrote: On Wed, 2011-03-23 at 13:42 +0100, Patrick Ohly wrote: How much of a problem is that in practice? It's getting to be a problem. Seemingly innocent changes to header files break builds in unexpected ways. Here's a common scenario: [...] Okay, I see your point. But if the split into individual files is merely to group code and not done to speed up compilation, wouldn't the following also work: 1. move current files into an internal sub-directory 2. introduce the new include all header 3. make all the traditional names symlinks to that one header That introduces the desired advantage (rearrange header content) without breaking the API. Is there a chance to add the headers to 3.0 before it gets released? It's too late for 3.0.0. I can add it for 3.0.1 sans the preprocessor warnings if that would help. 3.0.1 is too late to help much, unless 3.0.0 can be expected to not be used by anyone... -- Bye, Patrick Ohly -- patrick.o...@gmx.de http://www.estamos.de/ ___ evolution-hackers mailing list evolution-hackers@gnome.org To change your list options or unsubscribe, visit ... http://mail.gnome.org/mailman/listinfo/evolution-hackers
Re: [Evolution-hackers] Front-end header files for E-D-S libraries
On Wed, 2011-03-23 at 15:52 +0100, Patrick Ohly wrote: I thought that this break would go into 3.0 (see my initial reply). So if 3.1 requires changes anyway, then sure, go ahead and break it some more ;-) Oh, I missed that in your first reply. Sorry. That was the plan originally, but keeping up with GTK3 prior to its first stable release sucked up huge amounts of time during 2.91, at least for me. So a lot of my goals for 3.0 got pushed out. ___ evolution-hackers mailing list evolution-hackers@gnome.org To change your list options or unsubscribe, visit ... http://mail.gnome.org/mailman/listinfo/evolution-hackers
