This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.

Please visit our production wiki at https://wiki.gentoo.org

Project:Games/Ebuild howto

From Gentoo Wiki (test)
Jump to:navigation Jump to:search
Warning
This guide is outdated and is in violation of current game ebuild development practices. Until it is updated, please refer to generic ebuild development guidelines, such as Gentoo Development Guide. Michał Górny (talk) 16:14, 13 February 2016 (UTC)

Introduction

This guide was intended to give an overview of how to write good game ebuilds. Writing games ebuilds using the best possible style allows for your submission to be added to Gentoo quickly and with no issues. There are several simple steps that you can follow to achieve this goal, starting from games ebuilds basics to some really nice tricks to work around the broken state of some upstream packages. This guide also tries to point out common mistakes made when contributing an ebuild.

Prerequisites

First and foremost, this document will show you the proper way to write an ebuild, starting with the file naming and placement.

Installing vim

This ebuild guide recommends using vim as the text editor creating ebuilds. Together with the app-vim/gentoo-syntax package, ebuilds can be created quite simply.

root #emerge --ask app-editors/vim app-vim/gentoo-syntax

Once these packages are emerged, vim will have syntax highlighting for ebuilds. It also has a default template for ebuilds. Readers who are unfamiliar with vim should read the vim guide to become familiarize.

Creating a games ebuild in your overlay

We are going to create a game ebuild in your portage overlay. The first thing you will need to do, is to decide which game you would like to write as an ebuild. Next, you will want to decide which category your game best fits.


  • games-action
  • games-arcade
  • games-board
  • games-emulation
  • games-engines
  • games-fps
  • games-kids
  • games-misc
  • games-mud
  • games-puzzle
  • games-roguelike
  • games-rpg
  • games-server
  • games-simulation
  • games-sports
  • games-strategy
  • games-util

If, for example, your game is a soccer game named "kickball", you would create a directory in your local overlay like follows.

root ## Creating your overlay directory
root #mkdir -p /usr/local/portage/games-sports/kickball

If the package is a binary package, and does not support compilation, then append a "-bin" to the end of the package name to make up the portage package name. If the package is a demo version of a commercial, or otherwise full-version game, please name the package with "-demo" appended to the end of the package name. This is a requirement, and is a good idea. Next, you will need to know the version number of the package. It might be needed to convert this number into a format suitable to portage. The ebuild naming policy can be found in the developer handbook online. After deciding on the category and naming of your new ebuild, we will want to start editing on it.

root ## Using vim to edit your ebuild
root #cd /usr/local/portage/games-sports/kickball
root #vim kickball-1.0.ebuild

At this point, vim will populate out a skeleton ebuild for you. It should look like the following.

CODE Skeleton ebuild example
# Copyright 1999-2007 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# Header: $

DESCRIPTION=""
HOMEPAGE=""
SRC_URI=""

LICENSE=""
SLOT="0"
KEYWORDS="~x86"
IUSE=""

DEPEND=""
RDEPEND=""

This actually is a fully functional ebuild, but we will definitely need to do some more editing to get it in a usable state.

Writing the ebuild

Writing the ebuild is the meat of this document. We start by describing the elements above and add elements to our ebuild to create a fully working ebuild for our new game.

inherit games

The first thing we will do is add inherit games to the ebuild. The games team prefers this to be located between the header and the description lines, surrounded by a blank line. This is where you inherit eclasses. If you use a function from an eclass, you must inherit it. Also, always list the games eclass last, unless using another games eclass to override the default games functionality. More on this will be explained later. The games eclass, which will be explained below, is full of functions common to all games ebuilds, and also sets up new defaults for certain ebuild functions, such as pkg_preinst, pkg_postinst, src_compile, and pkg_setup. It also contains some variables that we will use across all games ebuilds, to maintain consistency.

DESCRIPTION

This is the description of the package. The description should be no more than a single line, and should give a quick overview of the game. Try to make it descriptive, yet succinct. A good example for our kickball game would be "a fast-paced SDL soccer game with network play".

