Index: simtest-howto.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/simtest-howto.html,v
retrieving revision 1.29
retrieving revision 1.30
diff -p -u -r1.29 -r1.30
--- simtest-howto.html	27 Jun 2014 11:48:46 -0000	1.29
+++ simtest-howto.html	10 Sep 2014 19:37:25 -0000	1.30
@@ -16,22 +16,32 @@

     <h2>Set up sources</h2>

-    <p>Testing with a simulator requires use of a combined tree;
+    <p>Testing with a simulator makes use of a combined tree here;
     you can't easily build newlib, required for simulator testing,
     outside of a combined tree, and the build of the other components
-    is easiest in a combined tree.</p>
+    is easiest in a combined tree.  A combined tree is not a
+    <em>requirement</em> for testing with a simulator; other alternatives
+    exist.  For example, binutils and simulators can be built for the
+    target, and installed beforehand.  However, we use a combined tree
+    here as it's a convenient example and does not require separate
+    installation steps or parameters.</p>

-    <p>The combined tree contains GCC sources plus several modules of
-    the <code>src</code> tree: <code>binutils</code> and
-    <code>newlib</code> for the build and <code>sim</code> for the
+    <p>The combined tree contains GCC sources plus <code>binutils</code> and
+    <code>newlib</code> for the generated code and <code>sim</code> for the
     simulators. If you already build with a combined tree you can use
     your current setup; if not, these instructions will get you the
     sources you need.</p>

-    <h3>Check out initial CVS trees</h3>
+    <p></p>

-    <p>If you don't yet have either tree you'll need to do an initial
-    check-outs.</p>
+    <h3>Check out initial trees</h3>
+
+    <p>We check out each component from each separate project's
+    version-control-system repository, but it's possible to use
+    release or snapshot tarballs, with an increased risk of version
+    lag causing configuration framework mismatches in the combined
+    tree.  If you don't yet have either tree you'll need to do some
+    initial check-outs.</p>

     <p>Check out mainline GCC:</p>

@@ -43,19 +53,26 @@ cd ${TOP}/gcc
 contrib/gcc_update --touch
 </pre>

-    <p>Check out the <code>src</code> tree:</p>
+    <p>Check out the <code>newlib</code> (src) tree:</p>

 <pre>
 cd ${TOP}
 cvs -d :pserver:anoncvs@sourceware.org:/cvs/src login
 # You will be prompted for a password; reply with "anoncvs".
-cvs -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils newlib sim
+cvs -d :pserver:anoncvs@sourceware.org:/cvs/src co newlib
+</pre>
+
+    <p>Check out the <code>sim</code> and <code>binutils</code> tree:</p>
+
+<pre>
+cd ${TOP}
+git clone git://sourceware.org/git/binutils-gdb.git sim+binutils
 </pre>

-    <h3>Update CVS trees</h3>
+    <h3>Update trees</h3>

-    <p>You can update existing CVS trees rather than starting from
-    scratch each time.  Update the GCC tree using the
+    <p>You can update existing CVS, git and subversion trees rather than
+    starting from scratch each time.  Update the GCC tree using the
     <code>gcc_update</code> script, which touches generated files and
     handles directory changes in the tree.  Be sure to do this from
     the directory in which you did the original check-out, NOT in the
@@ -66,17 +83,23 @@ cd ${TOP}/gcc
 contrib/gcc_update
 </pre>

-    <p>Update the <code>src</code> tree with the same sequence of
-    commands that you used to check out that tree initially, invoked from
-    the <code>src</code> directory (NOT from within the combined tree).</p>
+    <p>Update the newlib <code>src</code> tree with the same sequence of
+    commands that you used to <em>check out</em> that tree initially
+    (edits in the <code>src</code> tree will be preserved).
+    Make sure you do <em>not</em> do this from within the combined tree.
+    For the binutils+sim tree a normal <code>git pull</code> command will do.
+    Remove the combined tree and re-create it.  (Beware, edits in the
+    combined tree will be lost.)</p>

     <h3>Create a combined tree</h3>

     <p>Create a tree that consists of all of the files from the GCC and
     binutils/sim/newlib source trees (including several simulators in
-    <code>src/sim</code>), with the GCC files overriding the
-    binutils/sim/newlib files when there's a conflict.  It's done this
-    way because the GCC files are the master copy.  To save on disk
+    the <code>sim</code> directory), with the GCC files overriding the
+    binutils/sim/newlib files when there's a conflict, and binutils and
+    with sim overriding newlib files.  It's done this way because the GCC
+    files are the master copy, while binutils and gdb move faster than
+    newlib. To save on disk
     space, these commands actually make a tree of hard links rather
     than duplicating all the files:</p>

@@ -85,25 +108,30 @@ cd ${TOP}
 rm -rf combined
 mkdir combined
 cd src &amp;&amp; find . -print | cpio -pdlm ../combined &amp;&amp; cd ..
+cd sim+binutils &amp;&amp; find . -print | cpio -pdlmu ../combined &amp;&amp; cd ..
 cd gcc &amp;&amp; find . -print | cpio -pdlmu ../combined &amp;&amp; cd ..
 </pre>

     <h2>Build it</h2>

-    <p>Use a recent version of GCC as the build compiler, no earlier
-    than 2.95.</p>
+    <p>Make sure the
+    <a href="http://gcc.gnu.org/install/prerequisites.html">building
+    prerequisites</a> for GCC are met, for example a host GCC no earlier
+    than 3.4 or later, with C++ support enabled.</p>

     <p>The target name suitable for the simulator is usually `*-elf' for a
     target `*'.  There are some exceptions, for instance on powerpc
-    it's powerpc-eabi or powerpc-eabisim.  Here we build
-    <code>arm-elf</code>.</p>
+    it's powerpc-eabi or powerpc-eabisim, and for arm, the arm-elf support
+    is obsoleted.  Here we build <code>arm-eabi</code>, but we avoid gdb
+    and build only for the c and c++ languages, because some of the targets
+    mentioned below will otherwise fail building.</p>

 <pre>
 cd ${TOP}
 mkdir build install
 cd build
 ../combined/configure \
-    --target=arm-elf --prefix=${TOP}/install
+    --target=arm-eabi --disable-gdb --enable-languages=c,c++ --prefix=${TOP}/install
 make
 </pre>

