A Bit of A Rant

So I get to the lab this morning and there's a note:

Igor,

I'll be out of town all week for that symposium I mentioned.  Please carry on with the experiments in my absence.  We'll chat when I get back.

Thank You,
F

Oh, well.  I suppose that means I'll do all the work, and he'll get all the credit, but what's a lab assistant for, anyway?  The Doctor treats me well enough, so I really can't complain.

What I can go off on a rant about is this:  There seems to be some sort of a disorder which afflicts more advanced Linux/Unix types which causes them to  use the most cryptic and obtuse of shorthands to "explain" complex and not-so-straightforward procedures.  I'll call this disorder cryptiphilia.  But first, the synopsis:

---

Synopsis:

A rant about cryptiphilia is interlaced among extensive reports of preparations for and progress in building the LFS toolchain (an important set of building blocks for all the rest of the LFS system.)

---

I'll get to my rant presently, but good scientific method demands we take things in order.  This is, after all, supposed to be a scientific journal.

Let me say, at the outset, that the documentation for the LFS project included on the LiveCD is generally quite good, but that it does suffer from cryptiphilia in places that can make it maddening to follow if one is not a careful reader.

The instructions in Chapter 3 of the LFS documentation assume the source code packages will be downloaded rather than copied from the Live CD, and they make no mention at all of this faster and less bandwidth-intensive option.  (Bandwidth is at a premium in the wild country surrounding Castle Frankenputer.)  This is a small matter, though, as it doesn't take a mad genius to realize that a Live CD designed to facilitate building LFS should have everything needed.  I simply created the folder /mnt/lfs/sources and set its permissions per the given instructions, then issued the command:

root# cp /lfs-sources/* $LFS/sources (using that useful $LFS shorthand)

to copy over all the source and patch packages listed in section 3.2 of the documentation.

I had some trouble here with input/output errors during copying that I tracked down to a defective DVD-RW drive, and so shut the system down, disconnected the defective drive, and re-configured the system to use the installed second DVD drive (being careful to set it's jumper to "MASTER") as the bootable removable drive, and that was that.  It did take some time and re-reading of the steps in the manual to make sure I got the system back to where it needed to be, but it was worth the effort.

Once the packages finally completed copying over, checking them against that list yielded a satisfactory confirmation of my hypothesis (i.e., that all the needed packages were, indeed, present on the LiveCD), and I was free to continue.

Chapter 4 of the manual went in a pretty much textbook (one might almost say "cookbook") fashion.  This sets up the /mnt/lfs/tools folder and its associated symbolic link, /tools, adds the user lfs and sets up its group, password, environmental and other settings in a very straightforward manner. (Pay close attention to Section 4.4, about setting up the environment, though, and you will avoid some of the more subtle pitfalls.)  It is worth noting, also, that the instructions in this chapter will move the experimenter from a root login to a login as user lfs.  It is important that this set of steps not be overlooked (so see Section 4.3 if you missed it, please.)

Chapter 5 is where I must take issue, and is the source of my rantings against cryptiphilia. Things start well enough until one encounters two Important Notes (in Section 5.1):

Important

Before issuing the build instructions for a package, the package should be unpacked as user lfs and a cd into the created directory should be performed.  The build instructions assume that the bash shell is in use.

Important

After installing each package, delete its source and build directories, unless specifically instructed otherwise.  Deleting the sources prevents misconfiguration when the same package is reinstalled later.

{A LATE NOTE:  for this part, I have found Midnight Commander (mc) to be most helpful in deleting directories recursively with one or two keystrokes.}

Now these look to be helpful in their intent, but they conceal a fair number of discrete steps the experimenter must take in each and every package installation to follow.  I'll use the package binutils-2.17.tar.bz2 as an example, since it is the first of the packages to be built:

Part of the first note above states, "...the package should be unpacked as user lfs...", however, in the installation section for binutils (Section 5.3.1, a couple of pages later) it states, "The Binutils documentation recommends building Binutils outside of the source directory in a dedicated build directory:" and goes on to instruct the user to issue the commands:

mkdir -v ../binutils-build

cdd ../binutils-build

which don't work if one takes them at face value.  What the reader is supposed to be able to infer from the previous note and the later following installation section is this (all done as user lfs from /home/lfs):

1.) cp /lfs-sources/binutils* /home/lfs (copies the archive binutils-2.17.tar.bz2 to the lfs home folder)

2.) bunzip2 binutils*.bz2 (unzips the bzip2 archived package, leaving the file binutils-2.17.tar .)

3.) tar -xvf binutils*.tar (extracts the tar archive resulting from the step above into a directory called binutils-2.17 under /home/lfs.  This takes care of the "unpacking the packages" part.  To continue:)

4.) cd ~/binutils-2.17 (here the "~/" stands in for /home/lfs.  It's at the next steps I begin to really take issue, because this is the place where we cut in with:)

5.) mkdir -v ../binutils-build (and this is a roundabout way to get there from here.  The cryptic shorthand "../" indicates "from the directory above the present one" [referred to as it's parent directory].    In essence, one could have more elegantly created /home/lfs/binutils-build with the simpler command:

mkdir -v binutils-build

issued while still in /home/lfs before step (4.), which would have been much more straightforward and not have had the reader jumping all round through the text in Chapters 4 and 5 trying to figure that out.  Either this, or they should have explained the entire process in discrete steps as I just did.  It would have saved us all a lot of time, really.)

 All of that is just to get ready to do the build!  I do understand a desire for conciseness.  Would it have been so much to ask, though, for the authors to have gone through the first build step-by-step and then noted which steps would be repeated for each build?  To have seen all this on one page, in one place, would have saved so much head scratching trying to figure out if I knew what the authors really meant.

It's like it's part of a subtle test to see of one is somehow "worthy" to be doing this, when Open Source is supposed to be OPEN.  Well, all I can say at this point is, "I've made it this far, and I'm blazing a clearer trail for others to follow.  So there."

At this point, I have managed to install the first three packages and am presently working on getting glibc installed.  I'm in the third pass of the "make check" step, and seeing errors.  Perhaps all will be made clear eventually, if I don't go dotty trying to decode these directions.