catalyst-spec.5.txt: Clarify "within the loop" (squashfs)

When you build a livecd-stage2, you get an ISO, inside of which is
something like:

  # mount -o loop livecd.iso iso
  # tree iso
  iso/
  |-- # stuff from livecd/overlay
  |-- image.squashfs  # the compressed root filesystem
  |-- isolinux
  |   |-- # kernel
  |   |-- # and
  |   `-- # related help
  |-- livecd          # empty, probably just a marker
  `-- README.txt      # help for kernel command line options

Inside the image.squashfs (or image.*, as configured by
livecd/fstype) is the root filesystem:

  # mount -o loop iso/image.squashfs squashfs
  # ls squashfs
  bin   dev  home  media  opt   root  sbin  tmp  var
  boot  etc  lib   mnt    proc  run   sys   usr

So if you want to tweak the root filesystem, use livecd/root_overlay.
If you want to tweak the ISO filesystem, use livecd/overlay.

Signed-off-by: W. Trevor King <wking@tremily.us>

Merge branch 'pkgcache-warning' into rewrite

* pkgcache-warning:
  doc/catalyst-config.5.txt: Document linking issues with binary packages
  doc/catalyst-config.5.txt: Add man page for catalyst.conf
  doc/HOWTO.txt: Explain how to run catalyst without installing

doc/catalyst-config.5.txt: Document linking issues with binary packages

This gives users a heads up explaining why they might see linking
errors when pkgcache is enabled.  I first saw this when I build a
stage1 without update_seed.  Because my seed stage3 linked against
libmpc.so.2, some of my stage1 files linked against the older mpc.
However, the mpc-1.0.1 built for the stage1 installed libmpc.so.3.
When I tried to use this stage1 to build a stage2, it died with:

  /usr/libexec/gcc/i686-pc-linux-gnu/4.6.3/cc1:
    error while loading shared libraries: libmpc.so.2:
    cannot open shared object file: No such file or directory

To fix this, I enabled update_seed, but binary packages built during
my first pass were used to populate the stage1, so even though I'd
updated the seed stage3 toolchain, I still had a stage1 with cc1
linked against libmpc.so.2.

After clearing the binary package cache, I got a stage1 *built* with
the updated seed stage3, which gave a cc1 linked against libmpc.so.3
(hurray!).

This commit adds a warning in the pkgcache documentation that should
help people understand what might be going wrong if they see similar
linking errors.  For more details, see the thread following
http://thread.gmane.org/gmane.linux.gentoo.catalyst/2137/focus=2193

doc/catalyst-config.5.txt: Add man page for catalyst.conf

This mostly translates the inline comments from files/catalyst.conf
into asciidoc.  While it's nice to have that as stand-alone
documentation, it also makes it easier to refer to longer descriptions
of any tricky issues.  This gives us a place to distill the collected
wisdom of current users for the benefit of others.

doc/HOWTO.txt: Explain how to run catalyst without installing

Thanks to Chris White for explaining this to me.

Reviewed-by: Matt Turner <mattst88@gmail.com>

Merge branch 'livecd-startx' into rewrite

* livecd-startx:
  livecdfs-update.sh: Use `bash --login` to spawn startx
  livecd-bashrc: Avoid a startx race by restricting to tty1

Merge branch 'xsession' into rewrite

* xsession:
  livecdfs-update.sh: Run env-update to pick up any /etc/env.d/ changes
  livecdfs-update.sh: Set XSESSION in /etc/env.d/90xsession

livecdfs-update.sh: Fix '/etc/sshd' check for sshd_config tweaks

sshd_config lives in /etc/ssh, not /etc/sshd.  This typo has been
present since the block was introduced by c06264e (Initial import of
Catalyst 2.0.0, 2005-04-04), so it's obviously not a widely used
feature ;).  It might be better to just remove the block entirely.

examples: Add newlines to accidentally unwrapped comment lines

