2011-06-17 Jeff Johnston <jjohnstn@redhat.com>

 * faq.html: Add some new items. 

1 files changed, 34 insertions, 0 deletions

diff --git a/faq.html b/faq.html
index 533aa5b..f457295 100644
--- a/faq.html
+++ b/faq.html
@@ -13,6 +13,9 @@ cross-compiler that it should, based on the --target setting. What is wrong?</a
 <li><a href="#q5">What does newlib do for chips that have optional features such as
 endianness or has different models with distinct instruction sets?</a>
 <li><a href="#q6">What is needed to port newlib to a new platform?</a>
+<li><a href="#q7">How do I regenerate various configuration files?</a>
+<li><a href="#q8">What version of autotools should I use to regenerate files?</a>
+<li><a href="#q9">When and how is newlib released?</a>
 </ul>
 <ol>
 <a name="q1"></a>
@@ -195,6 +198,37 @@ other platform-specific files would need to be ported as well.</p>
 
 <a href="#top">back to top</a>
 <p>
+<a name="q7"></a>
+<li>How do I regenerate various configuration files?
+<p>There are a few things to understand. First of all, aclocal needs to be run first where ever there is a configure.ac or configure.in file. The aclocal tool creates a set of macros that will be used by the generated configure script. This enables the end-user not to have to install autoconf or automake on their systems to run the configuration. The aclocal tool uses the configure.in or configure.ac files to determine what is needed so you need to run this whenever you change these files. The output of running aclocal is the aclocal.m4 file.</p>
+<p>Now, there is a special macro for newlib called NEWLIB_CONFIGURE. It is defined in the top-level newlib directory in acinclude.m4 and it has common logic such that special newlib configuration variables are handled. This macro should be included in every configure.in or configure.ac file in the newlib tree. Every call to aclocal should use a -I parameter that points to the newlib top-level directory. In addition, there are special m4 files in the top-level src directory that is the parent of newlib. This directory should also be specified via a -I parameter.</p>
+<p>The next thing to run is autoconf in a directory where there is a configure.in or configure.ac file. This generates the configure script for that directory. In general, you don't need to specify any parameters when calling autoconf.</p>
+<p>Finally, there is automake. Automake should be run after autoconf and specify a Makefile parameter for every directory that has a Makefile.am file. The role of automake is to take the Makefile.am file plus the configure script and create a Makefile.in which is the template for the configure script to create the final Makefile during configuration. In newlib, we run automake from the directory that contains a configure script and specify all sub-directories that do not have their own configure script. In addition, a special option is used: --cygnus. This determines special targets that will ultimately end up in the final Makefile. For example, the newlib/libc directory has a number of sub-directories that do not have their own configuration (e.g. string, stdlib, ctype). To generate Makefile.in files for each, we specify: automake --cygnus Makefile string/Makefile stdlib/Makefile ctype/Makefile ...).</p>
+<p>So, when do each of the tools need to be run? If you modify configure.in or configure.ac or the top-level acinclude.m4 file, you must run aclocal, then autoconf, and finally automake for that directory and all sub-directories that do not have their own configure.in/configure.ac. If all you change is Makefile.am, then all you need to run is automake. If you change no configuration input files, then you need not regenerate anything.</p>
+<p>The following shows the steps needed to be run in newlib/libc if one changes the configure.in file found in that directory.<xmp>
+ aclocal -I .. -I../..
+ autoconf
+ automake --cygnus Makefile argz/Makefile ctype/Makefile errno/Makefile \
+ iconv/Makefile locale/Makefile misc/Makefile posix/Makefile reent/Makefile \
+ search/Makefile signal/Makefile stdio/Makefile stdio64/Makefile \
+ stdlib/Makefile string/Makefile syscalls/Makefile time/Makefile \
+ unix/Makefile iconv/ccs/Makefile iconv/ces/Makefile iconv/lib/Makefile \
+ iconv/ccs/binary/Makefile
+</xmp>
+<p>Note how we do not specify the machine or sys sub-directories. This is because they both have their own configure.in files. Also note that we must specify a number of subdirectories of iconv. This is because they have Makefile.am files and the closest configure.in/configure.ac parent file for them is the one found in libc.</p>
+<a href="#top">back to top</a>
+<p>
+<a name="q8"></a>
+<li>What version of autotools should I use for regenerating files?
+<p>Newlib doesn't attempt to be bleeding-edge when it comes to autotool usage. Each snapshot release will be made using a set of autotools felt to be stable. You can determine the versions that were used by looking at the generated files (each documents what level was used). For example, to see the level of autoconf, look inside the configure script you wish to regenerate. To see the level of automake, look inside a Makefile.in file. Using the same version of the tool as was used previously is usually recommended, but you may have more recent tools installed on your system. If you do not have commit rights, you should omit submitting generated files and allow a committer to regenerate them for you. In some cases, committers may start using newer versions of autotools for various changes as we approach the date of a snapshot.</p>
+<p>
+<a href="#top">back to top</a>
+<p>
+<a name="q9"></a>
+<li>When and how is newlib released?
+<p>Newlib currently has a yearly snapshot which is taken in December. The snapshot is taken from the source code repository and tar'd. The tar file is made available here through the newlib web-site: http://sourceware.org/newlib. Newlib does not have a formal test cycle so a snapshot is not necessarily more stable than the current repository contents. Testing does occur as a number of consumers of newlib such as Cygwin and RTEMS do extra testing as time draws nearer to a snapshot. In general, one is advised to try using the source repository as it contains the latest fixes. No fixes are posted to snapshot releases.</p>
+<p>
+<a href="#top">back to top</a>
 </ol>
 </body>
 </html>