Note
Please do not add something like "kickball is" to the beginning of the description. It is redundant and unwanted by the games team.

HOMEPAGE

This is the location of this package's homepage. This should always be linked to the English version of the page, if available. This should also never contain any variables.

SRC_URI (and friends)

This is the first real interesting thing in our ebuild, and also the first place for potential problems. Most upstream packagers use very strange names for their packages. Let's say kickball uses sourceforge.net's distribution system. The file is named "kick-ball-src-v1.0.tar.gz". As you can see, this does not fit the package name in portage. There are a few portage variables which can be used here. The two that I will be discussing are ${P} and ${PV}, which refer to the package name and version, and package version, respectively. If you need to make changes to these, it is recommended to use MY_P or MY_PV, as needed. Proper games team coding style places these variables above DESCRIPTION, but in the same block. In this example, we are going to set MY_P to "kick-ball-src" and MY_PV to "v${PV}". We want to use the ${PV} variable within MY_PV so that future upgrades are easier.


Note
Never hard-code package versions within an ebuild unless there is absolutely no other choice.

This makes our SRC_URI look like the following.

CODE SRC_URI example 1
SRC_URI="mirror://sourceforge/${PN}/${MY_P}-${MY_PV}.tar.bz2"

This would cause portage to search the sourceforge mirrors for kickball/kick-ball-src-v1.0.tar.bz2, which is exactly what we are looking to find. If the package sources are named to match the package, then the SRC_URI line is much simpler.

CODE SRC_URI example 2
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"

LICENSE

The license is an important point in your ebuild. It is also a common place for making mistakes. Try to check the license on any ebuild that you submit. Often times, the license will be in a COPYING file, distributed in the package's tarball. If the license is not readily apparent, try contacting the authors of the package for clarification. For a list of available licenses, look in /usr/portage/licenses . Also, if the license requires the user to accept the license before installation, then you will need to set GAMES_CHECK_LICENSE="yes" in your ebuild.

SLOT

Leave SLOT="0" unless you know what you are doing. The slot is designed to allow two different version packages, that are not compatible and not conflicting, to exist on the system simultaneously. A good example of this is gtk+ 1.x and gtk+ 2.x packages. So far, there have been no games where this is the case, so most likely you will never need to change this.

KEYWORDS

This should state the architectures on which you have tested the game. Since every package should start in a testing state, prefix all architectures with a "~" to show this state. Also, do not list any architecture which you cannot personally test. If you are writing the ebuild on x86, then the KEYWORDS would be "~x86".

IUSE

Does this package have additional features that can be toggled on and off? IUSE lists all the USE flags that this package is capable of using. Do not list any USE flags here which are not used by the package, and also, do not forget to list any USE flags here that you use within the package ebuild. For the meaning of each global USE flag, please check /usr/portage/profiles/use.desc and /usr/portage/profiles/use.local.desc for more information. A local USE flag is used for any additional feature that does not fall under the scope of the already-defined global USE flags.

DEPEND

This variable is used to build the dependency tree for packages that are required to build this package. You should list all packages that are used not only by the game build itself, but also in the ebuild, so if you use "unzip" in your ebuild, you must also add it to DEPEND. These packages are only used at build time.

RDEPEND

This variable is used for run-time dependencies. If left undefined, portage assumes RDEPEND to be equal to DEPEND. These are dependencies required by the package to run. If you have packages listed here, you should also refer to this in DEPEND as follows, otherwise, remove RDEPEND completely.

CODE DEPEND with RDEPEND example
RDEPEND="virtual/opengl"
DEPEND="${RDEPEND}
app-arch/unzip"

S and upstream packaging

The S variable is used to store the starting location that the ebuild should use for performing work. By default, this is S=${WORKDIR}/${P}. If the upstream packager did not use a subdirectory when packing their package, which is common with zip file distribution, then you would set S as follows.

CODE S with no subdirectory example
S=${WORKDIR}

