Makefile: Use asciidoc and Pandoc to generate MediaWiki doc versions

We need this because hosting content under:

  https://www.gentoo.org/proj/

is deprecated, with per-project documentation migrating to the wiki [1]

* `--attribute 'toc!'` disables AsciiDoc's table of contents [2],
  which Pandoc doesn't like.
* The Pandoc invocation is about as basic as it gets [3].

[1]: https://wiki.gentoo.org/wiki/Gentoo_Wiki:Developer_Central/Project_pages#Migration_from_www.gentoo.org.2Fproj.2F
[2]: http://asciidoc.org/userguide.html#X91
[3]: http://johnmacfarlane.net/pandoc/README.html#using-pandoc

generic_stage_target: Add a trailing / to the cp /etc/reolv.conf command

livecdfs-update: No tmpfs on /lib/firmware

As of a while ago, we no longer ship a separate firmware tarball, so we
don't need a tmpfs for /lib/firmware anymore, so let's stop mounting
one.  Fixes firmware issues with current minimal install ISOs.

Move confdefaults out of main.py

Move generic_stage_targets.py constants to defaults.py

Rename the source and target mounts defaults to remove
the double plural.

Creation of a new defaults.py

catalyst/support.py: Move some defaults to a new defaults file.

Fix undefined variable: RLIMIT_NOFILE

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

main.py: print the output of an ImportError to help in debugging.

Initial separation and creation of contents.py

Initial separation and creation of a hash_utils.py module

files/catalyst.conf: Whitespace cleanup

Add arm64 support

Brian Dolbec: Modify patch for the new directory structure and apply.
              Cleanup the imports.

catalyst/targets/generic_target.py: Pass TERM through to the chroot

Avoid:

  Running stage1-chroot.sh in chroot /var/tmp/catalyst/tmp/default/...
  tput: No value for $TERM and no -T specified

by passing the caller's TERM environment variable [1] through to the
chroot.  If the caller does not supply TERM, default to 'dumb' which
disables color etc., but should be the most portable.  On Gentoo, the
dumb terminfo (/usr/share/terminfo/d/dumb) is distributed as part of
ncurses [2].  You can list supported terminals with toe, which is also
distributed with ncurses [2]:

  $ toe
  ansi            ansi/pc-term compatible with color
  dumb            80-column dumb tty
  linux           linux console
  ...

[1]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03
[2]: http://www.gnu.org/software/ncurses/

generic_stage_target.py: Fix an intermittent snapshot_cache_path keyerror

Fix autoresume file paths to only be configured once.

Use: pjoin as a shorter alias to os.path.join()

Commit a testpath file to source with instructions on it's use.

Make testpath automagic via dwfeed's tweak
Update HOWTO on how to run the git checkout code directly without being installed.

catalyst/support.py: Update for snakeoil API change.

catalyst/arch/m68k.py: fix missed import cleanup during move/rebase.

Makefile: Fix PACKAGE_VERSION extraction

The old method grepped for __version__ in catalyst.  That broke with
24c5352 (Initial rearrangement of the python directories, 2013-01-10),
which moved catalyst to bin/catalyst, kept the __version__ in
bin/catalyst, and added a new __version__ in catalyst/main.py.  Then
46b261e (setup.py: Add disutils-based packaging, 2013-06-05)
consolidated the __version__ definitions in catalyst/__init__.py,
removing them from bin/catalyst and catalyst/main.py.  This patch
adjusts the Makefile, invoking Python to extract catalyst.__version__
instead of grepping through the file that defines it.

setup.py: Add disutils-based packaging

Package catalyst in the usual manner for Python projects.  Now it is
ready for PyPI :).

I also expose the version string in catalyst.__version__ and the
maintainer string in catalyst.__maintainer__, since those are more
traditional locations.

I dropped official Python 2.6 support following:

  19:31 <@jmbsvicetto> I don't see a need to make catalyst
        incompatible with 2.6, but I think it's time we drop it as a
        "requirement". So feel free to do any changes that improve the
        code, even if they drop 2.6 compatibility

I kept the explicit indexes in the string formatting, since Python 2.6
doesn't support:

  '{}'.format(value)

Move catalyst.conf and catalystrc to an etc/ directory

Rename the modules subpkg to targets, to better reflect what it contains.

Move catalyst_support, builder, catalyst_lock out of modules, into the catalyst namespace.

Initial rearrangement of the python directories

New minimal start script, moving the original catalyst script to catalyst/main.py.
Add __init__.py's to modules and arch sub-pkgs.
skip __init__.py when loading the modules.
Update the module loading paths for the new locations.
Fix catalyst_support import to new location and specify imported modules.

