[gentoo-doc-cvs] cvs commit: hb-portage-files.xml hb-portage-configuration.xml hb-working-features.xml

[Josh Saddler]

nightmorph    06/11/03 22:03:06

  Modified:             hb-portage-files.xml hb-portage-configuration.xml
                        hb-working-features.xml
  Log:
  Updated handbook for Portage 2.1, bug 144128. thanks to antarus, genone, and zmedico for reviewing

Revision  Changes    Path
1.13                 xml/htdocs/doc/en/handbook/hb-portage-files.xml

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-portage-files.xml?rev=1.13&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-portage-files.xml?rev=1.13&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-portage-files.xml?r1=1.12&r2=1.13

Index: hb-portage-files.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-files.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- hb-portage-files.xml	28 Oct 2006 09:17:55 -0000	1.12
+++ hb-portage-files.xml	3 Nov 2006 22:03:06 -0000	1.13
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-files.xml,v 1.12 2006/10/28 09:17:55 neysx Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-files.xml,v 1.13 2006/11/03 22:03:06 nightmorph Exp $ -->
 
 <sections>
 
@@ -13,8 +13,8 @@
 files and data.
 </abstract>
 
-<version>1.7</version>
-<date>2005-06-27</date>
+<version>1.8</version>
+<date>2006-11-03</date>
 
 <section>
 <title>Portage Files</title>
@@ -290,9 +290,114 @@
 <p>
 Portage can create per-ebuild logfiles, but only when the PORT_LOGDIR variable
 is set to a location that is writable by Portage (the portage user). By default
-this variable is unset.
+this variable is unset. If you don't set PORT_LOGDIR, then you won't receive
+any build logs with the current logging system, though you may receive some
+logs from the new <c>elog</c>. If you do have PORT_LOGDIR defined and you use
+elog, you will receive build logs and any logs saved by elog, as explained
+below.
 </p>
 
+<p>
+Portage offers fine-grained control over logging through the use of
+<c>elog</c>:
+</p>
+
+<ul>
+  <li>
+    PORTAGE_ELOG_CLASSES: This is where you set what kinds of messages to be
+    logged. You can use any space-separated combination of <c>info</c>,
+    <c>warn</c>, <c>error</c>, and <c>log</c>.
+  </li>
+  <li>
+    <ul>
+      <li>info: Logs "einfo" messages printed by an ebuild</li>
+      <li>warn: Logs "ewarn" messages printed by an ebuild</li>
+      <li>error: Logs "eerror" messages printed by an ebuild</li>
+      <li>log: Logs the "elog" messages found in some ebuilds</li>
+    </ul>
+  </li>
+  <li>
+    PORTAGE_ELOG_SYSTEM: This selects the module(s) to process the log
+    messages. If left empty, logging is disable. You can use any
+    space-separated combination of <c>save</c>, <c>custom</c>, <c>syslog</c>,
+    and <c>mail</c>. You must select at least one module in order to use elog.
+  </li>
+  <li>
+    <ul>
+      <li>
+	save: This saves one log per package in <path>$PORT_LOGDIR/elog</path>,
+	or <path>/var/log/portage/elog</path> if $PORT_LOGDIR is not defined.
+      </li>
+      <li>
+	custom: Passes all messages to a user-defined command in
+	$PORTAGE_ELOG_COMMAND; this will be discussed later.
+      </li>
+      <li>syslog: Sends all messages to the installed system logger.</li>
+      <li>
+	mail: Passes all messages to a user-defined mailserver in
+	$PORTAGE_ELOG_MAILURI; this will be discussed later. The mail features
+	of elog require &gt;=<c>portage-2.1.1</c>.
+      </li>
+    </ul>
+  </li>
+  <li>
+    PORTAGE_ELOG_COMMAND: This is only used when the <c>custom</c> module is
+    enabled. Here is where you specify a command to process log messages. Note
+    that you can make use of two variables: ${PACKAGE} is the package name and
+    version, while ${LOGFILE} is the absolute path to the logfile. Here's one
+    possible usage:
+  </li>
+  <li>
+    <ul>
+      <li>
+        PORTAGE_ELOG_COMMAND="/path/to/logger -p '\${PACKAGE}' -f '\${LOGFILE}'"
+      </li>
+    </ul>
+  </li>
+  <li>
+    PORTAGE_ELOG_MAILURI: This contains settings for the <c>mail</c> module
+    such as address, user, password, mailserver, and port number. The default
+    setting is "root@localhost localhost".
+  </li>
+  <li>
+    Here's an example for an smtp server that requires username and
+    password-based authentication on a particular port (the default is port
+    25):
+  </li>
+  <li>
+    <ul>
+      <li>
+	PORTAGE_ELOG_MAILURI="user@××××.domain
+	username:password@×××××××××.domain:995"
+      </li>
+    </ul>
+  </li>
+  <li>
+    PORTAGE_ELOG_MAILFROM: Allows you to set the "from" address of log mails;
+    defaults to "portage" if unset.
+  </li>
+  <li>
+    PORTAGE_ELOG_MAILSUBJECT: Allows you to create a subject line for log
+    mails. Note that you can make use of two variables: ${PACKAGE} will display
+    the package name and version, while ${HOST} is the fully qualified domain
+    name of the host Portage is running on.
+  </li>
+  <li>Here's one possible use:</li>
+  <li>
+    <ul>
+      <li>
+	PORTAGE_ELOG_MAILSUBJECT="package \${PACKAGE} was merged on \${HOST}
+	with some messages"
+      </li>
+    </ul>
+  </li>
+</ul>
+
+<impo>
+If you used <c>enotice</c> with Portage-2.0.*, you must completely remove
+enotice, as it is incompatible with elog.
+</impo>
+
 </body>
 </subsection>
 </section>



