NOTE
  • This post contains links to external resources, which I have little, if any, control over and hence I cannot guarantee their accuracy.

  • Any instruction involving Portage or manual installation from source code, has the capability to break your system and cause other problems, so if you follow them you and you alone assume any and all responsibility for the consequences!

Often, on this blog, I write posts regarding installing software with Sabayon’s two package managers: Portage which it borrows from Gentoo and Entropy which is wholly original. I felt I would dedicate this post to both package managers, giving you some tips on how to use them safely and most efficiently. Generally speaking when it comes to Sabayon, unless you know what you are doing (for future reference users that “know what they are doing” in this context will be referred to as competent Sabayon users), you are recommended to only use Entropy as your package management system (PMS), as working with Portage is more risky and mixing Entropy with Portage is known to sometimes lead to system breaks. I mix the two, even though I have no formal training in anything technology-related and I have only been using Sabayon since July/August 2015 and had no experience before this with Gentoo Linux or Gentoo-based distributions like Calculate Linux.

This post will cover some of the basics of using Entropy and Portage individually and how to use them together, in the safest way possible. It will also cover other related topics like using Layman to add overlays and the basics on how to write ebuilds. You will probably notice that the command-line is featured heavily in this article, with little mention (usually all they will get is about a sentence mention each, if they are really notable) of graphical user interface (GUI) front-ends for these programs, this is because I tend to find command-line front-ends for package managers are more stable than their graphical counterparts.

Glossary

To ensure that everything in this post is clear as day to understand I felt I should explain some acronyms, terminology and formatting conventions adopted in this post.

Acronyms

The acronyms used in this post include:

  • CLI: command-line interface. Which is usually accessed on Sabayon via terminal emulators.
  • GPO: Gentoo Portage overlay.
  • GUI: graphical user interface.
  • PMS: package management system.
  • PT: Portage Tree, the main official overlay of the Gentoo Foundation.

Formatting

Angle brackets < and > with a word between them denotes user-provided variables. For example, <PACKAGE> denotes the name of a software package, <OVERLAY> denotes the name of a software overlay, <FILE> is the name of a file, including its extension (e.g., it may equal atom-1.3.2.ebuild, when are referring to ebuild files), etc. This formatting denotes pieces of code, file paths or file extensions, while this formatting denotes pieces of code/file paths for which I have provided a hyperlink. user $ means that code that follows, that is on the same line, are to be run as standard user (as opposed to superuser, or root). root # indicates that the code that follows, that is on the same line, is to entered into a instance of Bash with root privileges.

Terminology

Bandwidth

This is a term I am using to mean data transferred via a network, such as the Internet. Although this definition may not be strictly correct, see for example its Wikipedia article.

Bash

The Bourne-Again Shell that is developed as part of the GNU Project, is the default command shell of Sabayon Linux and most other Linux distributions (including Gentoo Linux). It is covered in greater detail, by the Bash Scripting and the Command-Line: an Introduction for Sabayon Users post.

Binary package

A type of software package that contains an executable script that is ready to be run. They are usually produced from pre-compiled source code. Most package managers work with binary packages, example of package managers that work with binary packages by default, include:

  • APT, the default command-line package manager used by Debian-based distributions, including Ubuntu. APT uses Deb packages which have the .deb file extension. Deb packages are installed using dpkg (dpkg), although APT (apt) provides dependency resolution, repository management, package querying, etc. and uses dpkg to perform the actual package installation. Deb packages can be unpacked using the command ar -xv <PACKAGE> (ar is provided by GNU Binutils). They contain a metadata tarball called control that can be left uncompressed, gzipped or xzipped, yielding the file names control.tar/control.tar.gz/control.tar.xz, binary package data (including installable files) tarball (which can be compressed with gzip (making the file extension .tar.gz), bzip2 (.tar.bz2), xzip (.tar.xz) or lzma (.tar.lzma)) and debian-binary (which contains the Debian format version number, currently the latest version is 2.0).
  • APT-RPM, the default command-line package manager used by OpenMamba and PCLinuxOS. It is a version of APT that has been specifically modified to work with RPM packages. RPM packages can be decompressed (or unpacked) using bsdtar, namely by running: user $  bsdtar -xf <PACKAGE> .
  • DNF, which is the default package manager of Fedora ≥22. It uses RPM packages (with the .rpm file extension).
  • Entropy is the default package manager of Sabayon and uses .tbz2 binaries, the same type of binaries that Portage packages software as.
  • yum, the default package manager of CentOS, Fedora <22 and Red Hat Enterprise Linux, which also uses RPM packages.
  • ZYpp, the default command-line package manager of openSUSE and SUSE Linux Enterprise, which also works with RPM packages.

Metadata

Metadata is essentially information (or data) about data. Software package metadata may contain details about when the package was built, who built the package, the features of the package, maybe a description, its web page, etc.

Software package

A distribution of software and data contained in archive files, that can be used by package managers to install software.1 There are two main types of software package: binary and source code, which are both covered separately.

Source code package

A type of software package that contain raw software source code which must be configured and compiled before an executable script is generated that can be run, as opposed to binary packages which contain an executable script that can be immediately run. The best example Linux package manager that works with source code packages by default is Portage.

Preliminaries

Entropy, Layman and Portage are all written in Python, Bash script and to smaller extents other programming languages like C. Entropy is maintained by Fabio Erculiani and other developers of Sabayon, while Layman and Portage are both maintained by the Gentoo community. This section will cover some of the preliminary information for each of these programs, including their command-line syntax, so as to make the rest of this post easier to understand.

Portage

Screenshot of Porthole running under KDE Plasma 5

Screenshot of Porthole running under KDE Plasma 5

Portage (sys-apps/portage: ES, GPO, PT, GW, SWWP) is a package management system that is arguably the most powerful Linux PMS available today. It is written in Python and Bash script, so as to afford users the ability to script with Portage. Portage installs, removes and upgrades software using the instructions contained in a specialized type of Bash script known as an ebuild. The sys-apps/portage package provides the executable commands listed below. Each are hyperlinked to their respective manpage, if they have one. You can replicate this list using user $  equery files sys-apps/portage | grep /usr/bin. You can show all the manpages associated with sys-apps/portage with (assuming the Gentoolkit is installed): user $  equery files sys-apps/portage | grep /usr/share/man.

