[vtk-developers] RE: API Change

[Andrew Maclean]

Here is my 2c worth.

First and foremost: In VTK, you have an EXCELLENT product with brilliant
quality control so don't be afraid to change it to make it better. We will
cope with the changes! In particular, I think pipelining and widgets have to
change in the future (lots of work here!). You have some brilliant and
creative people working with you so I am confident in them and the
improvements they do!

To be more specific:

1) Please DON'T go back to including all of windows.h. It makes building
projects very complicated. I like the minimalist approach you have taken.

2) I always thought AddProp() and RemoveProp() didn't reflect what they were
really doing so AddViewProp() and RemoveViewProp() were OK changes with me.
All it really meant was that I had to go through the code and do a search
and replace. In my case this was no big deal.

3) If something is marked as deprecated in the current release, then it must
go in the next release. You have a nice mechanism in CMake alerting users to
deprecated features.

4) API's and VTK evolve so I think that we (the developers and users) must
evolve with it. This is a touchy point because we often build up huge
amounts of legacy code and it is a lot of work updating it. However I think
VTK must evolve to take advantage of new design paradigms, and while a lot
of it can be hidden, some aspects must be exposed. I also appreciate Will's
point in that the dependent documentation has to be updated which is often a
big task. I guess my fear here is that in time VTK will get relegated to
being a historical curiosity if it doesn't incorporate new design paradigms.


5) I also think that there is a problem in maintaining code compatibility
for older compilers. You are creating a lot of work for yourselves by
constantly inventing workarounds for the older compilers. I suspect that at
some point you are going to have to bite the bullet and say that "As from
VTK version xxx the following compilers are no longer supported: <fill in
compilers such as gcc 2.95, VC6 and older bcc compilers>. Definitely keep no
longer maintained older versions of VTK around for people who are unable to
update to the newer compilers, but don't let it constrain development of VTK

6) To cope with change, I am trying to keep applications running on the
latest versions. In some cases this is difficult, particularly when there
are other dependencies on other libraries e.g pthreads, boost etc.

I have used VTK since the very early versions and it has really changed
since then! This is its strength, and the reason why it is so successful.

