Committed: update simtest-howto.html
diff mbox

Message ID alpine.BSF.2.02.1409101542360.95978@arjuna.pair.com
State New
Headers show

Commit Message

Hans-Peter Nilsson Sept. 10, 2014, 7:46 p.m. UTC
(Thanks to people CC'ed and others forgotten; I hope I
incorporated at least some of everyone's suggestions.)

First, as noted, the instructions are outdated due to repos merging,
splitting, moving and switching, with fallout such as it now seemed
odd as-is with one minor component randomly being named "src".  (It's
a CVS artefact: when the "-d topdir" option is used, cvs-1.11.22 gets
confused over the "newlib" subdirectory different to the "newlib" CVS
module; add -N and you get the "src" subdirectory anyway, within
"topdir".  Love CVS!  If someone has a simple working solution just
using options and it works for me too, we can call the newlib topdir
something else than "src".  In the meantime, not going there.)

There was other outdated information, such as gcc-2.95 being a valid
host-gcc.  Hah!  Better point to the general build prerequisites.

Also, the idea of using a *combined* tree here, has been challenged,
so I toned down the wording from the actual "require" to the
negation(!)  and added an apologetic blurb.  (For my own autotester, I
use a separate install as mentioned in the blurb, if only to simplify
not depending on a simultaneous working state, but I wouldn't do a
separate build just for newlib, so some kind of combination
instructions seems called for anyway.)

There has also historically been people doing their edits in the
combined tree.  (Understandable; that's where gdb points...)
Better add a few words about that.

With the combined binutils-gdb.git used as-is, now GDB has to be
manually disabled so we don't have to worry about its target
obsoletion triggers.  The gdb we're likely to use it probably the host
gdb anyway.  (If it's recent enough that is; if not, it might be a
good idea to install a native build somewhere locally, to apply on the
cross-gcc.)

Also arm-elf is obsoleted, so let's choose arm-eabi for the example.
Except when trying that, thebuild gets lost building libjava.

(Target maintainers: don't be afraid to add a clause for your target
in the *first* case in top/configure.ac where unsupported_languages is
set for a target, for languages you never use and never intend to
build.  For example, I know vax should do a
'unsupported_languages="$unsupported_languages
<everything-except-c>"', as last time I checked, it didn't build for
c++ and when checked, only C support was intended.)

Rather than choosing a target which mostly by coincidence doesn't
enable java (lack of libffi), I just added a language option to make
it more likely for a random build for a random target to complete.
ISTR reports to the gcc-testresults@ for several targets but just for
c and c++ enabled.  If you think this is a bad move, I'd value work
fixing the situation in the right way (see above) higher than just an
opinion.  Also, the reason is explained and people are free to not use
--enable-languages when testing.  I see mcore-elf build; I could use
that instead but let's not go to far off main-stream.  I could use
cris-elf if I also wanted decent test-results, but I'm probably too
biased to offer that with a straight face. ;)

As a future step, we may want to just drop the status-ish table at the
end, for one it's out of date by a decade.

Briefly watched locally, committed; watched again on-line to catch
glaring mark-up errors.

brgds, H-P

Comments

Oleg Endo Sept. 10, 2014, 8:14 p.m. UTC | #1
Hi,

On Wed, 2014-09-10 at 15:46 -0400, Hans-Peter Nilsson wrote:
> (Thanks to people CC'ed and others forgotten; I hope I
> incorporated at least some of everyone's suggestions.)
> 
> [...]
> Also, the idea of using a *combined* tree here, has been challenged,
> so I toned down the wording from the actual "require" to the
> negation(!)  and added an apologetic blurb.

It says:
"Testing with a simulator makes use of a combined tree here; you can't
easily build newlib, required for simulator testing,..."

I don't understand why newlib can't be built for simulator testing
easily outside of a combined tree.  Are you referring to the separate
make all-gcc - build newlib - continue with full gcc build?  Or is it
just a coincidence that it works rather easily on SH?

" other alternatives exist. For example, binutils and simulators can be
built for the target, and installed beforehand."

I still think we should somehow document how to do that.  The info is
scattered out there on the net, but it'd be easier to have it on the
official doc pages.

Cheers,
Oleg
Hans-Peter Nilsson Sept. 10, 2014, 8:56 p.m. UTC | #2
On Wed, 10 Sep 2014, Oleg Endo wrote:
> On Wed, 2014-09-10 at 15:46 -0400, Hans-Peter Nilsson wrote:
> > (Thanks to people CC'ed and others forgotten; I hope I
> > incorporated at least some of everyone's suggestions.)
> >
> > [...]
> > Also, the idea of using a *combined* tree here, has been challenged,
> > so I toned down the wording from the actual "require" to the
> > negation(!)  and added an apologetic blurb.
>
> It says:
> "Testing with a simulator makes use of a combined tree here; you can't
> easily build newlib, required for simulator testing,..."
>
> I don't understand why newlib can't be built for simulator testing
> easily outside of a combined tree.

Why would that be an improvement?  At most it'd be break-even.

>  Are you referring to the separate
> make all-gcc - build newlib - continue with full gcc build?

It's not clear to me what you mean and I haven't done a build
from newlib sources separate from gcc in any way.  It seems to
add at least one step and just remove the merge of the newlib
tree.  You'd also have to point at the newlib sources with
separate configure-options.  Why a separate "make all-gcc" if
you can point it at the newlib sources from the beginning?
Maybe it's still easier than "can't easily", maybe better with
some other wording?  I forgot to say "suggestions are welcome"
(but wholesale rewrites aren't, sorry for sounding apologetic).

>  Or is it
> just a coincidence that it works rather easily on SH?

I don't know, have you actually tried it on other targets?
I'd suggest you do that before any improvement suggestion.
(I built arm-eabi and mcore-elf with the updated
simtest-howto.html)

Have you inspected the configuration and build logs? I see
sh-elf doesn't use libgloss, so I'm leaning towards a tentative
"yes" to your question.

> " other alternatives exist. For example, binutils and simulators can be
> built for the target, and installed beforehand."
>
> I still think we should somehow document how to do that.

I assume you mean the general configure && make all install, as in
binu+gdb/configure --target=... --prefix=... && make all install
(Not forgetting to include .../bin in your $PATH.)

>  The info is
> scattered out there on the net, but it'd be easier to have it on the
> official doc pages.

Maybe but please put that in the official documentation.

This page isn't that; that'd be in the .texi pages or maybe the
wiki depending on your taste.  This is not the "build and
install a simulator toolchain to develop your own programs"
documentation, this is the "build a simulator to test gcc"
howto.  IMO this page will not improve by adding detailed
instructions for several alternatives.  The intended audience is
people working on gcc but just about grasping the concept of a
cross-compiler and who actually wants a reasonably simple way to
test their patches on a wider set of targets than their native
x86_64 box.

brgds, H-P

Patch
diff mbox

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>