Re: [frogs] CG chapter 3, first draft

[Mark Polesky <markpolesky@xxxxxxxxx>]

Here are the links again:
http://www.markpolesky.com/norobots/compiling_new.itexi
http://www.markpolesky.com/norobots/compiling_new.itexi.html

Graham Percival wrote:
> Just to check, do you know that basic-compile.itexi [...]
> INSTALL.txt ? [...]
>
> [...] AFAIK nobody's really thought about what material
> should be in the CG only, vs. what material should be
> shared with INSTALL.txt.  [...]

Yes, I know.  I'll decide that later.  For the moment, I'd
like to get the CG-specific stuff out of the way.

> I think that guile 1.8.2 is fairly old, as is ghostscript
> 8.15.  Instead of saying "guile 1.8.1 with patch x and y,
> and ghostscript 8.15 with patch z", why not just specify
> the later version number?

Done.

> Similarly, let's stop talking about g++ 3.4; just say 4.0
> or higher.... I mean, if somebody complains that it
> doesn't work in 3.4, we're (probably) not going to
> actually fix that.

Not done.  I met with some resistance on -devel.  Feel free
to step in there.
http://lists.gnu.org/archive/html/lilypond-devel/2010-01/msg00499.html

> Since we have links for everything else, let's add a link
> for Imagemagick.

Done.

> It would be *really* nice if we stopped telling people to
> look at input/regression/utf-8.ly for hints about fonts,
> and had that info in the install chapter directly.

Done.  But---what's the RPM equivalent of "apt-get install"?
As it stands the RPM stuff starts with "taipeifonts", as if
it were a command.

> 3.3
>
> Don't tell people about the source snapshot.  The whole
> point about encouraging tarballs is that they're a known
> point in time -- particularly, a believed-to-be-compilable
> point in time.  If they want to use the full bleeding
> edge, they should use git.

Hmm.  Certainly some readers might be curious to see the
snapshot without bothering with Git.  I don't think that
including a quick link to it is going to harm anybody.  How
strongly do you feel about this?  I kind of like it there.

> I personally would just give them the @rweb{Source} link.
> If you really want to give the link to linuxaudio, I guess
> you could, but it'll look better inside a
>
> @example
> @uref{...}
> @end example

Done.

> I really don't think the warnings about untarring are
> necessary.  Newbies aren't supposed to screw with source
> tarballs.

Yes, but newbies might not *know* that they're not supposed
to screw with source tarballs.  Again, I don't see any harm
in including the warning.  I don't think those two sentences
are a big obstacle to the overall flow.

> Who's going to update the list of generated files whenever
> they change?  Also, I don't believe that autogen.sh
> creates an out/ dir.
>
> I'd rather just say that it creates a number of files and
> directories to aid configuration (or something like that).

Done.

> as Carl or John already pointed out, you don't need to run
> ./configure if you run ./autogen.sh.

Okay, I changed "you need to run" to "you should run".

> BTW, ./configure is *known* to not check all doc
> requirements.  A warning here would definitely be
> appropriate.

Which doc requirements does it not check?  I know that
../configure doesn't issue an ERROR when missing a doc
requirement, but it was my assumption that it should issue a
WARNING.  This much is clear in the text (I thought), so let
me know what I'm missing.

> Changing the install directory doesn't force a full
> recompile, so changing the --prefix after compiling isn't
> a big deal.

Okay, I removed the portentous sentence.

> You also don't need to create the directory; as long as
> you have write permission to the higher directory, make
> install will create the install dir just fine.

Hmm.  I didn't think the paragraph implies that the directory
needs to exist.  Should I add "(or within)" like this?

  `make install' will only succeed if the installation
  prefix points to (or within) a directory where you have
  write permission (such as your home directory).

> The technical term for separate build directory is
> "out-of-tree build".  Note that in some cases, you'll need
> to run make distclean in the main source dir before you
> can successfully do the out-of-tree configure and make.

Okay, I added a note about it.

> I'd put ./configure --help at the top of this subsection.

Done.

> 3.5.1
>
> You don't need to run "make clean" unless you specifically
> want to.  If the build system worked perfectly, you'd
> *never* need to run make clean.  As it is, "make clean" is
> only needed once every 2-3 months (from empirical
> evidence).

Oh.  I must have over-interpreted this post of yours:
http://lists.gnu.org/archive/html/lilypond-devel/2009-12/msg00496.html

> I'd mention -jX somewhere, since that's a very
> commonly-used and desired option, with most people having
> 2 or 4 cores.

You mean specifically for `make' and not `make doc'?  If so,
could you write a little paragraph?  I don't really know how
it works.  I added a node.

> 3.6.2
>
> sweet mao, we don't want people running doc-clean!!!

Why not?  You make it sound like there's something I don't
know.  Something that should be mentioned, perhaps...

> I wouldn't bother mentioning info.  If somebody wants to
> trawl through the make targets, they'll find it... but
> really, who on earth wants info?

Apparently John does; he's the one who wrote it:
http://git.savannah.gnu.org/gitweb/?p=lilypond.git;h=0c9af42

> I'd put the -j3 CPU_COUNT=3 earlier in the section.
> Again, it's getting more and more useful with the
> direction that cpu manufacturers are going.

Done.

Thanks for your input.  Looking forward to more!
- Mark


      

---
----
Join the Frogs!