1 |
--- |
2 |
eclass/cdrom.eclass | 121 +++++++++++++++++++++++++++++++++++++++++----------- |
3 |
1 file changed, 96 insertions(+), 25 deletions(-) |
4 |
|
5 |
diff --git a/eclass/cdrom.eclass b/eclass/cdrom.eclass |
6 |
index 36d967d2f4cd..c95bb80325e9 100644 |
7 |
--- a/eclass/cdrom.eclass |
8 |
+++ b/eclass/cdrom.eclass |
9 |
@@ -6,13 +6,13 @@ |
10 |
# games@g.o |
11 |
# @BLURB: Functions for CD-ROM handling |
12 |
# @DESCRIPTION: |
13 |
-# Acquire cd(s) for those lovely cd-based emerges. Yes, this violates |
14 |
-# the whole 'non-interactive' policy, but damnit I want CD support! |
15 |
+# Acquire CD(s) for those lovely CD-based emerges. Yes, this violates |
16 |
+# the whole "non-interactive" policy, but damnit I want CD support! |
17 |
# |
18 |
-# With these cdrom functions we handle all the user interaction and |
19 |
-# standardize everything. All you have to do is call cdrom_get_cds() |
20 |
-# and when the function returns, you can assume that the cd has been |
21 |
-# found at CDROM_ROOT. |
22 |
+# Do not call these functions in pkg_* phases like pkg_setup as they |
23 |
+# should not be used for binary packages. Most packages using this |
24 |
+# eclass will require RESTRICT="bindist" but the point still stands. |
25 |
+# The functions are generally called in src_unpack. |
26 |
|
27 |
if [[ -z ${_CDROM_ECLASS} ]]; then |
28 |
_CDROM_ECLASS=1 |
29 |
@@ -24,8 +24,8 @@ inherit portability |
30 |
# @DESCRIPTION: |
31 |
# By default, the eclass sets PROPERTIES="interactive" on the assumption |
32 |
# that people will be using these. If your package optionally supports |
33 |
-# disc based installed, then set this to "yes", and we'll set things |
34 |
-# conditionally based on USE=cdinstall. |
35 |
+# disc-based installs then set this to "yes" and we'll set things |
36 |
+# conditionally based on USE="cdinstall". |
37 |
if [[ ${CDROM_OPTIONAL} == "yes" ]] ; then |
38 |
IUSE="cdinstall" |
39 |
PROPERTIES="cdinstall? ( interactive )" |
40 |
@@ -34,19 +34,41 @@ else |
41 |
fi |
42 |
|
43 |
# @FUNCTION: cdrom_get_cds |
44 |
-# @USAGE: <file on cd1> [file on cd2] [file on cd3] [...] |
45 |
+# @USAGE: <cd1 file>[:alt cd1 file] [cd2 file[:alt cd2 file]] [...] |
46 |
# @DESCRIPTION: |
47 |
-# The function will attempt to locate a cd based upon a file that is on |
48 |
-# the cd. The more files you give this function, the more cds the cdrom |
49 |
-# functions will handle. |
50 |
+# Attempt to locate a CD based upon a file that is on the CD. |
51 |
# |
52 |
-# Normally the cdrom functions will refer to the cds as 'cd #1', 'cd #2', |
53 |
-# etc... If you want to give the cds better names, then just export |
54 |
-# the appropriate CDROM_NAME variable before calling cdrom_get_cds(). |
55 |
-# Use CDROM_NAME for one cd, or CDROM_NAME_# for multiple cds. You can |
56 |
-# also use the CDROM_NAMES bash array. |
57 |
+# If the data spans multiple discs then additional arguments can be |
58 |
+# given to check for more files. Call cdrom_load_next_cd() to scan for |
59 |
+# the next disc in the set. |
60 |
# |
61 |
-# For those multi cd ebuilds, see the cdrom_load_next_cd() function. |
62 |
+# Sometimes it is necessary to support alternative CD "sets" where the |
63 |
+# contents differ. Alternative files for each disc can be appended to |
64 |
+# each argument, separated by the : character. This feature is |
65 |
+# frequently used to support installing from an existing installation. |
66 |
+# Note that after the first disc is detected, the set is locked so |
67 |
+# cdrom_load_next_cd() will only scan for files in that specific set on |
68 |
+# subsequent discs. |
69 |
+# |
70 |
+# The given files can be within named subdirectories. It is not |
71 |
+# necessary to specify different casings of the same filename as |
72 |
+# matching is done case-insensitively. Filenames can include special |
73 |
+# characters such as spaces. Only : is not allowed. |
74 |
+# |
75 |
+# If you don't want each disc to be referred to as "CD #1", "CD #2", |
76 |
+# etc. then you can optionally provide your own names. Set CDROM_NAME |
77 |
+# for a single disc, CDROM_NAMES as an array for multiple discs, or |
78 |
+# individual CDROM_NAME_# variables for each disc starting from 1. |
79 |
+# |
80 |
+# Despite what you may have seen in older ebuilds, it has never been |
81 |
+# possible to provide per-set disc names. This would not make sense as |
82 |
+# all the names are initially displayed before the first disc has been |
83 |
+# detected. As a workaround, you can redefine the name variable(s) |
84 |
+# after the first disc has been detected. |
85 |
+# |
86 |
+# This function ends with a cdrom_load_next_cd() call to scan for the |
87 |
+# first disc. For more details about variables read and written by this |
88 |
+# eclass, see that function's description. |
89 |
cdrom_get_cds() { |
90 |
unset CDROM_SET |
91 |
export CDROM_CURRENT_CD=0 CDROM_CHECKS=( "${@}" ) |
92 |
@@ -100,13 +122,62 @@ cdrom_get_cds() { |
93 |
|
94 |
# @FUNCTION: cdrom_load_next_cd |
95 |
# @DESCRIPTION: |
96 |
-# Some packages are so big they come on multiple CDs. When you're done |
97 |
-# reading files off a CD and want access to the next one, just call this |
98 |
-# function. Again, all the messy details of user interaction are taken |
99 |
-# care of for you. Once this returns, just read the variable CDROM_ROOT |
100 |
-# for the location of the mounted CD. Note that you can only go forward |
101 |
-# in the CD list, so make sure you only call this function when you're |
102 |
-# done using the current CD. |
103 |
+# If multiple arguments were given to cdrom_get_cds() then you can call |
104 |
+# this function to scan for the next disc. This function is also called |
105 |
+# implicitly to scan for the first disc. |
106 |
+# |
107 |
+# The file(s) given to cdrom_get_cds() are scanned for on any mounted |
108 |
+# filesystem that resembles optical media. If no match is found then |
109 |
+# the user is prompted to insert and mount the disc and press enter to |
110 |
+# rescan. This will loop continuously until a match is found or the |
111 |
+# user aborts with Ctrl+C. |
112 |
+# |
113 |
+# The user can override the scan location by setting CD_ROOT for a |
114 |
+# single disc, CD_ROOT if multiple discs are merged into the same |
115 |
+# directory tree (useful for existing installations), or individual |
116 |
+# CD_ROOT_# variables for each disc starting from 1. If no match is |
117 |
+# found then the function dies with an error as a rescan will not help |
118 |
+# in this instance. |
119 |
+# |
120 |
+# Users wanting to set CD_ROOT or CD_ROOT_# for specific packages |
121 |
+# persistently can do so using Portage's /etc/portage/env feature. |
122 |
+# |
123 |
+# Regardless of which scanning method is used, several variables are set |
124 |
+# by this function for you to use: |
125 |
+# |
126 |
+# CDROM_ROOT: Root path of the detected disc. |
127 |
+# CDROM_MATCH: Path of the matched file, relative to CDROM_ROOT. |
128 |
+# CDROM_ABSMATCH: Absolute path of the matched file. |
129 |
+# CDROM_SET: The matching set number, starting from 0. |
130 |
+# |
131 |
+# The casing of CDROM_MATCH may not be the same as the argument given to |
132 |
+# cdrom_get_cds() as matching is done case-insensitively. You should |
133 |
+# therefore use this variable (or CDROM_ABSMATCH) when performing file |
134 |
+# operations to ensure the file is found. Use newins rather than doins |
135 |
+# to keep the final result consistent and take advantage of Bash |
136 |
+# case-conversion features like ${FOO,,}. |
137 |
+# |
138 |
+# Chances are that you'll need more than just the matched file from each |
139 |
+# disc though. You should not assume the casing of these files either |
140 |
+# but dealing with this goes beyond the scope of this ebuild. For a |
141 |
+# good example, see games-action/descent2-data, which combines advanced |
142 |
+# globbing with advanced tar features to concisely deal with |
143 |
+# case-insensitive matching, case conversion, file moves, and |
144 |
+# conditional exclusion. |
145 |
+# |
146 |
+# Copying directly from a mounted disc using doins/newins will remove |
147 |
+# any read-only permissions but be aware of these when copying to an |
148 |
+# intermediate directory first. Attempting to clean a build directory |
149 |
+# containing read-only files as a non-root user will result in an error. |
150 |
+# If you're using tar as suggested above then you can easily work around |
151 |
+# this with --mode=u+w. |
152 |
+# |
153 |
+# Note that you can only go forwards in the disc list, so make sure you |
154 |
+# only call this function when you're done using the current disc. |
155 |
+# |
156 |
+# If you cd to any location within CDROM_ROOT then remember to leave the |
157 |
+# directory before calling this function again, otherwise the user won't |
158 |
+# be able to unmount the current disc. |
159 |
cdrom_load_next_cd() { |
160 |
local showedmsg=0 showjolietmsg=0 |
161 |
|
162 |
-- |
163 |
2.11.0 |