Project:Games/Ebuild howto

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

General introduction on writing ebuilds is documented in the Gentoo Development Guide and the Package Manager Specification.

The old games eclass is deprecated (see bug #574082), it must not be used for new ebuilds.

Here we describe the old games eclass and additional game specific procedures.

gamestat

The deprecated games.eclass

The deprecated games.eclass is used by several ebuilds on Gentoo. There are separate eclasses for some of the more commonly modified titles.

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.

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

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.