Main Window

General Features

A word about GUI interfaces: depending on the windowing system and theme you have installed, the colours and icons used by Porthole may differ radically from this help manual.  So if the illustrations in this manual don't look EXACTLY like yours, try to be open minded about it. Also continuing development may outpace the updates to the pictures used.

Some of the built-in features include:

The main window (figure 1) is divided into a menu bar, a tool bar, category list pane, package list pane and a tabbed package info pane.

Figure 1. Porthole's Main window

Menu Bar

The menu bar has four sub-menues: Action, Settings, Help and Active Plugins.  Each menu item has a hot key combo to select it from the keyboard.

Action Menu

Warning: advanced emerge is just what it says--advanced!  Resist the temptation to use this until you understand how portage works.  Using the standard emerge will warn you if problems exist and always install the best version.

Settings Menu

Help Menu

Active Plugins

This will be visible only if, and contain a list of active plugins installed

Tool Bar

TIP: The toolbar has its short cut keys underlined--hold down the ALT key then press the short-cut key!

The tool bar provides an alternative to the menu bar and can save you a click or two.

In addition, if porthole is run as a non-root user, there will be an icon on the right-hand side of the toolbar to remind the user.

View Selector

The view selector let's you choose between the following views:

Find

TIP: Setting "Search descriptions" using the settings sub-menu will include the package descriptions in the search too!

Enter a fragment of text in the input box next to the find button.  Clicking the find button or pressing enter will start the search.  The system will automatically switch to the Search results view when the search is complete.  The search engine will find any occurrence of the selected text in package names.

Category List Pane

This pane hold the portage library tree.  The categories and subcategories are sorted alphabetically.  Clicking on the device beside the package category will expand the tree to reveal the sub levels.  Selecting the sub category will cause the package view pane to be populated with the individual packages.

Package List Pane

This window displays a list of packages depending on the currently selected view. The columns indicate, from left to right: the name of the package, the installed version number (if any), the version that portage recommends installing, the size of files to be downloaded, and a short description of the package. In the "Upgradable Packages" view there will also be a column with checkboxes so you can indicate to Porthole which packages should be upgraded and which should not.

In all views except the "Upgradable Packages" view, there will be an icon beside the name of installed packages. Packages in your "world" file (those explicitly installed by you) will be marked in bold type, while packages that portage recommends upgrading will by default be marked in blue, and those portage recommends downgrading marked in red.

Package Information

Summary Tab

The summary tab (figure 4) gives you a quick overview of the selected packages latest version only.  Note this may vary from what you have installed or want installed. The summary includes:

TIP: Hovering the mouse cursor over the entry for a hard masked package will often give you the masking reason

The table of available versions (figure 2) follows approximately the same format as that used on packages.gentoo.org. Stable packages are shown in green with a "+" symbol. Keyword masked packages (those not yet deemed stable) are shown in yellow with a "~" symbol. Hard masked packages (those with known problems) are shown in red with an additional "M". The ebuild versions are now clickable and will set all other information displayed to use that version for display. The Overlay column will display a Y/N of whether it is from a local overlay, hovering over the entry will bring up a tooltip of the path the the overlay where this ebuild is located.

If you have already emerged the package, the emerged version or versions will be shown in blue. In addition, if you have modified your package.keywords file to un-mask a version, its "~" will change to "(+)" to indicate that it was keyword masked but may now be installed. Similarly, if unmasked by your package.unmask file any entries with "M?" will be changed to "[?]". So for example a highly unstable version of a package, unmasked by both package.keywords and package.unmask would change from displaying "M~" to displaying "[(+)]".

ebuild table with expalantions
Figure 2 Ebuild Table.

Dependencies Tab

This tab lists the packages that must be installed in order to install your selected package (figure 3). Items in this list that are already satisfied will be marked with your theme's "Yes" icon (normally a green circle). Items that are not satisfied and will also need to be installed are marked with your theme's "No" icon (normally a red circle).

When a dependency is marked as "Using" or "Not Using" (for example "Using png" in the screenshot to the right), this refers to dependencies that are only necessary if the specified Use Flag 1 is enabled or disabled, respectively. If this condition isn't met, the dependencies will be ignored, and the icon is changed to your theme's "Remove" icon (normally a horizontal line).

There are now several columns of information listed about the specific dependency that aid you in determining any needed config changes such as keyword unmasking. The dependency is also double-clickable which will bring up a popup window of that package's details like the one you are already viewing.


Figure 3. Dependencies Tab
Pop-up dependency window image
Figure 4. Pop-up Dependency Viewer

Dependency Viewer

The dependency viewer (figure 4) is a popup window that contains all the same package if information as the main porthole window. It too can have a popup depency window for any of it's dependecies. Only one dependency popup window is allowed per window, so double-clicking a different depency will change the displayed info in it's viewer.






Changelog tab image
Figure 5. Change Log Tab

Change Log

If available, the change log text (figure 5) is shown here.  This is a good resource to use to help decide if you want to upgrade/install it or not.  Look here for information on bug fixes and new features. The text is now custom highlighted to make it easier to find and identify the information you are seeking. The bug #'s are also click-able to open you browser to the bugzilla bug at bugzilla.gentoo.org.





Installed files tab image
Figure 6. Installed Files Tab

Installed Files

A list of all the files this version installed. (figure 6)  This can be useful for a number of reasons.  For example: the name of the executable binary file of that cool sounding utility you just installed which is completely different from the package name and was not mentioned in the release notes.

Ebuild

Here you can view the raw ebuild file (the script that will be used by Emerge to install the package).



Notes: [1] See Terms & References for more info on portage terms.