[ECOS] Newbie feedback and braindump.

[ECOS] Newbie feedback and braindump.

[Peter Lister]

Hello,

I've recently been playing with eCos - it seems like a fascinating
project with quite some potential. I have not yet run eCos on a really
embedded box (I'm thinking about getting an openbrick, based on the
Geode chipset),so I though I'd play with the Linux Synthetic setup. 

I swear I followed the advice on the web pages. Really. Don't tell me to
RTFM - I did, many times.  But still it took me 4 days to get as far as
successfully running "Hello World" on Linux...

First, I tried to use the 2.0 kit as suggested by the web pages but this
just didn't work. I tried the GUI configtool (BTW, please give it an
eCos specific name, it's very confusing otherwise) and frankly I don't
think it made the job any easier. The sequence of events is NOT
intuitive to someone learning how the components work.

Then I found http://www.mlbassoc.com/examples/ and used the command line
ecosconfig against the latest CVS version. Hooray - finally I saw "Hello
World".

The first problem, I perceive, is that it is NOT obvious to a newbie
that the "Linux Synthetic" platform is a thing distinct from the "PC"
platform. I assumed (not unreasonably, I think) that the default
template was the right one; the templates are not are not organised by
architecture, and so it is not obvious that the default i386 template is
NOT suitable for the "Synthetic" target. I'm sure that this distinction
is so stunningly obvious to many of you who know eCos well, so that you
can't imagine why I'm so stupid. Well I saw the instruction to select a
template, and the default seemed OK, so it never ocurred to me - had I
seen the available choices in the i386 domain by default, I might have
noticed that there was another choice.

Building the ecosynth target is also far from obvious. Once I'd actually
realised that, no, it is NOT built as part of the target, I read
http://ecos.sourceware.org/docs-2.0/ref/synth-install.html, which
advised me to cd "somewhere suitable" and use a directory synth_build.
So I did. Well I had an ecos directory and I'd created a config call
"synth" - obviously, this was a build for the synthetic target - and the
configtool had created a directory synth_build...

It tooks me HOURS to realise that the idea was to create a DIFFERENT
directory from the one I'd used for the rest of the eCos build, and that
the name synth_build was just a coincidence. You cannot tell a newbie
just to cd "somewhere suitable" - I do not yet know what "suitable"
*means* yet.

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. It may make Windows users feel happier (I
don't know), but I just found it confusing. Trying to configure the
right thing (I realised I wasn't getting the synthetic target, but
couldn't work out why), I was getting information about build problems
and conflict information with macro names - but nothing to link this to
the package names and configuration options in the main window (compare
to the Linux kernel "make xconfig" which always gives the actual macro
names in the GUI).

It's a very important part of the process of first using something like
this that the initial process and constructing the first demo is easy;
THEN one can start tweaking. The MLB Associates example came fairly
close to this ideal, but the eCos web info has a great deal of verbage
and screen shots to do the equivalent, and still doesn't work, as far as
I'm concerned. I have no idea whether the 2.0 code will work if I try
again from scratch, but I'm not that motivated to find out.

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,
and as that seems likely to be a very common first proof-of-concept, it
should eliminate many newbie questions. RPMs aren't hard to build; if
Etherboot images can be built by www.rom-o-matic.net, RedBoot really
shouldn't be any harder.



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

Re: [ECOS] Newbie feedback and braindump.

[Andrew Lunn]

On Thu, Nov 06, 2003 at 12:31:39AM +0000, Peter Lister wrote:
> Hello,

Hi

Its a long email, so im only going to reply to selective parts and do
some pruning.

> The first problem, I perceive, is that it is NOT obvious to a newbie
> that the "Linux Synthetic" platform is a thing distinct from the "PC"
> platform. I assumed (not unreasonably, I think) that the default
> template was the right one; the templates are not are not organised by
> architecture, and so it is not obvious that the default i386 template is
> NOT suitable for the "Synthetic" target.

A technical point first. Be careful of your terminology. You are
mixing up the words targets and templates. A target is basically a
board, eg ebsa285, MPC8xxFADS, EAB-2, PC motherboard etc. A template
is a preselected set of packages, eg net, POSIX, minimal. You also
have architectures. These are things like ARM, PPC, i386. Basically
instruction sets.

OK. The i386 target is a PC motherboard. The synth target does not run
on a PC motherboard. It runs on a synthetic board inside linux.

> I'm sure that this distinction is so stunningly obvious to many of
> you who know eCos well, so that you can't imagine why I'm so
> stupid. Well I saw the instruction to select a template, and the
> default seemed OK, so it never ocurred to me - had I seen the
> available choices in the i386 domain by default, I might have
> noticed that there was another choice.

You mistake here is mixing up template and target. You selected a
target, not a template.
 
> Building the ecosynth target is also far from obvious. Once I'd actually
> realised that, no, it is NOT built as part of the target, I read
> http://ecos.sourceware.org/docs-2.0/ref/synth-install.html, which
> advised me to cd "somewhere suitable" and use a directory synth_build.
> So I did. Well I had an ecos directory and I'd created a config call
> "synth" - obviously, this was a build for the synthetic target - and the
> configtool had created a directory synth_build...
> 
> It tooks me HOURS to realise that the idea was to create a DIFFERENT
> directory from the one I'd used for the rest of the eCos build, and that
> the name synth_build was just a coincidence. You cannot tell a newbie
> just to cd "somewhere suitable" - I do not yet know what "suitable"
> *means* yet.

Well, the instructions say:

$ cd <somewhere suitable>
$ mkdir synth_build
$ cd synth_build

This will result in an new empty directory. Always.

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? Do they suggests they might be already a directory
called synth_build? So instead of following the instructions you have
done something slightly different which has resulted in you getting
into problems.

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. 
 
> 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....

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. 
 
> 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. 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. They need to know all the inside details
so they can modify it to there own needs. 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. 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?

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

        Andrew

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

Re: [ECOS] Newbie feedback and braindump.

[Peter Lister]

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

Re: [ECOS] Newbie feedback and braindump.

[Andrew Lunn]

Again pruned...

On Fri, Nov 07, 2003 at 12:33:24AM +0000, Peter Lister wrote:
> 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.

I try to understand your POV i went back to the documentation. And you
are right! The GUI tool appear to me to be using the terminology at
least inconsistently and possibly wrongs. Its hard for me to be
sure. Im definitely a CLI guy and don't even have the ConfigTool
installed. But looking at
http://ecos.sourceware.org/docs-latest/user-guide/using-configtool-windows-linux.html
The label say "Figure 11-2 Template Selection". But the dialog box
allows you to select much more than the template. A much better name
would be "Basic configuration Selection". The section of the dialog
box called "Hardware" allows you to select the target. The section
"Packages" appears to allow you to select templates. 

Like i said, i don't know the ConfigTool too well. Hopefully somebody
like John will jump in here and correct/confirm what im says.

As an aside. My POV is from using ecosconfig and looking at the actual
sources. This very clearly uses the terminology as i defined it. eg
look a the help information for ecosconfig.

lunn@londo:~/eCos/work$ ecosconfig --help
Usage: ecosconfig [ qualifier ... ] [ command ]
  commands are:
    list                                       : list repository contents
    new TARGET [ TEMPLATE [ VERSION ] ]        : create a configuration
    target TARGET                              : change the target hardware
    template TEMPLATE [ VERSION ]              : change the template
    add PACKAGE [ PACKAGE ... ]                : add package(s)

or read ecos.db, the database of packages and targets.

> > 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.

Now i understand how this has happened......

> 
> > 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*).

Please suggest some text which would help explain this. Better still,
a patch to the SGML would be great. You can find it in 
packages/hal/synth/arch/current/doc/synth.shml. 
 
> 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.

This is something that is consistent though out the documentation. Its
also not a Unix issue. M$ would act in a similar way if you left in
the < or > characters. 

> > 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 will add some comments to Chapter 11. 

 
> > > 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. :)