With:

  $ sed -i 's/^\(#.*\)\(#.*\)/\1\n\2/' examples/*.spec

livecdfs-update.sh: Run env-update to pick up any /etc/env.d/ changes

Otherwise the XSESSION change from e523136 (livecdfs-update.sh: Set
XSESSION in /etc/env.d/90xsession, 2013-03-02) is not noticed.

livecdfs-update.sh: Set XSESSION in /etc/env.d/90xsession

As part of the OpenRC migration, the recommended place for configuring
the default X session moved from /etc/rc.conf to /etc/env.d/90xsession
[1].

[1]: http://www.gentoo.org/doc/en/openrc-migration.xml

livecdfs-update.sh: Use `bash --login` to spawn startx

Starting a "login" version of Bash via `su` is tricky.  The naive:

  su - ${first_user} -c startx

fails because `su - ...` clears a number of environment variables (so
the prefixed `source /etc/profile` doesn't accomplish anything), but
Bash isn't started with the `--login` option, so it doesn't source
/etc/profile internally.  From bash(1):

  A login shell is one whose first character of argument zero is a -,
  or one started with the --login option.
  ...
  An interactive shell is one started without non-option arguments and
  without the -c option whose standard input and error are both
  connected to terminals (as determined by isatty(3)), or one started
  with the -i option...
  ...
  When bash is invoked as an interactive login shell, or as a
  non-interactive shell with the --login option, it first reads and
  executes commands from the file /etc/profile, if that file exists.
  After reading that file, it looks for ~/.bash_profile,
  ~/.bash_login, and ~/.profile, in that order, and reads and executes
  commands from the first one that exists and is readable.  The
  --noprofile option may be used when the shell is started to inhibit
  this behavior.

In order to get the login-style profile loading with a non-interactive
`su` invocation, you need to use something like:

  echo "${command}" | su - "${user}"

This starts a login shell and pipes the command in via stdin, which
seems to fake Bash into thinking its running from an interactive
terminal.  Not the most elegant, but the other implementations I can
think of are even worse:

  su - "${user}" -c "bash --login -c ${command}"
  su - "${user}" -c 'source /etc/profile &&
      (source .bash_profile || ...) && ${command}"

The old expression was broken anyway due to unescaped ampersands in
the sed expression.  From sed(1):

  s/regexp/replacement/
    Attempt to match regexp against the pattern space.  If successful,
    replace that portion matched with replacement.  The replacement
    may contain the special character & to refer to that portion of
    the pattern space which matched, and the special escapes \1
    through \9 to refer to the corresponding matching sub-expressions
    in the regexp.

This means that the old expression (with unescaped ampersands) lead
to:

  source /etc/profile ##STARTX##STARTX su - ${first_user} -c startx

with ${first_user} expanded.  This commented out startx, so it was
never run.

livecd-bashrc: Avoid a startx race by restricting to tty1

Otherwise several virtual consoles may notice the existence of
/etc/startx, and spawn simultaneous X servers.  This way we only spawn
a single X server, regardless of timing.

A better solution here is probably to add a "start" or "x-server"
service to /etc/init.d/, but that's more work than I'm up to at the
moment.

Move bug-reporting and mailing list notes from TODO to README

This information is generally useful, and folks probably only read
TODO if they want to help but don't already have an idea of what to
help with ;).  Having the contact information in the README should
raise its visibility.

examples/README: Add a pointer to the releng Git repository

Thanks to Dustin C. Hatch for pointing this out, because I wasn't able
to find it on my own.  Having a pointer distributed with Catalyst
should help other newcomers find example spec files written by folks
who know what they're doing ;).  The current examples lack a full
stage1-through-stage3 progression.

temp set shebang to python2 until py3 compatibilty is done

Rename local unpack var to _unpack

The method name was unpack, so rename the local var to _unpack to help avoid confusion.

Fix a long line.

Remove some dead code

Fix some paths/normpath usage.  Use pjoin to join paths.
Use os.path.dirname() instead of splitting and rejoining without the filename.

Create AutoResume class to handle all file creation, deletion...

Create catalyst/base/resume.py.
Migrate all auto_resume operations to using the new class.

Refactor ClearBase code to remove code duplication.

Initial creation of fileops.py

Migrate to using ensure_dirs()

fix version for newer snakeoil

Migrate version to use snakeoil's format_version() to append git commit info.

This will make tagging releases easy as well as providing better debug info while running live versions of the software.

kmerge.sh: Fix line wrapping typo from 9ceebbf

In 9ceebbf (kmerge.sh: Make /var/tmp/${clst_kname}.config optional,
2013-02-09), I added a KERNCACHE check to a `[` test, wrapping the two
clauses in the test to avoid a very long line.  Unfortunately,
newlines do not appear to be legal in this position.  For example:

  $ if [ -n "a" -a
  > -n "b" ]; then echo "c"; fi
  bash: [: missing `]'
  bash: -n: command not found

This commit fixes the error by explicitly wrapping the line with a
backslash.

Reviewed-by: Matt Turner <mattst88@gmail.com>

files/.gitignore: Ignore $(DOCS) and $(DOC_SIDE_EFFECTS)

These are generated by the Makefile from sources in doc/.

Reviewed-by: Matt Turner <mattst88@gmail.com>

Makefile: Add DOCS for building files/HOWTO.html

The rules are more general though; any new *.txt file in doc/ that
doesn't match *.?.txt or one of the explicitly-listed *.generated.txt
files will be automatically built and distributed.

The generated `files/docbook-xsl.css` is a side effect of the xhtml
target.

Reviewed-by: Matt Turner <mattst88@gmail.com>

Drop addpatches from the livecd-stage2 example spec as well.

Drop addpatches from the stage4 example spec.

Make the use of preserved_libs optional by setting the options variable.

Ported from commits:
 462348d88b3a5fa783f322c64131025581ecc220
 f6ad384914a00099eea2a0f66232728c479ec628
 in the master branch.
AUTHOR: Jorge Manuel B. S. Vicetto (jmbsvicetto) <jmbsvicetto@gentoo.org> (Sun 14 Apr 2013 08:22:34 PM PDT)

Add support for m68k

port commit for the rewrite branch.
Brian Dolbec <dolsen@gentoo.org>

livecdfs-update.sh: Escape ampersands in STARTX sed expression

From sed(1):

  s/regexp/replacement/
    Attempt to match regexp against the pattern space.  If successful,
    replace that portion matched with replacement.  The replacement
    may contain the special character & to refer to that portion of
    the pattern space which matched, and the special escapes \1
    through \9 to refer to the corresponding matching sub-expressions
    in the regexp.

This means that the old expression (with unescaped ampersands) lead
to:

  source /etc/profile ##STARTX##STARTX su - ${first_user} -c startx

when we want:

  source /etc/profile && su - ${first_user} -c startx

with ${first_user} expanded in both cases.

Reviewed-by: Matt Turner <mattst88@gmail.com>

doc/HOWTO: First pass at a gentle Catalyst introduction

Reviewed-by: Matt Turner <mattst88@gmail.com>

create-iso.sh: add usb boot via isohybrid

Add an isohybrid call to create-iso.sh for isolinux targets so the resulting
images are usb/hdd bootable.

Fix bugs 407051 and 458536 by using FEATURES="preserve-libs" on the unmerge step of livecd-stage2 target.

update version to identify the rewite-git code is being run

fix indent.

Fix broken seed stage update...

Add a check for the update_seed option to set the correct update options.
Fix default seed stage update command to properly update gcc and it's deps.
Add --binpkg-respect-use=y for all cases --usepkg is enabled.
Apply patch to fix broken if logic in the setup_emergeoptions() by Douglas Freed <dwfreed@mtu.edu> and rebase

Fix typo in error message, clean up useless tracebacks

Remove useless python tracebacks for bash side target failures.

update gitignore

mixed spaces/tabs and indent cleanup.

Migrate hardcoded /etc/portage paths

Create "port_conf" default.
Migrate all references to /etc/portage to the config's default.
Migrate all make.conf paths to the config'd default.

Fix a bug that portage didn't get rebuilt with the build use flag

If clst_PGKCACHE is defined, --newuse was not being added to clst_myemergeopts, so then portage was not being rebuilt if portage was already up to date.

Add archdir to settings

Commit my testpath file with instructions to run the git checkout code directly without being installed.

FIXME! Add a forced debug print statement in cmd() for better debug output

Migrate this and other code to use python's logging module.

Remove trailing slash for consistency in variables

remove extra slashes in paths,
fix hash header

Fix a relative path bug

Add '--- 'to at the start of all echo messages to aid debugging

Make shdir a complete path to ease it's use.

Add a "shdir" setting to config.
This is to make moving the bash code around easier.
It also reduces more hardcoded paths in the bash scripts.
Migrate all target shell scripts to use the new shdir setting

Extend ParserBase to do variable substitution.

Also add embedded variable substitiution to default settings.
Why are we not using python's built-in ConfigParser?
We'll migrate it later.

reduce 2 operations into one simpler one

rename a make.conf key to make_conf due to bash variable name restrictions

Break out more repeated (path1 + path2)'s...

Just do it once and use the temp variable.
Comment out some debug print's.
Fix options conversion for export to bash.

FIXME! Comment out a small code block causing TypeError.

This was also short circuiting another large code block.  FIXME!!!! This
whole class seems overly complicated with TOO MANY nested try:excepts:

Rename all target .py files and classes without _target in them.

This is so they are the named the same as the target .sh files
and work with the now simplified module loading.

chmod +x all sh scripts so they can run from the git checkout

Use normpath from support

Fix mounts, mountmap hardcoding removal...

Use normpath to fix paths, add some debug print statements,
Fix some missed conversions from uppercase to lowercase settings members.

fix options being reset by a config file

Update module loading for the new python structure, rename snapshot_target to snapshot

Move base stage and target files to thier own sub-pkg

Fix an indent error in grp_target.py

remove redundant /bin/bash additions in cmd() calls

some spacing and comment and indent cleanup, etc.

Begin splitting up generic_stage_target into smaller code blocks.

This so snapshot_target does not need to import it since most of it was
not used or initialized properly.

Massive pyflakes import cleanup and broken CatalystError calls.

Replace "import *" with named imports, remove unused imports.
Fix broken CatalystError usage.

Move LockInUse from support.py to lock.py, fix bad execption raising,  pyflakes cleanup

Some options cleanup, unifying their use, reducing redundancy.

Move confdefaults out of main.py

Initial creation of a defaults file and Split up support.py

Split out hash and contents to their own classes, files.

Fix undefined variable: RLIMIT_NOFILE

It was not imported from resource, it was also not used correctly.

Remove unused variable new and an undefined variable s.

Commit b3475906d5f51a21ecaf4ff048002a2f44face52 introduced an
undefined variable "s".  The code must always be hitting the
general except: pass block.  Seems useless, if not maybe it'll
spit out a true error, so the real problem can be fixed.  Removed it all.

Remove unused urllib import.

This urllib import was added in commit 64c16cae70da13de3c55d8555a2e4c5dcdf2fcad
to fix an issue, but it is not used.  So must have covered up the real bug.  Removing it now
that I've completed some testing and haven't come across anything I can attribute to it.

rename files directory to etc to better reflect the directories contents

rename the modules subpkg to targets, it better reflects what it contains

move catalyst_support, builder, catalyst_lock out of modules, into the catalyst's base namespace

fix catalyst_support import to new location and specify imported modules

update the module loading paths for the new locations

add __init__.py's to modules and arch sub-pkgs

new minimal start script

Initial rearrangement of the python directories

cleanup long lines, improve usage() output formatting slightly

Remove self.mounts and self.mountmap's use of paths for keys and paths.

Migrate more hardcoded paths to use settings variables instead.

Add more configured defaults

Use the new configured snapshot_name and portdir settings
Use the portdir setting rather than hard-coded path

Whitespace cleanup.

Run the following command to cleanup whitespace.
  for FILE in $(git ls-tree -r --name-only HEAD | grep -v 'bz2$'); do
    sed -i 's/[[:space:]]*$//' "$FILE"
  done

kmerge.sh: Make /var/tmp/${clst_kname}.config optional

For users that don't want to specify a seed config.

Reviewed-by: Matt Turner <mattst88@gmail.com>

generic_stage_target: Handle unspecified boot/kernel/<kname>/config

If boot/kernel/<kname>/config is not set, make _copy_kernel_config a
no-op.

Reviewed-by: Matt Turner <mattst88@gmail.com>

generic_stage_target: Split ._copy_initramfs_overlay() from ._build_kernel()

_copy_initramfs_overlay() is long enough that it makes reading
_build_kernel() difficult.

Reviewed-by: Matt Turner <mattst88@gmail.com>

generic_stage_target.py: Dedent the bulk of ._build_kernel()

At the beginning of the function, we check for an autoresume point.
If we find it, just return.  This allows us to dedent the `else` block
that had been handling the no-autoresume-found case.

Reviewed-by: Matt Turner <mattst88@gmail.com>

generic_stage_target: Split ._copy_kernel_config() from ._build_kernel()

_copy_kernel_config() is one idea with a bunch of error handling.
Isolating it in its own function makes _build_kernel() easier to read.

Reviewed-by: Matt Turner <mattst88@gmail.com>

generic_stage_target: Split ._build_kernel() out of .build_kernel()

The indentation was getting too deep ;).  This also makes the
single-kernel-building code more digestible, by removing the
multiple-kernel looping and error handling from the function you're
reading.

Reviewed-by: Matt Turner <mattst88@gmail.com>

Make sure shutil.rmtree() isn't passed a symlink

Bugzilla: https://bugs.gentoo.org/show_bug.cgi?id=455022
Reviewed-by: Matt Turner <mattst88@gentoo.org>

Add hppa support for netboot 2 target

Bugzilla: https://bugs.gentoo.org/show_bug.cgi?id=455018
Reviewed-by: Matt Turner <mattst88@gentoo.org>

don't build packages during update_seed

when update_seed is run it uses the default catalyst emerge options
which causes binary packages to be built which are linked against the
seed stage rather than the generated stage.  These binary packages
can be later used and cause significant and odd issues due to being
linked to older libraries.  I am passing "--buildpkg=n" for the
update_seed runs to prevent this issue and close bug #454184

make bindist optional

After the recent fixes which ensure the bindist use flag
is always set, users now have no way to disable this flag.
This patch introduces the new "bindist" feature, enabled by
default, which will allow users to turn off bindist if
they are not going to redistribute the builds (or for
tinderbox testing, etc).

Use update_seed_command, as documented

Not update_command. Bug in 4dc9de30.

Use 'in' instead of deprecated has_key()

Since Python 2.2 'in' has been preferred to has_key() since it is
shorter, more readable, and faster. has_key() has been deprecated since
2.6 and was removed in 3.0.

See:
http://www.python.org/dev/peps/pep-0290/#testing-dictionary-membership

Mostly scripted with
sed -i -e 's/if \(not \)\?\(.*\)\.has_key(\(.*\))/if \3 \1in \2/'

bug fix wrt 443024, recent changes to use lbzip2 were too agressive
and we should only be using lbzip2 OUTSIDE the chroot, inside the
chroot we don't have lbzip2 available at this time.

ppc: Remove -fno-strict-aliasing from CFLAGS

Added temporarily in 2004 (commit b010c1bd) for gcc-3.3.3/nptl. Time to
go.

Fixes https://bugs.gentoo.org/show_bug.cgi?id=449240