Gentoo Games Ebuild HOWTOThis guide is intended to give an overview of how to write good games 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. First and foremost, this document will show you the proper way to write an ebuild, starting with the file naming and placement. This ebuild guide recommends using "vim" for creating ebuilds. Together with "gentoo-syntax" you can create ebuilds quite simply.
Now vim will have proper syntax highlighting for ebuilds. It also has a default template for ebuilds. If you are unfamiliar with vim, I recommend reading the Learning vi guide to familiarize yourself with it. 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.
If, for example, your game is a soccer game named "kickball", you would create a directory in your local overlay like follows.
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.
At this point, vim will populate out a skeleton ebuild for you. It should look like the following.
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 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. 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. 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".
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. 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.
This makes our SRC_URI look like the following.
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.
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. 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. 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". 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. 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. 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.
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.
If the upstream packager did not include a version number, but did use the package name, then S would be set as follows.
If you do not need special handling, leave S= out of the ebuild. 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.
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.
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.
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. 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.
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. After completing the compilation of the game, we need to actually install it.
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 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. 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.
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. 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.
This covers all of the games.eclass functions. The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply. |
|