Portage affords users this extra control via USE flags, which are “keywords that embodies support and dependency-information for a certain concept” (quoted from the Gentoo Handbook), in other words they are keywords that allow users to decide which (if any) optional package features (like language bindings, for example) will be built, when the package itself is built. These USE flags can be enabled or disabled for individual packages (via modifying files in the directory /etc/portage/package.use) or for all packages (via editing the USE="... line in /etc/portage/make.conf). USE flags should not be confused with package keywords (individual package keywords can be found in the directory /etc/portage/package.keywords, editing keywords for all packages can be done by editing the ACCEPT_KEYWORDS="..." line in /etc/portage/make.conf), which are entirely separate keywords, that detail architecture support (x86_64 vs. x86) and a few other features. Likewise packages you do not want Portage to emerge under any circumstances (which can be called masked packages) can be added to files within the directory /etc/portage/package.mask.

Portage is traditionally a command-line package management system (invoked by the command emerge), with no official graphical front-ends available, but a few unofficial graphical front-ends exist in the PT, of which the most popular is probably the GTK+ based Porthole (app-portage/porthole: ES, GPO, PT)

The PT contains over 18,750 software packages, as of December 2015, and while this may seem like quite a fair number (which it is) there will always be some people that will want to install software that is not in the PT. To do this it is advisable to search the GPO website, for the package you would like and then add the overlay that contains the package you want with Layman.

Emerge Syntax

According to Portage’s Manpage2, emerge commands have the following format:

root #  emerge [options] [action] [ebuild | tbz2file | file | @set | atom]                                     (1)

This can be confusing to users not familiar with the formatting used by Gentoo’s Manpages (or Linux Manpages in general, for that matter), but I will attempt to explain. Before I do, I need you to get into the mind-frame you had when you first learnt algebra in high school, where variables (like x or y) could be substituted with numbers, letters, other characters or a combination of any, or even all of these. With this mind-frame the above generalized format of emerge commands will make more sense, as all words in that command except for root and emerge can be substituted, depending on what you want to do with Portage.

What is in square-brackets ([...]) are optional parts of the command (that is, they can be omitted) and when you are writing an actual command you omit the square brackets and substitute the word inside with any of a set of possible values it can take on. Some (not all, I do not even understand them all!) possible values options and action can take on are covered in the tables below. Multiple options can be combined with certain actions, often using the shortened notation. For example, to combine the ask and verbose options when emerging GNU Octave, one can run the shortened form root #  emerge -av sci-mathematics/octave or the full-lengthed form root #  emerge –ask –verbose sci-mathematics/octave . The vertical lines or pipes, as they can also be called, which is |, in (1) means the options separated by it and between the square brackets are mutually-exclusive options (that is, you either pick one or you pick none, depending on what you want to do). To save time, I will call the following part of (1) "input":

[ebuild | tbz2file | file | @set | atom]

Sets (@set in the “input”) are essentially a useful way of specifying a large group of packages. There are six sets found in a default install of Sabayon, more can be created by users with root access by them editing files in the directory, /etc/portage/sets. Running root #  emerge –list-sets should list all available sets. ebuilds are just the names of packages you want to install. At a bare minimum they should be the package’s name (case-sensitive), without its category (e.g., wordpress for www-apps/wordpress), but sometimes specifying a package’s name without its category leaves some ambiguity (that is, there may be more than one package in the Portage Tree or unofficial overlays added with Layman, that has the name specified), so it is often safer to specify the category also. Some people may want to specify the specific package version they want too, to do this add an equal sign before the category and specify the package version after the package’s name, for example running root #  emerge =sys-apps/portage-2.2.20 should install Portage version 2.2.20. Files are files that have been created by installed packages. tbz2file, as one can probably guess are any binary packages created by emerge itself, in the .tbz2 file format that one wishes to install. Please note, however, that installing tbz2 files by path is deprecated and may not work, if you want to install tbz2 binaries use the -K option for emerge and instead specify the package’s Atom as the input for emerge. Atoms (atom) are essentially the same as ebuilds, only with bounds on their version numbers specified. For example, root #  emerge <dev-lang/python-2.0 should install the best (but not necessarily the latest) version of Python available before version 2.0.

Table 1: Options for Emerge
Long Short Meaning
--ask
-a Ask before running the action.
--autounmask [y|n]
N/A This option is enabled by default and it basically allows emerge to unmask packages as required and write changes for package.use. Possible forms this option can take on are --autounmask=y, --autounmask=n (which will disable this option and unmasking/package.use changes will not occur) or --autounmask.
--autounmask-write [y|n]
N/A This option is similar to --autounmask, except it can write to package.use and other configuration files directly.
--buildpkg [y|n]
-b By default this option is disabled, but when enabled it causes emerge to install the package(s) and it also creates binary package(s) from the installed package(s) (file format: .tbz2) in PKGDIR (which is specified by /etc/portage/make.conf, by default it is /usr/portage/packages).
--buildpkgonly
-B This option, which is not enabled by default, will only create binary package(s) and not install the package(s) specified to it.
--changed-use
-U Tells emerge to include installed packages where USE flags have changed since installation.
--debug
-d Show more detailed debugging information.
--deep
-D With this option emerge will look at the entire (or "deep") dependency tree (not just the immediate dependencies of the package it is emerging, which it does by default) for updates.
--emptytree
-e Reinstalls package and all deep dependencies.
--keep-going [ y | n ]
N/A Continue as much as possible after an error.
--newuse
-N Reinstall packages that have had their USE flags changed since installation. This option is more comprehensive in the packages it reinstalls than --changed-use.
--nodeps
-O Installs specified packages, without installing any dependencies. This option may cause package breakage.
--noreplace
-n Skips packages that are already installed.
--oneshot
-1 It will emerge the package as normal, but will not add the packages to the world file for later updating.
--onlydeps
-o Install the specified package(s) dependencies, only. This is the emerge equivalent to APT's apt-get build-dep.
--pretend
-p This option causes emerge to display which packages would have been emerged, had the pretend option not been used.
--quiet [y|n]
-q This option, although results do vary, should minimize the output provided by emerge.
--update
-u Updates packages to the best version available (not necessarily the latest, however).
--usepkg [y|n]
-k Tells emerge to use binary packages (stored in $PKGDIR), if they are available. Otherwise, if binary packages are unavailable for the required package(s), traditional ebuild installs will instead be used.
--usepkgonly [y|n]
-K Tells emerge to only use binary packages stored in $PKGDIR. If the required binary packages are not available in $PKGDIR then emerge will fail.
--verbose
-v This option causes more details to be given from ask and pretend commands. These details include GNU info errors and (for the pretend command) it will print USE flags.
--with-bdeps [y|n]
N/A During dependency calculations, build time dependencies that are not strictly required will be included. For installation actions this defaults to n, while for depclean actions this defaults to y.


Table 2: Action values for Emerge
Long Short IR? Meaning
None N/A Yes If no action is specified then emerge will merge all packages specified and their dependencies.
--config
N/A Yes Run specific configuring processes that must be done after the package is emerged. The best example for this I can provide are the MariaDB and MySQL packages. Configuring these packages is required in order to set up a database with them.
--depclean
-c Yes Removes packages not associated with any merged package.
--help
-h No Displays some basic syntactic information, although if you really want some documentation for emerge from the command-line use man emerge.
--prune
-P Yes Remove all but the highest installed version of the package specified.
--regen
N/A No Causes portage to check and update the dependency cache of all ebuilds in the portage tree.
--resume
-r No Resumes the last merge, if said merge was cancelled due to errors.
--search
-s Yes Search for packages who's name matches with the supplied case-insensitive string.
--searchdesc
-S Yes Search the Portage tree for string in package names and descriptions.
--sync
N/A No Updates all the ebuilds in the Portage Tree. You should do this once a week, at least. The first time you do it, this will take quite some time (potentially up to a few hours). To save time the first time you do this you may wish to run emerge-webrsync which will download the Portage Tree as a tarball.
--unmerge
-C Yes Unmerges (that is, uninstalls) software packages specified. WARNING: This command ignores packages that may depend on the unmerged packages. For a more dependency-conscious and hence safer version of this command use the --depclean or --prune options.
--version
-V No Display the version number of emerge.


tbz2 Binaries

As previously mentioned .tbz2 is the binary package format used by Portage. It contains a tarball (in .tar.bz2 format) that contains the binary package data (that is, the installed files of the package) and a xpak (with .xpak file extension) file that contains the package’s metadata, including the USE flags used to generate the package. You can split .tbz2 binaries into these two components by issuing the command (with app-portage/portage-utils installed):

user $  qtbz2 -s <PACKAGE>
Handbook
Manpages

ebuilds

As previously mentioned ebuilds are specialized Bash scripts that are used by Portage as instructions on how to install, package, uninstall and otherwise work with software packages. Many of the best-tested and scrutinously-analysed ebuilds are contained in the “Portage Tree” (PT) which is /usr/portage, by default. This tree is the official ebuild repository of the Gentoo Foundation and contains a wide range of different ebuilds, you can search this repository online at packages.gentoo.org). ebuilds in overlays added with Layman are added to another location, /var/lib/layman. Normally Portage installs (or “merges”) software from source code, so as to maximize the control users have over the features their software has, but some ebuilds (which I will henceforth refer to as binary ebuilds) in the Portage Tree install software from binary packages instead. ebuilds contain several specialized functions and variables that are unique to ebuilds and not found in other Bash scripts.

