Documentation update

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3505 42af7a65-404d-4744-a932-0658087f49c3

3 files changed, 88 insertions, 11 deletions

diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html
index b55dc6fd9..4f9b0694f 100644
--- a/nuttx/Documentation/NuttxPortingGuide.html
+++ b/nuttx/Documentation/NuttxPortingGuide.html
@@ -12,7 +12,7 @@
       <h1><big><font color="#3c34ec">
         <i>NuttX RTOS Porting Guide</i>
       </font></big></h1>
-      <p>Last Updated: April 7, 2011</p>
+      <p>Last Updated: April 14, 2011</p>
     </td>
   </tr>
 </table>
@@ -981,7 +981,11 @@ include/
 <ul><pre>
 tools/
 |-- Makefile.host
+|-- README.txt
 |-- configure.sh
+|-- cfgparser.c
+|-- cfgparser.h
+|-- define.sh
 |-- incdir.sh
 |-- indent.sh
 |-- link.sh
@@ -990,11 +994,19 @@ tools/
 |-- mkimage.sh
 |-- mknulldeps.sh
 |-- mkromfsimg.sh
+|-- mksyscall.c
+|-- mkversion.c
 |-- unlink.sh
+|-- version.sh
 |-- winlink.sh
-`-- zipme
+`-- zipme.sh
 </pre></ul>
 
+<p>
+  Refer to the README file in the <code>tools</code> directory for more information about the individual files.
+  Some of these tools are discussed below as well in the discussion of <a href="#configandbuild">configuring and building</a> NuttX.
+</p>
+
 <h2>2.16 <a name="topmakefile">nuttx/Makefile</a></h2>
 <p>
   The top-level <code>Makefile</code> in the <code>${TOPDIR}</code> directory contains all of the top-level control