1.12                 xml/htdocs/doc/en/handbook/hb-portage-configuration.xml

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-portage-configuration.xml?rev=1.12&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-portage-configuration.xml?rev=1.12&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-portage-configuration.xml?r1=1.11&r2=1.12

Index: hb-portage-configuration.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-configuration.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- hb-portage-configuration.xml	28 Oct 2006 09:17:55 -0000	1.11
+++ hb-portage-configuration.xml	3 Nov 2006 22:03:06 -0000	1.12
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-configuration.xml,v 1.11 2006/10/28 09:17:55 neysx Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-configuration.xml,v 1.12 2006/11/03 22:03:06 nightmorph Exp $ -->
 
 <sections>
 
@@ -13,8 +13,8 @@
 configuration file or as environment variable.
 </abstract>
 
-<version>1.4</version>
-<date>2005-01-22</date>
+<version>1.5</version>
+<date>2006-11-03</date>
 
 <section>
 <title>Portage Configuration</title>
@@ -57,7 +57,7 @@
   <li>
     MAKEOPTS is passed to the <c>make</c> command and is usually set to define
     the amount of parallelism used during the compilation. More information
-    about the make options can be found in the make man page.
+    about the make options can be found in the <c>make</c> man page.
   </li>
 </ul>
 
@@ -79,6 +79,12 @@
 are defined by the CLEAN_DELAY variable.
 </p>
 
+<p>
+You can tell <c>emerge</c> to use certain options every time it is run by
+setting EMERGE_DEFAULT_OPTS. Some useful options would be --ask, --verbose,
+--tree, and so on.
+</p>
+
 </body>
 </subsection>
 </section>
@@ -224,22 +230,68 @@
 
 <ul>
   <li>
