Yo all
As you may have seen from earlier emails, I encountered some
difficulty in modifying existing APIs within the streamlined build
system. After some effort, I think I have defined a method for
modifying the API-level of a subsystem that gets around some of the
problems. I thought I might share it so others don't make the same
mistakes I did.
The process involves multiple steps:
1. Do NOT modify the existing API function that you want to change.
Instead, create a new function with a new name. If you are working in
a framework, put this in the framework's base, but do NOT add it to
the framework's API definition at this time. Since it is a new
function, nobody will have called it yet, so you won't have to make
any changes to the tree to get it to compile. Be sure to add any
initialization the function requires to the respective open function.
For any global variables needed by the function, create new ones and
give them distinctive names - we'll revise the names later to remove
any duplications.
2. Test the new function with a unit test (or your favorite optional
approach) . Since the new function is in the base of a framework, it
will be statically linked, so you can call it without concern once
that framework has been initialized.
3. Once you are convinced the new function is working properly and
that its API is solid, convert a few of the functions that call the
old API function to the new one and test that the combination does
what you want. Since you built the new API as a base function, you
can call it directly for now - we'll fix it later.
4. Now that things look solid, move the new API function to the API
definition and replace the old one. This will force you to modify
every place in the tree that calls the function, but (a) at least now
you only have to do it once, and (b) you know that your new function
works, so any problems are likely to lie in the way it is called. Be
sure to resolve any duplications in global variables, and to update
the respective open function accordingly.
Just a suggested process based on some painful experience.
Ralph
