---
eclass/cdrom.eclass | 121 +++++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 96 insertions(+), 25 deletions(-)
diff --git a/eclass/cdrom.eclass b/eclass/cdrom.eclass
index 36d967d2f4cd..c95bb80325e9 100644
--- a/eclass/cdrom.eclass
+++ b/eclass/cdrom.eclass
@@ -6,13 +6,13 @@
# ga...@gentoo.org
# @BLURB: Functions for CD-ROM handling
# @DESCRIPTION:
-# Acquire cd(s) for those lovely cd-based emerges. Yes, this violates
-# the whole 'non-interactive' policy, but damnit I want CD support!
+# Acquire CD(s) for those lovely CD-based emerges. Yes, this violates
+# the whole "non-interactive" policy, but damnit I want CD support!
#
-# With these cdrom functions we handle all the user interaction and
-# standardize everything. All you have to do is call cdrom_get_cds()
-# and when the function returns, you can assume that the cd has been
-# found at CDROM_ROOT.
+# Do not call these functions in pkg_* phases like pkg_setup as they
+# should not be used for binary packages. Most packages using this
+# eclass will require RESTRICT="bindist" but the point still stands.
+# The functions are generally called in src_unpack.
if [[ -z ${_CDROM_ECLASS} ]]; then
_CDROM_ECLASS=1
@@ -24,8 +24,8 @@ inherit portability
# @DESCRIPTION:
# By default, the eclass sets PROPERTIES="interactive" on the assumption
# that people will be using these. If your package optionally supports
-# disc based installed, then set this to "yes", and we'll set things
-# conditionally based on USE=cdinstall.
+# disc-based installs then set this to "yes" and we'll set things
+# conditionally based on USE="cdinstall".
if [[ ${CDROM_OPTIONAL} == "yes" ]] ; then
IUSE="cdinstall"
PROPERTIES="cdinstall? ( interactive )"
@@ -34,19 +34,41 @@ else
fi
# @FUNCTION: cdrom_get_cds
-# @USAGE: <file on cd1> [file on cd2] [file on cd3] [...]
+# @USAGE: <cd1 file>[:alt cd1 file] [cd2 file[:alt cd2 file]] [...]
# @DESCRIPTION:
-# The function will attempt to locate a cd based upon a file that is on
-# the cd. The more files you give this function, the more cds the cdrom
-# functions will handle.
+# Attempt to locate a CD based upon a file that is on the CD.
#
-# Normally the cdrom functions will refer to the cds as 'cd #1', 'cd #2',
-# etc... If you want to give the cds better names, then just export
-# the appropriate CDROM_NAME variable before calling cdrom_get_cds().
-# Use CDROM_NAME for one cd, or CDROM_NAME_# for multiple cds. You can
-# also use the CDROM_NAMES bash array.
+# If the data spans multiple discs then additional arguments can be
+# given to check for more files. Call cdrom_load_next_cd() to scan for
+# the next disc in the set.
#
-# For those multi cd ebuilds, see the cdrom_load_next_cd() function.
+# Sometimes it is necessary to support alternative CD "sets" where the
+# contents differ. Alternative files for each disc can be appended to
+# each argument, separated by the : character. This feature is
+# frequently used to support installing from an existing installation.
+# Note that after the first disc is detected, the set is locked so
+# cdrom_load_next_cd() will only scan for files in that specific set on
+# subsequent discs.
+#
+# The given files can be within named subdirectories. It is not
+# necessary to specify different casings of the same filename as
+# matching is done case-insensitively. Filenames can include special
+# characters such as spaces. Only : is not allowed.
+#
+# If you don't want each disc to be referred to as "CD #1", "CD #2",
+# etc. then you can optionally provide your own names. Set CDROM_NAME
+# for a single disc, CDROM_NAMES as an array for multiple discs, or
+# individual CDROM_NAME_# variables for each disc starting from 1.
+#
+# Despite what you may have seen in older ebuilds, it has never been
+# possible to provide per-set disc names. This would not make sense as
+# all the names are initially displayed before the first disc has been
+# detected. As a workaround, you can redefine the name variable(s)
+# after the first disc has been detected.
+#
+# This function ends with a cdrom_load_next_cd() call to scan for the
+# first disc. For more details about variables read and written by this
+# eclass, see that function's description.
cdrom_get_cds() {
unset CDROM_SET
export CDROM_CURRENT_CD=0 CDROM_CHECKS=( "${@}" )
@@ -100,13 +122,62 @@ cdrom_get_cds() {
# @FUNCTION: cdrom_load_next_cd
# @DESCRIPTION:
-# Some packages are so big they come on multiple CDs. When you're done
-# reading files off a CD and want access to the next one, just call this
-# function. Again, all the messy details of user interaction are taken
-# care of for you. Once this returns, just read the variable CDROM_ROOT
-# for the location of the mounted CD. Note that you can only go forward
-# in the CD list, so make sure you only call this function when you're
-# done using the current CD.
+# If multiple arguments were given to cdrom_get_cds() then you can call
+# this function to scan for the next disc. This function is also called
+# implicitly to scan for the first disc.
+#
+# The file(s) given to cdrom_get_cds() are scanned for on any mounted
+# filesystem that resembles optical media. If no match is found then
+# the user is prompted to insert and mount the disc and press enter to
+# rescan. This will loop continuously until a match is found or the
+# user aborts with Ctrl+C.
+#
+# The user can override the scan location by setting CD_ROOT for a
+# single disc, CD_ROOT if multiple discs are merged into the same
+# directory tree (useful for existing installations), or individual
+# CD_ROOT_# variables for each disc starting from 1. If no match is
+# found then the function dies with an error as a rescan will not help
+# in this instance.
+#
+# Users wanting to set CD_ROOT or CD_ROOT_# for specific packages
+# persistently can do so using Portage's /etc/portage/env feature.
+#
+# Regardless of which scanning method is used, several variables are set
+# by this function for you to use:
+#
+# CDROM_ROOT: Root path of the detected disc.
+# CDROM_MATCH: Path of the matched file, relative to CDROM_ROOT.
+# CDROM_ABSMATCH: Absolute path of the matched file.
+# CDROM_SET: The matching set number, starting from 0.
+#
+# The casing of CDROM_MATCH may not be the same as the argument given to
+# cdrom_get_cds() as matching is done case-insensitively. You should
+# therefore use this variable (or CDROM_ABSMATCH) when performing file
+# operations to ensure the file is found. Use newins rather than doins
+# to keep the final result consistent and take advantage of Bash
+# case-conversion features like ${FOO,,}.
+#
+# Chances are that you'll need more than just the matched file from each
+# disc though. You should not assume the casing of these files either
+# but dealing with this goes beyond the scope of this ebuild. For a
+# good example, see games-action/descent2-data, which combines advanced
+# globbing with advanced tar features to concisely deal with
+# case-insensitive matching, case conversion, file moves, and
+# conditional exclusion.
+#
+# Copying directly from a mounted disc using doins/newins will remove
+# any read-only permissions but be aware of these when copying to an
+# intermediate directory first. Attempting to clean a build directory
+# containing read-only files as a non-root user will result in an error.
+# If you're using tar as suggested above then you can easily work around
+# this with --mode=u+w.
+#
+# Note that you can only go forwards in the disc list, so make sure you
+# only call this function when you're done using the current disc.
+#
+# If you cd to any location within CDROM_ROOT then remember to leave the
+# directory before calling this function again, otherwise the user won't
+# be able to unmount the current disc.
cdrom_load_next_cd() {
local showedmsg=0 showjolietmsg=0
--
2.11.0
