Ebuilds: Intro to Ebuilds 1
completed by: Eeshan Garg
mentors: Arc Riley, Calchan
Ebuilds are recipes for downloading, configuring, building, and installing software on Gentoo-based distributions (eg, Google's Chrome OS and our Sprout OS). With extensive documentation and thousands of examples in Gentoo's Portage tree, writing your first ebuild may feel intimidating, but you'll quickly learn its pretty easy (and sometimes even fun).
This task is well suited for a student with experience writing scripts and compiling software.
This guide assumes some experience with Linux, shell scripting, and build systems.
This task can be accomplished with little to no Linux experience, but if you're new to Linux a better beginner task may be PySoy: Intro to Linux Development.
Before getting started, you will want to connect to IRC (Internet Relay Chat) to get help should you run into any trouble. You can use webchat.freenode.net in your browser for now, but you may want to consider using a desktop IRC client such as Empathy or XChat. Getting comfortable with IRC now will make this task easier and help you as you continue with Google Code-in tasks.
[IMAGE http://gci.copyleftgames.org/img/icons/irc.png]Internet Relay Chat is one of the oldest Internet protocols, predating HTTP and the web. While not commonly used by casual Internet users, and there are more modern protocols supporting features like images and voice/video chat, many FOSS projects still use IRC for developer chat - and most have a channel on the Freenode network.
To chat in IRC just type and hit [enter]. Commands begin with the "/" character, such as /connect irc.freenode.net to connect to Freenode if you've not already done so.
Every user on Freenode has a unique nickname. Some nicknames are registered by other users so NickServ will tell you it is not available. You can change your nickname at any time with the /nick command, eg, /nick GCIUser
IRC is made of channels (think, "chat rooms") which start with a pound sign, such as "#CopyleftGames". On Freenode, you can expect to find a channel for almost any FOSS project, eg, #Fedora, #Python, #Ubuntu. To join a channel, use the /join command, eg, /join #CopyleftGames
Please keep in mind that during Google Code-in mentors are often swamped with helping students and reviewing tasks. They are not likely staring at an IRC window right when you join and may not see what you write for several minutes. However, especially for beginner tasks, other Google Code-in students are usually happy to help.
Also, open a text document to take notes especially on things you found difficult to understand or had trouble with. We use your feedback to improve our beginner tasks and help other students get started.
To start, you will need a working Portage system. There are many options for this, such as:
- Use a chroot in another Linux distribution like Fedora or Ubuntu
- Download and boot Sprout on your RaspberryPi
- Ask a mentor nicely for remote access to a Gentoo-based server
Once you're in, spend a few minutes looking at your /usr/portage directory - especially the .ebuild files in the subdirectories. If you've ever written a shell script, these should look familiar but with extra functions. You may also notice the /usr/portage/eclass directory contains .eclass files which provide these functions.
[IMAGE http://gci.copyleftgames.org/img/icons/script.png] This minimal example ebuild will make sure "libfoo" version 1.4 or above is installed (and install or upgrade it, as needed), download the source tarball from example.org, configure, build, and install it.
EAPI=5
DESCRIPTION="Foo Deluxe Elite"
HOMEPAGE="http://www.google-melange.com/"
SRC_URI="http://example.org/${PN}/${P}.tar.bz2"
LICENSE="AGPL-3"
SLOT="0"
KEYWORDS="~amd64 ~arm"
IUSE=""
RDEPEND=">=dev-libs/libfoo-1.4"
DEPEND="${RDEPEND}"
Refer to the Ebuild Variables page for what each of these do.
Your task is to write a virtual ebuild which ensures all libsoy dependencies listed in libsoy/INSTALL are installed.
Anything you edit in /usr/portage will be temporary, but an easy place to start. Create a new package directory in an appropriate category, and then copy /usr/portage/skel.ebuild to this new directory - renaming it appropriately.
Open your new ebuild (copied from skel.ebuild) in a text editor and read over the instructions within. You'll need to fill in appropriate values and functions as needed for this task. If you don't know, ask on IRC.
Now its time to test. ebuild [filename.ebuild] digest will try to create a file called Manifest in this directory listing all the files that are part of your ebuild (right now, just your ebuild itself) and a hash of those files. You should be able to now emerge -av [package name] to try out your new ebuild.
Problem? No sweat, that's normal. You can go back to edit the ebuild, create a new Manifest digest, and try to emerge the package again.
[IMAGE http://gci.copyleftgames.org/img/icons/ebuild.png]Nothing as big as Portage would be maintainable without tools to help check and test ebuilds for formatting and syntax errors. One of the most used is repoman.
From your ebuild's directory, type repoman -d full
Any QA (Quality Assurance) issues, such as the Changelog file you're likely missing, will be pointed out. If you're booted on Sprout, it may also pick up unrelated QA issues addressed with other Google Code-in tasks.
While working on this task you should join and remain in #CopyleftGames on Freenode to get help, feedback, and guidance from mentors and other developers.
When you've done, post your ebuild, any extra files you made, and notes to this task as separate files (please do not zip/tar/rar them).