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