-    RSYNC_EXCLUDEFROM points to a file listing the packages and/or categories
-    rsync should ignore during the update process
+    PORTAGE_RSYNC_OPTS sets a number of default variables used during sync,
+    each space-separated. These shouldn't be changed unless you know
+    <e>exactly</e> what you're doing. Note that certain absolutely required
+    options will always be used even if PORTAGE_RSYNC_OPTS is empty.
+  </li>
+    <li>
+    <ul>
+      <li>
+        --recursive: Thoroughly checks all category and package directories
+      </li>
+      <li>--times: Preserves file modification times</li>
+      <li>
+	--exclude='/distfiles --exclude='/local' --exclude='/packages': These
+	settings tell Portage to not tamper with the locations of downloaded
+	package files (which is specified in DISTDIR), any local Portage
+	overlay (specified in PORTDIR_OVERLAY), and any user-compiled binary
+	packages. Note that any of these options can be overriden with
+	--exclude='!', should you wish Portage to modify them.
+      </li>
+      <li>--compress: Compresses the data transmitted during sync</li>
+      <li>
+	--whole-file: Sends data as whole files, rather than block transfers
+      </li>
+    </ul>
+    </li>
+  <li>
+    PORTAGE_RSYNC_EXTRA_OPTS can be used to set additional options when
+    syncing. Each option should be space separated.
   </li>
   <li>
-    RSYNC_RETRIES defines how many times rsync should try connecting to the
-    mirror pointed to by the SYNC variable before bailing out. This variable
-    defaults to 3.
+    <ul>
+      <li>
+	--timeout=&lt;number&gt;: This defines the number of seconds an rsync
+	connection can idle before rsync sees the connection as timed-out. This
+	variable defaults to 180 but dialup users or individuals with slow
+	computers might want to set this to 300 or higher.
+      </li>
+      <li>
+	--exclude-from=/etc/portage/rsync_excludes: This points to a file
+	listing the packages and/or categories rsync should ignore during the
+	update process. In this case, it points to
+	<path>/etc/portage/rsync_excludes</path>. Please read <uri
+	link="?part=3&amp;chap=5">Using a Portage Tree Subset</uri> for the
+	syntax of this file.
+      </li>
+      <li>--quiet: Reduces output to the screen</li>
+      <li>--verbose: Prints a complete filelist</li>
+      <li>--progress: Displays a progress meter for each file</li>
+    </ul>
   </li>
   <li>
-    RSYNC_TIMEOUT defines the number of seconds an rsync connection can idle
-    before rsync sees the connection as timed-out. This variable defaults to
-    180 but dialup users or individuals with slow computers might want to set
-    this to 300 or higher.
+    PORTAGE_RSYNC_RETRIES defines how many times rsync should try connecting to
+    the mirror pointed to by the SYNC variable before bailing out. This
+    variable defaults to 3.
   </li>
 </ul>
 
+<p>
+For more information on these options and others, please read <c>man
+rsync</c>.
+</p>
+
 </body>
 </subsection>
 </section>



1.34                 xml/htdocs/doc/en/handbook/hb-working-features.xml

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml?rev=1.34&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml?rev=1.34&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml?r1=1.33&r2=1.34

Index: hb-working-features.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- hb-working-features.xml	28 Oct 2006 09:17:55 -0000	1.33
+++ hb-working-features.xml	3 Nov 2006 22:03:06 -0000	1.34
@@ -4,7 +4,7 @@
 <!-- The content of this document is licensed under the CC-BY-SA license -->
 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
 
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.33 2006/10/28 09:17:55 neysx Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.34 2006/11/03 22:03:06 nightmorph Exp $ -->
 
 <sections>
 
@@ -13,8 +13,8 @@
 ccache and more.
 </abstract>
 
-<version>1.29</version>
-<date>2006-10-16</date>
+<version>1.30</version>
+<date>2006-11-03</date>
 
 <section>
 <title>Portage Features</title>
@@ -291,4 +291,32 @@
 </body>
 </subsection>
 </section>
+<section>
+<title>Fetching Files</title>
+<subsection>
+<title>Parallel fetch</title>
+<body>
+
+<p>
+When you are emerging a series of packages, Portage can fetch the source files
+for the next package in the list even while it is compiling another package,
+thus shortening compile times. To make use of this capability, add
+"parallel-fetch" to your FEATURES.
+</p>
+
+</body>
+</subsection>
+<subsection>
+<title>Userfetch</title>
+<body>
+
+<p>
+When Portage is run as root, FEATURES="userfetch" will allow Portage to drop
+root privileges while fetching package sources. This is a small security
+improvement.
+</p>
+
+</body>
+</subsection>
+</section>
 </sections>



-- 
gentoo-doc-cvs@g.o mailing list