Update AUTHORS to review credit and split the list of people in original authors, significant contributors and contributors.

Remove an extra slash in the path.

Remove some troublesome trailing slashes from paths

Change the docstring to warn to use a proper path join function.
Modify the functions.sh output to display the actual command it
is about to run.

chmod +x targets/stage1/build.py

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

catalyst/targets/generic_stage_target.py: mount /dev/shm on linux

Add shm targets defaults. Anthony G. Basile <blueness@gentoo.org>
Some build systems require /dev/shm to be mounted, like python's
build system.  We make sure that on Linux systems, /dev/shm is
mounted in the stage chroots.  See bug #496328.

Douglas Freed <dwfreed@mtu.edu> :
Mount /dev/shm in the chroot with the right options
Bind mounting /dev/shm into the chroot isn't a good idea, as there may
be collisions and result in weird side effects.  Instead, we can just
mount a new tmpfs there, with the right options to ensure security.

(Forward ported to pending branch from 2.X Brian Dolbec)
Conflicts:
catalyst/targets/generic_stage_target.py

modules/generic_stage_target.py, Create SOURCE_MOUNTS_DEFAULTS

Similarly to TARGET_MOUNTS_DEFAULTS this is a temporary location.
This will simplify the migration to being fully configurable.
It also simplifies initialization somewhat.

doc/HOWTO.txt: Fix stage descriptions, and add extra context

Thanks to Zero_Chaos, dwfreed, and jmbsvicetto for clarification and
review on #gentoo-releng.

Set mountmap["icecream"] from settings for now.

“mountmap” is for source paths.  “mounts” is for path-agnostic keys.
I plan to add a source_mounts to settings later to compliment the target_mounts paths.

modules/generic_stage_target.py, modules/stage1_target.py: Add a target_mounts dictionary

Temporary location to define TARGET_MOUNTS_DEFAULTS.
It will be moved to a new defaults.py file in a later commit.
I also plan to make them configurable.

Also:
* Clean up all self.mounts, self.mountmap usage.
* Replace multiple path additions with one instance at the
  beginning of the function, reuse the result multiple times.
* Add some extra debug prints (to be converted to logging later)

Fix mounts and mountmap port_logdir code block.

Add "local_overlay" to configdefaults.

Fixes commit 463d98f
  (modules/generic_stage_target.py: Use a 'local_overlay'
   setting instead of hard-coding '/usr/local/portage',
   2012-12-19)

Fix a missed self.settings["repo_name"] migration

Use normpath() on it as well.
Fix the coding style in the lines touched.

modules/generic_stage_target.py: Use portdir, distdir, ... instead of paths for keys

If snapcache is enabled, self.mounts and self.mountmap had not been
modified like they were if it was not enabled.

Added a print statement for debugging to be converted to logging in
the future.

modules/generic_stage_target.py: Use 'devpts' as mountmap key.

Missed in 0c68d30b. Would cause catalyst to fail if snapcache were
enabled.

Tested-by: Brian Dolbec <dolsen@gentoo.org>

catalst: improve usage() output formatting slightly

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'ccache' instead of '/var/tmp/ccache' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'kerncache' instead of '/tmp/kerncache' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'packagedir' instead of '/usr/portage/packages' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'devpts' instead of '/dev/pts' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'port_tmpdir' instead of '/var/tmp/portage' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'distdir' instead of '/usr/portage/distfiles' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'dev' instead of '/dev' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'proc' instead of '/proc' as the mountmap key

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Don't use paths as mountmap keys

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

catalyst: Add 'packagedir' default instead of hard-coding '/usr/portage/packages'

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

catalyst: Add 'snapshot_name' default

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

catalyst: Add 'repo_name' default

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

catalyst: Split confdefaults into line-per-entry

This makes it easy to find the key you're looking for.  Future
additions and removals will also have cleaner diffs.

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use a 'local_overlay' setting instead of hard-coding '/usr/local/portage'

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'distdir' instead of hard-coding '${PORTAGE}/distfiles'

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'portdir' instead of hard-coding '/usr/portage'

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/generic_stage_target.py: Use 'portdir' instead of hard-coding '/usr/portage'

W. Trevor King: Refactored Git history for Brian Dolbec's content changes.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

modules/tinderbox_target.py: Use 'portdir' instead of hard-coding '/usr/portage'

W. Trevor King: Refactored Git history for Brian Dolbec's content
changes with additional whitespace cleanups.

Reviewed-by: Matt Turner <mattst88@gentoo.org>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Brian Dolbec <dolsen@gentoo.org>

catalyst 2.0.15

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.

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

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

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

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

This reverts commit ed4d1623c3dac22ed008f518b79deecde1f33c26.