Binary ebuilds usually take binary packages for other Linux distributions (such as .deb and .rpm packages for Debian and Fedora, respectively), extract their contents (as these binary packages are essentially just file archives) and move their contents to the appropriate location on one’s system. Quite often when a program is installed using a binary ebuild its performance will not be as good as if it were installed using a standard (source code) ebuild. The natural question is, of course, “Why even use a binary ebuild then?” Well usually it is a matter of time, see if you install a program from source code it will often take substantially longer than installing it from a binary package, even if that binary package was originally built for another Linux distribution. For most packages Gentoo users are assumed to be willing to put up with the extra time it takes to build a software from source code, as if they are not they probably should not be using a source-based distribution like Gentoo in the first place, but for some packages the compiling time is so unbelievably long (potentially taking days or even weeks) that the maintainers of the PT decided to provide a binary ebuild for the package too. Most binary ebuilds that fit this mold have the suffix -bin in their name to distinguish them from their respective source code ebuilds, an example of such an binary ebuild is app-emulation/virtualbox-bin and its corresponding source code ebuild, app-emulation/virtualbox. Other times a binary ebuild is used because of licensing restrictions that do not allow users to access the source code, so they are forced instead to use binary packages from distributions with official releases of the software available. Examples of such binary ebuilds include www-client/google-chrome and media-sound/spotify, both of which build their respective software from Debian packages.

ebuilds in overlays, including the Portage Tree, often come with accompanying files. One of these files is called a manifest, which is mandatory for all ebuilds but it can be shared by more than one ebuild, provided the ebuilds sharing a manifest are for different versions of the same package. Manifests contain checksums for ebuild(s), the package’s source code and accompanying files, other than itself. Another accompanying file that is sometimes seen (but not all ebuilds have one) is that of metadata.xml, which contains metadata for the package (such as a description, its home page, its maintainer, etc.). Some ebuilds will also come with a ChangeLog, documenting the changes between the different releases of the package. Some ebuilds will need patch files which are usually kept in a files/ subdirectory of the directory in which the ebuild is stored.

ebuild Syntax

ebuild is also the name of a command used on Gentoo-based systems like Sabayon to create manifests, merge ebuilds, build binary packages from ebuilds, etc. The ebuild command is included in the sys-apps/portage package and its syntax is shown below:

root #  ebuild <FILE> <COMMAND>

where <FILE> is the ebuild file you are running the ebuild command on, while <COMMAND> is any one of the commands listed in table 3. Note, however, that several commands can be used in the same line.

Table 3: Basic commands for ebuild

Command

Meaning

Example(s)

clean

Cleans the temporary build directory for this ebuild.

ebuild atom-1.3.1.ebuild clean

compile

Compile the ebuild following the instructions in the src_compile() function.

ebuild atom-1.3.1.ebuild compile

config

Perform post-installation configuration specified in the pkg_config() function.

ebuild mysql-5.6.27-r1.ebuild config

configure

Configure the source code in the ${S} directory, by running the src_configure() function. Supported for EAPI ≥2.

ebuild atom-1.3.1.ebuild configure

digest/
manifest

Produce a manifest for the ebuild.

ebuild atom-1.3.1.ebuild digest
or
ebuild atom-1.3.1.ebuild manifest

fetch

Checks if the sources specified in SRC_URI are available in DESTDIR. If they are not available in DESTDIR, an attempt is made to download them.

ebuild atom-1.3.1.ebuild fetch

help

Shows condensed form of the ebuild(1) manpage, with information specified to the package specified.

ebuild atom-1.3.1.ebuild help

install

Installs the package to the temporary install directory by running the src_install() function. This will not install the package into your local filesystem, however.

ebuild atom-1.3.1.ebuild install

merge

Run the fetch, unpack, compile, install and qmerge functions, which should install the package into your live file system.

ebuild atom-1.3.1.ebuild merge

package

Essentially the equivalent to the merge command, except without installation into the live file system, rather the package is turned into a .tbz2 binary and stored in $PKGDIR (usually /usr/portage/packages).

ebuild atom-1.3.1.ebuild package

postinst

Runs pkg_postinst() function in ebuild, which normally runs after a package is install into the live file system.

ebuild atom-1.3.1.ebuild postinst

postrm

Runs pkg_postrm() function in ebuild, which is normally run after a package is unmerged.

ebuild atom-1.3.1.ebuild postrm

preinst

Runs the pkg_preinst() function which is usually run before the package is installed into the live file system.

ebuild atom-1.3.1.ebuild preinst

prepare

Runs src_prepare() function on extracted sources.

ebuild atom-1.3.1.ebuild prepare

prerm

Runs pkg_prerm(), which is normally before an unmerge is performed.

ebuild atom-1.3.1.ebuild prerm

qmerge

This function installs all the files in the install directory to the live file system.

ebuild atom-1.3.1.ebuild qmerge

rpm

Builds an RPM binary package from the files in the temporary install directory.

ebuild atom-1.3.1.ebuild rpm

setup

Runs the pkg_setup() function.

ebuild atom-1.3.1.ebuild setup

test

Runs the src_test() function.

ebuild atom-1.3.1.ebuild test

unmerge

Removes installed files from the live file system, effectively uninstalling it.

ebuild atom-1.3.1.ebuild unmerge

For details on how to write ebuilds see the Writing ebuilds section of this post.

Manpages

Layman

Layman (app-portage/layman: ES, GP, GPO, PT, GR, , GW, ) is a command-line tool for managing Portage overlays. It can be installed with Portage (from the PT) using the command:

root #  emerge -av app-portage/layman

