Re: [ECOS] Newbie feedback and braindump.

[Peter Lister <prl at peterlister dot co dot uk>]

On Thu, 2003-11-06 at 09:38, Andrew Lunn wrote:

> A technical point first. Be careful of your terminology. You are
> mixing up the words targets and templates.

I am very, very careful with my terminology, often to the point where
I'm accused of pedantry. One of things I am trying to convey is that the
help for newcomers is poor at pointing out the target / template
distinction, making it harder than necessary to perceive decisions.

While I'm sure you are trying to help, and I understand that you are
making sure that I *do* understand this distinction, you are being a bit
presumptious in stating that I'm mixing things up. I should make it
clear that I have a fairly good understanding of this sort of thing; I
have worked on kernel code designed to work in an OS abstraction which
accommodated Linux and Solaris, and I'm familiar with Etherboot and
LinuxBIOS. I'm just a newbie to eCos.

The point I'm trying to make is precisely that it took some time to work
out that the way I make a library for a specific *target* is indeed
defined in the first instance by the *template* I choose. Futher, when
presented with a list of templates that Linux Synthetic - which appears
way down a flat list which gives no clear cues that I might need to be
looking for something else rather than the obvious "PC" one at the top -
the documentation told me to choose one and the default seemed OK.

Just to make it clear - I'm raising this on ecos-discuss not to ask for
help, but as a heads-up to those maintaining the documentation and
configuration code that there are some problems. I'm criticising the
fact that the *process* is a bit clunky, but I perceive that the reason
is just the common one when directions e.g. within a city are given to a
newcomer by people who know the place well; they're *so* familiar with
it, that they forget that there are "obvious" landmarks which need to be
pointed out to because they are *not* obvious to non-locals. The best
way to get such problems sorted out is to ask a non-local to run the
route and add the details which they actually needed - so that's what
I'm doing here.

> You mistake here is mixing up template and target. You selected a
> target, not a template.

I selected a template. Sorry, but that's how the GUI presents the
ability to build a working library for a target.

> Well, the instructions say:
> 
> $ cd <somewhere suitable>
> $ mkdir synth_build
> $ cd synth_build
> 
> This will result in an new empty directory. Always.

"somewhere suitable" is not clearly defined or even hinted at, so I
*had* to interpret what the docs would have me do. I now realise that
the intention was to suggest that a newcomer should work in a new
directory. But the doc didn't *say* that (we can argue forever about
what was *meant*, but I can only go by what I *read*).

And, normally, creating a new directory is the kind of thing which
appears in installation docs for people who aren't used to Unix like
systems. Interestingly, the thing which is actually *prescribed* above
is the name "synth_build", even though this is *not* actually a
requirement. While we're here, I'd suggest that using "angle brackets"
is not a good way to represent a name substitution on a Unix command
line.

Good documentation tells one *what* to do AND *why*. Once good reason -
quite apart from the fact that it educates the new comer, is that one
usually helps resolve ambiguities in the other.

> Look at it the other way around, the way you have interpreted it. If
> it wanted you to go into a specific directory which already existed
> and had the name synth_build, it would not have said "cd somewhere
> suitable". It would of explicitly told you to goto that
> directory. Does these instructions in any way suggest to use an
> existing directory? 

In the circumstance I found myself in, it seemed entirely plausible that
the documentation was failing by telling me not to bother creating a
directory of this name if I already had one, rather than failing to tell
me that the point was to create a new working directory (name
unimportant) and cd to it.

> Do they suggests they might be already a directory called synth_build? 

They certainly suggest that's the name wanted, since the typographical
convention used didn't imply that another name could be substituted.
I'll concede that this didn't make a great deal of sense at the time,
but I was genuinely trying to follow the instructions as rigourously as
I could, given that the "how" was incomplete and there wasn't any "why".

> So instead of following the instructions you have done something
> slightly different which has resulted in you getting into problems.

Undoubtedly I did something different from what was *intended*: hey, I'm
the one pointing this out to you guys. But, looking back at my thought
processes, I don't think I did anything wrong, given the context I found
myself in.

> When im faced with something new, i try to follow the instructions
> exactly. I don't try to interpret them and make changes. I know i
> don't know enough about the system yet to know why im being asked to
> do it this particular way, but i assume i must otherwise i get into
> trouble. 

Then I strongly suggest that you rigourously pretend that you know
nothing about eCos, keep in mind the experience that you have had when
installing software on Unix like systems, then go through the procedure.
Better, watch someone else with similar experience in this area do it.
I've done this in my previous career; it's a chastening experience
usually accompanied by much brow slapping as the clunks are pointed out.