The commit was a v1 commit that was supposed to be replaced.

catalyst: Remove commented sections of code

Code in the upstream tree should either run or it shouldn't be there.

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

catalyst: split combined import

Combining multiple modules into a single import is discouraged in
python's PEP8 style guide:

"""
Imports should usually be on separate lines, e.g.:

Yes: import os
     import sys

     No:  import sys, os
"""

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

catalyst: use a more pythonic method to import modules

Rather than appending a directory to the system path, this patch adds a
__init__.py file to modules, which allows python to search it, and it's
children for python modules. This also requires changes to a few of the
module files to make them happy.

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

catalyst: Specify python2 rather than the generic python

This allows catalyst to work regardless of whether a user prefers that
usr/bin/python be python 2.x or 3.x.

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

catalyst 2.0.14

generic_stage_target: default {PORT,PKG,DIST}DIR

This provides forward compatiblity so that stage builds do not break
in the future when portage changes the default PORTDIR, PKGDIR, and
DISTDIR locations (bug #378603).

Also, it provides backward compatibility for various tools that require
PORTDIR to be defined in make.conf, such as the following:

gentoo-bashcomp - bug #478444
euse - bug #474574
euses and ufed - bug #478318

X-Gentoo-Bug: 479062
X-Gentoo-Bug-URL: https://bugs.gentoo.org/show_bug.cgi?id=479062
Reviewed-by: Matt Turner <mattst88@gmail.com>

stop tarballing firmware

I can't find a reason why firmware is tarballed in the first
place, and now things are messing up because of missing firmware.
Remove tarballing and tmpfs mount for /lib/firmware and just leave
it alone. Bug 479456

kerncache improperly sets --nodeps

It makes no sense to set --nodeps just because kerncache is being
used, the kernel still must be built at least once

Fix incorrect type for livecd/modblacklist.

Bug reported by tstellar.

correctly remove USE=build

c0fcbf027169da8b6f0d5e3c80c1526642c6c672 indavertantly dropped all
livecd-stage2 use flags, rewrite to just drop undesired build.

Revert "kmerge.sh: Don't set USE=build for emerging kernels."

This appears to inadvertantly drop livecd-stage2 use flags entirely.

This reverts commit c0fcbf027169da8b6f0d5e3c80c1526642c6c672.

catalyst 2.0.13

Fix a py3 syntax error, use print()

Bug reported by Michael Weber <xmw>

kmerge.sh: Don't set USE=build for emerging kernels.

USE=build for kernels means that they're not going to be built and that
we just want to install the sources. In catalyst, we do also want to
build the kernels, so settings the (badly named) USE flag prevents
installing sys-devel/bc, ultimately leading to the kernel build failing.

Remove USE=build from kmerge.sh and let it install dependencies
necessary for actually building the kernel. Fixes Live CD builds with
kernels that require bc (>= 3.9, I believe). See bug 478244.

Tested-by: Ben Kohler <bkohler@gmail.com>

Remove ChangeLog.

git tells us the same information, but better.

chroot-functions: Give variables more appropriate names.

Replace 'system' with '@system' where applicable, to be more greppable.

Fixes a bug inadvertently caused by 6c0a577 where setting update_seed
to no would result in dropping the use and making of binpkgs while
building stage1, which is undesirable.  The conditional was getting a
bit unwieldly, so I added a comment explaining when it matches, which is
especially helpful to those who don't know every single test flag.

Tested-By: Rick Farina <zerochaos@gentoo.org>
Tested-By: Brian Dolbec <dolsen@gentoo.org>

proper lbzip2 decompression of stages

use lbzip2 to decompress stages ONLY, snapshots can be bz2 or xz.
This provides me a 6x increase and likely more if you have fast IO

Revert "use lbzip2 to unpack the stages"

This reverts commit 978c02e6fa04ab7ed1a40003fa0eb4cfce952ca2, missed a
test

use lbzip2 to unpack the stages

Since we already use lbzip2 to compress everthing,
it makes a significant performance difference to
also unpack the stages using lbzip2.  When the stage
compression is selectable this should be enhanced to use
other decompressors as well (although xz doesn't seem to
need a multi-threaded decompressor).

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

Drop addpatches from the stage4 example spec.

Fix broken "preserve_libs" commit - ";" is not ":".

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

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

Fix update_seed use by not using nor building binary packages during the seed update.

Add support for m68k

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.txt: Explain how to run catalyst without installing

Thanks to Chris White for explaining this to me.

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>

doc/HOWTO: First pass at a gentle Catalyst introduction

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

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
  git checkout COPYING ChangeLog

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.

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>

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>