On Fri, Mar 8, 2013 at 2:31 PM, Gabriela Gibson
<gabriela.gibson_at_gmail.com> wrote:
> I would like to make get-deps.sh a little more informative.
>
> 1) every time it downloads something, it should tell you what it got,
> where it is and what it's needed for and what you're expected to do
> with it, if anything.
>
> For example:
>
> - downloading apt (required library) from ...
> - done -- <pointer to complex instructions>
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
> - downloading Serf (optional library) from ...
> - renaming directory
> -- done -- <simple instruction what to do next>
> ....
Unix philosophy:
"Rule of Silence: When a program has nothing surprising to say, it
should say nothing."
http://www.faqs.org/docs/artu/ch01s06.html
Part of the reason around this is it makes it much easier to see the
information you actually need to know (e.g. an error about a failed
download). Our current build process is a good example of way too
much noise since we don't filter needless output.
Sometimes you want that extra information, however the shell already
provides that functionality. If you want to see what it's doing run
it with -x e.g.:
sh -x get-deps.sh
Perhaps it makes sense to include a pointer to INSTALL at the end of
the get-deps.sh script run. But I suspect anyone running get-deps.sh
is probably following INSTALL already.
> 2) if it doesn't download something it should tell you what there is,
> if possible, e.g.
>
> -- Serf 1.1.1 already present in trunk/serf/
It does do this:
echo "Local directory '$i' already exists; the downloaded copy won't
be used" >&2
Your proposed text implies that it knows that the serf directory is
1.1.1, which the script doesn't really know and it'd probably take a
lot of work to make it know which would take a fair amount of effort
to keep up to date since dependencies change things from time to time.
As it is just keeping the URLs working in get-deps.sh to download
things is a burden.
> 3) A more informative --help output that introduces get-deps.sh, with
> subcategories that display the help for the downloads, e.g.
> ./get-deps.sh help serf
> <instructions regarding how to proceed with serf after download>
I don't think documentation belongs here. It's undesirable to
duplicate documentation, we have INSTALL which is a fairly standard
place to put this information. When you start duplicating
documentation it increases the burden to keep it up to date.
I'd concentrate on improving INSTALL rather than tweaking get-deps.sh.
Received on 2013-03-09 01:22:00 CET