I think you need to look back at this in a couple of months time when
you have some more experience with eCos. Ask the question "Did i learn
something useful during the time spent installing eCos which i would
not have learnt if it was all pre-installed?" It might not seem useful
now, but i think it will be once you learn more and start doing some
real work.

> 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.

Embedded systems don't work like that. Each embedded system is
different. I doubt you could produce a neat utility which is totally
independent of what system it runs in. Also, ask the question, who are
the end-users of embedded systems? Its the house(wife/husband)
programming his washing machine for 40C degree wash, its an officer
worker pressing a button to select the floor she want the lift to take
her to. Its a music lover listening to there MP3 player? How many of
these end users know how to put new software into there washing
machine, lift or MP3 player?

eCos is for the highly educated software engineer, not the end user.

> > 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...

Abstractions are two sided. If you port eCos to a new target, you
probably have to write a new HAL or at least modify an existing
HAL. The abstraction allows you to do this without having to know
about the kernel. But some people need to modify the kernel to meet
there needs. eg add functionality to how POSIX signals are delivered
is a recent example. People have modifying existing serial drivers to
make them more responsive at the cost of CPU load, or the exact
opposite, less CPU and less responsive. This has come from application
requirements. 

You have the sources to eCos and can make it do what you need it to
do. Its not a black box you have no control over.
 
> 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.

On a desktop system or server you have no need to recompile libc. For
embedded system, especially configurable embedded systems, recompiling
libc is normal practice. I might want to trade speed for code size
because i have a small FLASH? Or my application may be running a
little too slow, so i recompile libc for speed. eCos has default
settings, but every embedded system will probably need tuning to match
the requirements of the application and hardware. You need to know how
to do this and its a fundamental part of eCos. Thats what the C in
eCos stands for, Configurable.

> > 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.

Yes, im a maintainer. As to if i would accept your patches, the answer
is probably yes. Look in the ecos-patches archive. See how many
contributed patches i've commit and how many i've rejected.

      Andrew

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

Re: [ECOS] Newbie feedback and braindump.

[Andrew Lunn]

> > > 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 will add some comments to Chapter 11. 

I added some comments suggestion unix users may prefer the CLI
tool. It may take a while for the changes to appear in the online
version.

        Andrew

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

RE: [ECOS] Newbie feedback and braindump.

[Retallack, Mark (Siemens)]

Thank you for you letting us know your experiences with eCos. 

After using eCos for a long time, it is possible to forget the problems that
most people have when starting to use it. So it is very useful to get a
detailed report into what someone's first impressions are, the problems that
they encountered and where they got help from (Hello World examples are
always useful). This always helps to fix it so new people don't fall down
the same holes. 


-----Original Message-----
From: Peter Lister [mailto:prl@peterlister.co.uk]
Sent: Friday 07 November 2003 12:33 AM
To: Andrew Lunn; ecos-discuss
Cc: prl@peterlister.co.uk
Subject: Re: [ECOS] Newbie feedback and braindump.


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


Siemens Traffic Controls is a division of Siemens plc. Registered No.
727817, England. 
Registered office: Siemens House, Oldbury, Bracknell, Berkshire, RG12 8FZ. 

This communication contains information which is confidential and 
may also be privileged. It is for the exclusive use of the addressee. 
If you are not the addressee please note that any distribution, 
reproduction, copying, publication or use of this communication 
or the information in it is prohibited.  If you have received this 
communication in error, please contact us immediately and also 
delete the communication from your computer. 



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