diff options
Diffstat (limited to 'eclass')
| -rw-r--r-- | eclass/cdrom.eclass | 121 |
1 files changed, 96 insertions, 25 deletions
diff --git a/eclass/cdrom.eclass b/eclass/cdrom.eclass index 5eeb52a0ed0f..800d97383b52 100644 --- a/eclass/cdrom.eclass +++ b/eclass/cdrom.eclass @@ -6,13 +6,13 @@ # games@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 |