Re: [frogs] CG chapter 3, first draft

[Graham Percival <graham@xxxxxxxxxxxxxxxxx>]

On Tue, Jan 19, 2010 at 7:30 AM, Mark Polesky <markpolesky@xxxxxxxxx> wrote:
> http://www.markpolesky.com/norobots/compiling_new.itexi.html
>
> Right now, it's all in one file for convenience---I'll
> patch it properly with basic-compile.itexi etc. later.

Just to check, do you know that basic-compile.itexi is the stuff that
gets turned into INSTALL.txt ?  It's included in
Documentation/topdocs/install.texi

I mention this because AFAIK nobody's really thought about what
material should be in the CG only, vs. what material should be shared
with INSTALL.txt.  The text file should contain enough info to compile
from scratch (if somebody downloads the source tarball), but nobody's
really thought about what additional info, if any, would be
appropriate to add or subtract.


> Also, let me know if you find any factual inaccuracies;
> hopefully there aren't any, but some of this is confusing
> for me too!

Speaking of facts, I think we could simplify a few things.  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?

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.

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

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.

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.

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

@example
@uref{...}
@end example

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


3.4.1

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


3.4.2

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

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


Changing the install directory doesn't force a full recompile, so
changing the --prefix after compiling isn't a big deal.  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.


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.

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


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

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

3.6.2

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

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?

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.


Cheers,
- Graham

---
----
Join the Frogs!