As an aside, to me, the biggest problem in the MS Windows environment is the
total lack of standardization with respect to where libraries and header
files go (don't even mention dlls!). Some of my CMake files are horrendous!
Also proper symbolic links would be a godsend. In addition, I don't like the
fact that Visual Studio builds separate Release and Debug versions of the
code using separate directories - but I guess we have to live with this.


These are my views, some of it may be useful when developing policies.

Andrew 


-----Original Message-----
From: vtk-developers-bounces+a.maclean=cas.edu.au at vtk.org
[mailto:vtk-developers-bounces+a.maclean=cas.edu.au at vtk.org] On Behalf Of
Will Schroeder
Sent: Tuesday, 6 September 2005 00:21
To: Lorensen, William E (Research); Brad King
Cc: vtk-developers at vtk.org
Subject: [vtk-developers] RE: API Change

Hey Bill-

Quite frankly I have been annoyed with this particular API change as 
well. But when it gets down to it, the problem is with Microsoft's 
sucky compiler. As far as I understand, we are faced with problems no 
matter what we do, either inconsistencies in API or compile/link 
problems. Or if we again include windows.h everywhere there is the 
big hit on compile time, not to mention that (I suspect) in some 
cases the compiler will die because of too many includes.

(Bill, please indulge me here while I belabor this because I am 
forwarding this email to others who have not seen some of these
discussions.)

What I do with my applications is to require them to built against a 
particular version of VTK. I don't like to try to keep an application 
running on different versions of a library, whether it's VTK or 
other. Instead I depend on the tag/branch facilities of CVS. and make 
sure everything stays in synch. I prefer to move forward 'cause I 
don't like carrying the complexity around. Such API changes are very 
painful to me, Kitware, and the community (I have to go through 
several books, not to mention the various applications that we build 
on top of VTK). But I have seen what happens to a complicated 
software system when the API does not change and past features 
linger...a slow suffocation under its own weight/complexity. Of 
course, we could just come out with a new system each time 
(psychologically, adapting to a new system seems easier somehow), but 
this is no different than picking a version and sticking with it, 
except that the expectation is that with a new version there is 
backward compatibility, which is where the psychology gets bad when 
this doesn't happen.

We do try, sometimes we fail, to mark methods deprecated and keep 
them around for a while before removing them. And I'm not sure what 
to do about evolving software like the widgets, which are going 
through a big redesign. We are actually doing some cutting edge work 
here and none of us knows at this point how it's going to work out 
until we can use it for a while. Which means that API will certainly 
be broken along the way.

BTW Bill-- Ross Whitaker, you and I are supposed to come up with a 
backwards compatibility policy for the ITK Developer's Meeting in 
October (Stephen expects us to give a report). I can take an initial 
crack and we can iterate together.

Will



At 02:45 PM 9/4/2005, Lorensen, William E \(Research\) wrote:
>I guess we have different philosophies. I would prefer to protect 
>the large installed base of VTK users and keep the ugliness within VTK
itself.
>
>Bill
>
>-----Original Message-----
>From: Brad King [mailto:brad.king at kitware.com]
>Sent: Sunday, September 04, 2005 12:21 PM
>To: Bill Lorensen
>Cc: Sebastien BARRE; will Schroeder; Lorensen, William E (Research)
>Subject: Re: API Change
>
>
>Bill Lorensen wrote:
> > I can't follow the reasoning in that thread. Why couldn't AddProp be
> > retained, just calling AddViewProp? Seems like an arbitrary API change.
>
>A full explanation of the windows.h change is here:
>
>http://www.vtk.org/cgi-bin/viewcvs.cgi/Utilities/Upgrading/README.WindowsMa
ngling.txt?rev=HEAD&view=auto
>
>If AddProp is retained then RemoveProp should be retained too.  In order
>to retain RemoveProp and work with sources that include windows.h the
>definition must look like this:
>
>#ifdef VTK_WORKAROUND_WINDOWS_MANGLE
># define RemovePropA RemoveProp
># define RemovePropW RemoveProp
>#endif
>    void RemoveProp(vtkProp*);
>#ifdef VTK_WORKAROUND_WINDOWS_MANGLE
># undef RemovePropA
># undef RemovePropW
>    //BTX
>    void RemovePropA(vtkProp*);
>    void RemovePropW(vtkProp*);
>    //ETX
>#endif
>
>This ugliness is the reason the "Prop" API was deprecated and replaced
>with the "ViewProp" API.
>
>  >
>  > I noticed that Viewport's API changed recently. For example AddProp
>no longer exists. Why was it removed?
>  >  We have code now that needs lines like this:
>  >
>  > #if (VTK_MAJOR_VERSION == 4 && VTK_MINOR_VERSION <= 5)
>  >  foo->AddProp( volume );
>  > #else
>  >  foo->AddViewProp( volume );
>  > #endif
>
>Unfortunately this is inevitable when an API is deprecated and you want
>to write code that works with both the old and new version.  You can
>reduce the number of places that look like that by writing a header with
>code like this:
>
>template <class L, class R>
>void myprojAddProp(L l, R r)
>{
>#if VTK_MAJOR_VERSION > 4 || \
>     (VTK_MAJOR_VERSION == 4 && VTK_MINOR_VERSION >= 5)
>   l->AddViewProp(r);
>#else
>   l->AddProp(r);
>#endif
>}
>
>and then everywhere else just replace
>
>foo->AddProp(volume)
>
>with
>
>myprojAddProp(foo, volume)
>
>It is up to you whether this is more readable or easier to maintain than
>your current solution.
>
>-Brad

_______________________________________________
vtk-developers mailing list
vtk-developers at vtk.org
http://www.vtk.org/mailman/listinfo/vtk-developers