@@ -1105,7 +1117,7 @@ netutils/
 <p>
   And if <code>configs/</code><i>&lt;board-name&gt;</i><code>/[</code><i>&lt;config-dir&gt;</i><code>/appconfig</code>
   exists and your application directory is not in the standard loction (<config>../apps</config>),
-  then you should also specify the location of the application directory on the +command line like:
+  then you should also specify the location of the application directory on the command line like:
 </p>
 <ul><pre>
   cd tools
@@ -1113,6 +1125,51 @@ netutils/
 </pre></ul>
 
 <p>
+  <b>Version Files</b>.
+  The NuttX build expects to find a version file located in the top-level NuttX build directory.
+  That version file is called <code>.version</code>.
+  The correct version file is installed in each versioned NuttX released.
+  However, if you are working from an SVN snapshot, then there will be no version file.
+  If there is no version file, the top-level <code>Makefile</code> will create a dummy <code>.version</code> file on the first make.
+  This dummy version file will contain all zeroes for version information.
+  If that is not what you want, they you should run the <code>version.sh</code> script to create a better <code>.version</code> file.
+</p>
+
+<p>
+  You can get help information from the <code>version.sh</code> script using the <code>-h</code> option.
+  For example:
+</p>
+<ul><pre>
+$ tools/version.sh -h
+tools/version.sh is a tool for generation of proper version files for the NuttX build
+
+USAGE: tools/version.sh [-d|-h] [-b build] -v &lt;major.minor&gt; &lt;outfile-path&gt;
+
+Where:
+        -d
+                Enable script debug
+        -h
+                show this help message and exit
+        -v &lt;major.minor&gt;
+                The NuttX version number expressed a major and minor number separated
+                by a period
+        &lt;outfile-path&gt;
+                The full path to the version file to be created
+</pre></ul>
+
+<p>
+  As an example, the following command will generate a version file for version 6.1 using the current SVN revision number:
+</p>
+<ul><pre>
+tools/version.h -v 6.1 .version
+</pre></ul>
+
+<p>
+  The <code>.version</code> file is also used during the build process to create a C header file at <code>include/nuttx/version.h</code> that contains the same version information.
+  That version file may be used by your C applications for, as an example, reporting version information.
+</p>
+
+<p>
   <b>Additional Configuration Steps</b>.
   The remainder of configuration steps will be performed by <a href="#topmakefile"><code>${TOPDIR}/Makefile</code></a>
   the first time the system is built as described below.
@@ -1154,7 +1211,8 @@ The system can be re-made subsequently by just typing <code>make</code>.
   These additional steps include:
 </p>
 <ul>
-  <li>Auto-generating the file <code>include/nuttx/config.</code> using the <code>${TOPDIR}/.config</code> file.
+  <li>Auto-generating the file <code>include/nuttx/config.h</code> using the <code>${TOPDIR}/.config</code> file.
+  <li>Auto-generating the file <code>include/nuttx/version.h</code> using the <code>${TOPDIR}/.version</code> file.
   <li>Creating a link to <code>${TOPDIR}/arch/</code><i>&lt;arch-name&gt;</i><code>/include</code> at <code>${TOPDIR}/include/arch</code>.
   <li>Creating a link to <code>${TOPDIR}/configs/</code><i>&lt;board-name&gt;</i><code>/include</code> at <code>${TOPDIR}/include/arch/board</code>.
   <li>Creating a link to <code>${TOPDIR}/configs/</code><i>&lt;board-name&gt;</i><code>/src</code> at <code>${TOPDIR}/arch/</code><i>&lt;arch-name&gt;</i><code>/src/board</code>
diff --git a/nuttx/tools/README.txt b/nuttx/tools/README.txt
index 76ec3a66f..14783ae56 100755
--- a/nuttx/tools/README.txt
+++ b/nuttx/tools/README.txt
@@ -17,20 +17,33 @@ configure.sh
   target board.  See configs/README.txt or Documentation/NuttxPortingGuide.html
   for a description of how to configure NuttX with this script.
 
-mkconfig.c
+mkconfig.c, cfgparser.c, and cfgparser.h
 
   This is C file that is used to build mkconfig program.  The mkconfig
   program is used during the initial NuttX build.
 
   When you configure NuttX, you will copy a configuration file called .config
-  into the top level NuttX directory (See configs/README.txt or
+  in the top level NuttX directory (See configs/README.txt or
   Documentation/NuttxPortingGuide.html).  The first time you make NuttX,
   the top-level makefile will build the mkconfig executable from mkconfig.c
-  (using Makefile.mkconfig).  The top-level Makefile will then execute the
+  (using Makefile.host).  The top-level Makefile will then execute the
   mkconfig program to convert the .config file in the top level directory
   into include/nuttx/config.h.  config.h is a another version of the
   NuttX configuration that can be included by C files.
 
+mkversion.c, cfgparser.c, and cfgparser.h
+
+  This is C file that is used to build mkversion program.  The mkversion
+  program is used during the initial NuttX build.
+
+  When you build NuttX there should be a version file called .version in
+  the top level NuttX directory (See Documentation/NuttxPortingGuide.html).
+  The first time you make NuttX, the top-level makefile will build th
+  mkversion executable from mkversion.c (using Makefile.host).  The top-
+  level Makefile will then execute the mkversion program to convert the
+  .version file in the top level directory into include/nuttx/version.h.
+  version.h provides version information that can be included by C files.
+
 mksyscall.c
 
   This is C file that is used to build mksyscall program.  The mksyscall
@@ -56,7 +69,8 @@ mksyscall.c
 Makefile.host
 
   This is the makefile that is used to make the mkconfig program from
-  the mkconfig.c C file or the mksyscall program from the mksyscall.c file.
+  the mkconfig.c C file, the mkversion program from the mkconfig.c C file,
+  or the mksyscall program from the mksyscall.c file.
 
 mkromfsimg.sh
 
@@ -80,7 +94,13 @@ mknulldeps.sh
     MKDEP = $(TOPDIR)/tools/mknulldeps.sh
 
   The mknulldeps.sh is a stub script that does essentially nothing.
-  
+
+define.sh
+
+  Different compilers have different conventions for specifying pre-
+  processor definitions on the compiler command line.  This bash
+  script allows the build system to create create command line definitions
+  without concern for the particular compiler in use.
 
 incdir.sh
 
diff --git a/nuttx/tools/version.sh b/nuttx/tools/version.sh
index e098695a7..7cad7ee03 100755
--- a/nuttx/tools/version.sh
+++ b/nuttx/tools/version.sh
@@ -57,8 +57,7 @@ while [ ! -z "$1" ]; do
 		VERSION=$1
 		;;
 	-h )
-		echo "$progname is a tool for flexible generation of include path arguments for a"
-		echo "variety of different compilers in a variety of compilation environments"
+		echo "$0 is a tool for generation of proper version files for the NuttX build"
 		echo ""
 		echo $USAGE
 		echo ""