If the upstream packager did not include a version number, but did use the package name, then S would be set as follows.

CODE S with no version example
S=${WORKDIR}/${PN}

If you do not need special handling, leave S= out of the ebuild.

src_unpack

The default src_unpack from portage tends to be all you need for most ebuilds. This function is used to unpack the sources for a particular package. A few examples of when you would want a src_unpack function are below.

CODE Makeself archive example
src_unpack() {
unpack_makeself
}

By default, both unpack and unpack_makeself use ${A} as the target to unpack. You can also specify the target, if you need to only unpack a single download, rather than them all. A good example of this comes from the ut2003 ebuild.

CODE unpack and unpack_makeself example
src_unpack() {
unpack_makeself linux_installer.sh
unpack UT2003CrashFix.zip
}

As you can see, each function specifically calls a certain file to be unpacked. If you need additional steps before compilation, such as making changes to a Makefile, then you will need add it into a src_unpack function. Now, in this final example, let's pretend that our fictional package, kickball, has both a broken Makefile, and also a binary that must be removed for compilation to complete.

CODE kickball src_unpack example
src_unpack() {
unpack ${A}
cd "${S}"
sed -i \
-e "/TARGET/s:/usr/bin/:${GAMES_BINDIR}:" Makefile \
|| die "sed Makefile failed"
rm -f kickball
}

This function shows us several important things that we need to know about games ebuilds. First, when making your own src_unpack, you must always include your own unpacking methods, or use the built-in functions. Next, you see that we cd to our unpacked location, ${S}, which must be quoted.

Now, imagine a line like "TARGET=/usr/bin/" in the game's Makefile. This is wrong for Gentoo, since by default games binaries go into "/usr/games/bin", which is defined by "${GAMES_BINDIR}" in games.eclass. Always use the variable to refer to the games binary location, as this allows users to specify for themselves where they want the games to install their binaries by overriding this variable. There are several other games-specific variables available for you to use, which will be explained further in the document.

You will also notice that we have added "|| die" after each required external command. This is necessary, since it stops the emerge process if that command failed. Never omit these as all important external commands need it. All die messages should be short and to the point. Good examples are above. There is no die after unpack, as it does its own checking and aborts the emerge process on its own.

We did not add a die after the rm above. The reason for this is the presence of kickball will cause the build to fail, but the lack of the file will not hurt us in any way. Remove only items that stop the ebuild from working when present. If there are, for example, Makefiles for 25 different systems, just ignore them. They will not be installed unless we specifically ask for them to be during src_install, and they will be deleted by portage at the end of the completed emerge.

src_compile

This function is where both the configuration and compilation steps take place. By default, this function is slightly different for games ebuilds than for non-games ebuilds. The default function looks as follows.

CODE Default src_compile for games.eclass
src_compile() {
egamesconf || die "egamesconf failed"
emake || die "emake failed"
}

As you can see, we use the egamesconf function, rather than econf. The egamesconf function is a wrapper function that runs "./configure" with the proper paths for a Gentoo games ebuild.

We use emake instead of make. This is standard for all Gentoo ebuilds where make is called.

Since both of these commands are essential for our source-based game, we use "|| die" with a proper die message in our ebuild. This causes the emerge to stop if one either of these steps fails.

src_install

After completing the compilation of the game, we need to actually install it.

