Project:Games/Ebuild howto

From Gentoo Wiki
Jump to: navigation, 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

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.