[Openmcl-devel] OSX install difficulties

[Gary Byers]

On Thu, 30 Sep 2004, Hamilton Link wrote:

> > > I'm not sure that it's really the job of the OpenMCL documentation
> > > to go into great depth in discussing these issues; there are probably
> >  > entire websites devoted to helping people who are unfamiliar with
> >  > them.  It might suffice to say something like "the files
> >  > available here should be transferred in binary mode and archive
> >  > contents should be extracted without line conversion or other loss
> >  > of information.  If you don't have any idea what this means, see
> >  > <http://helpful-web-site.org>"
> >  >
> >
> > I fully agree.
> >
> > Francis
>
> Yeah, it's important to not clutter the docs with tidbits that help
> people, because that will get in the way of people who know what
> they're doing and are re-reading the docs trying to make sure they are
> correct or have operations out of order...
>

Since we're agreeing, I would also agree that there are lots of places
where the docs assume a certain level of familiarity with/comfort with
the shell and Unix-y command-line stuff.  That assumption was probably
more valid when OpenMCL was a Linux-only project; when it was ported
to Darwin, the docs were updated to say "and for Darwin, do:

shell> ./dppccl ppc-boot.image

instead", but the underlying assumption and orientation didn't really change.

(The assumption that the user would be familiar with/comfortable with
the shell environment probably wasn't universally valid in the Linux-
only days, but I think that it's fair to say that there's a wider range
of familiarity/comfort levels amongst OSX users, if only because there's
a larger sample involved.)

> 2.6 Troubleshooting
>
> FOO1<br>
> <a href=linktohelpfulsite>FOO2</a><br>
> etc.
>
> Where FOO can be replaced with the following, and we can link stuff in
> as we see fit.
>
> Remember to FTP/HTTP files down as binaries.
> Remember to use tar to unpack files, not unstuffit.
> Remember to export your startup script's CCL_DEFAULT_DIRECTORY.
> Remember to put your favorite path/to/ccl/scripts in your path.
> Remember to edit path/in/ccl/scripts/openmcl when you need to have
> multiple installations coexist.
> Remember that you can not turn a source release archive into a
> bleeding-edge CVS working copy.
>
> and so on.
>
> Sort of like a mini-FAQ for the build process, plus a place to put
> reminders about shell and tool things people have had trouble with. Can
> you set that up Dan?
>
> h
>

The main web page is an out-of-data, static FAQ.  The "news" page
should probably be the first page (and should be updated more often!),
and should probably  link to a more dynamic, user-extensible FAQ.
(There's a package called "FAQ-O-Matic" that I'm thinking of, there
may be other things that're easier to use or maintain.)

If anyone who was interested in doing so could add/modify FAQ entries,
that might be the best solution.  Things like "remember to transfer
files in binary mode" and "depending on what versions of OSX/Dev Tools
are installed in what order, "/usr/lib/crt1.o" may get clobbered and
here's Apple's explanation" probably -do- belong somewhere visible,
but that stuff's orthogonal to understanding the chicken-and-egg build
process and other domain-specific OpenMCL issues.  I think that it's
hard to present that domain-specific OpenMCL stuff clearly (where
"clearly" apparently means "clear to someone other than someone
already very familiar with the issues"), and I think that it'd
be even harder to present that and also have to say "when you get to
the kernel build step, make sure that the Apple Installer hasn't
clobbered this file ..."

Another approach (which may or may not be helpful to Dan): the PHP
website (the website for the PHP server-side scripting language)
used to (and may still)  have several versions of the language manual
online, including one which could be "annotated" by users ("This
reference entry for FOO is incorrect; the return value is only a
float if all of its arguments are also floats.")

Sorry to ramble; I don't like the thought that someone who might do
great things with OpenMCL would be discouraged from doing so because
the web site didn't warn them against using Stuffit and they couldn't
get things installed and working.  I also think that it'd be even
harder to present the circular-boostrapping issues and other
domain-specific stuff without keeping that and the metainformation
("these are Unix text files, lines are terminated with LF and that's
sometimes very important.") separate.