or with Entropy using the command:

root #  equo i -av app-portage/layman

I would recommend installing Layman using Entropy as it is less error-prone and the Layman package it installs was compiled with all the USE flags required to add every type of overlay available (including Bazaar (bzr), Git, Mercurial (hg) and Subversion (svn)). It is important to note that the Layman packages in the Entropy repositories do not have dev-vcs/bazaar, dev-vcs/git, dev-vcs/mercurial or dev-vcs/subversion listed amongst its dependencies, which means each of these packages will need to be installed manually in order to add overlays managed by them. If you want to install Layman and these version control systems run:

root #  equo i -av app-portage/layman dev-vcs/bazaar dev-vcs/git dev-vcs/mercurial dev-vcs/subversion

Layman-added overlays (and the ebuilds contained within them) are stored in /var/lib/layman/.

Layman Syntax

The basic syntax for Layman is:

root #  layman [options] [action]

As with emerge, I am not going to cover every option and action available for layman, as that would take too long, plus this is not meant to be a substitute for the manpages of the package managers and other tools covered in this post. Some of the more important/frequently-used actions and options are covered in tables 4 and 5. Please note that all actions when given in long form, if they require input (like --add does) this input must be specified with an equal sign and no spaces. For example, to add the sabayon overlay you may run:

root #  layman --add=sabayon

or in shortened notation:

root #  layman -a sabayon

It is important to note that while this technique will add the sabayon overlay to one’s machine not all overlays can be added this way, as some overlays are not within Layman’s default list of available overlays (which I will henceforth refer to as the remote list). To view the remote list, run:

root #  layman -L

while to see the list of overlays currently installed, locally, on your machine run:

root #  layman -l

To add a new overlay that is not within the Layman remote list, run:

root #  layman -o <URL of repository XML file> -f -a <OVERLAY>

For example, for my overlay sabayon-tools, you could add it with:

root #  layman -o https://raw.githubusercontent.com/fusion809/sabayon-tools/master/overlays.xml -f -a sabayon-tools

