On Mon, 2009-06-29 at 18:32 -0700, David Brownell wrote: > On Monday 29 June 2009, Zach Welch wrote: > > > > +That OpenOCD Users's Guide contains information about OpenOCD-specific > > > > +configuration options that are available. > > > > > > I'd rather not see the User's guide get further clutter like > > > such config/install instructions... those are for developers, > > > or maybe packagers, not normal users. > > > > Okay, except those options are already described therein. I am all for > > moving them, but I opted for a "least change" type of patch to start. > > Personally, I think the recent discussions (and my "packaging for 0.2.0" > > post) point us in the direction that you are suggesting, so I would be > > happy to see us move these bits to the Developer Manual at this time. > > > > Thoughts? > > Ideally, in my book, README says how to make a quick > build that works for better than 90% of folk ... by > using "sh configure" ... maybe with --prefix, but not > needing anything else. And "sh configure --help" has > good enough explanations about what each option means.
I guess my thought was that a simple 'configure' should be enough to run 'make docs' (if all the tools have been installed). From there, users could re-run configure with the proper options. Clearly, it would be better to have them run it once with the correct options. > Clearly we're not there today. Example, "configure" > doesn't just notice that libftdi is present and then > enable all FT2232-based drivers by default (using that > code not D2XX). Or failing that, that D2XX is there. > (Or failing both, warn that the "signature" support > of OpenOCD is missing...) And "configure --help" > doesn't show which settings are default vs not... > > So I guess I'm thinking I'd like to see the config > scripts simplified to that point, so that there's > much less of a need to resolve questions like where > the doc should sit. :) Yes, but I do not want to muck with those portions of the configure script at this point. There are several other things that I want to "break in order to fix" therein, beyond the problems you mention. > Plus note the chicken/egg thing: it should not > be necessary to build the software in order to get > docs about how to configure it... I am now thinking that all of this information should be contained in the README file. In revisiting this patch, I also started to think about leaving the INSTALL file unmodified from the GNU version, so it can be updated easily when upstream changes are made to it. In that respect, the file could be removed; it can be replaced automatically by automake during the bootstrap stage. I have tested that process here, and it works with another small patch to switch from --foreign to --gnu mode in our automake configuration. Attached is a new patch that can be substituted for the original #6 in the series. Cheers, Zach
Further improve README file to introduce the project to new users. Add reference to standard INSTALL file. Add notes about required Subversion repository build steps. --- README | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) ====== diff -u README README --- README (working copy) +++ README (working copy) @@ -1,6 +1,42 @@ Welcome to OpenOCD! +=================== -The INSTALL file contains tips to configure and compile the source. +OpenOCD provides on-chip programming and debugging support with a +layered architecture of JTAG interface and TAP support, debug target +support (e.g. ARM, MIPS), and flash chip drivers (e.g. CFI, NAND, etc.). +Several network interfaces are available for interactiving with OpenOCD: +HTTP, telnet, TCL, and GDB. The GDB server enables OpenOCD to function +as a "remote target" for source-level debugging of embedded systems +using the GNU GDB program. + +This README file contains an introduction to the installation process, +as well as how to access the full documentation. + +OpenOCD Installation +==================== + +The INSTALL file contains generic instructions for running 'configure' +and compiling the OpenOCD source code. That file is provided by default +for all GNU automake packages, and those instructions should enable new +developers produce the OpenOCD User's Guide using the 'make' system. + +The OpenOCD Users's Guide contains information about OpenOCD-specific +configuration options that are available and details about building +and packaging. (TODO: move that material to Developer's Manual, or here). + +Building From The Subversion Repository +*************************************** + +1) Check out the latest code from the OpenOCD Subversion Repository URL: + + http://svn.berlios.de/svnroot/repos/openocd + +2) Run './bootstrap' to create the 'configure' script. + +3) Run './configure --enable-maintainer-mode' with other options. + +OpenOCD Documentation +===================== The OpenOCD User's Guide can be produced in two different format
_______________________________________________ Openocd-development mailing list [email protected] https://lists.berlios.de/mailman/listinfo/openocd-development
