Difference between revisions of "GNOME package guidelines"

From ArchWiki
Jump to navigation Jump to search
(initial submission based on JGC's work)
 
(simplification and beautification of wikilinks (interactive))
Tag: wiki-scripts
 
(64 intermediate revisions by 28 users not shown)
Line 1: Line 1:
The GNOME packages on Arch Linux follow a certain schema.
+
[[Category:Arch package guidelines]]
 +
[[it:GNOME package guidelines]]
 +
[[ja:GNOME パッケージガイドライン]]
 +
[[pt:GNOME package guidelines]]
 +
{{Package guidelines}}
  
==Gnome profile initialization==
+
The [[GNOME]] packages on Arch Linux follow a certain schema.
  
There is no gnome profile initialization anymore. The old line below should be stripped from any PKGBUILD:
+
== Source URL ==
[ -z "$GNOMEDIR" ] && . /etc/profile.d/gnome.sh
 
  
==GConf schemas==
+
This topic contains the most commonly used source URL used by GNOME packages in both [[official repositories]] and [[AUR]]. For examples, search for GNOME packages in the official repositories[https://www.archlinux.org/packages/?q=gnome] and in the AUR[https://aur.archlinux.org/packages/?K=gnome]
 +
 
 +
=== Using released tarball ===
 +
 
 +
When downloading a released tarball, you can get it from https://download.gnome.org using the following source array:
 +
 
 +
<nowiki>source=("https://download.gnome.org/sources/$pkgname/${pkgver%.*}/$pkgname-$pkgver.tar.xz")</nowiki>
 +
 
 +
where ''${pkgver%.*}'' returns the ''major''.''minor'' package version, by removing the suffix of {{ic|pkgver}} (which is the ''micro'' package version). E.g., if ''pkgver=3.28.0'' then ''${pkgver%.*}'' would return ''3.28''.
 +
 
 +
=== Using a commit from Git repository ===
 +
 
 +
Another common practice is to use as source a specific commit from a GNOME software's source code git repository. It doesn't classify as VCS package because Pacman's feature of setting specific commit[https://www.archlinux.org/pacman/PKGBUILD.5.html#_using_vcs_sources_a_id_vcs_a] makes PKGBUILD not follow latest development commits neither update the {{ic|pkgver}} field, using the source from the specified commit hash instead.
 +
 
 +
See a template below:
 +
{{hc|1=PKGBUILD|2=
 +
makedepends=(git)
 +
commit=''hash_of_a_commit'' <nowiki>
 +
source=("git+https://gitlab.gnome.org/GNOME/$pkgname.git#commit=$_commit")
 +
md5sums=('SKIP')
 +
 
 +
pkgver() {
 +
  cd $pkgname
 +
  git describe --tags | sed 's/-/+/g'
 +
}</nowiki>
 +
}}
 +
 
 +
Replace ''hash_of_a_commit'' with the Git commit hash desired.
 +
 
 +
Please notice that since the source is downloaded with ''git'', then {{pkg|git}} must be in makedepends and checksums must be set to 'SKIP', just like it would happen with any other VCS package. Using {{ic|pkgver()}} function is highly recommended, so it sets {{ic|pkgver}} accordingly for the commit hash provided.
 +
 
 +
{{Note|GNOME previously used https://git.gnome.org, but then migrated to https://gitlab.gnome.org[https://www.gnome.org/news/2018/05/gnome-moves-to-gitlab-2/]. Old links should automatically redirect to the new gitlab.gnome.org domain, but it might be wise to manually update your source URL.}}
 +
 
 +
== Building with meson ==
 +
 
 +
Many GNOME software migrated the build system to [https://mesonbuild.com/ Meson], consequently dropping [[GNU Build System|GNU Autotools]] support. That means you will not be using ''./configure'' and ''make'' in this case.
 +
 
 +
In order to build using Meson, add the {{Pkg|meson}} package to [[makedepends]] and call its command ''meson'', optionally including any desired options supported by the target software. The {{Pkg|ninja}} package will also be used in this build system but it is a dependency of {{Pkg|meson}}, so you do not need to include it in the ''makedepends'' array.)
 +
 
 +
The [[Creating packages#build()|build()]], [[Creating packages#check()|check()]], and [[Creating packages#package()|package()]] functions should look something like:
 +
 
 +
{{hc|1=PKGBUILD|2=
 +
makedepends=(meson)
 +
 
 +
build() {
 +
  meson --prefix /usr --buildtype=plain ''source'' ''build''
 +
  ninja -C ''build''
 +
}
 +
 
 +
check() {
 +
  ninja -C ''build'' check
 +
}
 +
 
 +
package() {
 +
  DESTDIR="$pkgdir" ninja -C ''build'' install
 +
}
 +
}}
 +
 
 +
where
 +
* ''source'' is the directory containing the extracted source code, e.g. ''$pkgname'' or ''$pkgname-$pkgver''; and
 +
* ''build'' is the directory that will hold the binary files to be installed.  Normally the dirname "build" is used so you may want to keep it for standardization, but you may rename it to whatever pleases you.
 +
 
 +
{{Note|
 +
* Some software do not support invoking ''meson'' from outside the source code's root directory. If that is your case, adapt the above code block by simply adding {{ic|cd ''source''}} to the start of the three functions above, and also changing the above ''meson'' command-line to {{ic|meson . ''build''}}.
 +
* If the software have no testing rules set (case which the above code block would fail to build the package), remove/comment the whole ''check()'' function.
 +
}}
 +
 
 +
{{Tip|In order to toggle a build option in ''meson'', append {{ic|1=-D ''option=value''}} flags to the ''meson'' command-line, where ''option'' is a supported option for the target software you are building, and ''value'' is a valid value for the ''option'' given. So, for instance, if the software has a ''gtk_doc'' option as ''false'' by default and you want to enable it, append {{ic|1=-D gtk_doc=true}} to the ''meson'' command-line. Read {{ic|meson.build}} and {{ic|meson_options.txt}} files in the source code's root directory to find the available options.}}
 +
 
 +
== GConf schemas ==
 +
 
 +
Some GNOME packages install [[wikipedia:GConf#Schemas|GConf schemas]], even though many others already migrated to GSettings. Those packages should depend on {{Pkg|gconf}}.
 +
 
 +
Gconf schemas get installed in the system GConf database, which has to be avoided.
 +
Some packages provide a {{Ic|--disable-schemas-install}} switch for '''./configure''', which hardly ever works. However, gconftool-2 has a variable called {{Ic|GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL}} which you can set to tell gconftool-2 to not update any databases.
 +
 
 +
When creating packages that install GConf schema files, use
 +
 
 +
{{Bc|1=make GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1 DESTDIR=${pkgdir} install}}
  
Many GNOME packages install GConf schemas. These schemas get installed in the system GConf database, which has to be avoided.
 
Some packages provide a --disable-schemas-install switch for ./configure, which hardly ever works. Therefore, gconftool-2 has a variable called <code>GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL</code>, whenever this is set, gconftool-2 won't update any databases.
 
When creating packages that install schema files, use
 
make GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1 DESTDIR=$startdir/pkg install
 
 
for the package installation step in the PKGBUILD.
 
for the package installation step in the PKGBUILD.
  
GConf schemas need to be installed and removed in the .install file using pre_remove, pre_upgrade and post_upgrade and post_install. Use gconf-merge-schemas to merge several schemas into one package specific file, install or uninstall them with <code>usr/sbin/gconfpkg --(un)install $pkgname</code>.
+
Do not call {{Ic|gconfpkg}} in the .install file, as GConf schemas are automatically installed/removed (while installing/removing the GNOME package) via [[pacman hooks]] since {{Pkg|gconf}}=3.2.6-4
The usage of gconfpkg requres a dependency on gconf>=2.18.0.1-4 (or gconfmm>=2.20.0).
+
 
 +
== GSettings schemas ==
 +
 
 +
The GConf schemas were migrated to GSettings schemas, so many GNOME applications can be found using this new schema file. GSettings uses dconf as backend, so all packages that contain GSettings schemas require {{Pkg|dconf}} as dependency. When a new GSettings schema installed on the system, the GSettings database has to be recompiled, but not when packaging.
 +
 
 +
To avoid recompiling GSettings database on packaging, use the {{Ic|--disable-schemas-compile}} switch for '''./configure'''.
 +
 
 +
Do not call {{Ic|glib-compile-schemas}} in the .install file, as GSettings schema databases are automatically recompiled via [[pacman hooks]] since {{Pkg|glib2}}=2.48.0-2.
 +
 
 +
== Scrollkeeper documentation ==
 +
 
 +
Starting from GNOME 2.20 there is no need to handle scrollkeeper anymore, as {{Pkg|rarian}} reads its OMF files directly. Scrollkeeper-update is a dummy these days. The only required thing now is to makedepend on {{Pkg|gnome-doc-utils}}>=0.11.2.
 +
 
 +
It can be disabled using {{Ic|--disable-scrollkeeper}} switch from '''./configure'''.
 +
 
 +
== GTK icon cache ==
 +
 
 +
Quite some packages install icons in the hicolor icon theme.
 +
 
 +
Do not call {{Ic|gtk-update-icon-cache}} in the .install file, as the icon cache is updated via [[pacman hooks]] since {{Pkg|gtk-update-icon-cache}}=3.20.3-2.  These packages should ''not'' depend on {{Pkg|gtk-update-icon-cache}}, as any application which makes use of gtk icon caches will install the package with the hook and do a full, retroactive cache update.
  
==Scrollkeeper documentation==
+
== .desktop files ==
Starting from GNOME 2.20 there's no need to handle scrollkeeper anymore, as rarian reads OMF files directly. Scrollkeeper-update is a dummy these days. The only required thing now is to makedepend on gnome-doc-utils>=0.11.2.
 
  
==.desktop files==
+
Many packages install Freedesktop.org compatible {{Ic|.desktop}} files and register MimeType entries in them.
Many packages install Freedesktop.org compatible .desktop files and register MimeType entries in them. Running <code>update-desktop-database -q</code> in post_install() and post_remove() is recommended.
 
  
==GTK Icon cache==
+
Do not call {{Ic|update-desktop-database}} in the .install file, as the database is automatically updated via [[pacman hooks]] since {{Pkg|desktop-file-utils}}=0.22-2. They should ''not'' depend on {{Pkg|desktop-file-utils}}, as any desktop which makes use of desktop files will install the package with the hook and do a full, retroactive database update.
Quite some packages install icons in the hicolor icon theme. These packages should depend on hicolor-icon-theme and should have <code>gtk-update-icon-cache -q -t -f usr/share/icons/hicolor</code> in the post_install, post_upgrade and post_remove function.
 
  
==.install files==
+
== .install files ==
For many gnome packages, all .install files look almost exactly the same. The gedit package contains a very generic install file:
 
http://cvs.archlinux.org/cgi-bin/viewcvs.cgi/gnome/gedit/gedit.install
 
  
Basically, the only thing that has to be changed is the pkgname variable on top of the .install file. As long as pacman doesn't supply us with the pkgname variable, we need to supply it in the .install file.
+
Previously, most of the GNOME packages had a .install file calling commands like {{Ic|glib-compile-schemas}}, {{Ic|gtk-update-icon-cache}}, and {{Ic|update-desktop-database}} in order to install/update local cache or databases.  This is deprecated since pacman 5.0 implemented [[Pacman#Hooks|hooks]] which call those commands automatically when installing the package.
When packages don't have gconf .schemas, hicolor icon files, or .desktop files, remove the parts that handle those subjects.
 
  
==Example==
+
To avoid being called twice, the above mentioned commands should be removed from .install file.
For an example of above rules, take a look at the gedit PKGBUILD and the .install file supplied above:
 
http://cvs.archlinux.org/cgi-bin/viewcvs.cgi/gnome/gedit/PKGBUILD
 

Latest revision as of 14:18, 10 November 2018

Package creation guidelines

32-bitCLRCrossEclipseElectronFree PascalGNOMEGoHaskellJavaKDEKernelLispMinGWNode.jsNonfreeOCamlPerlPHPPythonRRubyRustVCSWebWine

The GNOME packages on Arch Linux follow a certain schema.

Source URL

This topic contains the most commonly used source URL used by GNOME packages in both official repositories and AUR. For examples, search for GNOME packages in the official repositories[1] and in the AUR[2]

Using released tarball

When downloading a released tarball, you can get it from https://download.gnome.org using the following source array:

source=("https://download.gnome.org/sources/$pkgname/${pkgver%.*}/$pkgname-$pkgver.tar.xz")

where ${pkgver%.*} returns the major.minor package version, by removing the suffix of pkgver (which is the micro package version). E.g., if pkgver=3.28.0 then ${pkgver%.*} would return 3.28.

Using a commit from Git repository

Another common practice is to use as source a specific commit from a GNOME software's source code git repository. It doesn't classify as VCS package because Pacman's feature of setting specific commit[3] makes PKGBUILD not follow latest development commits neither update the pkgver field, using the source from the specified commit hash instead.

See a template below:

PKGBUILD
makedepends=(git)
commit=hash_of_a_commit 
source=("git+https://gitlab.gnome.org/GNOME/$pkgname.git#commit=$_commit")
md5sums=('SKIP')

pkgver() {
  cd $pkgname
  git describe --tags | sed 's/-/+/g'
}

Replace hash_of_a_commit with the Git commit hash desired.

Please notice that since the source is downloaded with git, then git must be in makedepends and checksums must be set to 'SKIP', just like it would happen with any other VCS package. Using pkgver() function is highly recommended, so it sets pkgver accordingly for the commit hash provided.

Note: GNOME previously used https://git.gnome.org, but then migrated to https://gitlab.gnome.org[4]. Old links should automatically redirect to the new gitlab.gnome.org domain, but it might be wise to manually update your source URL.

Building with meson

Many GNOME software migrated the build system to Meson, consequently dropping GNU Autotools support. That means you will not be using ./configure and make in this case.

In order to build using Meson, add the meson package to makedepends and call its command meson, optionally including any desired options supported by the target software. The ninja package will also be used in this build system but it is a dependency of meson, so you do not need to include it in the makedepends array.)

The build(), check(), and package() functions should look something like:

PKGBUILD
makedepends=(meson)

build() {
  meson --prefix /usr --buildtype=plain source build
  ninja -C build
}

check() {
  ninja -C build check
}

package() {
  DESTDIR="$pkgdir" ninja -C build install
}

where

  • source is the directory containing the extracted source code, e.g. $pkgname or $pkgname-$pkgver; and
  • build is the directory that will hold the binary files to be installed. Normally the dirname "build" is used so you may want to keep it for standardization, but you may rename it to whatever pleases you.
Note:
  • Some software do not support invoking meson from outside the source code's root directory. If that is your case, adapt the above code block by simply adding cd source to the start of the three functions above, and also changing the above meson command-line to meson . build.
  • If the software have no testing rules set (case which the above code block would fail to build the package), remove/comment the whole check() function.
Tip: In order to toggle a build option in meson, append -D option=value flags to the meson command-line, where option is a supported option for the target software you are building, and value is a valid value for the option given. So, for instance, if the software has a gtk_doc option as false by default and you want to enable it, append -D gtk_doc=true to the meson command-line. Read meson.build and meson_options.txt files in the source code's root directory to find the available options.

GConf schemas

Some GNOME packages install GConf schemas, even though many others already migrated to GSettings. Those packages should depend on gconf.

Gconf schemas get installed in the system GConf database, which has to be avoided. Some packages provide a --disable-schemas-install switch for ./configure, which hardly ever works. However, gconftool-2 has a variable called GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL which you can set to tell gconftool-2 to not update any databases.

When creating packages that install GConf schema files, use

make GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1 DESTDIR=${pkgdir} install

for the package installation step in the PKGBUILD.

Do not call gconfpkg in the .install file, as GConf schemas are automatically installed/removed (while installing/removing the GNOME package) via pacman hooks since gconf=3.2.6-4

GSettings schemas

The GConf schemas were migrated to GSettings schemas, so many GNOME applications can be found using this new schema file. GSettings uses dconf as backend, so all packages that contain GSettings schemas require dconf as dependency. When a new GSettings schema installed on the system, the GSettings database has to be recompiled, but not when packaging.

To avoid recompiling GSettings database on packaging, use the --disable-schemas-compile switch for ./configure.

Do not call glib-compile-schemas in the .install file, as GSettings schema databases are automatically recompiled via pacman hooks since glib2=2.48.0-2.

Scrollkeeper documentation

Starting from GNOME 2.20 there is no need to handle scrollkeeper anymore, as rarian reads its OMF files directly. Scrollkeeper-update is a dummy these days. The only required thing now is to makedepend on gnome-doc-utils>=0.11.2.

It can be disabled using --disable-scrollkeeper switch from ./configure.

GTK icon cache

Quite some packages install icons in the hicolor icon theme.

Do not call gtk-update-icon-cache in the .install file, as the icon cache is updated via pacman hooks since gtk-update-icon-cache=3.20.3-2. These packages should not depend on gtk-update-icon-cache, as any application which makes use of gtk icon caches will install the package with the hook and do a full, retroactive cache update.

.desktop files

Many packages install Freedesktop.org compatible .desktop files and register MimeType entries in them.

Do not call update-desktop-database in the .install file, as the database is automatically updated via pacman hooks since desktop-file-utils=0.22-2. They should not depend on desktop-file-utils, as any desktop which makes use of desktop files will install the package with the hook and do a full, retroactive database update.

.install files

Previously, most of the GNOME packages had a .install file calling commands like glib-compile-schemas, gtk-update-icon-cache, and update-desktop-database in order to install/update local cache or databases. This is deprecated since pacman 5.0 implemented hooks which call those commands automatically when installing the package.

To avoid being called twice, the above mentioned commands should be removed from .install file.