or as it is now in the Layman remote list (per Gentoo Bug Report #566188) you could add it with:

root #  layman -a sabayon-tools
Table 4: Options for Layman
Long Short Meaning
--nocolor
-N Remove colour codes from Layman output.
--quiet
-q Reduce output.
--quietness
-Q Takes a numerical value between 0 and 4 to determine the amount of output provided. 0 means no output, 4 means full output.
--verbose
-v Makes Layman give more output details, such as a description of the overlays you download.


Table 5: Actions for Layman
Long Short Meaning
--add
-a Add overlay.
--delete
-d Delete overlay. Specify "ALL" to delete all locally installed overlays.
--disable
-D Disable overlay. Specify "ALL" to disable all locally-installed overlays.
--info
-i Display all available information about the overlay.
--list
-L List all available overlays. Note that these overlays are not necessarily installed on your system.
--list-local
-l List all locally-installed overlays.
--readd
-r Re-add overlay(s) specified, to re-add all overlays, use the input "ALL".
--sync
-s Synchronize (or in other words, update) overlay(s) specified. To sync them all use the input "ALL" or use the -S option mentioned below.
--sync-all
-S Update all overlays.


Entropy

Rigo Application Browser running under KDE Plasma 5

Rigo Application Browser running under KDE Plasma 5

Entropy (PDF) (sys-apps/entropy: ES, GPO, PT, GR, SW) , is a PMS that was specifically designed for Sabayon by Fabio Erculiani, the original creator of Sabayon. Its first unstable release to be added to Sabayon was in July 2008 (although its first unstable release full stop was back in 2007, according to Entropy’s GitHub repository3) when Sabayon 3.5 was released and its first stable release to be added to Sabayon was made in 2012. Unlike Portage which is primarily designed to install source code packages (although it can also install binary packages), Entropy is designed to work with binary packages only. Binary packages take less time than source code packages to install and requires less user know-how and input. Entropy is also unique in that it has two official front-ends: command-line/textual (Equo) and graphical (Rigo). I personally favour using the command-line for installing packages on Linux distributions, because in my experience graphical installers are more prone to crashes during installation than their command-line/textual counterparts.

Compared to Portage, Entropy is far more simple to use, if you go to the Entropy Store you can see the USE flags used to compile the software packages provided by Entropy, as all packages provided by Entropy had to be compiled with Portage on another machine first (in .tbz2 format) and then convert from a Portage package to an Entropy package with root #  equo pkg inflate <PACKAGE>. Entropy contains packages from the Portage Tree and packages from Sabayon’s own overlays, which are called sabayon and sabayon-distro, respectively. Entropy is also safer to use and support for using Entropy to install packages is far better than support for Portage-installed packages on the Sabayon forums.

As of December 2015 there are over 13,100 different packages (not including different package versions) in the Entropy repositories. If you want to check how many unique packages (not including differing package versions) are in the official repositories merely run:

# Check the number of unique packages in the sabayonlinux.org
export SABO=$(sudo equo query list available --quiet sabayonlinux.org | sort | uniq | wc -l)
# Check the number of unique packages in the sabayon-weekly
export SABW=$(sudo equo query list available --quiet sabayon-weekly | sort | uniq | wc -l)
# Check the number of unique packages in the sabayon-limbo
export SABL=$(sudo equo query list available --quiet sabayon-limbo | sort | uniq | wc -l)

echo "There are ${SABO} unique packages (not including different package version) in the sabayonlinux.org (DAILY) repository"
echo "There are ${SABW} unique packages (not including different package version) in the sabayon-weekly (WEEKLY) repository"
echo "There are ${SABL} unique packages (not including different package version) in the sabayon-limbo (LIMBO) repository"

Equo Syntax

The generalized syntax for Entropy’s command-line front-end, Equo, is:

root #  equo [action] [options] [ebuild | atom]

Some (but by no stretch of the imagine all) options and actions for Equo are listed in tables 5 and 6, below. Note some options are only available for certain actions, for details see the man pages for Equo and its various actions (e.g., run man equo install for the equo install manual). One action and another option that are not covered in these tables, that I felt were worthwhile mentioning, are repo and mirrorsort, respectively. The command:

root #  equo repo mirrorsort <REPO>

where <REPO> is the name of an Entropy repository (e.g., sabayonlinux.org, sabayon-weekly or sabayon-limbo), can be used to optimize the order of preference for the repository’s mirrors, hence, potentially, accelerating the process by which Sabayon downloads software packages.

Table 6: Options for Equo
Option Meaning
-a, --ask Ask before performing actions. For example equo i -a [ebuild] will ask you before it will install the package specified by the ebuild argument.
--deep Reinstall dependencies, even if unnecessary.
-h, --help, help Print help information.
-o If given to the "install" action this option will cause only the package's dependencies to be installed. This is the equivalent to running apt-get build-dep for APT.
-p, --pretend Show what would be done, had this option not been given.
--purge (for upgrade) it will remove unmaintained packages, if any.
-q, --quiet Quiet (reduce) output.
-v, --verbose Verbose output.


Table 7: Actions for Equo
Long Short Meaning Manpage
cleanup N/A Remove downloaded packages and clean temporary directories. equo-cleanup.1.html
config N/A Configure installed packages. equo-config.1.html
deptest dt Look for unsatisfied dependencies. equo-deptest.1.html
install i Install software. equo-install.1.html
libtest lt Look for missing libraries required by other packages. equo-libtest.1.html
mask N/A Mask packages given as input. equo-mask.1.html
remove rm Remove packages given as input. equo-remove.1.html
rescue N/A Tools to rescue system equo-rescue.1.html
search s Search for packages in repositories. equo-search.1.html
unmask N/A Unmask packages given as input. equo-unmask.1.html
update up Update repositories. equo-update.1.html
upgrade u Upgrade packages that have been updated (in the software repositories) since they were installed, or since you last ran this command. equo-upgrade.1.html

It is important to understand the output of Entropy, for example here is some of the output I obtained on 17 December 2015 when running user $  sudo equo upgrade :

## [U</span>] [sabayonlinux.org] sys-libs/glibc-2.21-r1|0   [2.20-r2|0]</span>
## [U</span>] [sabayon-limbo] kde-plasma/kde-cli-tools-5.5.1|0   [5.5.0|0]</span>
## [U] [sabayonlinux.org->sabayon-limbo] sys-apps/grep-2.22|0   [2.21-r1|0]</span>
## [U] [spm-db->sabayonlinux.org] net-p2p/qbittorrent-3.2.5|0   [3.2.4|9999]</span>

The first of these lines, indicates that the package glibc in the sabayonlinux.org repository was being upgraded from 2.20-r2 to 2.21-r1. Second, that kde-cli-tools in the sabayon-limbo repository was being upgraded from 5.5.0 to 5.5.1. Third, that grep 2.22 was being installed from the sabayon-limbo repository, over the old version 2.21-r1 that was in the sabayonlinux.org repository. Forth indicates that qbittorrent was going to be upgraded to version 3.2.5 in the sabayonlinux.org repository from the present version 3.2.4 that was installed using Portage (which is what spm-db indicates).


Gentoolkit

Gentoolkit (app-portage/gentoolkit: ES, GPO, PT, GR, , GW, WP) is a suite of tools written in Python and Bash script that make Gentoo administration easier. Examples of these tools include:

  • eclean which can be used to remove old source files and binary packages from one’s system.
  • equery which can be used to query installed packages. For example, it can list the installed files associated with a package, as well as to determine which package an installed file belongs. It can also be used to determine an installed package’s dependencies
  • euse which can be used to set, unset or see USE flags.
  • glsa-check a tool to locally monitor and manage Gentoo Linux Security Advisories (GLSAs).
  • revdep-rebuild which will scan for packages that have become broken as a result of the upgrade of packages they depend on. It will also attempt to fix these problems itself by emerging package dependencies. It will pass all flags to emerge so root #  revdep-rebuild -p will show the packages that would be emerged if the -p (shortened version of --pretend) flag was not passed.

The Gentoolkit can be installed using Entropy or Portage. Using Entropy one would install it using the command:

root #  equo i app-portage/gentoolkit

The Gentoolkit also has a toolkit for Gentoo developers: Gentoolkit-dev (app-portage/gentoolkit-dev: ES, GPO, PT).

q applets

The q applets (app-portage/portage-utils: ES, GPO, PT, GR, , GW, ) are a collection of small and fast tools written in C and Bash script for the purpose of aiding with Gentoo administration. They are predominantly just faster equivalents to the tools that come bundled with Gentoolkit, although q applets lacks a glsa-check or revdep-rebuild equivalent.

Mixing Entropy and Portage

By default Entropy and Portage act fairly independently of one another. In order for you to use them together, you must tell Entropy that you are also using Portage to install packages by running:

root #  equo rescue spmsync

whenever you emerge, unmerge or update a package. I have this saved in my ~/.bashrc (for root user) as the function spm, so as to make it easier for me to run it when necessary. What this will do is it will cause packages you installed with Portage to be acknowledged by Entropy, as otherwise Entropy has no clue as to their existence. After this you may also wish to mask packages you installed with Portage, so as to prevent Entropy from attempting to upgrade or remove software installed with Portage. To do this run:

root #  equo mask <PACKAGE>

To prevent Entropy from downgrading emerged packages you need to edit /etc/entropy/client.conf and uncomment (removing the hashtag #) the line ignore-spm-downgrades = enable. Packages installed with Entropy are almost always safer (less likely to lead to system breaks or have bugs) than their Portage-installed counterparts, so when you want to install a package with Portage that has several dependencies that are not yet installed, I would suggest you install as many of these dependencies as possible with Entropy before you merge the remaining dependencies and the package itself with Portage. To get Portage to print you a list of the dependencies you need, along with the USE flags they require, run:

root #  emerge -pv <PACKAGE>

Unfortunately there is no Bash script to automate the process of installing Portage package dependencies with Entropy, according to the responses to this forum thread I started.

Further Reading

ebuild Writing

NOTE
  • This section is for advanced users (or those that are interested in attaining this level of understanding) and is mostly based on the official ebuild writing guide.

ebuild writing and testing are two of the most important, yet difficult activities for Gentoo developers to do. Efficient ebuild writing requires a good knowledge of Bash scripting, which I do not even possess, so bare with me. ebuilds can contain traditional Bash functions and calls to standard POSIX utilities (such as cp or mv), as well as specialized ebuild functions, ebuild variables and code snippets. eclasses (which are included into an ebuild by a line that starts with inherit) can add extra functions, variables and code snippets to ebuilds. If you are interested in writing ebuilds I recommend you install app-portage/eclass-manpages with Entropy by running: root #  equo i app-portage/eclass-manpages as this will add manpages (and additional documentation) for the various eclasses to your system. To list the eclass manpages installed with this package, run (assumming you have the Gentoolkit installed): user $  equery files app-portage/eclass-manpages | grep /usr/share/man.

ebuilds are so varied in their contents and structure that it is difficult for me to find a reasonable example with which to teach their general structure. This is partly because many ebuilds have components that are specific to them and take up so much space that I do not wish to include them here. This is probably the best ebuild example I can provide (which is in the Portage Tree, its name is supertux-0.1.3.ebuild and is in the games-arcade category):

# Copyright 1999-2015 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$

EAPI=5
inherit eutils games

DESCRIPTION="A game similar to Super Mario Bros"
HOMEPAGE="http://super-tux.sourceforge.net"
SRC_URI="https://supertux.googlecode.com/files/${P}.tar.bz2"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="amd64 ~mips ppc ~ppc64 sparc x86 ~x86-fbsd"
IUSE="opengl"

DEPEND="media-libs/libsdl[joystick]
    media-libs/sdl-image[png,jpeg]
    media-libs/sdl-mixer[mod,vorbis]
    x11-libs/libXt"
RDEPEND=${DEPEND}

src_prepare() {
    epatch \
    "${FILESDIR}"/${P}-gcc41.patch \
    "${FILESDIR}"/${P}-ndebug.patch \
    "${FILESDIR}"/${P}-desktop.patch
}

src_configure() {
    egamesconf \
        --disable-debug \
        $(use_enable opengl)
}

src_install() {
    emake DESTDIR="${D}" \
        desktopdir=/usr/share/applications \
        icondir=/usr/share/pixmaps \
        install
    dodoc AUTHORS ChangeLog LEVELDESIGN README TODO
    prepgamesdirs
}

The header in lines one to three is common to all ebuilds, with the date 1999-2015 being adjusted every new year (e.g., in 2016 it will be adjusted to 1999-2016). Lines 5, 8-10, 12-15, 17-21 are where ebuild variables are being defined. They (and other allowed variables) are explained in table 8. Table 8 and 9 are essentially modified versions of tables present in the Gentoo Development Guide’s Variables Entry.

Table 8: Basic Variables set in ebuilds

Variable

Meaning

DEPEND

List of the package’s build dependencies. These dependencies are only required for building the package, the RDEPEND variable provides dependencies that are required to run the program after it is installed.

DESCRIPTION

A one-line description of the package. This field is mandatory.

DOCS

An array or space-separated list of documentation files to be installed using the dodoc function (requires EAPI≥4.).

EAPI

Portage API version. Allowed values are integers between 0 and 6. Default value is 0.

HOMEPAGE

The URL of the package’s home page. It is mandatory, except for virtual packages.

KEYWORDS

Keywords used to indicate package stability on different architecture types. A tilde (~) before an architecture (e.g., x86) denotes that while no bugs have been detected on this architecture, but it has not been sufficiently tested for its stability to be certain. No tilde before an architecture indicates that its stability has been established by rigorous testing and usage.

IUSE

List of USE flags that are used in the ebuild.

LICENSE

The package’s license or licenses, which should exactly correspond (including its case) to a file in licenses/.

RDEPEND

List of the package’s runtime dependencies.

RESTRICT

This is a space-delimited list of Portage features that should be disabled or restricted. For example, RESTRICT="mirror" forces the ebuild to only download the source code from the SRC_URI (or equivalent) and not try the Gentoo mirrors.

S

Path to temporary build directory that is used by src_compile() and src_install(). Default is ${WORKDIR}/${P}, should not be manually set unless it is not equal to the default value.

SLOT

The package’s SLOT. This is used to install multiple different versions of the same package simultaneously on the same system and is mandatory.

SRC_URI

URL of the source code (usually in archive format like .tar.gz). Can be in the form of a list. With EAPI≥2 the output file name of a given URI can be customized using the -> operator.

The sixth line, inherit eutils games, is where eclass functions are inherited (inheriting means make them available to the ebuild). Certain eclasses make extra ebuild-specified variables available for use. For example, the git-r3 eclass allows for the specification of a EGIT_REPO_URI variable, which is essentially the same as a SRC_URI field, except it is for a git repository instead. Table 9 describes variables that are predefined read-only in nature (that is, they are not set in ebuilds, although they can be used in ebuilds).

Table 9: Predefined Read-Only Variables.

Variable

Meaning

P

Package name and version, excluding its revision, if any. For example, for app-editors/vim-6.3-r1.ebuild, P would equal vim-6.3.

PN

Package name only. In the previous example this would be vim.

PV

Package version, excluding revision, if any. In the aforementioned example this would equal 6.3.

PR

Package revision, or r0 if no revision exists.

PVR

Package version and revision (if any). In the aforementioned example this would be equal to 6.3-r1.

PF

Package full name, including version and revision. For example, in the aforementioned example this would equal to vim-6.3-r1.

A

All package source files (excluding those that are unavailable due to USE flag constraints).

CATEGORY

The package’s category, for the previous example this would be app-editors.

FILESDIR

Path to the package’s files/ directory, which usually contains patches.

WORKDIR

Path to the ebuild’s root build directory.

T

Path to a temporary directory that may be used by the ebuild.

D

Path to the temporary install directory.

ROOT

Path to the root directory.

DISTDIR

Contains the path to the directory where all files fetched are stored.

ebuilds also contain their own set of functions, that are specified in table 10.

Table 10: Basic ebuild Functions1

Function

Meaning

pkg_pretend

Run sanity checks for a package during dependency calculation time.

pkg_nofetch

Tell the user how to deal with packages that require manual downloading.

pkg_setup

Pre-build environment configuration and checks.

src_unpack

Extract source packages and perform any necessary patching or fixes. Absolete as of EAPI≥2.

src_prepare

Prepare source packages and do any necessary patching or fixes. Used instead of src_unpack for EAPI≥2.

src_configure

Configure the source code, requires EAPI≥2..

src_compile

Compile the source code, for EAPI<2. this function also configures the source code.

src_test

Run pre-install test scripts

src_install

Install a package to ${D}.

pkg_preinst

Called before image is installed to ${ROOT}.

pkg_postinst

Called after image is installed to ${ROOT}.

pkg_prerm

Called before a package is unmerged.

pkg_postrm

Called after a package is unmerged.

pkg_config

Run any special post-install configuration. Examples of ebuilds with this function in the Portage Tree include dev-db/postgresql

pkg_info

Display information about the package.

  1. The order of functions in this table is that in which each function is executed by Portage.


Learning by Example

I personally learn ebuild writing best by trying it out myself, aided by the documentation and guided by specific examples that share similarities with the ebuild I am writing, so in order to aid you in finding example ebuilds I have decided to include this Bash script that can be used to search for them:

user $  grep --include='*.ebuild' -R "<PATTERN>" <DIRECTORY>

In most cases the best value for <DIRECTORY> would likely be /usr/portage (the Portage Tree), although for ebuilds found in all the unofficial overlays managed by Layman that have been locally installed on your system, the <DIRECTORY> variable can be set to /var/lib/layman. The <PATTERN> field depends on what you want in the ebuild examples you are searching for. For example:

user $  grep --include='*.ebuild' -R "pkg_config() {" /usr/portage

can be used to search for ebuilds in the Portage Tree with pkg_config() { appearing in them.

Whenever I feel I am ready to test out an ebuild, to see if it works, what I do is I run:

root #  ebuild <PACKAGE>.ebuild manifest && ebuild <PACKAGE>.ebuild package

if this command returns errors I go back to the ebuild and look for any errors I may have made, whilst simultaneously looking at the error message I received from ebuild.

Testing ebuilds

Usually the way I test out ebuilds is I enter a Sabayon chroot on my PC, build a binary package from the ebuild and if the package is usable from the command-line I install it on the chroot and test it out. To create a Sabayon chroot at /root2 I run:

# This is the best mirror for me, due to my geography. If you want to use this script you should change this variable to the best mirror for you.
MIRROR=ftp://mirror.optusnet.com.au/sabayon
wget -c $MIRROR/iso/daily/Sabayon_Linux_DAILY_amd64_tarball.tar.gz
sudo mkdir /root2
sudo cp -a "Sabayon_Linux_DAILY_amd64_tarball.tar.gz" /root2
cd /root2
sudo tar xvzpf Sabayon_Linux_DAILY_amd64_tarball.tar.gz
sudo mount -t proc none /root2/proc
sudo mount -o bind /dev /root2/dev
sudo mount -o bind /usr/portage /root2/usr/portage
sudo mount -o bind /usr/src/linux /root2/usr/src/linux
sudo mount -o bind /lib/modules /root2/lib/modules
sudo mount -o bind /sys /root2/sys
sudo cp /etc/resolv.conf /root2/etc/resolv.conf
sudo mount -o bind /tmp /root2/tmp
sudo mount --rbind /dev /root2/dev
sudo mount --rbind /sys /root2/sys

while to change into this chroot I run:

sudo chroot /root2 /bin/bash

When I reboot after setting up a chroot (regardless of its operating system, I have created both Gentoo and Sabayon chroots on my Sabayon machine) I find that it is then broken and will not work (specifically running emerge in the chroot will return an error mentioned here on the Gentoo forums). To fix this I run this script:

sudo mount -t proc none /root2/proc
sudo mount -o bind /dev /root2/dev
sudo mount -o bind /usr/portage /root2/usr/portage
sudo mount -o bind /usr/src/linux /root2/usr/src/linux
sudo mount -o bind /lib/modules /root2/lib/modules
sudo mount -o bind /sys /root2/sys
sudo cp /etc/resolv.conf /root2/etc/resolv.conf
sudo mount -o bind /tmp /root2/tmp
sudo mount --rbind /dev /root2/dev
sudo mount --rbind /sys /root2/sys

while if after rebooting I decide I no longer want to use the chroot I run this to free up memory (as otherwise quite often I will find I do not have enough free RAM to even use several instances of Bash or a single instance of Google Chrome):

sudo umount /root2/proc
sudo umount /root2/dev
sudo umount /root2/usr/portage
sudo umount /root2/usr/src/linux
sudo umount /root2/lib/modules
sudo umount /root2/sys
sudo umount /root2/tmp
sudo umount /root2/dev
sudo umount /root2/sys

Other methods for testing ebuilds out do exist, but in my experience they are very tedious and can be quite wasteful (in terms of the bandwidth they chew up). One such method I have tried (and do not intend to use again, due to these limitations) is using Docker, for details on this method see Ettore Di Giacinto (mudler)’s Blog Post. Another method, that provides one the ability to perform more extensive tests than building and installing in a chroot, is to build and install the package on a Sabayon Linux Virtual Machine (VM). I have used this method a few times, usually when the package in question is graphical, instead of textual (e.g., my Enlightenment 20 and Moksha ebuilds), which means that I cannot test it out properly in a chroot.

The Algorithm

If you come across a program you want to install on your Sabayon machine (and you know it is compatible with Linux systems) the following is an algorithm I would suggest you follow to install it.

  1. Search for the package in the Entropy Store. If it is there, install it with Entropy (e.g., via running root #  equo i <PACKAGE>) , if not, or if the package is unsuitable (due to the USE flags not being set properly) proceed to the next step.
  2. Search for the program in the Gentoo Overlay. If it is there, install it with Portage (e.g., via running root #  emerge -av <PACKAGE>) , otherwise, or if Portage fails due to errors, move onto the next step, or skip to the final step.
  3. Search for the program in any of the unofficial overlays found in the Layman remote list. If it is, and the version number is acceptable add the containing overlay with
    root #  layman -a <OVERLAY>
    then sync both Portage and Layman with (I also have this added as a function called sync in my ~/.bashrc script)
    root #  emerge --sync && layman -S
    and then emerge the package with
    root #  emerge -av <PACKAGE>
    otherwise I proceed to the next step. If the package fails to merge properly I may fork the ebuild into my own personal overlay, sabayon-tools, try to fix it and try to merge it again. Alternatively, if the ebuild version available from an overlay (including the Portage Tree) is lower than that which I want I may also fork the ebuild into my overlay.
    If the package has several dependencies I try to install as many as possible with Entropy, before I emerge the remaining dependencies and <PACKAGE> itself. Often using pretend instead of ask options (emerge -pv... instead of emerge -av...) will be helpful if you want a list of packages to install with Entropy. Sometimes emerge will say you need to adjust your USE flags (stored in /etc/portage/package.use/), package keywords (stored in /etc/portage/package.keywords), list of accepted software licenses (stored in /etc/portage/make.conf) and alike to install the package you want.
  4. If all else fails, get the source code and try compiling and installing it yourself (be warned, however, this is at least as dangerous as installing the program with Portage. Sometimes you cannot uninstall programs installed manually from source code, as opposed to Entropy and Portage-installed programs which are easy to uninstall). This step is last, because this step is very error prone if, like me, you do not know an awful lot about compiling software or programming, in general. This step depends on the instructions in any INSTALL or README file included with the source code. If these files do not exist I use my knowledge on common compiling methods to install the software. For example, if the source code is written in C/C++ often there will be an autogen.sh or configure file somewhere in the source code base directory, which I will run (usually by opening up a terminal emulator and running user $  ./<FILE> where <FILE>; is either autogen.sh or configure)) and read the output of. If the output includes an error, concerning some missing dependency, I will try to install said dependency (following the same algorithm outlined here) and re-run the autogen.sh/configure script or if the dependency is on my PC already I will try giving the autogen.sh or configure file a PATH variable pointing to the dependency's location on my system when I re-execute them. If no errors are encountered when running these scripts, or I manage to fix them with the methods I just mentioned I then run
    user $  make
    user $  sudo make install
    While if the source code is written in Python I look for a setup.py file and run
    root #  python setup.py install
  5. If errors are encountered at any of these steps (by errors I do not include the absence of available software packages as errors) I would also recommend you attempt to seek support. For example, if the failure happened with an added unofficial overlay I would recommend you find the GitHub repository that houses the overlay and create a new issue for said repository. This process of getting support often occurs quite slowly, taking several days, at least, to get any solution to the problem, so if failures happen I would probably move onto the next step of this algorithm (if there are any steps left) before I would report the failures.

Examples

OpenRA

An example of OpenRA running

An example of OpenRA running

OpenRA (games-strategy/openra: ES, GPO, PT, GR, WKWP) is a free and open-source futuristic strategy game. For me, it reminds me of one of my favourite Windows games, Outlive. OpenRA is unusual in that it is not available in the Entropy Store, although a few ebuilds for it do exist in the Portage Tree, although it is worthwhile mentioning that these ebuilds are often out of date. For example, as of 26 November 2015 the latest ebuild available in the Portage Tree was for version 20141029 (note how this number represents the date of the release, 29 October 2014), while the latest release was 20150919 (released 19 September 2015). There are unofficial overlays (such as games-overlay) that contain more recent versions of OpenRA, although it was not until 19 October 2015 that an ebuild for 20150919 was added to this overlay.

To install the latest version available of OpenRA on Sabayon one has four main options:

  1. Emerge the package from the Portage Tree. This will get you release 20141029, at best. I have not tried this due to how old a version this package is. To do this simply run:
    root #  emerge games-strategy/openra
  2. Add the games-overlay with Layman and emerge the latest version available from it, 20150919. To do this run:

    root #  layman -a games-overlay
    root #  emerge --sync && layman -S
    root #  emerge games-strategy/openra-20150919::games-overlay
  3. Add the dr overlay (not available with Layman) and emerge the latest version, 20150919. This option I have not done, due to the fact it needs freetype unmerged and that would break my system. To do this run:
    root #  layman -o http://github.com/cerebrum/dr/raw/master/repo.xml -f -a dr
    root #  emerge --sync && layman -S
    root #  emerge games-strategy/openra::dr
  4. Compile the source code yourself and install OpenRA from that (which will get you the latest version of OpenRA, 20150919). This option I have succeeded in doing and is how OpenRA is currently installed on my system. To do this I ran:

    user $  wget -c https://github.com/OpenRA/OpenRA/archive/release-20150919.tar.gz | tar -xz
    user $  cd OpenRA-release-20150919
    user $  make dependencies && make all

    This does not add an executable of OpenRA to /usr/games/bin/ and hence running openra from the command-line will not start the game. So after this I also created a shell script file called /usr/games/bin/openra with nano (that is, I ranroot #  nano /usr/games/bin/openra ) with the line mono --debug /path/to/OpenRA.Game.exe where /path/to is replaced with the path to where you built OpenRA from source code (which for me is /home/fusion809/Programs/OpenRA-release-20150919).

SuperTux

SuperTux 0.3.3

SuperTux 0.3.3

SuperTux (games-arcade/supertux: ES, GPO, PT, GR, WP) is a free and open-source (licensed under GNU GPLv3) 2D platform game that was first released in April 2003. Its gameplay is very similar to that of the proprietary game, Super Mario Bros. The initial 2003 release was called “Milestone 1” (or if you would prefer a version number 0.1.3) and is the version of SuperTux that is currently available in the Entropy Store and the Portage Tree. I have installed this version with Entropy, using:

root #  equo i games-arcade/supertux

This game is enjoyable, giving several hours of entertainment for me at least. Despite this, due to my preoccupation with using the latest software available, I looked to install the latest version of SuperTux (which are developmental, but still fairly stable, versions of Milestone 2 (or SuperTux 2) which is due to be released in December 2015). I tried installing it using the unofficial yarik-overlay and while this succeeded I found the most stable version provided by it (0.3.4) plagued by bugs. To do this I ran:

root #  layman -a yarik-overlay
root #  emerge --sync && layman -S
root #  emerge -av supertux

So after this, I decided to give manually building and installing it myself, a go. Then I got the latest tarball source code release (tar -xvf supertux-0.3.5a.tar.bz2 should do this from the command-line), decompressed it, changed into the supertux-0.3.5a directory and ran:

user $  mkdir build
user $  cd build
user $  cmake .. -DCMAKE_INSTALL_PREFIX=/usr
user $  make
user $  sudo make install

this ran without error and the resulting SuperTux 2 installation (which by-the-way I have managed to keep on my system despite never removing my SuperTux 1 Entropy installation) was less buggy. Later, I replaced this installation with the latest git release of SuperTux, via running:

user $  git clone https://github.com/SuperTux/supertux
user $  cd supertux
user $  mkdir build && cd build
user $  cmake .. -DCMAKE_INSTALL_PREFIX=/usr
user $  make
user $  sudo make install

and surprisingly (because git snapshots are usually less stable than tarball pre-releases) it had even fewer bugs than manually compiled SuperTux 0.3.5a. There was one bug that stayed quite persistently, however, after compiling the source code manually — after a while SuperTux2 would not launch (even when run from the command-line) and the error message it gave was related to SDL_BASEPATH not being set. Reinstalling libsdl2 with Entropy solved this problem, for some reason. In an attempt to overcome this error more permanently I have created an ebuild for the latest git snapshot of SuperTux (games-arcade/supertux-9999), installed it, although it seems this has not permanently fixed this problem and occasionally I still have to reinstall libsdl2.

Enlightenment

Enlightenment 20.1, the latest release of Enlightenment as of 24 December 2015.

Enlightenment 20.1, the latest release of Enlightenment as of 24 December 2015.

Enlightenment (x11-wm/enlightenment: ES, GPO, PT, GW, WP) is a free and open-source (BSD Licensed) feature-packed window manager that had its initial release in 1997. This initial release was dubbed Enlightenment DR16 and later in December 2012 (after 12 years of development) the DR17 series of Enlightenment had its first stable release. Both series (DR16 and DR17) are still under active, independent development. DR16 releases tend to be lighter weight (taking up less system resources) than their corresponding DR17 releases, although DR17 released are usually more feature-packed and aesthetically pleasing (or at least in my opinion). The DR17 series itself has its own set of branches: E17 (the original stable DR17 release in December 2012), E18 (released December 2013), E19 (released September 2014) and E20 (released November 2015).

As of 24 December 2015 the latest release of the DR16 series is present in the Portage Tree and Entropy repositories, although the E20 branch of the DR17 series is yet to be added to either repository. The latest releases of the Enlightenment libraries (namely 1.16.0 for all of these packages): EFL (dev-libs/efl: ES, GPO, PTWP), elementary (media-libs/elementary: ES, GPO, PT), evas generic loaders (media-plugins/evas_generic_loaders: ES, GPO, PT) and emotion generic players (media-plugins/emotion_generic_players: ES, GPO, PT), are also missing from the Portage Tree and Entropy repositories. I wanted to try out Enlightenment 20 (E20) on my Sabayon machine, to do so I had two options:

  • Manually compile and install E20 and the latest Enlightenment libraries from source code.
  • Write my own ebuilds for each package and use them to install E20 and its dependencies missing from the Entropy repositories, which are the Enlightenment libraries.

I originally opted for the first of these two options, but I eventually decided to give the second option a try as it would help other users of Gentoo-based Linux distributions such as Sabayon, due to the fact I would keep these ebuilds in my sabayon-tools overlay. To write the required ebuilds I essentially bumped the ebuilds already present in the Portage Tree, namely (where → indicates the bumping I did):

  • dev-libs/efl-1.15.2dev-libs/efl-1.16.0
  • media-libs/elementary-1.15.2media-libs/elementary-1.16.0
  • media-plugins/emotion_generic_players-1.15.0media-plugins/emotion_generic_players-1.16.0
  • media-plugins/evas_generic_loaders-1.15.0media-plugins/evas_generic_loaders-1.16.0
  • x11-wm/enlightenment-0.19.12x11-wm/enlightenment-0.20.0x11-wm/enlightenment-0.20.1

tested them out in a Sabayon chroot and made the adjustments that seemed necessary in order for them to build correctly. One adjustment I made to all of them is to set the RESTRICT="mirror" variable, as not one of these packages are hosted by the Gentoo mirrors yet. I also noticed that I needed to adjust the USE flags of dev-libs/efl-1.16.0 in order for it to build properly. After making these adjustments all five packages are building fine and I even had a Gentoo user on the #gentoo IRC channel build them successfully on their system.

Acknowledgements

I would like to thank pontiki from the #jekyll channel for some help with the formatting of this post and floppym from the #gentoo-dev-help channel for providing the Bash script for use searching the Portage Tree for specific examples.

Footnotes

  1. This is copied mostly from the English Wikipedia 

  2. Specifically the emerge.1.html manpage 

  3. Source: Entropy releases before 0.6.9