<?xml version="1.0" encoding="UTF-8"?>
<!-- vim : set noet sw=8 sts=8 : -->
<doc>
	<back to="packages"/>
	<title>Portage utils</title>
	<section>
		
		<description>
			<link href="http://www.gentoo-portage.com/app-portage/portage-utils" text="Portage-utils" /> is a set of <emph>"small and fast portage helper tools written in C".</emph>
			<para>The idea was to adapt theses tools for paludis. In short we have two patches:</para>
			<list>
				<item>* The first one add support for overlays, (portage users can use this patched version)</item>
				<item>* The second one make the q tools to work with paludis</item>
			</list>
		</description>
		<author>truc</author>

		<title>Installation</title>
		<section>
			<para>Well, no surprise,</para>
			<code>paludis -i portage-utils</code> 
			<para>should do it
				This package also come with two hooks and one configuration file:
			</para>
			<location>
				<item>/usr/share/paludis/hooks/common/qlop-hook.bash</item>
				<item>/usr/share/paludis/hooks/common/q-reinitialize.bash</item>
				<item>/etc/paludis/hooks/config/q-reinitialize.conf</item>
			</location>
			<para>
				This hook regenerate the the cache files portage-utils uses (<strong>.ebuild.x</strong> and <strong>.metadata.x</strong>). And, unless you disable it in the configuration file, it can regenerate the metadata/cache for the overlay with the <strong>write_cache</strong> key defined and different from <strong>/var/empty</strong>
			</para>
			<para>
				A short script <strong>palsearch</strong> is also included in the package. Use this script to search package on their name or their description see <link href="http://forums.gentoo.org/viewtopic-p-3857504.html#3857504" text="here" /> for a short introduction.
			</para>
		</section>
			
		<title>Usage</title>
		<section>
			<para>
				Basicaly you can do the same with the patched and the vanilla version of portage-utils, it's just that the later will not work with paludis, and even less with your overlays...
			</para>	
			<para>
				Here is some of the main differences:
			</para>	
				
			<code title="new options">q --ls-overlays

Overlay(s) :

Name : einit                 location : /var/paludis/repositories/einit                                      metadata : /var/cache/paludis/metadata/einit                           
Name : initng                location : /var/paludis/repositories/initng                                     metadata : /var/cache/paludis/metadata/initng                          
Name : paludis-overlay       location : /var/paludis/repositories/paludis-overlay                            metadata : /var/cache/paludis/metadata/paludis-overlay                 
Name : paludis-extras-scm    location : /home/sam/prog/gentoo/paludis-extras/overlay-scm                     metadata : /var/cache/paludis/metadata/paludis-extras-scm              
Name : local                 location : /var/paludis/repositories/local                                      metadata : /var/cache/paludis/metadata/local                           
Name : gentoo                location : /var/paludis/repositories/gentoo                                     metadata : /var/paludis/repositories/gentoo/metadata/cache             
Name : paludis-extras        location : /var/paludis/repositories/paludis-extras                             metadata : /var/cache/paludis/metadata/paludis-extras </code>
				

				
			<para>
				You will also notice an <emph>--overlay &lt;arg&gt;</emph> option has been added to various tools( <strong>qlop</strong>,<strong>qgrep</strong>,<strong>quse</strong> and <strong>qsearch</strong>), this option generally improves speed by performing the given action on only the the requested overlay (<emph>&lt;arg&gt;</emph>).
			</para>	
				
			<para>
				<strong>qatom</strong> now supports overlays too, and <strong>scm,live,cvs</strong> and <strong>svn</strong> version:
			</para>
				
			<code>qatom sys-apps/paludis-scm::paludis-extras
sys-apps paludis scm paludis-extras

qatom -c sys-apps/paludis-scm::paludis-extras sys-apps/paludis-22.0::paludis-extras
sys-apps/paludis-scm::paludis-extras > sys-apps/paludis-22.0::paludis-extras</code>

			<para>				
				<strong>qlop</strong> has been modified a <strong>lot</strong> to be as reliable as possible. you'll find in the changelog examples on how to use it.
			</para>
				
			<sources title="files">
				<item o-href="app-portage/portage-utils/ChangeLog">Changelog</item>
				<item href="files/qlop-hook.bash">qlop-hook.bash</item>
			</sources>

		</section>			

	</section>		
</doc>
