/[gentoo-src]/portage/pym/emergehelp.py
Gentoo

Contents of /portage/pym/emergehelp.py

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.10 - (show annotations) (download) (as text)
Sat Feb 26 06:35:20 2005 UTC (9 years, 8 months ago) by jstubbs
Branch: MAIN
CVS Tags: HEAD
Branch point for: portage_2_1
Changes since 1.9: +4 -3 lines
File MIME type: text/x-python
Brought forward changes from portage_2_0

1 # Copyright 1999-2004 Gentoo Foundation
2 # Distributed under the terms of the GNU General Public License v2
3 # $Header: /var/cvsroot/gentoo-src/portage/pym/emergehelp.py,v 1.9 2004/10/28 14:48:26 jstubbs Exp $
4 cvs_id_string="$Id: emergehelp.py,v 1.8.2.2 2005/01/16 02:35:33 carpaski Exp $"[5:-2]
5
6 import os,sys
7 from output import bold, turquoise, green
8
9 def shorthelp():
10 print
11 print
12 print bold("Usage:")
13 print " "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] [ "+turquoise("ebuildfile")+" | "+turquoise("tbz2file")+" | "+turquoise("dependency")+" ] [ ... ]"
14 print " "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] < "+turquoise("system")+" | "+turquoise("world")+" >"
15 print " "+turquoise("emerge")+" < "+turquoise("--sync")+" | "+turquoise("--metadata")+" | "+turquoise("--info")+" >"
16 print " "+turquoise("emerge")+" "+turquoise("--resume")+" [ "+green("--pretend")+" | "+green("--ask")+" | "+green("--skipfirst")+" ]"
17 print " "+turquoise("emerge")+" "+turquoise("--help")+" [ "+green("system")+" | "+green("config")+" | "+green("sync")+" ] "
18 print bold("Options:")+" "+green("-")+"["+green("abcCdDefhikKlnoOpPsSuUvV")+"] ["+green("--oneshot")+"] ["+green("--newuse")+"] ["+green("--noconfmem")+"]"
19 print " ["+green("--columns")+"] ["+green("--nospinner")+"]"
20 print bold("Actions:")+" [ "+green("--clean")+" | "+green("--depclean")+" | "+green("--inject")+" | "+green("--prune")+" | "+green("--regen")+" | "+green("--search")+" | "+green("--unmerge")+" ]"
21 print
22
23 def help(myaction,myopts,havecolor=1):
24 if not havecolor:
25 nocolor()
26 if not myaction and ("--help" not in myopts):
27 shorthelp()
28 print
29 print " For more help try 'emerge --help' or consult the man page."
30 print
31 elif not myaction:
32 shorthelp()
33 print
34 print turquoise("Help (this screen):")
35 print " "+green("--help")+" ("+green("-h")+" short option)"
36 print " Displays this help; an additional argument (see above) will tell"
37 print " emerge to display detailed help."
38 print
39 print turquoise("Actions:")
40 print " "+green("--clean")+" ("+green("-c")+" short option)"
41 print " Cleans the system by removing outdated packages which will not"
42 print " remove functionalities or prevent your system from working."
43 print " The arguments can be in several different formats :"
44 print " * world "
45 print " * system or"
46 print " * 'dependency specification' (in single quotes is best.)"
47 print " Here are a few examples of the dependency specification format:"
48 print " "+bold("binutils")+" matches"
49 print " binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1"
50 print " "+bold("sys-devel/binutils")+" matches"
51 print " binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1"
52 print " "+bold(">sys-devel/binutils-2.11.90.0.7")+" matches"
53 print " binutils-2.11.92.0.12.3-r1"
54 print " "+bold(">=sys-devel/binutils-2.11.90.0.7")+" matches"
55 print " binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1"
56 print " "+bold("<=sys-devel/binutils-2.11.92.0.12.3-r1")+" matches"
57 print " binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1"
58 print
59 print " "+green("--depclean")
60 print " Cleans the system by removing packages that are not associated"
61 print " with explicitly merged packages. Depclean works by creating the"
62 print " full dependency tree from the system list and the world file,"
63 print " then comparing it to installed packages. Packages installed, but"
64 print " not associated with an explicit merge are listed as candidates"
65 print " for unmerging."+turquoise(" WARNING: This can seriously affect your system by")
66 print " "+turquoise("removing packages that may have been linked against, but due to")
67 print " "+turquoise("changes in USE flags may no longer be part of the dep tree. Use")
68 print " "+turquoise("caution when employing this feature.")
69 print
70 print " "+green("--info")
71 print " Displays important portage variables that will be exported to"
72 print " ebuild.sh when performing merges. This information is useful"
73 print " for bug reports and verification of settings. All settings in"
74 print " make.{conf,globals,defaults} and the environment show up if"
75 print " run with the '--verbose' flag."
76 print
77 print " "+green("--metadata")
78 print " Causes portage to process all the metacache files as is normally done"
79 print " on the tail end of an rsync update using "+bold("emerge --sync")+". The"
80 print " processing creates the cache database that portage uses for"
81 print " pre-parsed lookups of package data."
82 print
83 print " "+green("--prune")+" ("+green("-P")+" short option)"
84 print " "+turquoise("WARNING: This action can remove important packages!")
85 print " Removes all but the most recently installed version of a package"
86 print " from your system. This action doesn't verify the possible binary"
87 print " compatibility between versions and can thus remove essential"
88 print " dependencies from your system."
89 print " The argument format is the same as for the "+bold("--clean")+" action."
90 print
91 print " "+green("--regen")
92 print " Causes portage to check and update the dependency cache of all"
93 print " ebuilds in the portage tree. This is not recommended for rsync"
94 print " users as rsync updates the cache using server-side caches."
95 print " Rsync users should simply 'emerge --sync' to regenerate."
96 print
97 print " "+green("--search")+" ("+green("-s")+" short option)"
98 print " searches for matches of the supplied string in the current local"
99 print " portage tree. The search string is a regular expression. Prepending"
100 print " the expression with a '@' will cause the category to be included in"
101 print " the search."
102 print " A few examples:"
103 print " "+bold("emerge search '^kde'")
104 print " list all packages starting with kde"
105 print " "+bold("emerge search 'gcc$'")
106 print " list all packages ending with gcc"
107 print " "+bold("emerge search @^dev-java.*jdk")
108 print " list all available Java JDKs"
109 print
110 print " "+green("--unmerge")+" ("+green("-C")+" short option)"
111 print " "+turquoise("WARNING: This action can remove important packages!")
112 print " Removes all matching packages "+bold("completely")+" from"
113 print " your system. Specify arguments using the dependency specification"
114 print " format described in the "+bold("--clean")+" action above."
115 print
116 print turquoise("Options:")
117 print " "+green("--ask")+" ("+green("-a")+" short option)"
118 print " before performing the merge, display what ebuilds and tbz2s will"
119 print " be installed, in the same format as when using --pretend; then"
120 print " ask whether to continue with the merge or abort. Using --ask is"
121 print " more efficient than using --pretend and then executing the same"
122 print " command without --pretend, as dependencies will only need to be"
123 print " calculated once."
124 print
125 print " "+green("--buildpkg")+" ("+green("-b")+" short option)"
126 print " Tell emerge to build binary packages for all ebuilds processed"
127 print " (in addition to actually merging the packages. Useful for"
128 print " maintainers or if you administrate multiple Gentoo Linux"
129 print " systems (build once, emerge tbz2s everywhere) as well as disaster"
130 print " recovery."
131 print
132 print " "+green("--buildpkgonly")+" ("+green("-B")+" short option)"
133 print " Creates a binary package, but does not merge it to the"
134 print " system. This has the restriction that unsatisfied dependencies"
135 print " must not exist for the desired package as they cannot be used if"
136 print " they do not exist on the system."
137 print
138 print " "+green("--changelog")+" ("+green("-l")+" short option)"
139 print " When pretending, also display the ChangeLog entries for packages"
140 print " that will be upgraded."
141 print
142 print " "+green("--columns")
143 print " Display the pretend output in a tabular form. Versions are"
144 print " aligned vertically."
145 print
146 print " "+green("--debug")+" ("+green("-d")+" short option)"
147 print " Tell emerge to run the ebuild command in --debug mode. In this"
148 print " mode, the bash build environment will run with the -x option,"
149 print " causing it to output verbose debug information print to stdout."
150 print " --debug is great for finding bash syntax errors as providing"
151 print " very verbose information about the dependency and build process."
152 print
153 print " "+green("--deep")+" ("+green("-D")+" short option)"
154 print " When used in conjunction with --update, this flag forces emerge"
155 print " to consider the entire dependency tree of packages, instead of"
156 print " checking only the immediate dependencies of the packages. As an"
157 print " example, this catches updates in libraries that are not directly"
158 print " listed in the dependencies of a package."
159 print
160 print " "+green("--emptytree")+" ("+green("-e")+" short option)"
161 print " Virtually tweaks the tree of installed packages to contain"
162 print " nothing. This is great to use together with --pretend. This makes"
163 print " it possible for developers to get a complete overview of the"
164 print " complete dependency tree of a certain package."
165 print
166 print " "+green("--fetchonly")+" ("+green("-f")+" short option)"
167 print " Instead of doing any package building, just perform fetches for"
168 print " all packages (main package as well as all dependencies.) When"
169 print " used in combination with --pretend all the SRC_URIs will be"
170 print " displayed multiple mirrors per line, one line per file."
171 print
172 print " "+green("--fetch-all-uri")+" ("+green("-F")+" short option)"
173 print " Same as --fetchonly except that all package files, including those"
174 print " not required to build the package, will be processed."
175 print
176 print " "+green("--getbinpkg")+" ("+green("-g")+" short option)"
177 print " Using the server and location defined in PORTAGE_BINHOST, portage"
178 print " will download the information from each binary file there and it"
179 print " will use that information to help build the dependency list. This"
180 print " option implies '-k'. (Use -gK for binary-only merging.)"
181 print
182 print " "+green("--getbinpkgonly")+" ("+green("-G")+" short option)"
183 print " This option is identical to -g, as above, except it will not use"
184 print " ANY information from the local machine. All binaries will be"
185 print " downloaded from the remote server without consulting packages"
186 print " existing in the packages directory."
187 print
188 print " "+green("--newuse")
189 print " Tells emerge to include installed packages where USE flags have "
190 print " changed since installation."
191 print
192 print " "+green("--noconfmem")
193 print " Portage keeps track of files that have been placed into"
194 print " CONFIG_PROTECT directories, and normally it will not merge the"
195 print " same file more than once, as that would become annoying. This"
196 print " can lead to problems when the user wants the file in the case"
197 print " of accidental deletion. With this option, files will always be"
198 print " merged to the live fs instead of silently dropped."
199 print
200 print " "+green("--nodeps")+" ("+green("-O")+" short option)"
201 print " Merge specified packages, but don't merge any dependencies."
202 print " Note that the build may fail if deps aren't satisfied."
203 print
204 print " "+green("--noreplace")+" ("+green("-n")+" short option)"
205 print " Skip the packages specified on the command-line that have"
206 print " already been installed. Without this option, any packages,"
207 print " ebuilds, or deps you specify on the command-line *will* cause"
208 print " Portage to remerge the package, even if it is already installed."
209 print " Note that Portage won't remerge dependencies by default."
210 print
211 print " "+green("--nospinner")
212 print " Disables the spinner regardless of terminal type."
213 print
214 print " "+green("--oneshot")
215 print " Emerge as normal, but don't add packages to the world profile."
216 print " This package will only be updated if it is depended upon by"
217 print " another package."
218 print
219 print " "+green("--onlydeps")+" ("+green("-o")+" short option)"
220 print " Only merge (or pretend to merge) the dependencies of the"
221 print " specified packages, not the packages themselves."
222 print
223 print " "+green("--pretend")+" ("+green("-p")+" short option)"
224 print " Instead of actually performing the merge, simply display what"
225 print " ebuilds and tbz2s *would* have been installed if --pretend"
226 print " weren't used. Using --pretend is strongly recommended before"
227 print " installing an unfamiliar package. In the printout, N = new,"
228 print " U = updating, R = replacing, F = fetch restricted, B = blocked"
229 print " by an already installed package, D = possible downgrading,"
230 print " S = slotted install. --verbose causes affecting use flags to be"
231 print " printed out accompanied by a '+' for enabled and a '-' for"
232 print " disabled USE flags."
233 print
234 print " "+green("--quiet")+" ("+green("-q")+" short option)"
235 print " Effects vary, but the general outcome is a reduced or condensed"
236 print " output from portage's displays."
237 print
238 print " "+green("--resume")
239 print " Resumes the last merge operation. Can be treated just like a"
240 print " regular merge as --pretend and other options work along side."
241 print " 'emerge --resume' only returns an error on failure. Nothing to"
242 print " do exits with a message and a success condition."
243 print
244 print " "+green("--searchdesc")+" ("+green("-S")+" short option)"
245 print " Matches the search string against the description field as well"
246 print " the package's name. Take caution as the descriptions are also"
247 print " matched as regular expressions."
248 print " emerge -S html"
249 print " emerge -S applet"
250 print " emerge -S 'perl.*module'"
251 print
252 print " "+green("--skipfirst")
253 print " This option is only valid in a resume situation. It removes the"
254 print " first package in the resume list so that a merge may continue in"
255 print " the presence of an uncorrectable or inconsequential error. This"
256 print " should only be used in cases where skipping the package will not"
257 print " result in failed dependencies."
258 print
259 print " "+green("--tree")+" ("+green("-t")+" short option)"
260 print " Shows the dependency tree using indentation for dependencies."
261 print " The packages are also listed in reverse merge order so that"
262 print " a package's dependencies follow the package. Only really useful"
263 print " in combination with --emptytree, --update or --deep."
264 print
265 print " "+green("--update")+" ("+green("-u")+" short option)"
266 print " Updates packages to the best version available, which may not"
267 print " always be the highest version number due to masking for testing"
268 print " and development. This will also update direct dependencies which"
269 print " may not what you want. In general use this option only in combi-"
270 print " nation with the world or system target."
271 print
272 print " "+green("--usepkg")+" ("+green("-k")+" short option)"
273 print " Tell emerge to use binary packages (from $PKGDIR) if they are"
274 print " available, thus possibly avoiding some time-consuming compiles."
275 print " This option is useful for CD installs; you can export"
276 print " PKGDIR=/mnt/cdrom/packages and then use this option to have"
277 print " emerge \"pull\" binary packages from the CD in order to satisfy"
278 print " dependencies."
279 print
280 print " "+green("--usepkgonly")+" ("+green("-K")+" short option)"
281 print " Like --usepkg above, except this only allows the use of binary"
282 print " packages, and it will abort the emerge if the package is not"
283 print " available at the time of dependency calculation."
284 print
285 print " "+green("--verbose")+" ("+green("-v")+" short option)"
286 print " Effects vary, but the general outcome is an increased or expanded"
287 print " display of content in portage's displays."
288 print
289 print " "+green("--version")+" ("+green("-V")+" short option)"
290 print " Displays the currently installed version of portage along with"
291 print " other information useful for quick reference on a system. See"
292 print " "+bold("emerge info")+" for more advanced information."
293 print
294 elif myaction in ["rsync","sync"]:
295 print
296 print bold("Usage: ")+turquoise("emerge")+" "+turquoise("--sync")
297 print
298 print " 'emerge --sync' tells emerge to update the Portage tree as specified in"
299 print " The SYNC variable found in /etc/make.conf. By default, SYNC instructs"
300 print " emerge to perform an rsync-style update with rsync.gentoo.org."
301 print
302 print " 'emerge-webrsync' exists as a helper app to emerge --sync, providing a"
303 print " method to receive the entire portage tree as a tarball that can be"
304 print " extracted and used. First time syncs would benefit greatly from this."
305 print
306 print " "+turquoise("WARNING:")
307 print " If using our rsync server, emerge will clean out all files that do not"
308 print " exist on it, including ones that you may have created. The exceptions"
309 print " to this are the distfiles, local and packages directories."
310 print
311 elif myaction=="system":
312 print
313 print bold("Usage: ")+turquoise("emerge")+" [ "+green("options")+" ] "+turquoise("system")
314 print
315 print " \"emerge system\" is the Portage system update command. When run, it"
316 print " will scan the etc/make.profile/packages file and determine what"
317 print " packages need to be installed so that your system meets the minimum"
318 print " requirements of your current system profile. Note that this doesn't"
319 print " necessarily bring your system up-to-date at all; instead, it just"
320 print " ensures that you have no missing parts. For example, if your system"
321 print " profile specifies that you should have sys-apps/iptables installed"
322 print " and you don't, then \"emerge system\" will install it (the most"
323 print " recent version that matches the profile spec) for you. It's always a"
324 print " good idea to do an \"emerge --pretend system\" before an \"emerge"
325 print " system\", just so you know what emerge is planning to do."
326 print
327 elif myaction=="config":
328 outstuff=green("Config file management support (preliminary)")+"""
329
330 Portage has a special feature called "config file protection". The purpose of
331 this feature is to prevent new package installs from clobbering existing
332 configuration files. By default, config file protection is turned on for /etc
333 and the KDE configuration dirs; more may be added in the future.
334
335 When Portage installs a file into a protected directory tree like /etc, any
336 existing files will not be overwritten. If a file of the same name already
337 exists, Portage will change the name of the to-be- installed file from 'foo' to
338 '._cfg0000_foo'. If '._cfg0000_foo' already exists, this name becomes
339 '._cfg0001_foo', etc. In this way, existing files are not overwritten,
340 allowing the administrator to manually merge the new config files and avoid any
341 unexpected changes.
342
343 In addition to protecting overwritten files, Portage will not delete any files
344 from a protected directory when a package is unmerged. While this may be a
345 little bit untidy, it does prevent potentially valuable config files from being
346 deleted, which is of paramount importance.
347
348 Protected directories are set using the CONFIG_PROTECT variable, normally
349 defined in /etc/make.globals. Directory exceptions to the CONFIG_PROTECTed
350 directories can be specified using the CONFIG_PROTECT_MASK variable. To find
351 files that need to be updated in /etc, type:
352
353 # find /etc -iname '._cfg????_*'
354
355 You can disable this feature by setting CONFIG_PROTECT="-*" in /etc/make.conf.
356 Then, Portage will mercilessly auto-update your config files. Alternatively,
357 you can leave Config File Protection on but tell Portage that it can overwrite
358 files in certain specific /etc subdirectories. For example, if you wanted
359 Portage to automatically update your rc scripts and your wget configuration,
360 but didn't want any other changes made without your explicit approval, you'd
361 add this to /etc/make.conf:
362
363 CONFIG_PROTECT_MASK="/etc/wget /etc/rc.d"
364
365 etc-update is also available to aid in the merging of these files. It provides
366 a vimdiff interactive merging setup and can auto-merge trivial changes.
367
368 """
369 print outstuff

  ViewVC Help
Powered by ViewVC 1.1.20