Conclusion

Finishing Touches

The final script appears at the end of this article.

The Windows problem I mentioned earlier is caused by the platform specific directory path separator. Unix uses forward slashes, Windows backslashes. My chosen solution is to work with normalised paths internally until we actually write out the include files, when we make sure forward slashes are used as separators.

As a gesture towards user-friendliness I have added an indication of progress and an output log. However, this script remains very much for software developers who understand what it's doing. I have chosen sys.stdout.write in preference to the print statement used during the script's development, since it gives greater control over output format.

I have not done anything special with Makefiles, project files, Jamfiles – or whatever else you use with your build system. There will be an order of magnitude fewer of these to deal with (unless you have a very strange build system), but the same techniques can be applied.

The script as it stands has several weaknesses. It is, of course, suited to doing a very specific job: solving the exact problem laid out at the start of this article, right down to the specified directory mapping. Whilst it would be overkill to provide a GUI allowing users to enter this mapping, this input data could usefully be separated from the body of the script. Similarly, as already mentioned, the script makes some big assumptions about way include paths are used in this particular system. Finally, there are no unit tests – the only testing has been a rather ad hoc probing of functions during the script's development.

On Scripted Solutions

This sort of bulk re-arrangement of files is well suited to a scripted solution for reasons of:

Reliability. The script can be shown to work by unit tests and by system tests on small data sets. Then it can be left to do its job.
Efficiency. Editing dozens – perhaps hundreds – of files by hand is error prone and tedious. What's worse, unless some moratorium on check-ins has been imposed during the restructure, the new structure may be out of date before it is ready. A script can process Megabytes of source in minutes. Alternatively, it will happy to run at night after even the most nocturnal of programmers has logged out.
Recordability. The script becomes part of the source tree (perhaps in the tools/scripts directory, in which place it can record accurately and repeatably the tasks it performs.
Reusability. A well-written script can be amended and enhanced to solve future source re-organisations. And even if it can't be re-used, a knowledge of scripting can.