To install programs, Gentoo uses ebuilds to automatically compile and install packages from source code including their dependency. Check the chapter ebuilds in the Gentoo developer manual.
See: https://devmanual.gentoo.org/general-concepts/index.html
The Gentoo ebuilds are in /usr/portage
and represent the heart
of the Gentoo Linux meta distribution with 10000 thousands of ebuilds.
Additionally /usr/portage
contains some directories not containing ebuilds as
/usr/portage/distfiles
or for newer installations /var/cache/distfiles
that holds the compressed sources
of the single packages that got installed,
The
/usr/portage
directory will be updated (synchronized with the mirror
defined in /etc/portage/make.conf
) using the command emerge --sync.
There is the portage tool that can query portage. Type portageq --help for more.
=<ebuild-version>
is used to mean an specific ebuild containing its version
>=<ebuild-version>
means ebuilds newer or equal
<ebuild>
:<slot>
means the ebuild with the slot number
Before writing an ebuild, check if nobody else has already written this ebuild. Places to look are the overlays with emerge --search when installed and emerge eix when looking in overlays that are not installed. An other place is https://bugs.gentoo.org/. This is usually the place where people put the request to have an ebuild. So ebuilds under development and under test appear there.
The internals of /usr/portage
can be observed as help to
create some ebuilds yourself.
To get more help read https://devmanual.gentoo.org/ or the development manual under https://www.gentoo.org/.
Ebuilds are best developed in a local overlay and when done they can be moved to an overlay residing on th Internet. Using a local overlay avoids that commands to move and copy files to the Internet. The ebuild should not be on both overlays the local and the one on the Internet, since then Gentoo and probably yourself gets confused.
So add the overlay directory to /etc/portage/make.conf
Inside the overlay directory there must be a subdirectory metadata
containing a file layout.conf
with inside
masters = gentoo
Additionally there must be a subdirectory profiles
inside the overlay directory containing a file repo_name
with inside a name of the overlay as
linursdev
Run the following to make your console aware of it:
source /etc/portage/make.conf
echo $PORTDIR_OVERLAY
Beside the ebuild you need a metadata.xml file in the directors containing the maintainers e-mail
address. A skeleton can be found /usr/portage/skel.metadata.xml
Further there are the following files and directories:
The file ChangeLog
that contains the history of the ebuild
The Manifest
and of course the ebuild itself are the only files necessary to emerge an ebuild.
The file Manifest
contains all the checksum of all the ebuild versions plus all the files to be
downloaded. When one file gets changed or one file is missing (e.g. old ebuild version) then the
emerge will fail with a digest failure, to get around that the Manifest
could be re-created.
The directory files
that contains patches to the source archives and digest files containing
checksums of the source archives. Digest files will be obsolete when the Manifest format Manifest2 is
used. Small files that come not with the package as *.desktop
files can also be added here.
Create a subdirectory (ebuild category) in the local overlay as app-misc
and then add subdirectory below that with the name of the ebuild. Finally copy /usr/portage/skel.ebuild
or some other file to it and give it an ebuild name <name>
-<version>
.ebuild
Ebuild are shell scripts using the bash syntax plus helper functions. They follow the package manager specification and this has currently the version number EAPI=5
There are different standard ways how to install a package under Linux as make, automake, distutils. Packages making use of a standard way can inherit the corresponding eclasses in their ebuilds so the ebuild gets very simple and can contain just the package definitions and no code at all.
A good way to get familiar is browsing through /usr/portage
and look for real and simple
ebuilds and use them as examples (start with the simple ones).
https://devmanual.gentoo.org/ebuild-writing/variables/index.html
The name of the ebuild contains the name of the software package, the version or the software package. A released ebuild might require later a modification. To identify that this happens, also the ebuilds have versions, to the first revision of a released ebuild -r1 will be added to the ebuilds name.
Ebuilds with the number 9999 are live ebuilds and can be considered as ebuilds without version.
Once live ebuilds are emerged they are frozen regarding future updates. To update them emerge @live-rebuild or emerge -1 <name>
-9999.ebuild or make it more clever and update them just if something has changed smart-live-rebuild
There is a very rich set of solutions available for writing the ebuild. The difficult part is to know what is available and understand it and get the documentation.
Ebuilds can also include eclasses in /usr/portage/eclass
to
not have to repeat the same lines over and over.
There is also a collection scripts to be used in ebuilds in /usr/lib/portage/bin
The KEYWORDS variable shows if the ebuild is for stable architectures (e.g. x86) or/and to be tested
(e.g. ~x86). If you write an ebuild then it should to be tested and therefore something like ~x86 applies.
Therefore it is not yet to be considered stable and has to be unmasked in
/etc/portage/package.keywords
. Edit this file
manually or append a line as:
echo "<my ebuild>
~x86" >> /etc/portage/package.keywords
See also:
man 1 emerge
man 1 ebuild
man 5 ebuild (it contains an example)
man 5 portage
man 5 make.conf
man 1 ebuild
and about writing ebuilds
man 5 ebuild
The ebuild (at least when making it official) must have a header as
/usr/portage/header.txt
To have something to work more efficient see: http://www.linurs.org/ebuildtool.html
A more complex ebuild would have the DEPEND (build dependency) or RDEPEND (run dependency) line showing what dependencies to other ebuilds including their version ranges.
RDEPEND=" >=media-libs/libmtp-1.1.0 >=sys-fs/fuse-2.6:0 "
Require one of the following
RDEPEND="|| (sys-fs/jmtpfs sys-fs/mtpfs sys-fs/simple-mtpfs sys-fs/go-mtpfs )"
On of the available license from /usr/portage/license
should be selected.
GPL license means also that you have also some duties. You have to make your source code and all of
its published versions available for public for a certain amount of time, therefore you might choose an
other license see /usr/portage/licenses
. By the
way, this is the reason why I prefer sometimes not using GPL, since I do not want to keep track of releases
and versions.
The work of emerging an ebuild is done in temporary directories under /var/tmp/portage/
So all directories have a temporary prefix and doing file operation must take care about that. Variables as ${D} could be used to create a directory
mkdir ${D}/usr/share/icons/hicolor/512x512/apps
Instead of using ${D} or when using relative paths, helper functions as dodir can be used to have the same result:
dodir /usr/share/icons/hicolor/512x512/apps
There are many other helper functions as dosym to create links
Install executable files are done with
exeinto /usr/bin
doexe <something that runs>
The installation of man pages is done with doman
src_install() {
<other code>
doman girttools/girt2html.1
doman girttools/ggirt.1
doman girttools/girtd.1
}
To install documentation the files can be listed in the DOCS variable as
DOCS=( README.txt COPYING.txt )
this makes installing them using the dodoc function.
Try to avoid this but if non of the specific installs can be found in https://devmanual.gentoo.org/function-reference/install-functions/index.html or in https://devmanual.gentoo.org/eclass-reference/eutils.eclass/, then the file they can be installed as
insinto<path>
doins<file>
If a desktop file exist within the package install it to /usr/share/applications
and the menu
domenu slic3r.desktop
If there is no desktop file, create one. This is best done by just copy and rename an existing one and edit it.
If you are the developer, add it to the package.
If you are not the developer add it to the ebuilds directory in the subdirectory file. Then add it
domenu ${FILESDIR}/serna-free-bin.desktop
There is also a function to create a desktop file using the ebuild (see: https://devmanual.gentoo.org/eclass-reference/eutils.eclass/)
make_desktop_entry<command>
<name of desktop file>
<icon>
<Category>
Unfortunately it ends up with a desktop file having an odd file name. In graphical environments the file name is usual replaced by the name inside the desktop file. So it is fine to simply ignore this file name.
Declare the useflag (in the example below hyphenation) with IUSE and then use it in an if condition. Use it in the package dependencies if applies.
IUSE="hyphenation" DEPEND=" hyphenation? ( >=dev-java/offo-hyphenation-2.0 ) ${CDEPEND}" src_configure() { if use hyphenation; then elog "do things here when usflag is set" fi }
Object oriented ebuild writing has also arrived using eclasses https://devmanual.gentoo.org/eclass-reference/index.html. Since non object oriented ebuild functions and object oriented ebuild functions are used in parallel some confusion might occur what is now object oriented and what not. Additional some non object oriented helper functions as doicon come from an eclass.
The eclass https://devmanual.gentoo.org/eclass-reference/eutils.eclass/ is the universal eclass that holds all modern features and should therefore inherited by most ebuilds (if not already inherited by an other eclass used).
inherit eutils
Objects have methods and they can be overwritten. This way eclasses can overwrite the generic or empty methods and then have some useful code to emerge ebuild for specific build methods as automake or dist. In the simplest cases the ebuild has no code at all and just inherits the proper eclass.
emerge app-portage/eclass-manpages allows to type man epatch.eclass to get the manual pages.
When inheriting eclasses function calls as src_install() will be overwritten. Additionally eclasses can overwrite eclasses. However when adding src_install() in the ebuild the eclass install methods are overwritten.
Adding customized stuff to an method can be done by overwriting it, add the custom commands and then recall it.
For distutils-r1, overwrite python_install_all to insert your commands but recall distutils-r1_python_install_all to not disturb the installation (check the eclass reference pages for the names):
python_install_all() { doman girttools/girt2html.1 doman girttools/ggirt.1 doman girttools/girtd.1 distutils-r1_python_install_all }
Inside the directory where the ebuild is a subdirectory files has to be added where the patch can be copied (assuming the patch is not coming from the Internet). Using
inherit eutils
gives the support for patches to the ebuild and
src_prepare() {
epatch "${FILESDIR}/<name>
.patch"
}
will do the job.
epatch handles the patch -p command line option automatically, but there must be a long enough path inside the patch files that points to the file being patched.
Binary ebuilds are not the Gentoo way but sometimes still necessary and Gentoo supports also that. Binary ebuilds should have a filename as
to not get in conflict with the regular source ebuilds. Since binary depends on the architecture they need multiple version to download and restriction to the architecture, so SRC_URI will be a list: <name>
-<version>
-bin.ebuild
SRC_URI="${SRC_URI} amd64? ( <uri for amd64> ) x86? ( <uri for x86> )"
Ebuilds are installed using the following sequential steps:
fetch (download)
unpack
patch
compile
install to temporary location (BUILD_PREF variable showed by emerge -v info. To manually clean rm -rf /var/tmp/portage)
merge from temporary location
and maybe unmerge
Using the command
emerge /usr/portage/<category>
/<ebuild>
/<ebuild>
.ebuild <command>
all those steps are executed automatically. Optionally the program ebuild allows you to do it individually what is an advantage for trouble shooting. To get more help about the use:
Using the command ebuild instead of emerge lets you observe what is going on during installation and you can do a step by step installation.
After that being satisfied with the ebuild, it can be emerged:
emerge -va<program name>
ebuild wants to be smart and avoids to do things already be done. But you are smarter and want during development on an ebuild have ebuild repeating the steps. The command clean resets ebuild's memory:
ebuild /usr/locale/portage/local-overlay/app-misc/<program name>
/<program name>
-< version number>
.ebuild clean
The ebuild needs a digest (a checksum) that ends up in a Manifest
file. For that it needs the package usually tar.gz file found on the Internet as defined inside the ebuild. This fetch from the Internet places it into /usr/portage/distfiles
or on newer installations /var/cache/distfiles
. If the file is not yet on the Internet then this can be done manually by copy the tar.gz
file to . After that the digest can be created with
ebuild /usr/locale/portage/local-overlay/app-misc/<program name>
/<program name>
-< version number>
.ebuild digest
or the following that should do the same
ebuild /usr/locale/portage/local-overlay/app-misc/<program name>
/<program name>
-< version number>
.ebuild manifest
When developing an ebuild then it might be annoying to recreate the Manifest
file after each modification.
There is also the option --skip-manifest
Additional creating the manifest file is omitted when ebuild thinks there is nothing to do since nothing has changed, this behavior can be overwritten using --force
ebuild /<absolute directory where ebuild is>
/<ebuild name>
.ebuild fetch
The zipped package gets downloaded to /usr/portage/distfiles
and the checksums get checked. If the package is not yet on the Internet (e.g. if you are the developer of it) then the package can simply get copied to /usr/portage/distfiles
or make a link. Newer installations use /var/cache/distfiles
Live ebuilds seem to be the way for development, but they get always fetched from the Internet. During package development it is therefore better to avoid them.
Packages that can not automatically be downloaded due to logging requirements need to be copied manually there.
ebuild /<absolute directory where ebuild is>
/<ebuild name>
.ebuild unpack
The package gets unpacked in /var/tmp/portage/
additional
directories are created under <category and file name>
/work/var/tmp/portage/
as <category and file name>
/distdir
, homedir
, temp
After prepare follows configure are these are good steps to fix and modify everything before compilation starts. If everything is already well done then prepare and configure can be empty.
ebuild /<absolute directory where ebuild is>
/<ebuild name>
.ebuild compile
The package gets compiled in the /var/tmp/portage/
directory.
Compilation works in a sandbox that prevents that accidentally writes out of the working directories can be
performed.<category and file name>
/work
ebuild /<absolute directory where ebuild is>
/<ebuild name>
.ebuild install
Installs everything under /var/tmp/portage/
. This directory
serves as temporary root directory. Also for this step the sandbox is active.<category and file name>
/image
ebuild /<absolute directory where ebuild is>
/<ebuild name>
.ebuild merge
Copies all the files over from /var/tmp/portage/
to the root
directory and deletes the files in <category and file name>
/image/var/tmp/portage/
Both programs are python scripts and are in /usr/lib/portage/bin
. In the same location also the bash helper functions are located.
To get familiar with the variables an ebuild uses, print them out as:
Example 14.3. ebuild variables
# to get familiar with the ebuild variables einfo "P=${P}" einfo "PN=${PN}" einfo "PV=${PV}" einfo "PR=${PR}" einfo "A=${A}" einfo "D=${D}" einfo "S=${S}" einfo "WORKDIR=${WORKDIR}" einfo "FILESDIR=${FILESDIR}"
For fop-2.0-r100 this will get
* P=fop-2.0
* PN=fop
* PV=2.0
* PR=r100
* A=fop-2.0-src.zip
* D=/var/tmp/portage/dev-java/fop-2.0-r100/image/
* S=/var/tmp/portage/dev-java/fop-2.0-r100/work/fop-2.0
* WORKDIR=/var/tmp/portage/dev-java/fop-2.0-r100/work
* FILESDIR=/var/tmp/portage/dev-java/fop-2.0-r100/files
All ebuilds the user installs are listed in /var/lib/portage/world
What is installed will be written in the following directories:
|
Top directory |
|
Here is all detail data of the packages installed. |
/var/db/pkg/ |
Holds all directories installed plus all files including their checksums. |
|
Web applications installed with web-config |