On Sun, 2009-05-24 at 14:06 -0700, David Brownell wrote: > On Saturday 23 May 2009, Zach Welch wrote: > > 1) library header file rework: > > a) rename src/ as openocd/ (preferred) > > - this will allow public #include, e.g. <openocd/jtag/jlink.h> > > b) do not rename src, e.g. #include <jtag/jlink.h> > > - something needs to be done; the library work is only half-complete > > - i have a patch for "unit tests", based on this "external interface" > > - > > http://www.mail-archive.com/openocd-development@lists.berlios.de/msg04077.html > > While src/ is a bit odd (it's a source tree, *everything* is > some kind of source code), I'd suggest instead creating a > new include/ area to hold only files which will be getting > commitment for such public usage.
This is common and I suppose that I should have listed it (to be fair), but I am not a particular fan for the fact that it splits the interface and implementation into different trees. To support the long names, the file I gave as an example would be include/openocd/jtag/jlink.h. Yuck. Both options that I presented require minimal invasiveness; no files need to be moved. This option also requires new directories to be created and individual files moved (or maybe the whole src/ tree copied and .c files deleted). This should not be used to judge the merits of each for starting new projects, but I think it comes into consideration when thinking about ways the change-over process might go wrong. I am trying to "KISS" with the process as much as with the results. > That seems reasonable for 0.2.x ... I think supporting any > library interface as "stable" before 0.3.x seems unwise, > considering the current interface hasn't particularly been > identified (include/*) much less carefully reviewed. I agree. In fact, I am not particularly interested in being "strict" about stability until 1.0.0. I silently agreed with this point when it was raised originally (after I first posted about the library topic). A "stable" interface can become a veritable straight-jacket that prohibits innovation and development. We should be in no hurry to put ourselves under such restrictions. My primary goal with the library work will be to allow us to strengthen the APIs for the project's own internal use of the code. Building real applications with them should be one ultimate strategic goal; however, anyone pursuing such today needs to expect to rewrite them in tandem with OpenOCD's API changes. For now, I want this effort to help clarify -- for our collective understanding and documentation -- how these pieces have been designed to fit together. This work will also expose what we can test, which will force further refinements to the APIs (as we realize how many warts there are left). While I would like to see a trend toward more and more stability, we should always give ourselves room to fix our problems. If nothing else, we can simple start releasing 1.0, 2.0, 3.0, and so on with nothing in between them. ;) Cheers, Zach _______________________________________________ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