> > The advice from the web pages is for newcomers to build with the GUI. I
> > disagree. The GUI does not make the process clearer - in fact it
> > obscures what is going on.
> 
> Isn't that the whole point of a GUI? But thats a digression which will
> lead to a GUIvCLI flame war....

Er, no, that is not the point of a GUI (and without wishing to embark on
this any further, I observe that the GUI/CLI flame wars are generally
based on failing to understand what the user needs to do). In this
particular case, Linux's make xconfig manages to convey the same
information as the text version, but makes the process non-linear;
AFAICS that's the point of using it. eCos configtool masks some
important information unneccessarily, but I should point out that it
seems to be a very good tool in many respects. It can definitely be
fixed.

> I think it depends on what direction you are coming from, Unix or
> Windows. If you are a M$ Windoze person, i'd suggest trying to use the
> GUI to start with. If you are a Unix person, use ecosconfig. 

Here we do agree, so I suggest that this sentence appears right at the
top of the build docs, along with the simple ecosconfig scripts to build
"Hello World" from the MLB web pages.

> > I happen to be fairly motivated to investigate eCos, and I do know that
> > it actually works, so I persevered, but blimey it was uphill work. It
> > wouldn't be hard to make the ecos-install.tcl ask "would you like to
> > build the Synthetic Linux demo" and run Hello World out of the packet,
> 
> It could do that, but its a bad idea.

I'm happy to discuss this, but you are making an undefensible assertion,
since I must observe that this just isn't true. I am by definition
right, since it would have been a good idea FOR ME. I really am 100%
authoritative in the area of what I find useful. :)

> eCos is not an application for end users. Its a set of sources for
> embedded systems programmers. Users of applications just want to use
> the application. Programmers need to know how to build it, how to
> install it, how to run and debug it.

I *definitely* see some point in have a "run-time" eCos kit.  If someone
develops a neat utility that many people would like to put on a target
system, then it's fairly clear that end-users will need to be able to
build and install a target specific version on whatever they happen to
have available.

> They need to know all the inside details so they can modify it to
> there own needs.

Really? That's an interesting comment about a code tree which is fairly
heavily object oriented, and I'd sort of thought the idea of things like
HAL was *precisely* so that one does NOT need to know the details on the
other side of the abstraction...

On most systems with a package management utility such as RPM,
developers get the development facilities by installing the "devel" kit.

> There is a learning process here. In your 4 days of struggle you have
> learnt some of these things. You have taken a few steps towards being
> able to use eCos to write embedded applications.

No. While I repeat that I am sure you are trying to help, I perceive
your tone to be rather patronising. I knew the basic terminology and
concepts already. It took 4 days to work out that the presentation of
the initial docs are somewhat lacking.

> If the installation script did all this for you, you would have a
> working hello world, but what have you learned which will help you
> make your real application?

Well, amongst other things, I'd have been able to look at a guaranteed
working RPM install script and I'd have known that all the right pieces
were in place. I've yet to see an introductory course where the first
step required much more than "gcc hello.c"; certainly not a requirement
to - say - recompile libc.

One of the main reasons for providing Hello World (BTW, in the distant
past I *did* teach a programming course) is that it provides an
opportunity for people to play safely  - i.e. they can experiment and
then interpret problems relative to a simple known working example. It's
very frustrating if one has no feedback about whether failures are minor
"learning experiences" or major bugs that the code just doesn't work on
this system.

> Now, eCos is open source. This includes the documentation and the
> installation scripts. If you can make them better, please do send us
> patches.

I may very well do so if eCos will do what I'm after, but this does beg
the question of whether my patches would be accepted - and it does seem
that you (one of the maintainers, right?) wouldn't necessarily agree
with my POV. I'm not going to waste my time on patches which won't be
accepted. The first step was to post my observations to this list, but
it seems that you have interpreted what I said more as the "howto"
questions of someone who doesn't RTFM. Looking back at my previous
email, I don't believe that I did suggest that, but it's an
understandable reaction. Maybe I should have qualified "newbie" somewhat
and made my background somewhat clearer.

Anyway, thanks for your reply, Andrew; I don't agree with some of your
comments, but I hope you (and anyone else who has read this far)
appreciate that I wouldn't take the time to type this much if I weren't
interested in improving open source utilities like eCos.



-- 
Before posting, please read the FAQ: http://sources.redhat.com/fom/ecos
and search the list archive: http://sources.redhat.com/ml/ecos-discuss