Attachment 10048 Details for Bug 18249 – revisited portage user guide

revisited portage user guide

portage-user.xml (text/plain), 11.25 KB, created by Gregorio Guidi (RETIRED) on 2003-03-30 19:24:15 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Gregorio Guidi (RETIRED)

Created: 2003-03-30 19:24:15 UTC

Size: 11.25 KB

patch

obsolete

><?xml version='1.0' encoding="UTF-8"?>
><?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
><guide link="/doc/en/portage-user.xml">
><title>Portage User Guide</title>
><author title="Chief Architect"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
><author title="Editor"><mail link="thomasfl@gentoo.org">Thomas Flavel</mail></author>
><author title="Editor"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
><author title="Editor"><mail link="carl@gentoo.org">Carl Anderson</mail></author>
>
><abstract>This guide briefly covers how to keep your packages up to date, and how to maintain
>your system.</abstract>
>
><version>1.3</version>
><date>31 March 2002</date>
>
><chapter>
><title>Getting Started</title>
>
><section>
><title>Getting Portage Current</title>
><body>
>
><p>After you get Gentoo Linux installed and you play around a bit, you may find some bugs or
>quirks in some packages, or maybe you'd like to install the latest software provided by Gentoo Linux
>or update your current packages. To do this, you'll need to download our Portage tree. We have
>provided several servers that you can use to get our latest Portage tree; you can synchronize your
>tree with one of these servers using the 'rsync' protocol. Here's how you do it.
></p>
>
><p>Use the following command to synchronize your Portage tree:
></p>
>
><pre caption = "Getting portage up to date">
># <c>emerge --sync</c>
></pre>
>
><p>Please note that <c>emerge --sync</c> automatically evokes the <i>--clean</i> option, which will
>delete any of your personal changes or additions to the <path>/usr/portage tree</path>. If you wish
>to keep your own ebuilds seperate from the main Portage tree, please use the <i>PORTDIR_OVERLAY</i>
>function.</p>
>
><pre caption = "Using PORTDIR_OVERLAY">
><comment>Add this line to <path>/etc/make.conf</path></comment>
>PORTDIR_OVERLAY="/dir/where/your/ebuilds/are"
></pre>
>
><p>If you begin modifying many ebuilds, fixing bugs, etc, you might want to consider
>becoming a part of the Gentoo Linux Development Team. Please contact
>either <mail link = "drobbins@gentoo.org">Daniel Robbins</mail> or
><mail link = "seemant@gentoo.org">Seemant Kulleen</mail> for more information.
></p>
>
></body>
></section>
>
><section>
><title>Updating Portage</title>
><body>
><p>Before using our Portage tree, it's important that you make sure you have installed the most
>recent version of Portage. To do this, do the following:
></p>
>
><pre caption = "Updating Portage">
><comment>This will show you what packages that are going to be updated</comment>
># <c>emerge -up system </c>
><comment>This will update the necessary packages</comment>
># <c>emerge -u system </c>
></pre>
>
><p>Now you'll be using the newest portage, and you can start to use our ebuild
>system to update your installed software.</p>
>
></body>
></section>
></chapter>
><chapter>
><title>Introducing <c>emerge</c></title>
><section>
><title><c>emerge --pretend</c></title>
><body>
>
><p>Before installing a package, it is a good idea to see what dependencies are going
>to be installed, what packages need updating etc. <c>emerge --pretend</c> or
><c>emerge -p</c> can do this for you.
></p>
>
><pre caption = "Using emerge -p">
># <c>emerge -p xmms</c>
>
>These are the packages that I would merge, in order:
>
>Calculating dependencies ...done!
>[ebuild  N   ] media-sound/esound-0.2.29
>[ebuild  N   ] media-libs/libmikmod-3.1.10
>[ebuild  N   ] media-sound/xmms-1.2.7-r19
>
># <c>emerge -p xchat</c>
>
>These are the packages that I would merge, in order:
>
>Calculating dependencies ...done!
>[ebuild    U ] dev-libs/glib-2.2.1 [2.0.7]
>[ebuild  N   ] x11-libs/pango-1.2.1
>[ebuild  N   ] dev-libs/atk-1.2.2
>[ebuild    U ] x11-libs/gtk+-2.2.1 [1.2.10-r10]
>[ebuild  N   ] net-irc/xchat-2.0.0
>
></pre>
>
><p>We are attempting to merge <i>xchat</i> or <i>xmms</i>, thus, <c>emerge
>--pretend</c> correctly identifies that several dependencies need to be satisfied first.
>Specifically, <path>media-sound/esound</path> and <path>media-libs/libmikmod</path>
>need to be merged before <i>xmms</i> can be installed; to be able to merge <i>xchat</i> we have to
>upgrade <path>dev-libs/glib</path> and <path>x11-libs/gtk+</path> and install two
>other packages.
></p>
></body>
></section>
><section>
><title>USE and <c>emerge</c></title>
><body>
><p>Above, I executed <c>emerge --pretend</c> on a system that did not have
><c>gnome</c> defined in the <c>USE</c> variable in <path>/etc/make.conf</path>.
>This means that optional GNOME support, if present, will not be enabled.
>However, <path>xmms</path> <e>does</e> have optional GNOME support, so let's
>take a look at the <c>emerge --pretend</c> output after I add <c>gnome</c> to
>the <c>USE</c> environment variable in <path>/etc/make.conf</path>:
></p>
>
><pre caption = "Using emerge with USE variables">
># <c>emerge -p xmms</c>
>
>These are the packages that I would merge, in order:
>
>Calculating dependencies ...done!
>[ebuild  N   ] media-sound/esound-0.2.29
>[ebuild  N   ] app-text/scrollkeeper-0.3.11-r1
>[ebuild  N   ] dev-libs/libxml-1.8.17-r2
>[ebuild  N   ] gnome-base/libglade-0.17-r6
>[ebuild  N   ] gnome-base/gnome-common-1.2.4-r3
>[ebuild  N   ] dev-util/indent-2.2.9
>[ebuild  N   ] gnome-base/oaf-0.6.10
>[ebuild  N   ] dev-util/guile-1.4.1
>[ebuild  N   ] gnome-base/gconf-1.0.8-r3
>[ebuild  N   ] gnome-base/gnome-mime-data-2.2.0
>[ebuild  N   ] gnome-base/gnome-vfs-1.0.5-r3
>[ebuild  N   ] gnome-base/control-center-1.4.0.5-r1
>[ebuild  N   ] gnome-base/gnome-panel-1.4.2-r2
>[ebuild  N   ] media-libs/libmikmod-3.1.10
>[ebuild  N   ] media-sound/xmms-1.2.7-r19
>
></pre>
>
><p>As you can see, with <c>gnome</c> added to <c>USE</c>, emerge recognizes
>that <i>xmms</i> should include optional GNOME support.  And of course, in order for
>this optional GNOME support to compile and run correctly, GNOME must first be
>installed.  <c>emerge</c> figures this all out and adds various packages
>required by GNOME to its list of ebuilds to merge.  As the <c>USE</c> variable can
>greatly impact the beheviour of emerge, unexpectedly including or excluding support for various
>optional extensions, I recommended that you always perform an <c>emerge --pretend</c>
>before executing the actual <c>emerge</c>, especially for new, unfamiliar
>ebuilds. Moreover, I also suggest to check the <c>USE</c> flags you are currently using by running
><c>emerge</c> with the <c>-v</c> or <c>--verbose</c> option.
>
><pre caption = "Displaying USE flags">
># <c>emerge -pv xmms</c>
>
>These are the packages that I would merge, in order:
>
>Calculating dependencies ...done!
>[ebuild  N   ] media-sound/esound-0.2.29  -tcpd +alsa
>[ebuild  N   ] media-libs/libmikmod-3.1.10  -oss +esd +alsa
>[ebuild  N   ] media-sound/xmms-1.2.7-r19  -xml +nls +esd -gnome +opengl +mmx +oggvorbis -3dnow
>+mikmod -directfb -ipv6 -cjk
>
></pre>
>
>That way, you'll know what to expect. :)  Once
>everything looks OK,you can go ahead with the actual <c>emerge</c> by dropping the 
><c>--pretend</c>option:</p>
><pre caption = "Emerging xmms">
># <c>emerge xmms</c>
></pre>
>
><p>After all dependencies are merged (if they exist; not all packages have
>them), the xmms sources will be downloaded (to
><path>/usr/portage/distfiles</path>), verified, unpacked, compiled and
>installed to a temporary directory called the sandbox. Then, they will be merged into the local
>filesystem and a package database will be created at
><path>/var/db/pkg/media-sound/xmms-1.2.7-r19/CONTENTS</path>, containing the files
>installed and the md5sums for all files.</p>
>
></body>
></section>
></chapter>
><chapter>
><title>Upgrading packages</title>
><section>
><body>
>
><p>The standard way to update a package in Portage is to use <c>emerge --update</c>
>or <c>emerge -u</c>.
></p>
>
><pre caption = "Using emerge -u">
># <c>emerge -u xmms</c>
></pre>
>
><p>This command will update <c>xmms</c> and all its dependencies to the latest available version. If
>you only want to make sure that you have the most recent version of <c>xmms</c>, you can
>simply do <c>emerge xmms</c> (this will reinstall xmms even if the newest version is already
>installed).
></p>
><p>Portage uses what is called a "safe" unmerge; it's only going to unlink original files. If
>a file has been overwritten or modified in some way, it will be left on the filesystem (presumably,
>you've installed a newer version of the package). So, if you unmerge an old version of xmms after
>merging a newer version, the xmms executable will not be deleted off your filesystem,since it has a
>newer timestamp and different md5sum. Safe unmerges are really great because they ensure that some
>version of the application is available at all times. If you had to unmerge first, then xmms
>wouldn't be available for a few minutes while the new version was being downloaded, compiled,
>installed and merged.</p>
>
><impo>Portage has a special feature called "config file protection".  The
>purpose of this feature is to prevent new package installs from clobbering
>existing configuration files.  By default, config file protection is turned on
>for /etc and the KDE configuration dirs; more may be added in the future.  Type
><c>emerge --help config</c> for more details.</impo>
>
></body>
></section>
></chapter>
><chapter>
><title>Masked packages</title>
><section>
><title>Which packages are masked?</title>
><body>
><p>If you played around a bit with portage, you probably discovered that not all the bleeding-edge
>software in the portage tree is available to you when you do an <c>emerge -u world</c>. This happens
>because some packages in the tree are <i>masked</i>, which means that it's not safe for a normal
>user to have those packages installed on his system.
></p>
>
><p>Packages can be masked either in <path>package.mask</path> (which is a file in
><path>/usr/portage</path>) or being assigned a <c>~arch keyword</c> (for example a package marked
>with the <c>~x86</c> keyword is masked for the x86 architecture). If a package is listed in
>package.mask it means that it's known to be broken or that it will surely create problems on
>your system; instead, if a package is keyword masked, it simply means that it is not enough tested
>to be considered safe to install. You can find more infos about masked packages in the
><uri link="http://forums.gentoo.org/viewtopic.php?t=33534">Masked Packages FAQ</uri> in our <uri
>link="http://forums.gentoo.org/">Gentoo Forums</uri>.
></p>
><p>Clearly we discourage you from manipulating package.mask, nonetheless, you surely can feel
>confident enough and desire to try out a keyword masked package. Let's see what emerge offers.
></p>
></body>
></section>
><section>
><title>Emerging masked packages</title>
><body>
><p>You can tell emerge to consider a precise ebuild file (works also with packages in
><path>package.mask</path>):
></p>
><pre caption = "Specifying an ebuild">
># <c>emerge /usr/portage/x11-base/xfree/xfree-4.3.0-r1.ebuild</c>
></pre>
>
><p>Or you can instruct portage to consider masked packages through the <c>ACCEPT_KEYWORDS</c>
>variable:
></p>
><pre caption = "Using ACCEPT_KEYWORDS">
><comment>replace <c>x86</c> with your architecture</comment>
># <c>ACCEPT_KEYWORDS="~x86" emerge xfree</c>
></pre>
>
><note>If you happen to do an <c>emerge -u package</c> when your <c>ACCEPT_KEYWORDS</c> is set,
>remember that all package dependencies will be upgraded to the latest unstable version.
></note>
>
><p>Finally, if you think you're a Real Man, you can set <c>ACCEPT_KEYWORDS="~x86"</c> in your
><c>make.conf</c>, thus getting the most out of Portage. But remeber, if you do so don't blame Gentoo
>developers if you run into trouble!
></p>
></body>
></section>
></chapter>
></guide>

Actions: View

Attachments on bug 18249: 9856 | 9857 | 9858 | 10047 | 10048 | 12390 | 12391 | 12392 | 12409 | 12410 | 17630 | 29203