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.

Reply via email to