CODE Example src_install
src_install() {
dogamesbin ${PN} || die "dogamesbin failed"

insinto "${GAMES_DATADIR}"/${PN}
doins -r data/* || die "doins failed"
dodoc README manual.pdf

# optional
doicon ${PN}.xpm
make_desktop_entry ${PN} KickBall ${PN}.xpm

prepgamesdirs
}

This is a complete src_install for our fictional kickball package. As you can see, it contains a few functions that are specific to the games.eclass, which I will discuss fully below.

First, we have dogamesbin, which works like dobin, except that it puts the binaries into "${GAMES_BINDIR}". This allows for user customized binary directories, without the user needing to edit the ebuild directly.

Next, we tell the ebuild to use "${GAMES_DATADIR}/${PN}" as the default location for our doins calls. We follow this up with a "doins -r" to install the data. Again, we use the variables to allow users to modify these locations without editing the ebuild.

Now, we install the documentation that ships with the package. You should always install documentation for the package. In some cases there will be some optional documentation, such as a walk-thru. For these, you wrap them behind a conditional on the doc USE flag and add doc to IUSE. Never install any COPYING or INSTALL files, as this information is redundant for portage.

We also use two optional commands. The first, doicon, is from the eutils.eclass. This eclass is inherited by the games.eclass, but if you use functions from it, it is advised to inherit the eclass yourself. Remember that the eclass goes before games.eclass on the inherit line. As you can guess, doicon installs an icon file into /usr/share/pixmaps .

Next is make_desktop_entry, also from eutils.eclass. This function creates a freedesktop.org-compliant .desktop entry for this package, which gives it a menu item in the GNOME or KDE menus, or in the menu of any other freedesktop.org-compliant window manager.

The last function is not optional. We use prepgamesdirs last in our src_install function, as it goes through the directories and files that are to be installed and sets proper permissions and ownership on them. The owner is set to root, with the group being set to "${GAMES_GROUP}".


The games.eclass

The games eclasses are designed to fill any needs for writing an ebuild for a game on Gentoo. There are separate eclasses for some of the more commonly modified titles. These eclasses will be discussed further later. For now, we are going to focus on games.eclass.

Variables

The games.eclass provides many variables that control all aspects of a games ebuild. Below is a listing of the variables provided by the eclass, their defaults, and a description of each.

Variable Default Description
GAMES_PREFIX /usr/games This is the prefix into which games are installed
GAMES_PREFIX_OPT /opt This is the prefix into which binary games are installed
GAMES_DATADIR /usr/share/games This is the location into which games should installi their data
GAMES_DATADIR_BASE /usr/share This is the same as ${GAMES_DATADIR}, but some packages append "games" to the directory
GAMES_SYSCONFDIR /etc/games This is a global configuration directory for games
GAMES_STATEDIR /var/games This location is where games store writable state data, such as score files
GAMES_LOGDIR /var/log/games This is the default location for log files, such as that created by a dedicated server
GAMES_LIBDIR NULL This variable should not be used in any ebuilds but can be set by the user to override the games_get_libdir function
GAMES_BINDIR /usr/games/bin Location used by dogamesbin
GAMES_ENVD 90games File that holds environment settings for games, such as the binary path
GAMES_USER root Default owner for games files
GAMES_USER_DED games Default user for dedicated servers
GAMES_GROUP games Group which owns all games and group in which game players should be members
GAMES_CHECK_LICENSE NULL This should be used if you need to have the user accept the ebuild's license before installation. If you require this, set GAMES_CHECK_LICENSE="yes" in your ebuild before calling games_pkg_setup and be sure that games_pkg_setup is called before any other actions take place in your pkg_setup function.

One thing you need to be aware of when creating a games ebuild is that we do not allow games to write to /usr, so any game that does so will need to be patched to write to ${GAMES_STATEDIR} or ${HOME} instead.

Functions

There are many functions within the games.eclass for you to use. Some of them are convenience functions, and some of them are an absolute requirement.

Function Description
games_get_libdir This function prints the architecture-specific location into which games ebuilds should install libraries.
egamesconf As we discussed before, egamesconf is used to configure your package for proper paths on Gentoo. If your package requires a "./configure" step, then egamesconf is a requirement.
gameswrapper The gameswrapper function is an internal function for the games.eclass and should never be used in your ebuild. Its purpose is to modify the default locations for installation of normal Gentoo ebuild functions. The following few functions are all wrapped with gameswrapper.
dogamesbin This is our first function using gameswrapper. This function performs the same actions as dobin, but is wrapped to install into ${GAMES_BINDIR} instead of the default of /usr/bin.
dogamessbin This funtion wraps the dosbin function, and is used for adding files to ${GAMES_PREFIX}/sbin. This function is not very common, as most games expect anyone in the games group to be able to use all of its functions.
dogameslib This function wraps the dolib function. It is used for installing libraries into the proper directory. Be aware that this function installs the libraries into directories based on $(get_libdir). This means the default location on AMD64 would be /usr/games/lib64, rather than the expected /usr/games/lib.
dogameslib.a This function wraps dolib.a and like dogameslib, it installs into the architecture-specific default location.
dogameslib.so This function wraps dolib.so and like dogameslib, it installs into the architecture-specific default location.
newgamesbin This function works the same as dogamesbin, except it gives you the opportunity to rename the binary. This is useful for wrapper scripts, where storing the script in portage requires a different name to differentiate it from other files in ${FILESDIR}.
newgamessbin This function works the same as dogamessbin, except it gives you the opportunity to rename the binary. This is useful for wrapper scripts, where storing the script in portage requires a different name to differentiate it from other files in ${FILESDIR}.
games_make_wrapper This is our last function that employs gameswrapper. This function is used for creating a wrapper in ${GAMES_BINDIR} that points to your actual game binary. This is mostly used for binary games that are installed into ${GAMES_PREFIX_OPT}. You should avoid using a wrapper whenever possible. It is best to patch the sources to resolve any issues, instead.
gamesowners This function is used internally by prepgamesdirs to setup the owner of the files installed by the ebuild to ${GAMES_USER}:${GAMES_GROUP}. You should never call this function yourself.
gamesperms This function does not appear to be used.
prepgamesdirs This function is used to ensure that all files installed by games ebuilds have the proper permissions. This function should be called last in src_install, as it potentially touches every file and directory installed by the ebuild. The purpose of this function is to ensure that the files and directories are writable by ${GAMES_USER}, readable by ${GAMES_GROUP}, and not readable or executable by anyone else.
gamesenv This function sets up the default PATH and LDPATH for games ebuilds. It is called automatically by the games_pkg_postinst function and should not be run manually.
games_pkg_setup This is the default games.eclass pkg_setup function. It does several things to ensure that games will run correctly under Gentoo. First, it runs enewgroup to create the ${GAMES_GROUP} group and enewuser to create the ${GAMES_USER} and ${GAMES_USER_DED} users. If ${GAMES_CHECK_LICENSE} is defined, it will ask the user to accept the package's license via check_license. If your ebuild requires its own pkg_setup function, then be sure to call this function from within yours.
games_src_compile This is the default games.eclass src_compile function. It is actually quite simple as it only runs the following commands. First, it checks if configure is executable, then it runs egamesconf. Then, if checks for the existence of a Makefile, and runs emake.
games_pkg_preinst This is the default games.eclass pkg_preinst function. It is used to copy files from ${GAMES_STATEDIR} to the temporary location used by portage prior to merging. This ensures that any state information files are not unmerged with the old package during an upgrade. If your ebuild requires its own pkg_preinst function, then be sure to call this function from within yours.
games_pkg_postinst This is the default games.eclass pkg_postinst function. First, it runs gamesenv to setup the environment. This is also the function that warns the user about the games group requirement for playing games on Gentoo.
games_ut_unpack This function is used to unpack .uz and .uz2 files that are typically associated with the Unreal Tournament series of games. It can take either a file name or a directory name as an argument. Use of this function requires that your ebuild has games-util/uz2unpack in DEPEND.
games_umod_unpack This function is used to unpack .umod, .ut2mod, and .ut4mod files that are typically associated with the Unreal Tournament series of games. This function requires an installation of one of these games, and is generally only used for modifications to these games.

This covers all of the games.eclass functions.

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Christoph Brill, Chris Gianelloni
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.

Retrieved from "https://wikitest.gentoo.org/index.php?title=Project:Games/Ebuild_howto&oldid=694990"