https://en.opensuse.org/api.php?action=feedcontributions&user=Thomas-schraitle&feedformat=atomopenSUSE Wiki - User contributions [en]2024-03-29T07:52:17ZUser contributionsMediaWiki 1.37.6https://en.opensuse.org/index.php?title=SDB:Live_USB_stick&diff=154266SDB:Live USB stick2021-04-30T07:38:44Z<p>Thomas-schraitle: Improve steps in section "Using the commandline"</p>
<hr />
<div>{{DEFAULTSORT:{{PAGENAME}}}}<br />
{{Installation_navbar}}<br />
{{cleanup}}<br />
{{Intro|This page explains how to create a bootable USB stick in a Linux System. There are dedicated articles about how to [[SDB:Create a Live USB stick using Windows|Create a Live USB stick using '''Windows'''™]] and [[SDB:Create_a_Live_USB_stick_using_Mac_OS_x|Create a Live USB stick using '''macOS''']] }}<br />
{{Version note|12.2+|This applies to openSUSE 12.2 and later.}} Specially this should also work for openSUSE Leap 15.1.<br />
{{Warning|The instructions on this page will destroy all data currently on the USB stick being used. Please be certain it does not contain important information.}}<br />
{{Warning|Do not try to apply procedures found on the internet for other distributions to convert the images into bootable sticks (unetbootin). Doing that will break the images. The openSUSE images are already prepared for being used directly on usb sticks, and can persist filesystem changes without further steps.}} <br />
<br />
== Download the latest openSUSE ISO file ==<br />
<br />
See http://download.opensuse.org/distribution/leap/ as of Nov 2019, this repo keep all the Leap versions (since 42.2 to 15.2), following the links lead to a repo "live" with live isos.<br />
<br />
Official URL: [http://software.opensuse.org/ http://software.opensuse.org/]<br />
<br />
== Backup your USB drive ==<br />
<br />
You could, if you prefer, make a backup image of the stick prior to using it for installation, with dd, and recover it after the installation. [Detailed instructions needed]<br />
<br />
== Using SUSE Studio Image Writer ==<br />
<br />
These a general instructions to write an hybrid iso dvd to an usb device.<br />
<br />
=== Install ImageWriter for openSUSE===<br />
<br />
Install SUSE Imagewriter with 1-Click Install<br />
<br />
For openSUSE 15.1:<br />
[[File:Oneclick.png|link=https://software.opensuse.org/ymp/openSUSE:Leap:15.1/standard/imagewriter.ymp|1-click installation of Imagewriter]]<br />
<br />
For openSUSE 15.0:<br />
[[File:Oneclick.png|link=https://software.opensuse.org/ymp/openSUSE:Leap:15.0/standard/imagewriter.ymp|1-click installation of Imagewriter]]<br />
<br />
For openSUSE Leap 42.3:<br />
[[File:Oneclick.png|link=https://software.opensuse.org/ymp/openSUSE:Leap:42.3/standard/imagewriter.ymp|1-click installation of Imagewriter]]<br />
<br />
For openSUSE Tumbleweed:<br />
[[File:Oneclick.png|link=https://software.opensuse.org/ymp/openSUSE:Factory/snapshot/imagewriter.ymp?base=openSUSE%3AFactory&query=imagewriter|1-click installation of Imagewriter]]<br />
<br />
Or you can use this command as a root to install Imagewriter.<br />
<pre><br />
# sudo zypper install imagewriter<br />
</pre><br />
<br />
=== Write ISO to USB ===<br />
{|<br />
{{Screenshot step|<br />
* Start SUSE Studio Imagewriter from the start menu.<br />
* The image writer needs root permissions. So enter the password for root when prompted.|Studioimagewriter_root.png}}<br />
<br />
{{Screenshot step|<br />
* Open a file manager application.<br />
* Navigate in the file manager to the downloaded ISO file.|Studioimgwriter_1.png}}<br />
<br />
{{Screenshot step|<br />
* Drag&Drop it to the Imagewriter.|Studioimgwriter_2.png}}<br />
<br />
{{Screenshot step|<br />
* Plug your USB memory device in your computer.<br />
* Select it from the dropdown menu at the bottom corner of Imagewriter.|Studioimgwriter_3.png}}<br />
<br />
{{Screenshot step|Confirm overwriting your data on the USB device by clicking OK.|Studioimgwriter_4.png}}<br />
<br />
{{Screenshot step|Writing the data takes a few minutes. After that your openSUSE bootable USB device is ready!|Studioimgwriter_5.png}}<br />
|}<br />
<br />
==Using live-fat-stick, live-grub-stick, live-usb-gui (Command line or GUI way)==<br />
If you'd rather not reformat the USB device and keep the ability of putting files on it and accessible by other operating systems, you have the option of using the <tt>'''live-fat-stick'''</tt> or <tt>'''live-fat-stick'''</tt> scripts from command line or <tt>live-usb-gui</tt> point and click graphical interface. You can put ISO on vfat partitioned USB stick or hard disk.<br />
<br />
On openSUSE you can install the packages simply via yast (Leap 15.1) or via 1-click from here [http://software.opensuse.org/package/live-fat-stick live-fat-stick], [http://software.opensuse.org/package/live-grub-stick live-grub-stick] and [http://software.opensuse.org/package/live-usb-gui live-usb-gui], if you are running any other distribution, get the scripts from [https://github.com/cyberorg/live-fat-stick here] and make it executable(as '''root''', with <code>chmod +x /usr/bin/live-fat-stick</code>) after copying it to <tt>/usr/bin/</tt>, make sure you have '''<tt>syslinux</tt>''' and '''<tt>gpart</tt>''' installed before running it.<br />
<br />
Run the following as root (with <code>su -</code>, not using <code>sudo</code>) in terminal to get the USB device path:<br />
{{Shell|# live-fat-stick -l}}<br />
Run the following to make USB stick with vfat(fat32) partition bootable with iso copied on it:<br />
{{Shell|# live-fat-stick --suse /path/to/openSUSE-filename.iso /dev/sdXY}}<br />
To make USB device bootable with EFI(Secure boot capabilities) wiping all data from it, run:<br />
{{Shell|# live-fat-stick --isohybrid /path/to/openSUSE-filename.iso /dev/sdX}}<br />
For more help, run:<br />
{{Shell|# live-fat-stick -h}}<br />
<br />
Use '''<tt>live-grub-stick</tt>''' command in place of live-fat-stick as shown in above examples if you wish to create bootable usb sticks formatted in any file systems supported by grub2, for example you can use ext3/ntfs formatted stick to create bootable USB from standard openSUSE installation iso, this allows the use of remaining space for putting other iso images or data.<br />
<br />
Multiple iso images from multiple distributions can be added to the USB device with vfat partition when not using "isohybrid" option, boot menu will offer a choice of distribution to boot from. Scripts does not format or remove data from the device.<br />
<br />
== Using commandline tools ==<br />
<br />
The following steps use CLI tools. The example uses prompts: the <code>$</code> is the user prompt and <code>#</code> means the root prompt.<br />
<br />
=== Download LiveCD ISO ===<br />
Download the installation image of your choice from [http://software.opensuse.org/ http://software.opensuse.org/].<br />
<br />
=== Verify the integrity of a downloaded image ===<br />
After the download has been succeeded, verify the correct download with the commands:<br />
<br />
$ gpg --recv-keys 9C800ACA<br />
$ gpg -a openSUSE-*.iso.asc<br />
<br />
<br />
=== Find Block Device ===<br />
To find the block device of your USB stick, make sure you have NOT plugged the stick to your computer.<br />
<br />
1. Run:<br />
<br />
$ lsblk --fs >/tmp/withoutusb.txt<br />
<br />
2. Plug in your USB stick to your computer.<br />
<br />
3. Run:<br />
$ lsblk --fs >/tmp/withusb.txt<br />
$ diff --ignore-space-change /tmp/withoutusb.txt /tmp/withusb.txt<br />
> sdb udf openSUSE 15.2 527a66480003416e <br />
> └─sdb1 vfat ... CF4D-E297<br />
<br />
The output can vary depending on the content of the stick. In this case, your disk is <code>sdb</code> so you need to use the device <code>/dev/sdb</code>.<br />
<br />
<br />
=== Write ISO to USB ===<br />
Finally, once you've found your block device, write the image to it. Point 'dd' to the full path such as '/home/user/Downloads/openSUSE-*.iso'.<br />
<br />
Replace <code>/dev/sd<X></code> with your block device of your USB stick from the previous step:<br />
<br />
# umount /dev/sd<X><br />
# dd if{{=}}/path/to/downloaded.iso of{{=}}/dev/sd<X> bs{{=}}4M status{{=}}progress && sync<br />
<br />
If you get the message<br />
<br />
# dd: invalid status flag: 'progress'<br />
<br />
your dd version does not support the ''status{{=}}progress'' option and therefore you have to remove it (and you will miss the writing progress indicator).<br />
<br />
== Optional steps ==<br />
=== How to recover the USB stick for "normal" use again ===<br />
After system installation, you may want to reuse the stick as you would normally to write things on it. In that case you have to reformat it. Often people complain that Windows fails to do it.<br />
<br />
Typically, you would simply start fdisk:<br />
# fdisk /dev/sdX<br />
and select:<br />
o create a new empty DOS partition table<br />
and then:<br />
n add a new partition<br />
(primary, number 1, default size to use the entire device)<br />
t change a partition's system id<br />
Use type 6, FAT16<br />
w write table to disk and exit<br />
<br />
Finally:<br />
# mkfs.msdos -n SOME_NAME /dev/sdX1<br />
This last step is necessary, particularly the -n SOME_NAME, or the USB stick will mount with the iso name.<br />
<br />
And done. Or, you could use gparted for partitioning and formatting.<br />
<br />
If that doesn't work try the following steps with extreme care:<br />
<br />
If you look at the 12.3 DVD image on a USB stick with fdisk, you would see something like this (notice the GPT warning):<br />
<br />
{{Shell|# fdisk -l /dev/sdX}}<br />
WARNING: GPT (GUID Partition Table) detected on '/dev/sdX'! The util fdisk doesn't support GPT. Use GNU Parted.<br />
<br />
<br />
Disk /dev/sdX: 7742 MB, 7742685184 bytes<br />
64 heads, 32 sectors/track, 7384 cylinders, total 15122432 sectors<br />
Units = sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disk identifier: 0x1bf0d4df<br />
<br />
Device Boot Start End Blocks Id System<br />
/dev/sdX1 4248 12439 4096 ef EFI (FAT-12/16/32)<br />
/dev/sdX2 * 12440 9162751 4575156 17 Hidden HPFS/NTFS<br />
<br />
So, before reformatting, you have to repartition it again. And sometimes, if this fails, you may need an extra step - because software thinks the stick is a CD and thus not writable:<br />
<br />
Notice: all these instructions assume the stick device is /dev/sdX. You have to find which is yours (see “Find Block Device” section above). An error here will destroy some other disk in your system.<br />
<br />
# umount /dev/sdX<br />
# dd if=/dev/zero of=/dev/sdX count=100<br />
<br />
That destroys the boot sector, partition table, and initial structures. Any operating system should be happy to reformat it again.<br />
<br />
== Troubleshooting ==<br />
=== How to make a USB drive bootable ===<br />
This situation would happen very rarely, but in the event that your computer doesn't boot from the LiveUSB/DVD from the steps above, you might try the following procedure.<br />
<br />
[[Image:Linux_fdisk.png|thumb|right|300px|Linux fdisk]]<br />
Open a console and do the following as root:<br />
# umount /dev/sdX<br />
# fdisk /dev/sdX<br />
: p «--- print partition table<br />
: a «--- activate partition (bootable)<br />
: 1 «--- apply to partition 1<br />
: w «--- write changes and exit<br />
<br />
== See also ==<br />
*[[YaST_Image_Creator|YaST Image Creator module]]<br />
*[[SDB:KIWI_Cookbook_Live_USB-Stick|KIWI Cookbook: Live USB Stick]]<br />
<br />
== External links ==<br />
* [http://lizards.opensuse.org/2012/09/13/live-fat-stick/ live-fat-stick]<br />
* [https://lizards.opensuse.org/2013/02/14/live-usb-gui/ live-usb-gui]<br />
<br />
[[Category:SDB:12.2]]<br />
[[Category:SDB:12.3]]<br />
[[Category:SDB:13.1]]<br />
[[Category:SDB:15.1]]<br />
[[Category:SDB:HOWTOs]]<br />
<br />
[[de:SDB:Live_USB_Stick]]<br />
[[es:SDB:Live_USB_stick]]<br />
[[fr:SDB:Live_USB_stick]]<br />
[[it:SDB:Chiavetta USB Live]]<br />
[[ja:SDB:ライブ USB メモリ]]<br />
[[pt:SDB:Live_USB]]<br />
[[ru:SDB:Live_USB_брелок]]<br />
[[zh:SDB:Live_USB_U盘安装]]<br />
[[zh-tw:SDB:Live USB 隨身碟]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Fonts&diff=142555openSUSE:Packaging Fonts2020-05-26T15:29:59Z<p>Thomas-schraitle: Change year and openSUSE release</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging Fonts''' is an overview on how to build font packages for openSUSE and others using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for package names, its content, and other related information.<br />
<br />
== How to Select a New Font ==<br />
There are lots of "free" fonts out there which ''could'' theoretically be packaged. However, we should strive for ''quality'', not quantity. Therefore, here are some guidelines you should answer first before you package a new font at all:<br />
<br />
* '''Is the font open source?''' <br/> You should focus on free fonts released under the OFL, GPL, or any other open or free source license. Although it should be clear, but commercial fonts '''MUST NOT''' be packaged at all!<br />
* '''Is the font already packaged?''' <br/> Before you package a new font, ''always'' look into M17N:fonts repository first. Search for similar package names.<br />
* '''How many font styles does the font bring with?''' <br/> Try to package fonts which have at least a regular and italic style. Preferably the font has also bold and italic+bold (that would make four styles). Sometimes, a font comes with small caps, other brings a condensed or wider variant, but this is not the usual case. <br />
* '''Can the font be used for different languages?''' <br/> Although you rarely will find a font which contains ''all'' possible languages, look for fonts which supports at least European languages. Some contains also Greek or Cyrillic glyphs. Others may support Asian characters. The more languages a font supports, the better will it be for the majority of users.<br />
* '''How many glyphs does the font have?''' <br/> This question is related to the previous one. However, there are more useful glyphs like arrows, dingbats, mathematical symbols, etc. Additional glyphs make it easier to use them for other purposes, like programming or specific texts.<br />
<br />
== Naming and Central Font Repository ==<br />
<br />
Think of a good font name. The general syntax is this (all lower-case):<br />
<pre>[foundryname-]projectname[-fontfamilyname][-fonttype]-fonts</pre><br />
<br />
Here is more detailed explanation<br />
<br />
* '''foundryname''': Usually the name of the designer or a type foundry<br />
* '''projectname''': the name of the font project<br />
* '''fontfamilyname''': if the project contains different font families, specify it here<br />
* '''fonttype''': subsitute 'bitmap' in case you package a bitmap font<br />
<br />
In most cases, the package name is pretty short. For example, if you have a font project "foo", the package name will be "foo-fonts". <br />
<br />
Almost all font packages are located in the [https://build.opensuse.org/project/show/M17N%3Afonts M17N:fonts] repository now.<br />
<br />
See discussion on opensuse-packaging mailinglist [http://lists.opensuse.org/opensuse-packaging/2011-12/msg00093.html RFC: Fonts Repo and Renaming Questions]. It also evolved from FATE #313035 ([https://features.opensuse.org/313035 Invent Consistent Font Naming Schema/Central Font Repository]).<br />
<br />
See [https://build.opensuse.org/project/show?project=M17N%3Afonts M17N:fonts] for names of packages and subpackages or the list of renamed packages in [[openSUSE:Packaging Fonts:Fontlist]].<br />
<br />
== Package content ==<br />
Fonts are different and so the project pages and their archives. Some projects just publish an archive and nothing else, others bring a specimen or additional information.<br />
<br />
If possible, try to package these additional information in <tt>%{_docdir}/PACKAGENAME</tt>.<br />
<br />
== Package Layout for Fonts ==<br />
<br />
Consider how you split your package into subpackages. Best practices are<br />
# to spent one (noarch) rpm for one family and<br />
# do not spread font files of one family over more rpms.<br />
These rules are not binding though, you will meet some counterexamples in M17N:fonts for sure.<br />
<br />
== How to Create a New Font Package ==<br />
The following procedure shows how to create a new font package.<br />
<br />
<ol><br />
<li>Create a new package in your home repository (in our case "foo-fonts"):<br />
<pre>osc mkpac foo-fonts</pre><br />
</li><br />
<li>Download the font package archive from the project's home page and save it to your newly created foo-fonts directory.</li><br />
<li>Create a spec file (in our case, it's foo-fonts.spec) and fill in the gaps. Usually, such file looks like this:<br />
<pre><br />
#<br />
# spec file for package foo-fonts<br />
#<br />
# Copyright (c) 2020 SUSE LINUX Products GmbH, Nuernberg, Germany.<br />
# <br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owner, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
#<br />
# Please submit bugfixes or comments via http://bugs.opensuse.org/<br />
<br />
# Definitions<br />
%define fontname foo<br />
<br />
Name: foo-fonts<br />
Summary: ...<br />
License: OFL-1.1<br />
Group: System/X11/Fonts<br />
BuildArch: noarch<br />
Version: 1.0<br />
Release: 0<br />
Source: %{fontname}-%{version}.tar.bz2<br />
## If the font supports several languages (denoted as X and Y), it's recommended<br />
## to add the following lines:<br />
# Provides: scalable-font-X<br />
# Provides: scalable-font-Y<br />
# Provides: locale(X;Y)<br />
# You can do it conveniently with<br />
# %{lua: <br />
# l = "X;Y;" <br />
# print (string .gsub (l, "(%a+);", "Provides: scalable-font-%1\n"), "\n") <br />
# print (string .sub (l, 1, string .len (l) - 1)) }<br />
BuildRequires: fontpackages-devel <br />
BuildRequires: unzip # only if zipped<br />
%reconfigure_fonts_prereq<br />
URL: http://www.example.org/foo-font<br />
<br />
%description<br />
Foo fonts is...<br />
<br />
Designer: Add the name of the font designer<br />
<br />
%prep<br />
%setup -n %{fontname}-%{version}<br />
# Usually empty, but insert fixes here, if necessary<br />
<br />
# Zipped fonts require unzip and prepare like this:<br />
# %setup -cT<br />
# %{uncompress:%{S:0}}<br />
<br />
%build<br />
# Usually nothing to do<br />
<br />
%install<br />
install -d '%{buildroot}%{_ttfontsdir}<br />
install '-t%{buildroot}%{_ttfontsdir}' -m 644 *.ttf <br />
<br />
# call fonts-config after installation or deinstallation of this package<br />
%reconfigure_fonts_scriptlets<br />
<br />
%files<br />
# Include additional content for the font package, if available<br />
# %doc METADATA FONTLOG.txt OFL.txt<br />
%{_ttfontsdir}<br />
<br />
%changelog<br />
</pre><br />
</li><br />
<li>Create a changelog and write your comment:<br />
<pre>osc vc</pre><br />
</li><br />
<li>Build the package locally:<br />
<pre>osc build --local-package openSUSE_Leap_15.2 foo-fonts.spec</pre><br />
</li><br />
<li>If there are no errors, commit the font package:<br />
<pre>osc ci</pre><br />
</li><br />
<li>Check if everything is built correctly:<br />
<pre>osc r</pre><br />
</li><br />
<li>Submit your package to our M17N:fonts repository:<br />
<pre>osc sr YOUR_REPO foo-fonts M17N:fonts</pre><br />
</li><br />
</ol><br />
<br />
=== RPM macros ===<br />
<br />
Using rpm macros in font packages is highly recomended. Every font package should buildrequire <br />
fontpackages-devel and use macros defined in <br />
[https://build.opensuse.org/package/view_file?file=rpm-macros.fonts-config&package=fontpackages&project=M17N%3Afonts /etc/rpm/macros-fontconfig].<br />
That is because:<br />
# changing common font package behaviour is centralized that way on one place and<br />
# spec files using them can be more clear.<br />
<br />
=== Examples ===<br />
<br />
Here are some example packages with simple spec files:<br />
* [https://build.opensuse.org/package/view_file/M17N:fonts/dejavu-fonts/dejavu-fonts.spec?expand=1 dejavu-fonts]<br />
* [https://build.opensuse.org/package/view_file/M17N:fonts/caslon-fonts/caslon-fonts.spec?expand=1 caslon-fonts]<br />
* [https://build.opensuse.org/package/view_file/M17N:fonts/gdouros-musica-fonts/gdouros-musica-fonts.spec?expand=1 gdouros-musica-fonts]<br />
<br />
== How to Update an Existing Font Package ==<br />
If you want to update a font to a newer version or you found a bug, the following procedure shows how to do it:<br />
<br />
<ol><br />
<li>Open a shell and branch the existing font package on <tt>M17N:fonts</tt>:<br />
<pre>osc bco M17N:fonts FONTPACKAGE</pre><br />
The <tt>osc</tt> script checks out the font package and saves it into <tt>home/USER/branches/M17N/fonts/FONTPACKAGE</tt> (if you have set <tt>checkout_no_colon=1</tt> in your <tt>~/.oscrc</tt> config file). This will be your current working directory.<br />
</li><br />
<li>Download the new package and save it into your working directory. Usually you can find the package from the project's homepage.</li><br />
<li>Change the version number in the spec file.</li><br />
<li>If needed, add patches or other requirements into the spec file (usually mostly not needed).</li><br />
<li>Write a meaningful changelog entry:<br />
<pre>osc vc</pre><br />
(Probably you find information about the changes in the <tt>Changelog</tt> file if included into the archive, or on the project's homepage).<br />
</li><br />
<li>Remove the old archive and add the new one:<br />
<pre>osc rm OLD_ARCHIVE<br />
osc add NEW_ARCHIVE</pre><br />
</li><br />
<li>Build your package and fix any errors (you may replace <tt>openSUSE_Factory</tt> with your preferred distribution):<br />
<pre>osc build openSUSE_Factory *.spec</pre><br />
</li><br />
<li>Commit all your changes:<br />
<pre>osc ci</pre><br />
</li><br />
<li>Submit your changes back to the <tt>M17N:fonts</tt> repository:<br />
<pre>osc sr -m"Updated to version x.y"</pre><br />
</li><br />
</ol><br />
<br />
Your submission will be reviewed and if it conforms to our packaging rules it will be accepted. In case it is declined, you will be informed about the reason. Fix the errors or problems and submit it again (probably you may want to combine the <tt>-s</tt> option (superseding another request by this one) with your <tt>sr</tt> command).<br />
<br />
== Font Package with More Families ==<br />
<br />
Many packages don't split into subpackages even if it contains more font families. Nevertheless, when you want to give users the chance to choose which family from your package to install, then you will have to split your font package in subpackages.<br />
<br />
As a general rule of thumb: split a font into several packages, if it's "big". For "big" there is no exact definition, but a font can be considered "big" if it contains more than one font families or has lots of files which lead to a monstrous file size.<br />
<br />
The spec file can look like:<br />
<br />
<pre># spec file for package bar-fonts<br />
#<br />
# Copyright (c) 2020 SUSE LINUX Products GmbH, Nuernberg, Germany.<br />
#<br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owners, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
<br />
# Please submit bugfixes or comments via http://bugs.opensuse.org/<br />
#<br />
<br />
%define projname bar<br />
<br />
Name: bar-fonts<br />
Version: 2.0<br />
Release: 0<br />
Summary: ...<br />
License: OFL.1.1<br />
Group: System/X11/Fonts<br />
Url: ...<br />
Source0: %{projname}-%{version}.tar.bz2<br />
BuildRequires: fontpackages-devel<br />
%reconfigure_fonts_prereq<br />
BuildRoot: %{_tmppath}/%{name}-%{version}-build<br />
BuildArch: noarch<br />
<br />
%description<br />
...<br />
<br />
%package -n %{projname}-family1-fonts<br />
Summary: ...<br />
Group: System/X11/Fonts<br />
<br />
%description -n %{projname}-family1-fonts<br />
...<br />
<br />
%package -n %{projname}-family2-fonts<br />
Summary: ...<br />
Group: System/X11/Fonts<br />
<br />
%description -n %{projname}-family2-fonts<br />
...<br />
<br />
%package -n %{projname}-family3-fonts<br />
Summary: ...<br />
Group: System/X11/Fonts<br />
<br />
%description -n %{projname}-family3-fonts<br />
...<br />
<br />
%prep<br />
%setup -q -n %{projname}-%{version}<br />
<br />
%build<br />
<br />
%install<br />
mkdir -p %{buildroot}%{_ttfontsdir}<br />
for i in *.ttf<br />
do<br />
install -m 644 $i %{buildroot}%{_ttfontsdir}<br />
done<br />
<br />
%reconfigure_fonts_scriptlets -c -n %{projname}-family1-fonts<br />
<br />
%reconfigure_fonts_scriptlets -c -n %{projname}-family2-fonts<br />
<br />
%reconfigure_fonts_scriptlets -c -n %{projname}-family3-fonts<br />
<br />
# main package can be also empty, then don't inclue %files section<br />
# at all<br />
%files<br />
# Include common content for the font package, if available<br />
# %doc METADATA FONTLOG.txt OFL.txt<br />
<br />
%files -n %{projname}-family1-fonts<br />
%dir %{_ttfontsdir}/<br />
%{_ttfontsdir}/family1.*<br />
<br />
%files -n %{projname}-family2-fonts<br />
%dir %{_ttfontsdir}/<br />
%{_ttfontsdir}/family2.*<br />
<br />
%files -n %{projname}-family3-fonts<br />
%dir %{_ttfontsdir}/<br />
%{_ttfontsdir}/family3.*<br />
<br />
%changelog<br />
<br />
</pre><br />
<br />
=== Examples ===<br />
<br />
* [https://build.opensuse.org/package/show?package=ipa-fonts&project=M17N%3Afonts ipa-fonts]<br />
* [https://build.opensuse.org/package/show?package=stix-fonts&project=M17N%3Afonts stix-fonts]<br />
<br />
== Packaging Fontconfig Files along Font Package ==<br />
<br />
It may happen that you want to package a fontconfig file along with your font files. There's no policy<br />
that the fontconfig file should be part of fontconfig package itself, so you are encouraged to include<br />
it in your font package. With one exception: mapping to generic names serif, sans-serif, <br />
monospace, cursive and fantasy. Especially <default> alias: it is intended to help fontconfig to find similar<br />
fonts to yours when yours are not installed, so packaging it along with your package will evidently not work. <br />
<br />
The fontconfig file can be shipped inside upstream tarball or you can add it as package source.<br />
<br />
There's no strict rules for the name of the fontconfig file except common ones for fontconfig files <br />
(see <tt>/etc/fonts/conf.d/README</tt>). If you want to use the RPM macro <tt>%install_fontsconf</tt>, you have to ensure that the name <br />
of the fontconfig file is identical to that one you want to have in <tt>/etc/fonts/conf.d</tt>. <br />
<br />
In following spec file example, <br />
we want to install <tt>/etc/fonts/conf.d/31-foo-fonts.conf</tt>, so the file name in package source is <tt>31-foo-fonts.conf</tt>. If the <br />
fontconfig file is part of the upstream tarball, you have to either rename it manually or don't use the <tt>%install_fontsconf</tt> RPM macro (i. e. install it manually).<br />
<br />
Example spec file follows; it packages one fontconfig file.<br />
<br />
<pre>#<br />
# spec file for package foo-fonts<br />
#<br />
# Copyright (c) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.<br />
#<br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owners, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
<br />
# Please submit bugfixes or comments via http://bugs.opensuse.org/<br />
#<br />
<br />
<br />
%define fontname foo<br />
<br />
Name: foo-fonts<br />
Version: 3.0<br />
Release: 0<br />
Summary: ...<br />
License: GPL-2.0-with-font-exception<br />
Group: System/X11/Fonts<br />
Url: ...<br />
Source0: %{fontname}-%{version}.tar.bz2<br />
Source1: 31-%{fontname}-fonts.conf<br />
BuildRequires: fontconfig<br />
BuildRequires: fontpackages-devel<br />
%reconfigure_fonts_prereq<br />
BuildRoot: %{_tmppath}/%{name}-%{version}-build<br />
BuildArch: noarch<br />
<br />
%description<br />
...<br />
<br />
%prep<br />
%setup -q -n %{fontname}<br />
<br />
%build<br />
<br />
%install<br />
mkdir -p %{buildroot}%{_ttfontsdir}/<br />
install -m 0644 *.otf %{buildroot}%{_ttfontsdir}<br />
%install_fontsconf %{SOURCE1}<br />
<br />
%reconfigure_fonts_scriptlets<br />
<br />
%files<br />
%doc COPYING README<br />
%{_ttfontsdir}<br />
%files_fontsconf_availdir<br />
%files_fontsconf_file -l 31-linux-libertine.conf<br />
<br />
%changelog<br />
</pre><br />
<br />
Note there are few essential additions compared to simple font package:<br />
<br />
* Adding configuration file into package sources <pre>Source1: 31-%{fontname}-fonts.conf</pre><br />
* Adding build requirements for fontconfig: <pre>BuildRequires: fontconfig</pre><br />
* Installing fontconfig file into availdir (currently <tt>/usr/share/%{name}/conf.avail</tt> defined in <tt>%{_fontsconfavaildir}</tt> RPM macro) and link it into confdir (currently <tt>/etc/fonts/conf.d</tt> defined in <tt>%{_fontsconfddir}</tt> RPM macro) with <pre>%install_fontsconf %{SOURCE1}</pre><br />
* Adding availdir to the package file list <pre>%files_fontsconf_availdir</pre><br />
* Adding configuration file itself into file list; <tt>-l</tt> switch tells macro to include confdir link: <pre>%files_fontsconf_file -l 31-linux-libertine.conf</pre><br />
<br />
Including fontconfig files in fontpackage is not very common, though. At the time of writing, only 9 packages out of 141 in [https://build.opensuse.org/project/show?project=M17N%3Afonts M17N:fonts] do so.<br />
<br />
=== Examples ===<br />
<br />
* [https://build.opensuse.org/package/files?package=linux-libertine-fonts&project=M17N%3Afonts linux-libertine-fonts] -- includes one fontconfig file as package source<br />
* [https://build.opensuse.org/package/files?package=wqy-bitmap-fonts&project=M17N%3Afonts wqy-bitmap-fonts] -- installs one fontconfig file shipped in upstream tarball<br />
* [https://build.opensuse.org/package/files?package=wqy-zenhei-fonts&project=M17N%3Afonts wqy-zenhei-fonts] -- installs three fontconfig files (manually) but links only one to the system config<br />
* [https://build.opensuse.org/package/files?package=stix-fonts&project=M17N%3Afonts stix-fonts] -- includes more fontconfig files as package source, installs one per subpackage<br />
* [https://build.opensuse.org/package/files?package=thai-fonts&project=M17N%3Afonts thai-fonts] -- includes two fontconfig files but doesn't link them in confddir<br />
* [https://build.opensuse.org/package/files?package=cantarell-fonts&project=M17N%3Afonts cantarell-fonts] -- installs one fontconfig file through native build process and link it into system config<br />
<br />
== Notes ==<br />
<br />
=== How to Rename a Font ===<br />
The following procedures show how to rename font package.<br />
<br />
==== Preparing ====<br />
<br />
<ol><br />
<li>Check out the <tt>M17N:fonts</tt> repository:<br />
<pre>osc co M17N:fonts</pre><br />
</li><br />
<li>Open the [https://admin.fedoraproject.org/pkgdb/acls/list/*-fonts*?tg_paginate_limit=0&_csrf_token=db62e614973bacf84613db186a51a2d24fa90950 Fedora Font Package List] in your browser</li><br />
<li>Get a listing of the M17N repository with:<br />
<pre>osc ls M17N</pre></li><br />
<li>Grab a font in this list, for example <tt>LinuxLibertine</tt>.</li><br />
<li>Search the name in the above link to see which is the new name. In this case, it's <tt>linux-libertine-fonts</tt>. <br/><br />
<br />
If you cannot find an equivalent package name, use the following naming schema:<br />
<pre>[foundryname-]projectname[-fontfamilyname][-fonttype]-fonts</pre> <br />
</li><br />
</ol><br />
<br />
==== Copying and Renaming ====<br />
<br />
<ol><br />
<li>Copy the LinuxLibertine font to the new font repository M17N:fonts and use the new name:<br />
<pre>osc copypac M17N LinuxLibertine M17N:fonts linux-libertine-fonts</pre><br />
</li><br />
<li>Update your <tt>M17N:fonts</tt> repository. You will get the new renamed font package:<br />
<pre>osc update<br />
cd linux-libertine-fonts</pre><br />
</li><br />
<li>Rename the <tt>.spec</tt> and <tt>.changes</tt> files to their new names:<br />
<pre>mv LinuxLibertine.spec linux-libertine-fonts.spec<br />
mv LinuxLibertine.changes linux-libertine-fonts.changes</pre><br />
</li><br />
<li>Open the file <tt>linux-libertine-fonts.spec</tt>. The important lines of the <tt>.spec</tt> file looks like this:<br />
<pre>Name: LinuxLibertine<br />
...<br />
Version: 5.1.3<br />
</pre><br />
</li><br />
<li>Change the content of the <tt>Name</tt> keyword to <tt>linux-libertine-fonts</tt>.</li><br />
<li>Copy the version number from the <tt>Version</tt> keyword and insert it into the <tt>Obsoletes</tt> keyword. Add the following lines:<br />
<pre># FIXME: This causes a rpmlint warning; change &lt;= to &lt; once there's a new upstream version<br />
Obsoletes: LinuxLibertine <= 5.1.3<br />
Provides: LinuxLibertine = %{version}</pre><br />
</li><br />
<li>Save the <tt>.spec</tt> file.</li><br />
</ol><br />
<br />
You can also see plenty examples in the [https://build.opensuse.org/project/show?project=M17N%3Afonts M17N:fonts] repository.<br />
<br />
==== Finishing ====<br />
<ol><br />
<li>Build the package, the warning is normal and is expected:<br />
<pre>$ osc build openSUSE_12.1 *.spec<br />
[...]<br />
RPMLINT report:<br />
===============<br />
linux-libertine-fonts.noarch: W: self-obsoletion LinuxLibertine <= 5.1.3 obsoletes LinuxLibertine = 5.1.3<br />
The package obsoletes itself. This is known to cause errors in various tools<br />
and should thus be avoided, usually by using appropriately versioned Obsoletes<br />
and/or Provides and avoiding unversioned ones.<br />
<br />
2 packages and 0 specfiles checked; 0 errors, 1 warnings.</pre><br />
</li><br />
<li>Run <tt>osc vc</tt> to open an editor.</li><br />
<li>Write some changelog lines and save it. We used the following wording:<br />
<pre>Renamed LinuxLibertine -> linux-libertine-fonts according to<br />
Fedora packaging guidelines and FATE#313035<br />
Adjusted Obsoletes and Provides accordingly</pre><br />
</li><br />
<li>Commit your changes:<br />
<pre>osc ci</pre></li><br />
<br />
<li>Submit your changes to factory:<br />
<pre>osc submitreq -m"... some meaningful message ..." openSUSE:Factory</pre><br />
</li><br />
<li>Wait until your submit request is accepted. If your submit request was declined, fix the problems. :-)<br />
</li><br />
<li>Change the devel repository of the old font to the new repository:<br />
<pre>osc changedevelreq openSUSE:Factory LinuxLibertine M17N:fonts linux-libertine-fonts</pre><br />
</li><br />
</ol><br />
<br />
=== BuildRequires Changes since 12.2 (bdftopcf,xmkmf,imake, mkfontdir) ===<br />
<br />
Since openSUSE 12.2, X11:XOrg project split and changed some packages. The packages bdftopcf, imake (includes xmkmf), and mkfontdir are now split into separate subpackages. It's good for end users for a minimal system, but such changes now breaks the old automatic build requirement chain, and makes BuildRequires more complicated.<br />
<br />
If your build fails in openSUSE 12.2 or Factory with error messages like<br />
<br />
<pre>bdftopcf/xmkmf/mkfontdir: Command not found.</pre><br />
<br />
or<br />
<br />
<pre>Imakefile.c:34:0: fatal error: Imake.tmpl: No such file or directory.</pre><br />
<br />
you need the tweaks in this section.<br />
<br />
The common BuildRequires used to package fonts before: <br />
<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
<br />
need to make some changes.<br />
<br />
=== Explanations of the old BuildRequires ===<br />
<br />
xorg-x11 provides <tt>/usr/bin/bdftopcf</tt>,and xorg-x11-devel is actually used to call in xorg-x11-utils-devel,which includes xmkmf, imake and mkfontdir. so xorg-x11 can't be ignored.<br />
<br />
*If the error message is about bdftopcf, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: bdftopcf<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about xmkmf/imake, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: imake //includes xmkmf<br />
BuildRequires: xorg-cf-files //includes Imake.tmpl<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about mkfontdir, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: mkfontdir //this is a "fake" package points to mkfontscale<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about fc-cache, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: fontconfig<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about libfreetype6.so, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: freetype2-devel<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
In Fedora, bdftopcf and mkfontdir are in xorg-x11-font-utils, so needs some more changes:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: bdftopcf<br />
BuildRequires: mkfontdir<br />
%else<br />
%if 0%{?fedora_version}<br />
BuildRequires: xorg-x11-font-utils<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
%endif<br />
<br />
<br />
[[zh:openSUSE:Packaging_Fonts]]<br />
<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Creating_a_changes_file_(RPM)&diff=137996openSUSE:Creating a changes file (RPM)2019-12-09T15:51:46Z<p>Thomas-schraitle: Changelog -> changelog; add tt tag; use upper case when starting a list</p>
<hr />
<div>{{Packaging docnav}}<br />
{{Intro|This article will give you a hints from the [[openSUSE:OpenSUSE_review_team|openSUSE review team]] how to write a good and useful changes entry.}}<br />
<br />
==Changelog section (%changelog)==<br />
Every time you make changes to the package, you must add a changelog entry. This is important not only to have an idea about the history of a package, but also to enable users, fellow packagers, and QA people to easily spot changes you made. (The osc log is underused, as it does not support linking history à la ''git merge'' when an SR is accepted.)<br />
<br />
The Open Build Service uses a separate file for package changes. This file is called like the specfile, but has <tt>.changes</tt> at the end instead of <tt>.spec</tt>.<br />
<br />
A <tt>.changes</tt> file follows these "rules":<br />
<br />
* Use the <tt>osc vc</tt> command to autocreate a new item with the basic structure and formatting.<br />
* Add changelog entries in chronological order.<br />
* List newer changelog entries the file above older entries, thus the first entry is the most recent one.<br />
* You '''shall not''' modify any existing component (where component is a text enclosed between ----------) if a package is checked in to the official repository (openSUSE:Factory).<br />
* Small typo fixes are accepted, as is the addition of bug references, and trimming useless trailing whitespace.<br />
* You may add new components in between older ones. This enables developing a package in more than one branch at a time.<br />
* Limit your maximum line legnth to 67 characters.<br />
* If you want to create a list, start the list with a dash (-). The second-level bullet point symbol ought to be an asterisk, not a plus sign as is sometimes seen. Third-level or deeper bullet points are not defined. The helper script <tt>/usr/lib/build/changelog2spec</tt> specifically recognizes the asterisk and will reflow such bullet points for the RPM changelog (inspectable <tt>rpm -q --changelog</tt>) should they not already be at the second indentation level.<br />
* Remenber, yast2-qt will show the log with a proportional font, so do not attempt any indentation beyond the two levels shown here.<br />
<br />
Entries in this changes file shall have the following structure/formatting styles:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com<br />
<br />
- level 1 bullet point; long descriptions<br />
should wrap<br />
* level 2 bullet point; long descriptions<br />
should wrap<br />
* another l2 bullet point<br />
- another l1 bullet point<br />
</pre><br />
<br />
== What goes into the changelog ==<br />
<br />
The intent of this changelog is to summarize the most newsworthy items, distilled for an openSUSE user. That means you shouldn't just provide a link to a changelog on the Internet. (Network connections may also be unavailable at the time a user wants to find out about changes.)<br />
<br />
=== Version updates ===<br />
<br />
If a version update was done, that should definitely be in the <tt>.changes</tt> file.<br />
Add the release in the first line after your mail address, for example:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - x.y.z<br />
<br />
- Update to new upstream release x.y.z:<br />
* bling and changes from upstream for that version<br />
* just the relevant parts, no info about other OS<br />
* and keep it as short as possible<br />
</pre><br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - 1.2.3.456789<br />
<br />
- Update to snapshot version 1.2.3.456789<br />
* Speed of computing primality of a number was improved two-fold<br />
</pre><br />
<br />
# First of all, find out what is new or has changed. Non-exhaustive list of potential sources for newsworthy items:<br />
## Files inside the source tree with a name of, or similar to, <tt>NEWS</tt>, <tt>CHANGES</tt>, <tt>ChangeLog</tt><br />
## the homepage of the project<br />
## a blog about the software / a blog by the author<br />
## an announce post on a mailing list or community site such as freshcode.club<br />
## your own experience with the new version.<br />
# If you cannot find anything in the aforementioned set of places, that is ok. Say so, and consider it done. (For example, “<tt>* No changelog was made available.</tt>”) It is not necessary to inspect commit logs or to analyze source code.<br />
<br />
Then, assort what you have found with due care:<br />
<br />
# Don't just copy what you find without reviewing yourself.<br />
# Avoid and trim anything related to the build procedure of the package if it has no visible effect on the user. The software is already built by the time it reaches the user.<br />
# Like with [[openSUSE:Package_description_guidelines#Summary|summaries]], remove anything about non-openSUSE platforms.<br />
# You can use SCM commit messages, if they prove to be useful. If in doubt, don't.<br />
# Now, can you, as a package maintainer, make sense of every news item? Does the item mean something to you? If not, then neither does it for the user, and the item in question should be dropped.<br />
# If, at this point, there is nothing to report, say so and consider it done. (E.g. “<tt>* No user-visible changes</tt>” when, for example, upstream only changed the way the software is built.)<br />
# Be concise. Pick only the topmost interesting points: If you have over 30 lines of changelog, it is time to stop and refer the user to the other materials (such as upstream-provided news files, web links, …)<br />
# Be concise (part 2). Summarize and generalize the points: Don't go too much into specifics of a modification — a suitably interested user can look for implementation details elsewhere.<br />
# If there is an incompatible change that requires the user to adapt their configuration and/or setup, this should be mentioned in the changelog of the package, too, to make the users aware of it.<br />
<br />
You can, optionally, add the original upstream change documents to the package as a file as a reference. This however is only in addition to something in .changes.<br />
<br />
If the latest changelog entry doesn't contain a version, rpmlint shows a <tt>no-version-in-last-changelog</tt> warning.<br />
<br />
== Distro-related changes ==<br />
<br />
Besides version updates, there may be changes related to the openSUSE packaging itself. Noteworthy items about that would simply be appended.<br />
<br />
<pre><br />
- update to new upstream release 2.0 (if not, omit)<br />
* this and that as per above<br />
- Added new BuildRequires glibc-devel: new dependency<br />
- Do magic trick in install section to overcome installation failure<br />
- add foobar-fix-ham.patch: <give a reason><br />
- add foobar-remove-spam.patch: <give a reason><br />
- modify foobar-autotools.patch: <give a reason><br />
- remove foobar-libpng15-compat.patch: <give a reason> <br />
- ... (other changes done to the package)<br />
</pre><br />
<br />
* Document the changes for future package changes. It can help in identifying if some hack is still needed (the hack in the .spec should have a comment anyway) and when it was added.<br />
* Make the life for any reviewer easier: a short explanation why something is the way it is helps with annoying declines due to misunderstandings. (This sometimes should go into .spec, whereever appropriate.)<br />
<br />
== Referring to upstream ChangeLog ==<br />
<br />
While it might sound like a good idea in the first run, a simple reference to the place of the upstream changelog (especially if it is tracked on GitHub or other popular collaboration plattforms) is NOT such a good idea. <br />
<br />
* If you reference the changelog in the "master" branch in your changes file, this file might have changed already. Making it really hard to identify which version your changes file entry belongs to <br />
* People with limited internet access (yes: such people still exist) need not only to download the package but also need to open the link (...and we are not starting the discussion on how to extract it from your changes file here) to really see what happened<br />
<br />
So - whenever possible - please try to follow the two simple suggestions:<br />
<br />
* Put the most important upstream changes in your changes file, so your package users can get an idea about important changes. 10-15 lines should be enough for this.<br />
* Refer to a changelog file which is installed together with your package (normally under <tt>/usr/share/doc/packages/$name/Changelog.md</tt> or similar), so people can read the full details without the need to open an internet connection.<br />
<br />
== Bug fix, feature implementation ==<br />
<br />
Anytime you have fixed a bug (or implemented the feature), you '''have to''' mention the number of bug in changes. As fix should be reported in upstream bugzilla, it is better to add a prefix before the number, so people will know where to find an information. For example use ''bsc#1234'' to reference https://bugzilla.suse.com/1234 . The full list of issue trackers is available on [[openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations | Current set of abbreviations]].<br />
<br />
In case the issue has some external identifier, like CVE number, it should be added as well. There are more common ways how to format the message <br />
<br />
- update to Firefox 13.0 (bnc#765204)<br />
* MFSA 2012-34/CVE-2012-1938/CVE-2012-1937/CVE-2011-3101<br />
Miscellaneous memory safety hazards<br />
<br />
- Fix string quoting. [bnc#666416]<br />
<br />
- Add xz BuildRequires because we can't build a package for a<br />
xz-compressed tarball without explicitly specifying that... See<br />
bnc#697467 for more details.<br />
<br />
- fix bnc#595144 - Compiled binary in ant<br />
<br />
== Package updates ==<br />
<br />
In case of package update, the new version have to be mentioned in changes. It is often useful to provide some basic changes from upstream changelog. In case upstream does not provide it, you have to still provide that information in the .changes file, such as <br />
<br />
- update to foo 1.2.3: no changelog available<br />
<br />
- update to Firefox 13.0.1<br />
* bugfix release<br />
<br />
== Patches changes ==<br />
<br />
All changes in patches must follow the [[openSUSE:Packaging_Patches_guidelines#Patch_live_cycle|Patches guidelines]]. It is always a good idea to put the patch name behind the line describing the fix<br />
<br />
- fix segfault on load incorrect document (bnc#123456)<br />
* foo-1.2.4-buffer-owerflow.patch<br />
<br />
- update to Firefox 7 (bnc#720264)<br />
* removed obsolete mozilla-cairo-lcd.patch (upstream)<br />
<br />
== Cross Service-Pack merges for SLE ==<br />
<br />
When you are merging cross Service Packs [0] it might not be always possible to cleanly<br />
merge Factory changelog i.e. without losing patches added/removed, fixed bugs etc<br />
might be getting lost.<br />
<br />
In these cases you are allowed to just use the Factory package as-is, provided that<br />
in your SR message:<br />
<br />
* You explain which patches get lost and why, is that fixed upstream? Not needed anymore? etc. Patch names are tracked because we do not want to introduce any regressions, you have to explicitly point out the situation with each such patch.<br />
<br />
* You mention the lost bug, jira and once again explicitly state that these are fixed (also tell us how, not needed? Fixed upstream?).<br />
<br />
Note that, in no circumstances you are allowed to lose any CVE references, these are very<br />
useful for customers.<br />
<br />
The main point is **not** that those changes file entries are lost, but the actual fixes<br />
get lost. This would mean we introduce regressions into the service pack.<br />
<br />
[0] One case is updating Gnome in a new Service Pack in SP2 where SP1 was already diverged<br />
from Factory and no longer can be cleanly merged.<br />
<br />
Here is a good example, where multiple patches were dropped:<br />
<br />
<pre><br />
needed due to GNOME 3.34 jsc#SLE-8245<br />
<br />
dropped SLE patches:<br />
gtk3-none-pixmap-for-no-background.patch<br />
gtk3-add-gdk_x11_display_get_parent_relative_pattern.patch<br />
gtk3-x11-be-more-careful-about-setting-parent-relati.patch<br />
gtk3-x11-fix-deprecation-macro-use.patch<br />
gtk-use-multiple-font-family-values.patch<br />
gtk3-x11-set-transparent-background.patch<br />
</pre><br />
<br />
[[Category:Packaging|{{PAGENAME}}]]<br />
[[Category:Packaging documentation]]<br />
[[it:openSUSE:Come scrivere buoni file delle modifiche]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Creating_a_changes_file_(RPM)&diff=137994openSUSE:Creating a changes file (RPM)2019-12-09T15:38:27Z<p>Thomas-schraitle: Move list after example into list so all "rules" belongs together</p>
<hr />
<div>{{Packaging docnav}}<br />
{{Intro|This article will give you a hints from the [[openSUSE:OpenSUSE_review_team|openSUSE review team]] how to write a good and useful changes entry.}}<br />
<br />
==Changelog section (%changelog)==<br />
Every time you make changes to the package, you must add a changelog entry. This is important not only to have an idea about the history of a package, but also to enable users, fellow packagers, and QA people to easily spot changes you made. (The osc log is underused, as it does not support linking history à la ''git merge'' when an SR is accepted.)<br />
<br />
The Open Build Service uses a separate file for package changes. This file is called like the specfile, but has <tt>.changes</tt> at the end instead of <tt>.spec</tt>.<br />
<br />
A <tt>.changes</tt> file follows these "rules":<br />
<br />
* Use the <tt>osc vc</tt> command to autocreate a new item with the basic structure and formatting.<br />
* Add changelog entries in chronological order.<br />
* List newer changelog entries the file above older entries, thus the first entry is the most recent one.<br />
* You '''shall not''' modify any existing component (where component is a text enclosed between ----------) if a package is checked in to the official repository (openSUSE:Factory).<br />
* Small typo fixes are accepted, as is the addition of bug references, and trimming useless trailing whitespace.<br />
* You may add new components in between older ones. This enables developing a package in more than one branch at a time.<br />
* Limit your maximum line legnth to 67 characters.<br />
* If you want to create a list, start the list with a dash (-). The second-level bullet point symbol ought to be an asterisk, not a plus sign as is sometimes seen. Third-level or deeper bullet points are not defined. The helper script <tt>/usr/lib/build/changelog2spec</tt> specifically recognizes the asterisk and will reflow such bullet points for the RPM changelog (inspectable <tt>rpm -q --changelog</tt>) should they not already be at the second indentation level.<br />
* Remenber, yast2-qt will show the log with a proportional font, so do not attempt any indentation beyond the two levels shown here.<br />
<br />
Entries in this changes file shall have the following structure/formatting styles:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com<br />
<br />
- level 1 bullet point; long descriptions<br />
should wrap<br />
* level 2 bullet point; long descriptions<br />
should wrap<br />
* another l2 bullet point<br />
- another l1 bullet point<br />
</pre><br />
<br />
== What goes into the changelog ==<br />
<br />
The intent of this changelog is to summarize the most newsworthy items, distilled for an openSUSE user. That means you shouldn't just provide a link to a changelog on the Internet. (Network connections may also be unavailable at the time a user wants to find out about changes.)<br />
<br />
=== Version updates ===<br />
<br />
If a version update was done, that should definitely be in the <tt>.changes</tt> file.<br />
Add the release in the first line after your mail address, for example:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - x.y.z<br />
<br />
- Update to new upstream release x.y.z:<br />
* bling and changes from upstream for that version<br />
* just the relevant parts, no info about other OS<br />
* and keep it as short as possible<br />
</pre><br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - 1.2.3.456789<br />
<br />
- Update to snapshot version 1.2.3.456789<br />
* Speed of computing primality of a number was improved two-fold<br />
</pre><br />
<br />
# First of all, find out what is new or has changed. Non-exhaustive list of potential sources for newsworthy items:<br />
## Files inside the source tree with a name of, or similar to, <tt>NEWS</tt>, <tt>CHANGES</tt>, <tt>ChangeLog</tt><br />
## the homepage of the project<br />
## a blog about the software / a blog by the author<br />
## an announce post on a mailing list or community site such as freshcode.club<br />
## your own experience with the new version.<br />
# If you cannot find anything in the aforementioned set of places, that is ok. Say so, and consider it done. (For example, “<tt>* No changelog was made available.</tt>”) It is not necessary to inspect commit logs or to analyze source code.<br />
<br />
Then, assort what you have found with due care:<br />
<br />
# Don't just copy what you find without reviewing yourself.<br />
# Avoid and trim anything related to the build procedure of the package if it has no visible effect on the user. The software is already built by the time it reaches the user.<br />
# Like with [[openSUSE:Package_description_guidelines#Summary|summaries]], remove anything about non-openSUSE platforms.<br />
# You can use SCM commit messages, if they prove to be useful. If in doubt, don't.<br />
# Now, can you, as a package maintainer, make sense of every news item? Does the item mean something to you? If not, then neither does it for the user, and the item in question should be dropped.<br />
# If, at this point, there is nothing to report, say so and consider it done. (E.g. “<tt>* No user-visible changes</tt>” when, for example, upstream only changed the way the software is built.)<br />
# Be concise. Pick only the topmost interesting points: If you have over 30 lines of changelog, it is time to stop and refer the user to the other materials (such as upstream-provided news files, web links, …)<br />
# Be concise (part 2). Summarize and generalize the points: Don't go too much into specifics of a modification — a suitably interested user can look for implementation details elsewhere.<br />
# If there is an incompatible change that requires the user to adapt their configuration and/or setup, this should be mentioned in the changelog of the package, too, to make the users aware of it.<br />
<br />
You can, optionally, add the original upstream change documents to the package as a file as a reference. This however is only in addition to something in .changes.<br />
<br />
If the latest changelog entry doesn't contain a version, rpmlint shows a <tt>no-version-in-last-changelog</tt> warning.<br />
<br />
== Distro-related changes ==<br />
<br />
Besides version updates, there may be changes related to the openSUSE packaging itself. Noteworthy items about that would simply be appended.<br />
<br />
<pre><br />
- update to new upstream release 2.0 (if not, omit)<br />
* this and that as per above<br />
- Added new BuildRequires glibc-devel: new dependency<br />
- Do magic trick in install section to overcome installation failure<br />
- add foobar-fix-ham.patch: <give a reason><br />
- add foobar-remove-spam.patch: <give a reason><br />
- modify foobar-autotools.patch: <give a reason><br />
- remove foobar-libpng15-compat.patch: <give a reason> <br />
- ... (other changes done to the package)<br />
</pre><br />
<br />
* Document the changes for future package changes. It can help in identifying if some hack is still needed (the hack in the .spec should have a comment anyway) and when it was added.<br />
* Make the life for any reviewer easier: a short explanation why something is the way it is helps with annoying declines due to misunderstandings. (This sometimes should go into .spec, whereever appropriate.)<br />
<br />
== Referring to upstream ChangeLog ==<br />
<br />
While it might sound like a good idea in the first run, a simple reference to the place of the upstream Changelog (especially if it is tracked on GitHub or other popular collaboration plattforms) is NOT such a good idea. <br />
<br />
* if you reference the Changelog in the "master" branch in your changes file, this file might have changed already. Making it really hard to identify which version your changes file entry belongs to <br />
* People with limited internet access (yes: such people still exist) need not only to download the package but also need to open the link (...and we are not starting the discussion on how to extract it from your changes file here) to really see what happened<br />
<br />
So - whenever possible - please try to follow the two simple suggestions:<br />
* put the most important upstream changes in your changes file, so your package users can get an idea about important changes. 10-15 lines should be enough for this.<br />
* refer to a Changelog file which is installed together with your package (normally under /usr/share/doc/packages/$name/Changelog.md or similar), so people can read the full details without the need to open an internet connection.<br />
<br />
== Bug fix, feature implementation ==<br />
<br />
Anytime you have fixed a bug (or implemented the feature), you '''have to''' mention the number of bug in changes. As fix should be reported in upstream bugzilla, it is better to add a prefix before the number, so people will know where to find an information. For example use ''bsc#1234'' to reference https://bugzilla.suse.com/1234 . The full list of issue trackers is available on [[openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations | Current set of abbreviations]].<br />
<br />
In case the issue has some external identifier, like CVE number, it should be added as well. There are more common ways how to format the message <br />
<br />
- update to Firefox 13.0 (bnc#765204)<br />
* MFSA 2012-34/CVE-2012-1938/CVE-2012-1937/CVE-2011-3101<br />
Miscellaneous memory safety hazards<br />
<br />
- Fix string quoting. [bnc#666416]<br />
<br />
- Add xz BuildRequires because we can't build a package for a<br />
xz-compressed tarball without explicitly specifying that... See<br />
bnc#697467 for more details.<br />
<br />
- fix bnc#595144 - Compiled binary in ant<br />
<br />
== Package updates ==<br />
<br />
In case of package update, the new version have to be mentioned in changes. It is often useful to provide some basic changes from upstream changelog. In case upstream does not provide it, you have to still provide that information in the .changes file, such as <br />
<br />
- update to foo 1.2.3: no changelog available<br />
<br />
- update to Firefox 13.0.1<br />
* bugfix release<br />
<br />
== Patches changes ==<br />
<br />
All changes in patches must follow the [[openSUSE:Packaging_Patches_guidelines#Patch_live_cycle|Patches guidelines]]. It is always a good idea to put the patch name behind the line describing the fix<br />
<br />
- fix segfault on load incorrect document (bnc#123456)<br />
* foo-1.2.4-buffer-owerflow.patch<br />
<br />
- update to Firefox 7 (bnc#720264)<br />
* removed obsolete mozilla-cairo-lcd.patch (upstream)<br />
<br />
== Cross Service-Pack merges for SLE ==<br />
<br />
When you are merging cross Service Packs [0] it might not be always possible to cleanly<br />
merge Factory changelog i.e. without losing patches added/removed, fixed bugs etc<br />
might be getting lost.<br />
<br />
In these cases you are allowed to just use the Factory package as-is, provided that<br />
in your SR message:<br />
<br />
* You explain which patches get lost and why, is that fixed upstream? Not needed anymore? etc. Patch names are tracked because we do not want to introduce any regressions, you have to explicitly point out the situation with each such patch.<br />
<br />
* You mention the lost bug, jira and once again explicitly state that these are fixed (also tell us how, not needed? Fixed upstream?).<br />
<br />
Note that, in no circumstances you are allowed to lose any CVE references, these are very<br />
useful for customers.<br />
<br />
The main point is **not** that those changes file entries are lost, but the actual fixes<br />
get lost. This would mean we introduce regressions into the service pack.<br />
<br />
[0] One case is updating Gnome in a new Service Pack in SP2 where SP1 was already diverged<br />
from Factory and no longer can be cleanly merged.<br />
<br />
Here is a good example, where multiple patches were dropped:<br />
<br />
<pre><br />
needed due to GNOME 3.34 jsc#SLE-8245<br />
<br />
dropped SLE patches:<br />
gtk3-none-pixmap-for-no-background.patch<br />
gtk3-add-gdk_x11_display_get_parent_relative_pattern.patch<br />
gtk3-x11-be-more-careful-about-setting-parent-relati.patch<br />
gtk3-x11-fix-deprecation-macro-use.patch<br />
gtk-use-multiple-font-family-values.patch<br />
gtk3-x11-set-transparent-background.patch<br />
</pre><br />
<br />
[[Category:Packaging|{{PAGENAME}}]]<br />
[[Category:Packaging documentation]]<br />
[[it:openSUSE:Come scrivere buoni file delle modifiche]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Creating_a_changes_file_(RPM)&diff=137992openSUSE:Creating a changes file (RPM)2019-12-09T15:28:55Z<p>Thomas-schraitle: Split long text into a list (improves readability)</p>
<hr />
<div>{{Packaging docnav}}<br />
{{Intro|This article will give you a hints from the [[openSUSE:OpenSUSE_review_team|openSUSE review team]] how to write a good and useful changes entry.}}<br />
<br />
==Changelog section (%changelog)==<br />
Every time you make changes to the package, you must add a changelog entry. This is important not only to have an idea about the history of a package, but also to enable users, fellow packagers, and QA people to easily spot changes you made. (The osc log is underused, as it does not support linking history à la ''git merge'' when an SR is accepted.)<br />
<br />
The Open Build Service uses a separate file for package changes. This file is called like the specfile, but has <tt>.changes</tt> at the end instead of <tt>.spec</tt>.<br />
<br />
A <tt>.changes</tt> has the following "rules":<br />
<br />
* Use the <tt>osc vc</tt> command to autocreate a new item with the basic structure and formatting.<br />
* Add changelog entries in chronological order.<br />
* List newer changelog entries the file above older entries, thus the first entry is the most recent one.<br />
* You '''shall not''' modify any existing component (where component is a text enclosed between ----------) if a package is checked in to the official repository (openSUSE:Factory).<br />
* Small typo fixes are accepted, as is the addition of bug references, and trimming useless trailing whitespace.<br />
* You may add new components in between older ones. This enables developing a package in more than one branch at a time.<br />
<br />
Entries in this changes file shall have the following structure/formatting styles:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com<br />
<br />
- level 1 bullet point; long descriptions<br />
should wrap<br />
* level 2 bullet point; long descriptions<br />
should wrap<br />
* another l2 bullet point<br />
- another l1 bullet point<br />
</pre><br />
<br />
Note: The recommended maximal length per line is 67 chars (equal to the dashed line/separator). Third-level or deeper bullet points are not defined. yast2-qt will show the log with a proportional font, so do not attempt any indentation beyond the two levels shown here.<br />
<br />
The second-level bullet point symbol ought to be an asterisk, not a plus sign as is sometimes seen. The helper script <tt>/usr/lib/build/changelog2spec</tt> specifically recognizes the asterisk and will reflow such bullet points for the RPM changelog (inspectable `<tt>rpm -q --changelog</tt>`) should they not already be at the second indentation level.<br />
<br />
== What goes into the changelog ==<br />
<br />
The intent of this changelog is to summarize the most newsworthy items, distilled for an openSUSE user. That means you shouldn't just provide a link to a changelog on the Internet. (Network connections may also be unavailable at the time a user wants to find out about changes.)<br />
<br />
=== Version updates ===<br />
<br />
If a version update was done, that should definitely be in the <tt>.changes</tt> file.<br />
Add the release in the first line after your mail address, for example:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - x.y.z<br />
<br />
- Update to new upstream release x.y.z:<br />
* bling and changes from upstream for that version<br />
* just the relevant parts, no info about other OS<br />
* and keep it as short as possible<br />
</pre><br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - 1.2.3.456789<br />
<br />
- Update to snapshot version 1.2.3.456789<br />
* Speed of computing primality of a number was improved two-fold<br />
</pre><br />
<br />
# First of all, find out what is new or has changed. Non-exhaustive list of potential sources for newsworthy items:<br />
## Files inside the source tree with a name of, or similar to, <tt>NEWS</tt>, <tt>CHANGES</tt>, <tt>ChangeLog</tt><br />
## the homepage of the project<br />
## a blog about the software / a blog by the author<br />
## an announce post on a mailing list or community site such as freshcode.club<br />
## your own experience with the new version.<br />
# If you cannot find anything in the aforementioned set of places, that is ok. Say so, and consider it done. (For example, “<tt>* No changelog was made available.</tt>”) It is not necessary to inspect commit logs or to analyze source code.<br />
<br />
Then, assort what you have found with due care:<br />
<br />
# Don't just copy what you find without reviewing yourself.<br />
# Avoid and trim anything related to the build procedure of the package if it has no visible effect on the user. The software is already built by the time it reaches the user.<br />
# Like with [[openSUSE:Package_description_guidelines#Summary|summaries]], remove anything about non-openSUSE platforms.<br />
# You can use SCM commit messages, if they prove to be useful. If in doubt, don't.<br />
# Now, can you, as a package maintainer, make sense of every news item? Does the item mean something to you? If not, then neither does it for the user, and the item in question should be dropped.<br />
# If, at this point, there is nothing to report, say so and consider it done. (E.g. “<tt>* No user-visible changes</tt>” when, for example, upstream only changed the way the software is built.)<br />
# Be concise. Pick only the topmost interesting points: If you have over 30 lines of changelog, it is time to stop and refer the user to the other materials (such as upstream-provided news files, web links, …)<br />
# Be concise (part 2). Summarize and generalize the points: Don't go too much into specifics of a modification — a suitably interested user can look for implementation details elsewhere.<br />
# If there is an incompatible change that requires the user to adapt their configuration and/or setup, this should be mentioned in the changelog of the package, too, to make the users aware of it.<br />
<br />
You can, optionally, add the original upstream change documents to the package as a file as a reference. This however is only in addition to something in .changes.<br />
<br />
If the latest changelog entry doesn't contain a version, rpmlint shows a <tt>no-version-in-last-changelog</tt> warning.<br />
<br />
== Distro-related changes ==<br />
<br />
Besides version updates, there may be changes related to the openSUSE packaging itself. Noteworthy items about that would simply be appended.<br />
<br />
<pre><br />
- update to new upstream release 2.0 (if not, omit)<br />
* this and that as per above<br />
- Added new BuildRequires glibc-devel: new dependency<br />
- Do magic trick in install section to overcome installation failure<br />
- add foobar-fix-ham.patch: <give a reason><br />
- add foobar-remove-spam.patch: <give a reason><br />
- modify foobar-autotools.patch: <give a reason><br />
- remove foobar-libpng15-compat.patch: <give a reason> <br />
- ... (other changes done to the package)<br />
</pre><br />
<br />
* Document the changes for future package changes. It can help in identifying if some hack is still needed (the hack in the .spec should have a comment anyway) and when it was added.<br />
* Make the life for any reviewer easier: a short explanation why something is the way it is helps with annoying declines due to misunderstandings. (This sometimes should go into .spec, whereever appropriate.)<br />
<br />
== Referring to upstream ChangeLog ==<br />
<br />
While it might sound like a good idea in the first run, a simple reference to the place of the upstream Changelog (especially if it is tracked on GitHub or other popular collaboration plattforms) is NOT such a good idea. <br />
<br />
* if you reference the Changelog in the "master" branch in your changes file, this file might have changed already. Making it really hard to identify which version your changes file entry belongs to <br />
* People with limited internet access (yes: such people still exist) need not only to download the package but also need to open the link (...and we are not starting the discussion on how to extract it from your changes file here) to really see what happened<br />
<br />
So - whenever possible - please try to follow the two simple suggestions:<br />
* put the most important upstream changes in your changes file, so your package users can get an idea about important changes. 10-15 lines should be enough for this.<br />
* refer to a Changelog file which is installed together with your package (normally under /usr/share/doc/packages/$name/Changelog.md or similar), so people can read the full details without the need to open an internet connection.<br />
<br />
== Bug fix, feature implementation ==<br />
<br />
Anytime you have fixed a bug (or implemented the feature), you '''have to''' mention the number of bug in changes. As fix should be reported in upstream bugzilla, it is better to add a prefix before the number, so people will know where to find an information. For example use ''bsc#1234'' to reference https://bugzilla.suse.com/1234 . The full list of issue trackers is available on [[openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations | Current set of abbreviations]].<br />
<br />
In case the issue has some external identifier, like CVE number, it should be added as well. There are more common ways how to format the message <br />
<br />
- update to Firefox 13.0 (bnc#765204)<br />
* MFSA 2012-34/CVE-2012-1938/CVE-2012-1937/CVE-2011-3101<br />
Miscellaneous memory safety hazards<br />
<br />
- Fix string quoting. [bnc#666416]<br />
<br />
- Add xz BuildRequires because we can't build a package for a<br />
xz-compressed tarball without explicitly specifying that... See<br />
bnc#697467 for more details.<br />
<br />
- fix bnc#595144 - Compiled binary in ant<br />
<br />
== Package updates ==<br />
<br />
In case of package update, the new version have to be mentioned in changes. It is often useful to provide some basic changes from upstream changelog. In case upstream does not provide it, you have to still provide that information in the .changes file, such as <br />
<br />
- update to foo 1.2.3: no changelog available<br />
<br />
- update to Firefox 13.0.1<br />
* bugfix release<br />
<br />
== Patches changes ==<br />
<br />
All changes in patches must follow the [[openSUSE:Packaging_Patches_guidelines#Patch_live_cycle|Patches guidelines]]. It is always a good idea to put the patch name behind the line describing the fix<br />
<br />
- fix segfault on load incorrect document (bnc#123456)<br />
* foo-1.2.4-buffer-owerflow.patch<br />
<br />
- update to Firefox 7 (bnc#720264)<br />
* removed obsolete mozilla-cairo-lcd.patch (upstream)<br />
<br />
== Cross Service-Pack merges for SLE ==<br />
<br />
When you are merging cross Service Packs [0] it might not be always possible to cleanly<br />
merge Factory changelog i.e. without losing patches added/removed, fixed bugs etc<br />
might be getting lost.<br />
<br />
In these cases you are allowed to just use the Factory package as-is, provided that<br />
in your SR message:<br />
<br />
* You explain which patches get lost and why, is that fixed upstream? Not needed anymore? etc. Patch names are tracked because we do not want to introduce any regressions, you have to explicitly point out the situation with each such patch.<br />
<br />
* You mention the lost bug, jira and once again explicitly state that these are fixed (also tell us how, not needed? Fixed upstream?).<br />
<br />
Note that, in no circumstances you are allowed to lose any CVE references, these are very<br />
useful for customers.<br />
<br />
The main point is **not** that those changes file entries are lost, but the actual fixes<br />
get lost. This would mean we introduce regressions into the service pack.<br />
<br />
[0] One case is updating Gnome in a new Service Pack in SP2 where SP1 was already diverged<br />
from Factory and no longer can be cleanly merged.<br />
<br />
Here is a good example, where multiple patches were dropped:<br />
<br />
<pre><br />
needed due to GNOME 3.34 jsc#SLE-8245<br />
<br />
dropped SLE patches:<br />
gtk3-none-pixmap-for-no-background.patch<br />
gtk3-add-gdk_x11_display_get_parent_relative_pattern.patch<br />
gtk3-x11-be-more-careful-about-setting-parent-relati.patch<br />
gtk3-x11-fix-deprecation-macro-use.patch<br />
gtk-use-multiple-font-family-values.patch<br />
gtk3-x11-set-transparent-background.patch<br />
</pre><br />
<br />
[[Category:Packaging|{{PAGENAME}}]]<br />
[[Category:Packaging documentation]]<br />
[[it:openSUSE:Come scrivere buoni file delle modifiche]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Creating_a_changes_file_(RPM)&diff=137714openSUSE:Creating a changes file (RPM)2019-11-25T12:34:42Z<p>Thomas-schraitle: Clarified where to find/add the version</p>
<hr />
<div>{{Packaging docnav}}<br />
{{Intro|This article will give you a hints from the [[openSUSE:OpenSUSE_review_team|openSUSE review team]] how to write a good and useful changes entry.}}<br />
<br />
==Changelog section (%changelog)==<br />
Every time you make changes to the package, you must add a changelog entry. This is important not only to have an idea about the history of a package, but also to enable users, fellow packagers, and QA people to easily spot the changes that you make. (The osc log is underused, as it does not support linking history à la ''git merge'' when an SR is accepted.)<br />
<br />
The Open Build Service uses a separate file for package changes. This file is called like the specfile, but has <tt>.changes</tt> at the end instead of <tt>.spec</tt>. The `osc vc` command can be used to autocreate a new item with the basic structure and formatting. Changelog entries have to be in chronological order. Newer changelog entries are listed in the file above older entries, thus the first entry is the most recent one. You '''shall not''' modify any existing component (where component is a text enclosed between ----------) if a package is checked in to the official repository (openSUSE:Factory). Small typo fixes are accepted, as is the addition of bug references, and trimming useless trailing whitespace. You may add new components in between older ones. This enables developing a package in more than one branch at a time.<br />
<br />
Entries in this changes file shall have the following structure/formatting styles:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com<br />
<br />
- level 1 bullet point; long descriptions<br />
should wrap<br />
* level 2 bullet point; long descriptions<br />
should wrap<br />
* another l2 bullet point<br />
- another l1 bullet point<br />
</pre><br />
<br />
Note: The recommended maximal length per line is 67 chars (equal to the dashed line/separator). Third-level or deeper bullet points are not defined. yast2-qt will show the log with a proportional font, so do not attempt any indentation beyond the two levels shown here.<br />
<br />
The second-level bullet point symbol ought to be an asterisk, not a plus sign as is sometimes seen. The helper script <tt>/usr/lib/build/changelog2spec</tt> specifically recognizes the asterisk and will reflow such bullet points for the RPM changelog (inspectable `<tt>rpm -q --changelog</tt>`) should they not already be at the second indentation level.<br />
<br />
== What goes into the changelog ==<br />
<br />
The intent of this changelog is to summarize the most newsworthy items, distilled for an openSUSE user. That means you shouldn't just provide a link to a changelog on the Internet. (Network connections may also be unavailable at the time a user wants to find out about changes.)<br />
<br />
=== Version updates ===<br />
<br />
If a version update was done, that should definitely be in the <tt>.changes</tt> file.<br />
Add the release in the first line after your mail address, for example:<br />
<br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - x.y.z<br />
<br />
- Update to new upstream release x.y.z:<br />
* bling and changes from upstream for that version<br />
* just the relevant parts, no info about other OS<br />
* and keep it as short as possible<br />
</pre><br />
<pre><br />
-------------------------------------------------------------------<br />
Tue Apr 22 20:54:26 UTC 2013 - your@email.com - 1.2.3.456789<br />
<br />
- Update to snapshot version 1.2.3.456789<br />
* Speed of computing primality of a number was improved two-fold<br />
</pre><br />
<br />
# First of all, find out what is new or has changed. Non-exhaustive list of potential sources for newsworthy items:<br />
## Files inside the source tree with a name of, or similar to, <tt>NEWS</tt>, <tt>CHANGES</tt>, <tt>ChangeLog</tt><br />
## the homepage of the project<br />
## a blog about the software / a blog by the author<br />
## an announce post on a mailing list or community site such as freshcode.club<br />
## your own experience with the new version.<br />
# If you cannot find anything in the aforementioned set of places, that is ok. Say so, and consider it done. (For example, “<tt>* No changelog was made available.</tt>”) It is not necessary to inspect commit logs or to analyze source code.<br />
<br />
Then, assort what you have found with due care:<br />
<br />
# Don't just copy what you find without reviewing yourself.<br />
# Avoid and trim anything related to the build procedure of the package if it has no visible effect on the user. The software is already built by the time it reaches the user.<br />
# Like with [[openSUSE:Package_description_guidelines#Summary|summaries]], remove anything about non-openSUSE platforms.<br />
# You can use SCM commit messages, if they prove to be useful. If in doubt, don't.<br />
# Now, can you, as a package maintainer, make sense of every news item? Does the item mean something to you? If not, then neither does it for the user, and the item in question should be dropped.<br />
# If, at this point, there is nothing to report, say so and consider it done. (E.g. “<tt>* No user-visible changes</tt>” when, for example, upstream only changed the way the software is built.)<br />
# Be concise. Pick only the topmost interesting points: If you have over 30 lines of changelog, it is time to stop and refer the user to the other materials (such as upstream-provided news files, web links, …)<br />
# Be concise (part 2). Summarize and generalize the points: Don't go too much into specifics of a modification — a suitably interested user can look for implementation details elsewhere.<br />
# If there is an incompatible change that requires the user to adapt their configuration and/or setup, this should be mentioned in the changelog of the package, too, to make the users aware of it.<br />
<br />
You can, optionally, add the original upstream change documents to the package as a file as a reference. This however is only in addition to something in .changes.<br />
<br />
If the latest changelog entry doesn't contain a version, rpmlint shows a <tt>no-version-in-last-changelog</tt> warning.<br />
<br />
== Distro-related changes ==<br />
<br />
Besides version updates, there may be changes related to the openSUSE packaging itself. Noteworthy items about that would simply be appended.<br />
<br />
<pre><br />
- update to new upstream release 2.0 (if not, omit)<br />
* this and that as per above<br />
- Added new BuildRequires glibc-devel: new dependency<br />
- Do magic trick in install section to overcome installation failure<br />
- add foobar-fix-ham.patch: <give a reason><br />
- add foobar-remove-spam.patch: <give a reason><br />
- modify foobar-autotools.patch: <give a reason><br />
- remove foobar-libpng15-compat.patch: <give a reason> <br />
- ... (other changes done to the package)<br />
</pre><br />
<br />
* Document the changes for future package changes. It can help in identifying if some hack is still needed (the hack in the .spec should have a comment anyway) and when it was added.<br />
* Make the life for any reviewer easier: a short explanation why something is the way it is helps with annoying declines due to misunderstandings. (This sometimes should go into .spec, whereever appropriate.)<br />
<br />
== Referring to upstream ChangeLog ==<br />
<br />
While it might sound like a good idea in the first run, a simple reference to the place of the upstream Changelog (especially if it is tracked on GitHub or other popular collaboration plattforms) is NOT such a good idea. <br />
<br />
* if you reference the Changelog in the "master" branch in your changes file, this file might have changed already. Making it really hard to identify which version your changes file entry belongs to <br />
* People with limited internet access (yes: such people still exist) need not only to download the package but also need to open the link (...and we are not starting the discussion on how to extract it from your changes file here) to really see what happened<br />
<br />
So - whenever possible - please try to follow the two simple suggestions:<br />
* put the most important upstream changes in your changes file, so your package users can get an idea about important changes. 10-15 lines should be enough for this.<br />
* refer to a Changelog file which is installed together with your package (normally under /usr/share/doc/packages/$name/Changelog.md or similar), so people can read the full details without the need to open an internet connection.<br />
<br />
== Bug fix, feature implementation ==<br />
<br />
Anytime you have fixed a bug (or implemented the feature), you '''have to''' mention the number of bug in changes. As fix should be reported in upstream bugzilla, it is better to add a prefix before the number, so people will know where to find an information. For example use ''bsc#1234'' to reference https://bugzilla.suse.com/1234 . The full list of issue trackers is available on [[openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations | Current set of abbreviations]].<br />
<br />
In case the issue has some external identifier, like CVE number, it should be added as well. There are more common ways how to format the message <br />
<br />
- update to Firefox 13.0 (bnc#765204)<br />
* MFSA 2012-34/CVE-2012-1938/CVE-2012-1937/CVE-2011-3101<br />
Miscellaneous memory safety hazards<br />
<br />
- Fix string quoting. [bnc#666416]<br />
<br />
- Add xz BuildRequires because we can't build a package for a<br />
xz-compressed tarball without explicitly specifying that... See<br />
bnc#697467 for more details.<br />
<br />
- fix bnc#595144 - Compiled binary in ant<br />
<br />
== Package updates ==<br />
<br />
In case of package update, the new version have to be mentioned in changes. It is often useful to provide some basic changes from upstream changelog. In case upstream does not provide it, you have to still provide that information in the .changes file, such as <br />
<br />
- update to foo 1.2.3: no changelog available<br />
<br />
- update to Firefox 13.0.1<br />
* bugfix release<br />
<br />
== Patches changes ==<br />
<br />
All changes in patches must follow the [[openSUSE:Packaging_Patches_guidelines#Patch_live_cycle|Patches guidelines]]. It is always a good idea to put the patch name behind the line describing the fix<br />
<br />
- fix segfault on load incorrect document (bnc#123456)<br />
* foo-1.2.4-buffer-owerflow.patch<br />
<br />
- update to Firefox 7 (bnc#720264)<br />
* removed obsolete mozilla-cairo-lcd.patch (upstream)<br />
<br />
[[Category:Packaging|{{PAGENAME}}]]<br />
[[Category:Packaging documentation]]<br />
[[it:openSUSE:Come scrivere buoni file delle modifiche]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=136730openSUSE:Packaging XML Schemas and Stylesheets2019-09-25T10:38:55Z<p>Thomas-schraitle: Mention spec-cleaner</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependent (compare <tt>/usr/share/xml/</tt> with <tt>C:\Program\...</tt>)<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group></tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Create your Spec File ===<br />
<br />
To create a spec file, use the following steps:<br />
<br />
<ol><br />
<li>Start with the usual copyright notice:<br />
<pre>#<br />
# spec file for package foo-schema<br />
#<br />
# Copyright (c) 2019 SUSE LINUX GmbH, Nuernberg, Germany.<br />
#<br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owners, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
<br />
# Please submit bugfixes or comments via https://bugs.opensuse.org/<br />
#</pre><br />
</li><br />
<br />
<li>Add the minimum set of placeholders:<br />
<pre>%define xml_sysconf_dir %{_sysconfdir}/xml<br />
%define xml_catalogd_dir %{xml_sysconf_dir}/catalog.d</pre><br />
</li><br />
<br />
<li>Recommended, but optionally, define more placeholders. It makes things easier to change and more consistent. For example, if your package <tt>foo</tt> comes with a RELAX NG, Schematron, XSD, and/or NVDL schemas, you could define (leave out the things you do not need):<br />
<br />
<pre>%define foo_dir %{_datadir}/xml/foo<br />
%define foo_schema_dir %{foo_dir}/schema<br />
%define foo_rng_dir %{foo_schema_dir}/rng<br />
%define foo_nvdl_dir %{foo_schema_dir}/nvdl<br />
%define foo_sch_dir %{foo_schema_dir}/sch<br />
%define foo_xsd_dir %{foo_schema_dir}/xsd<br />
%define foo_version 2.0</pre><br />
</li><br />
<br />
<li>In your header, add another source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<br />
<li>Optionally add a <tt>%build</tt> section if you need to build your<br />
catalog first. See [https://build.opensuse.org/package/show/Documentation:Tools/its-schema its-schema] as an example.<br />
</li><br />
<br />
<li>Install the XML catalog in the <tt>%install</tt> section:<br />
<pre>%install<br />
mkdir -p %{buildroot}%{xml_catalogd_dir}<br />
# ...<br />
cp -vi %{SOURCE1} %{buildroot}%{xml_catalogd_dir}</pre><br />
If you have already Makefile, Shell script etc. this step can be reduced.<br />
To install schemas and other files, you need to extend this step (use the<br />
placeholders from step 3).<br />
</li><br />
<br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
Done!<br />
<br />
It's recommended to apply the <tt>spec-cleaner</tt> command (same package name)<br />
to your spec file to improve style and consistency.<br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=136728openSUSE:Packaging XML Schemas and Stylesheets2019-09-25T10:36:18Z<p>Thomas-schraitle: its -> foo</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependent (compare <tt>/usr/share/xml/</tt> with <tt>C:\Program\...</tt>)<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group></tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Create your Spec File ===<br />
<br />
To create a spec file, use the following steps:<br />
<br />
<ol><br />
<li>Start with the usual copyright notice:<br />
<pre>#<br />
# spec file for package foo-schema<br />
#<br />
# Copyright (c) 2019 SUSE LINUX GmbH, Nuernberg, Germany.<br />
#<br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owners, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
<br />
# Please submit bugfixes or comments via https://bugs.opensuse.org/<br />
#</pre><br />
</li><br />
<br />
<li>Add the minimum set of placeholders:<br />
<pre>%define xml_sysconf_dir %{_sysconfdir}/xml<br />
%define xml_catalogd_dir %{xml_sysconf_dir}/catalog.d</pre><br />
</li><br />
<br />
<li>Recommended, but optionally, define more placeholders. It makes things easier to change and more consistent. For example, if your package <tt>foo</tt> comes with a RELAX NG, Schematron, XSD, and/or NVDL schemas, you could define (leave out the things you do not need):<br />
<br />
<pre>%define foo_dir %{_datadir}/xml/foo<br />
%define foo_schema_dir %{foo_dir}/schema<br />
%define foo_rng_dir %{foo_schema_dir}/rng<br />
%define foo_nvdl_dir %{foo_schema_dir}/nvdl<br />
%define foo_sch_dir %{foo_schema_dir}/sch<br />
%define foo_xsd_dir %{foo_schema_dir}/xsd<br />
%define foo_version 2.0</pre><br />
</li><br />
<br />
<li>In your header, add another source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<br />
<li>Optionally add a <tt>%build</tt> section if you need to build your<br />
catalog first. See [https://build.opensuse.org/package/show/Documentation:Tools/its-schema its-schema] as an example.<br />
</li><br />
<br />
<li>Install the XML catalog in the <tt>%install</tt> section:<br />
<pre>%install<br />
mkdir -p %{buildroot}%{xml_catalogd_dir}<br />
# ...<br />
cp -vi %{SOURCE1} %{buildroot}%{xml_catalogd_dir}</pre><br />
If you have already Makefile, Shell script etc. this step can be reduced.<br />
To install schemas and other files, you need to extend this step (use the<br />
placeholders from step 3).<br />
</li><br />
<br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
Done!<br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=136726openSUSE:Packaging XML Schemas and Stylesheets2019-09-25T10:35:49Z<p>Thomas-schraitle: Add additional steps, make it more elaborate</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependent (compare <tt>/usr/share/xml/</tt> with <tt>C:\Program\...</tt>)<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group></tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Create your Spec File ===<br />
<br />
To create a spec file, use the following steps:<br />
<br />
<ol><br />
<li>Start with the usual copyright notice:<br />
<pre>#<br />
# spec file for package its-schema<br />
#<br />
# Copyright (c) 2019 SUSE LINUX GmbH, Nuernberg, Germany.<br />
#<br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owners, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
<br />
# Please submit bugfixes or comments via https://bugs.opensuse.org/<br />
#</pre><br />
</li><br />
<br />
<li>Add the minimum set of placeholders:<br />
<pre>%define xml_sysconf_dir %{_sysconfdir}/xml<br />
%define xml_catalogd_dir %{xml_sysconf_dir}/catalog.d</pre><br />
</li><br />
<br />
<li>Recommended, but optionally, define more placeholders. It makes things easier to change and more consistent. For example, if your package <tt>foo</tt> comes with a RELAX NG, Schematron, XSD, and/or NVDL schemas, you could define (leave out the things you do not need):<br />
<br />
<pre>%define foo_dir %{_datadir}/xml/foo<br />
%define foo_schema_dir %{foo_dir}/schema<br />
%define foo_rng_dir %{foo_schema_dir}/rng<br />
%define foo_nvdl_dir %{foo_schema_dir}/nvdl<br />
%define foo_sch_dir %{foo_schema_dir}/sch<br />
%define foo_xsd_dir %{foo_schema_dir}/xsd<br />
%define foo_version 2.0</pre><br />
</li><br />
<br />
<li>In your header, add another source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<br />
<li>Optionally add a <tt>%build</tt> section if you need to build your<br />
catalog first. See [https://build.opensuse.org/package/show/Documentation:Tools/its-schema its-schema] as an example.<br />
</li><br />
<br />
<li>Install the XML catalog in the <tt>%install</tt> section:<br />
<pre>%install<br />
mkdir -p %{buildroot}%{xml_catalogd_dir}<br />
# ...<br />
cp -vi %{SOURCE1} %{buildroot}%{xml_catalogd_dir}</pre><br />
If you have already Makefile, Shell script etc. this step can be reduced.<br />
To install schemas and other files, you need to extend this step (use the<br />
placeholders from step 3).<br />
</li><br />
<br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
Done!<br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=136724openSUSE:Packaging XML Schemas and Stylesheets2019-09-25T07:56:03Z<p>Thomas-schraitle: Mention optional %build section</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependent (compare <tt>/usr/share/xml/</tt> with <tt>C:\Program\...</tt>)<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group></tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><br />
<li>Add another source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<br />
<li>Optionally add a <tt>%build</tt> section if you need to build your<br />
catalog first. See [https://build.opensuse.org/package/show/Documentation:Tools/its-schema its-schema] as an example.<br />
</li><br />
<br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=136722openSUSE:Packaging XML Schemas and Stylesheets2019-09-25T07:50:19Z<p>Thomas-schraitle: Add missing ></p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependent (compare <tt>/usr/share/xml/</tt> with <tt>C:\Program\...</tt>)<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group></tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add another source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=136720openSUSE:Packaging XML Schemas and Stylesheets2019-09-25T07:48:10Z<p>Thomas-schraitle: Add examples of platform dependent paths</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependent (compare <tt>/usr/share/xml/</tt> with <tt>C:\Program\...</tt>)<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group</tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add another source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Patches_guidelines&diff=136718openSUSE:Packaging Patches guidelines2019-09-25T07:00:21Z<p>Thomas-schraitle: Mention "git format-patch"</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|Packagers deal with lots of packages, and lots of patches inside those packages. These need to be marked in the .spec files with a well-known format to be able to run automatic tools on them, in order to generate reports, patch counts and other interesting information. They also need to be named consistently.}}<br />
<br />
== Patch life cycle ==<br />
Patches need to be added to packages for various reasons and it is important that the life cycle of a patch is well-defined. This helps in preventing that patches get "lost" and nobody knows why and when it was removed. The life cycle is defined in these simple steps:<br />
* Patch added to the package<br />
* Patch is modified (functional/rebased)<br />
* Patch is disabled (but not deleted)<br />
* Patch removed from the package<br />
<br />
The middle stages of the patch life cycle are optional and not every patch will live through them.<br />
<br />
Any of those stages needs to be mentioned in the .changes file, including the file name of the patch. This is only for the benefit of human readers, so does not need to be in a strict machine-parseable format; here are some examples of the suggested format:<br />
* Add package-awesomeness.patch: Makes package awesome<br />
* Drop package-awesomeness.patch: Upstream made it even more awesome.<br />
* Disable package-awesomeness.patch: Testing if users can live without awesomeness<br />
* Rebase package-awesomeness.patch to apply to the new version.<br />
<br />
== Upstream policy ==<br />
For the purpose of defining the upstream policy, we can divide patches into two categories:<br />
* '''upstream''' - upstream probably will be interested in it<br />
* '''openSUSE/SLE specific''' - upstream won't be interested in it<br />
<br />
=== Policy for upstream patches ===<br />
If you want to add a patch that can be interesting for upstream, please note that this '''patch must always be sent upstream'''. This is the only way to ensure that our fixes will be integrated upstream and we can get rid of these patches within the next upstream release. A significant advantage is also that upstream can provide you with sanity checking and a valuable feedback regarding your patch.<br />
<br />
==== When to send the patch to upstream ====<br />
Usually, it's useful to contact upstream before you submit the patch to OBS. You save yourself from resubmitting the patch if upstream finds an error in it.<br />
Also, some of the package maintainers may request this "upstream first" policy before such patch is to be considered for inclusion in the OBS package. Usually, there should be a mention about "upstream first" policy in the specfile of those packages (e. g. SuSEfirewall).<br />
However, sometimes upstream is not active enough and sending them the patch after you submit it to OBS is the only reasonable way.<br />
<br />
==== How to find upstream ====<br />
You have to dig. A good start is to check 'Url' or 'Source' tags in the specfile and visit the upstream website. Then you have to find a way upstream prefers for sending patches. It could be e. g. mail, mailing list, Bugzilla, git, ...<br />
<br />
=== Policy for openSUSE/SLE specific patches ===<br />
Usually, we try to add patches that can be merged upstream. However, it can happen that our package is different from the upstream and a specific patch is the only solution. Then please note that every openSUSE/SLE specific '''patch should be documented properly''' with a justification why this specific fix is needed.<br />
<br />
== Patch markup (also called "Tagging patches") ==<br />
<br />
To facilitate the use of automatic tools (some day), and to help inform future packagers about the patch nature, the following categories for our patches exist:<br />
<br />
* Fixes: these are normal fixes and are divided into three categories:<br />
** Fixes for openSUSE-specific things, that upstream maintainers will not be interested in.<br />
** Fixes for SLE-specific things, that upstream maintainers will not be interested in and that are not needed in openSUSE.<br />
** Fixes for the upstream sources that should be upstreamed.<br />
* Features: new features added to the packages, also divided into three categories:<br />
** Features for openSUSE-specific things (switching the displaymanager via /etc/sysconfig, for instance) with no interest for upstream maintainers.<br />
** Features for SLE-specific things with no interest for upstream maintainers or openSUSE.<br />
** Features that should be upstreamed. Whenever we write this kind of new feature, it is important to coordinate with upstream maintainers. That way, we can develop something that will be accepted upstream without changes. Once a feature is finished, it is a lot of work to rework it to be acceptable to upstream maintainers. As such, it is better to know from the beginning exactly what upstream maintainers would expect.<br />
<br />
There are two competing standards for this.<br />
<br />
=== Type 1: minimal single-line comment in spec file ===<br />
<br />
The old format consists of a comment line above a Patch: line, containing the patch category (see above), a (redundant) copy of the filename, and the rest of the line is a free-format string. Since a single line does not leave much room for words or other metadata, check out Type&nbsp;2 below.<br />
<br />
Type 1 format example:<br />
<br />
# PATCH-FIX-OPENSUSE fix-for-opensuse-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch1: fix-for-opensuse-specific-things.patch<br />
# PATCH-FIX-SLE fix-for-sle-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch2: fix-for-sle-specific-things.patch<br />
# PATCH-FIX-UPSTREAM fix-for-upstream-sources.patch bnc#<VAR >123456</VAR ><br />
Patch3: fix-for-upstream-sources.patch<br />
# PATCH-FEATURE-OPENSUSE feature-for-opensuse-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch4: feature-for-opensuse-specific-things.patch<br />
# PATCH-FEATURE-SLE feature-for-sle-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch5: feature-for-sle-specific-things.patch<br />
# PATCH-FEATURE-UPSTREAM feature-for-upstream.patch bnc#<VAR >123456</VAR ><br />
Patch6: feature-for-upstream.patch<br />
<br />
Special case: we often have patches that get commented out temporarily because they failed to apply to the latest sources, and the patches need to be rebased. Do not comment out the patch's declaration, but do comment out its application. When marking a patch as needing a rebase, it is a good idea to preserve its old tag.<br />
<br />
# PATCH-NEEDS-REBASE old-patch.patch bnc#<VAR >123456</VAR > -- Does something old. Was: PATCH-FEATURE-OPENSUSE<br />
Patch7: old-patch.patch<br />
[...]<br />
# %patch7<br />
<br />
Finally, we include e-mail addresses so that it will be easier to figure out who wrote a patch if we have questions later, and free-form comments after " -- ".<br />
<br />
That is:<br />
# PATCH-{FIX|FEATURE}-{OPENSUSE|SLE|UPSTREAM} ''name-of-file.patch'' bnc#<VAR >[0-9]+</VAR > <VAR >you</VAR >@<VAR >example.com</VAR > -- ''this patch makes things totally awesome''<br />
If there are related bugs in [http://bugzilla.novell.com Novell] or other bugzillas, please add them, it will help us to get more accurate information. If there are two or more available then it's preferable to list both (or more).<br />
<br />
In general, the bugzilla field is not required on new patches. For patches to released packages that will go out as updates, a bugzilla entry (BNC#) for the overall update in the changes file is required. If appropriate, the patch description should also include it.<br />
<br />
The primary use case of the patch field should be references to<br />
'''upstream''' bug trackers in case of PATCH-*-UPSTREAM patches, such<br />
patches should be submitted upstream first and then referenced in the<br />
patch tag. That helps a lot to keep track of patches, it makes it easy to<br />
determine which patches are still needed on version updates if<br />
upstream references the bug numbers in their changelog or release<br />
notes. Of course if there is already a corresponding bnc# bug<br />
open it should be referenced as well.<br />
<br />
You can find the current set of abbreviations at the end of this document. We can also define more abbreviations later if and when they prove necessary.<br />
<br />
Some patches fix bugs that are not explicitly recorded anywhere. The right thing to do in this case requires some judgment on the part of the packager, but here are some ideas:<br />
<br />
* If a release is imminent, create a bug for it. This is usually a requirement, and even if it were not, it is still the right thing to do.<br />
* If a release is a long way off and the bug has already been fixed upstream, note in the comment that it is already fixed in the <ABBR >SVN</ABBR > (or wherever) and the patch will go away when we next upgrade.<br />
<br />
=== Type 2: Complete Information provided in patch ===<br />
<br />
The Type 1 standard lacks the most important part of a patch: a useful description why it is needed or desired in the first place, its single line format is seldomly enough to convey all the desirable information, and the state of the patch (upstream or opensuse-specific, fix or feature, etc.) is cut off from the actual patch.<br />
<br />
The patches in the openSUSE kernel packages have traditionally used a form of tagging where metadata is directly attached to where it is needed — in the patch file itself. This facilitates submission of patches to upstream, as the description cannot be accidentally omitted, and the Git SCM (where used) knows to retain the metadata on import. Conversely, extraction of patches from Git repos also yields single files.<br />
<br />
Patch files are to follow a scheme of "<tt>key: value</tt>" pairs and a description, optionally with a diffstat, prepended to the actual hunks. Example.<br />
<br />
From: Random J Developer <email@example.org><br />
Date: 2012-07-28 01:28:22 +0200<br />
Subject: input: add Acer Aspire 5710 to nomux blacklist<br />
References: bnc#404881<br />
Upstream: submitted<br />
<br />
Acer Aspire needs to be added to nomux blacklist, otherwise the touchpad misbehaves.<br />
<br />
---<br />
drivers/input/serio/i8042-x86ia64io.h | 7 +++++++<br />
1 file changed, 7 insertions(+)<br />
<br />
--- a/drivers/input/serio/i8042-x86ia64io.h<br />
+++ b/drivers/input/serio/i8042-x86ia64io.h<br />
@@ -371,6 +371,13 @@ static const struct dmi_system_id __init<br />
[...]<br />
<br />
Use <tt>git format-patch -1</tt> to get the patch file for the last commit. You need to add the missing keys (Subject, References, Upstream) manually.<br />
<br />
It is advised to use e.g. Quilt which retains descriptions on refresh. <tt>quilt ref --sort --diffstat -p1</tt> creates/refreshes such patches, sorted, with a diffstat and in the wanted -p1 format.<br/><br />
Common fields encountered:<br />
<br />
* '''From:''' shall specify the e-mail address of the original author of the patch.<br />
* '''Date:''' when this patch was first created. Preferably an ISO-8601 timestamp with timezone. If a new patch was just created and has none, you can use `<tt>stat your.patch</tt>` to determine a timestamp.<br />
* '''References:''' links to mailing list posts, bugzillas, etc. No fixed format, though URLs are preferred for they are easy to copy&paste into the browser. See the below section “[[#Current set of abbreviations]]” for details.<br />
* '''Upstream:''' the disposition of the patch. No fixed format, though common options are “never”/“no” (openSUSE-specific), “to be done” (tbd), “sent”/“submitted” (sent to upstream developers; provide Reference if possible), “merged” (upstream has accepted it; provide Reference if possible) and “dead” (no activity in upstream project).<br />
* '''Subject:''' A short one-line summary of the patch.<br />
<br />
'''Patches are to provide a description.''' The description shall describe _why_ it is needed. Be as thorough as you like, because it will influence the decision what a different developer should do with the patch should it not apply anymore. The three questions “what command did you execute?”, “what did you observe?”, “what did you expect to see instead?” can give some guidance. If a related error message is available, e.g. when creating a patch to fix a syntactical error in a source file that causes the compilation to abort, it should be included, trimmed to the important parts. Furthermore, a summary on the how the solution is implemented can help readers grok larger patches.<br />
<br />
Reading material (from the mailing lists) that shows the need for this kind of tagging: [http://lists.opensuse.org/opensuse-factory/2012-08/msg00683.html (1)] [http://lists.opensuse.org/opensuse-factory/2012-08/msg00719.html (2)] [http://lists.opensuse.org/opensuse-factory/2012-08/msg00749.html (3)]<br />
<br />
== Patch naming ==<br />
<br />
All new patches should end with the extension '.patch'.<br />
<br />
Whether a patch's name should start with the name of the package it applies to is a matter of debate or style. When in doubt, follow the convention used in the package you are hacking on.<br />
<br />
Do '''NOT''' use <code>%{version}</code> macro in <code>Patch:</code> line, specify the version by hand. Using the macro:<br />
* causes lots of renames on version update<br />
* makes it easy to overlook patches that are no longer needed<br />
* makes it hard to determine when the patch was touch for the last time<br />
* makes it easy to find out when the patch broke (package archaelogy)<br />
<br />
An exception to this exists: patches that fix warnings that the compiler emits due to bogus code are frequently named <tt>abuild.patch</tt>.<br />
<br />
The preferred patchlevel is <tt>-p1</tt> as it makes importing using tools like ''quilt'' more straightforward.<br />
<br />
----<br />
== Current set of abbreviations ==<br />
To avoid confusion and double burden, referencing to other issue trackers is allowed. Here are some shortcuts for often used issue trackers, which should be added before the "#" of the issue id. Note there is no whitespace between the shortcut and the issue id.<br />
<br />
NOTE: this list is not authoritative, please check with the Open Build Service how they are defined there (osc api /issue_trackers). You can also request new trackers via the [https://github.com/openSUSE/open-build-service OBS github project].<br />
<br />
{| border="1" <br />
!Shortcut<br />
!Issue-Tracker-URL<br />
!Example<br />
|-<br />
| '''openSUSE Bug tracker'''<br />
| http://bugzilla.opensuse.org/show_bug.cgi?id=123456<br />
| (boo#123456)<br />
|-<br />
| Boost<br />
| https://svn.boost.org/trac/boost/<br />
| (boost#123456)<br />
|-<br />
| Clutter Project Bugzilla<br />
| http://bugzilla.clutter-project.org/<br />
| (bco#123)<br />
|-<br />
| CPAN Public Bug Tracker<br />
| http://rt.cpan.org/Public/<br />
| (RT#123456)<br />
|-<br />
| Debian<br />
| http://bugs.debian.org/<br />
| (deb#123456)<br />
|-<br />
| freedesktop.org<br />
| http://bugs.freedesktop.org/<br />
| (fdo#123456)<br />
|-<br />
| GCC<br />
| http://gcc.gnu.org/bugzilla/<br />
| (GCC#123456)<br />
|-<br />
| GNOME<br />
| http://bugzilla.gnome.org/<br />
| (bgo#123456)<br />
|-<br />
| ICCULUS<br />
| http://bugzilla.icculus.org/<br />
| (bio#123456)<br />
|-<br />
| Kernel or K<br />
| http://bugzilla.kernel.org/<br />
| (bko#123456)<br />
|-<br />
| KDE <br />
| http://bugs.kde.org/<br />
| (kde#123456)<br />
|-<br />
| Launchpad (Ubuntu)<br />
| https://bugs.launchpad.net/<br />
| (lp#123456)<br />
|-<br />
| MeeGo<br />
| http://bugs.meego.com<br />
| (MeeGo#123456)<br />
|-<br />
| Mozilla<br />
| http://bugzilla.mozilla.org/<br />
| (bmo#123456)<br />
|-<br />
| Novell<br />
| https://bugzilla.novell.com/<br />
| (bnc#123456)<br />
|-<br />
| SUSE bugs<br />
| https://bugzilla.suse.com/<br />
| (bsc#123456)<br />
|-<br />
| OpenLDAP<br />
| http://www.openldap.org/its/<br />
| (ITS#123456)<br />
|-<br />
| OpenOffice.org Issuezilla (obsolete)<br />
| http://qa.openoffice.org/issues/<br />
| (i#123456)<br />
|-<br />
| Fate (Feature tracking tool)<br />
| https://features.opensuse.org/ | https://fate.suse.com<br />
| (fate#123456)<br />
|-<br />
| RedHat<br />
| https://bugzilla.redhat.com/<br />
| (rh#123456)<br />
|-<br />
| Samba<br />
| https://bugzilla.samba.org/<br />
| (bso#123456)<br />
|-<br />
| Sourceforge<br />
| http://sf.net/support/tracker.php?aid=1234567<br />
| (sf#1234567); number is in the "aid=" part in an URL<br />
|-<br />
| Xamarin<br />
| http://bugzilla.xamarin.com/<br />
| (bxc#4321)<br />
|-<br />
| CVE entries (please add the number, even if there is an additional bugzilla for it)<br />
| http://cve.mitre.org<br />
| (CVE-2009-0067)<br />
|-<br />
| Xfce<br />
| https://bugzilla.xfce.org/<br />
| (bxo#123456)<br />
|-<br />
| OBS GitHub Issues<br />
| https://api.github.com/repos/openSUSE/open-build-service/issues<br />
| (obs#123)<br />
|-<br />
| OBS build script Issues<br />
| https://api.github.com/repos/openSUSE/obs-build/issues<br />
| (build#123)<br />
|-<br />
| OBS CLI Issues<br />
| https://api.github.com/repos/openSUSE/osc/issues<br />
| (osc#123)<br />
|-<br />
| Progress openSUSE issue<br />
| https://progress.opensuse.org/issues<br />
| (poo#123)<br />
|-<br />
| Linux Foundation<br />
| https://developerbugs.linux-foundation.org/<br />
| (lf#1234)<br />
|-<br />
| SUSE SLE features<br />
| https://jira.suse.com/ | https://jira.suse.de<br />
| (jsc#SLE-1234)<br />
|}<br />
<br />
For other issue ids, please use the full URL to the coresponding issue tracker at the beginning of the patch file. For example:<br />
* http://developer.berlios.de/bugs/?func=detailbug&bug_id=12707&group_id=769<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Paketbau Richtlinien für Patches]]<br />
[[el:openSUSE:Packaging Patches guidelines]]<br />
[[ja:openSUSE:パッケージング修正ガイドライン]]<br />
[[ru:openSUSE:Руководство по оформлению патчей]]<br />
[[zh:openSUSE:Packaging_Patches_guidelines]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Patches_guidelines&diff=136716openSUSE:Packaging Patches guidelines2019-09-25T06:54:17Z<p>Thomas-schraitle: Remove useless backticks around quilt</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|Packagers deal with lots of packages, and lots of patches inside those packages. These need to be marked in the .spec files with a well-known format to be able to run automatic tools on them, in order to generate reports, patch counts and other interesting information. They also need to be named consistently.}}<br />
<br />
== Patch life cycle ==<br />
Patches need to be added to packages for various reasons and it is important that the life cycle of a patch is well-defined. This helps in preventing that patches get "lost" and nobody knows why and when it was removed. The life cycle is defined in these simple steps:<br />
* Patch added to the package<br />
* Patch is modified (functional/rebased)<br />
* Patch is disabled (but not deleted)<br />
* Patch removed from the package<br />
<br />
The middle stages of the patch life cycle are optional and not every patch will live through them.<br />
<br />
Any of those stages needs to be mentioned in the .changes file, including the file name of the patch. This is only for the benefit of human readers, so does not need to be in a strict machine-parseable format; here are some examples of the suggested format:<br />
* Add package-awesomeness.patch: Makes package awesome<br />
* Drop package-awesomeness.patch: Upstream made it even more awesome.<br />
* Disable package-awesomeness.patch: Testing if users can live without awesomeness<br />
* Rebase package-awesomeness.patch to apply to the new version.<br />
<br />
== Upstream policy ==<br />
For the purpose of defining the upstream policy, we can divide patches into two categories:<br />
* '''upstream''' - upstream probably will be interested in it<br />
* '''openSUSE/SLE specific''' - upstream won't be interested in it<br />
<br />
=== Policy for upstream patches ===<br />
If you want to add a patch that can be interesting for upstream, please note that this '''patch must always be sent upstream'''. This is the only way to ensure that our fixes will be integrated upstream and we can get rid of these patches within the next upstream release. A significant advantage is also that upstream can provide you with sanity checking and a valuable feedback regarding your patch.<br />
<br />
==== When to send the patch to upstream ====<br />
Usually, it's useful to contact upstream before you submit the patch to OBS. You save yourself from resubmitting the patch if upstream finds an error in it.<br />
Also, some of the package maintainers may request this "upstream first" policy before such patch is to be considered for inclusion in the OBS package. Usually, there should be a mention about "upstream first" policy in the specfile of those packages (e. g. SuSEfirewall).<br />
However, sometimes upstream is not active enough and sending them the patch after you submit it to OBS is the only reasonable way.<br />
<br />
==== How to find upstream ====<br />
You have to dig. A good start is to check 'Url' or 'Source' tags in the specfile and visit the upstream website. Then you have to find a way upstream prefers for sending patches. It could be e. g. mail, mailing list, Bugzilla, git, ...<br />
<br />
=== Policy for openSUSE/SLE specific patches ===<br />
Usually, we try to add patches that can be merged upstream. However, it can happen that our package is different from the upstream and a specific patch is the only solution. Then please note that every openSUSE/SLE specific '''patch should be documented properly''' with a justification why this specific fix is needed.<br />
<br />
== Patch markup (also called "Tagging patches") ==<br />
<br />
To facilitate the use of automatic tools (some day), and to help inform future packagers about the patch nature, the following categories for our patches exist:<br />
<br />
* Fixes: these are normal fixes and are divided into three categories:<br />
** Fixes for openSUSE-specific things, that upstream maintainers will not be interested in.<br />
** Fixes for SLE-specific things, that upstream maintainers will not be interested in and that are not needed in openSUSE.<br />
** Fixes for the upstream sources that should be upstreamed.<br />
* Features: new features added to the packages, also divided into three categories:<br />
** Features for openSUSE-specific things (switching the displaymanager via /etc/sysconfig, for instance) with no interest for upstream maintainers.<br />
** Features for SLE-specific things with no interest for upstream maintainers or openSUSE.<br />
** Features that should be upstreamed. Whenever we write this kind of new feature, it is important to coordinate with upstream maintainers. That way, we can develop something that will be accepted upstream without changes. Once a feature is finished, it is a lot of work to rework it to be acceptable to upstream maintainers. As such, it is better to know from the beginning exactly what upstream maintainers would expect.<br />
<br />
There are two competing standards for this.<br />
<br />
=== Type 1: minimal single-line comment in spec file ===<br />
<br />
The old format consists of a comment line above a Patch: line, containing the patch category (see above), a (redundant) copy of the filename, and the rest of the line is a free-format string. Since a single line does not leave much room for words or other metadata, check out Type&nbsp;2 below.<br />
<br />
Type 1 format example:<br />
<br />
# PATCH-FIX-OPENSUSE fix-for-opensuse-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch1: fix-for-opensuse-specific-things.patch<br />
# PATCH-FIX-SLE fix-for-sle-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch2: fix-for-sle-specific-things.patch<br />
# PATCH-FIX-UPSTREAM fix-for-upstream-sources.patch bnc#<VAR >123456</VAR ><br />
Patch3: fix-for-upstream-sources.patch<br />
# PATCH-FEATURE-OPENSUSE feature-for-opensuse-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch4: feature-for-opensuse-specific-things.patch<br />
# PATCH-FEATURE-SLE feature-for-sle-specific-things.patch bnc#<VAR >123456</VAR ><br />
Patch5: feature-for-sle-specific-things.patch<br />
# PATCH-FEATURE-UPSTREAM feature-for-upstream.patch bnc#<VAR >123456</VAR ><br />
Patch6: feature-for-upstream.patch<br />
<br />
Special case: we often have patches that get commented out temporarily because they failed to apply to the latest sources, and the patches need to be rebased. Do not comment out the patch's declaration, but do comment out its application. When marking a patch as needing a rebase, it is a good idea to preserve its old tag.<br />
<br />
# PATCH-NEEDS-REBASE old-patch.patch bnc#<VAR >123456</VAR > -- Does something old. Was: PATCH-FEATURE-OPENSUSE<br />
Patch7: old-patch.patch<br />
[...]<br />
# %patch7<br />
<br />
Finally, we include e-mail addresses so that it will be easier to figure out who wrote a patch if we have questions later, and free-form comments after " -- ".<br />
<br />
That is:<br />
# PATCH-{FIX|FEATURE}-{OPENSUSE|SLE|UPSTREAM} ''name-of-file.patch'' bnc#<VAR >[0-9]+</VAR > <VAR >you</VAR >@<VAR >example.com</VAR > -- ''this patch makes things totally awesome''<br />
If there are related bugs in [http://bugzilla.novell.com Novell] or other bugzillas, please add them, it will help us to get more accurate information. If there are two or more available then it's preferable to list both (or more).<br />
<br />
In general, the bugzilla field is not required on new patches. For patches to released packages that will go out as updates, a bugzilla entry (BNC#) for the overall update in the changes file is required. If appropriate, the patch description should also include it.<br />
<br />
The primary use case of the patch field should be references to<br />
'''upstream''' bug trackers in case of PATCH-*-UPSTREAM patches, such<br />
patches should be submitted upstream first and then referenced in the<br />
patch tag. That helps a lot to keep track of patches, it makes it easy to<br />
determine which patches are still needed on version updates if<br />
upstream references the bug numbers in their changelog or release<br />
notes. Of course if there is already a corresponding bnc# bug<br />
open it should be referenced as well.<br />
<br />
You can find the current set of abbreviations at the end of this document. We can also define more abbreviations later if and when they prove necessary.<br />
<br />
Some patches fix bugs that are not explicitly recorded anywhere. The right thing to do in this case requires some judgment on the part of the packager, but here are some ideas:<br />
<br />
* If a release is imminent, create a bug for it. This is usually a requirement, and even if it were not, it is still the right thing to do.<br />
* If a release is a long way off and the bug has already been fixed upstream, note in the comment that it is already fixed in the <ABBR >SVN</ABBR > (or wherever) and the patch will go away when we next upgrade.<br />
<br />
=== Type 2: Complete Information provided in patch ===<br />
<br />
The Type 1 standard lacks the most important part of a patch: a useful description why it is needed or desired in the first place, its single line format is seldomly enough to convey all the desirable information, and the state of the patch (upstream or opensuse-specific, fix or feature, etc.) is cut off from the actual patch.<br />
<br />
The patches in the openSUSE kernel packages have traditionally used a form of tagging where metadata is directly attached to where it is needed — in the patch file itself. This facilitates submission of patches to upstream, as the description cannot be accidentally omitted, and the Git SCM (where used) knows to retain the metadata on import. Conversely, extraction of patches from Git repos also yields single files.<br />
<br />
Patch files are to follow a scheme of "<tt>key: value</tt>" pairs and a description, optionally with a diffstat, prepended to the actual hunks. Example.<br />
<br />
From: Random J Developer <email@example.org><br />
Date: 2012-07-28 01:28:22 +0200<br />
Subject: input: add Acer Aspire 5710 to nomux blacklist<br />
References: bnc#404881<br />
Upstream: submitted<br />
<br />
Acer Aspire needs to be added to nomux blacklist, otherwise the touchpad misbehaves.<br />
<br />
---<br />
drivers/input/serio/i8042-x86ia64io.h | 7 +++++++<br />
1 file changed, 7 insertions(+)<br />
<br />
--- a/drivers/input/serio/i8042-x86ia64io.h<br />
+++ b/drivers/input/serio/i8042-x86ia64io.h<br />
@@ -371,6 +371,13 @@ static const struct dmi_system_id __init<br />
[...]<br />
<br />
It is advised to use e.g. Quilt which retains descriptions on refresh. <tt>quilt ref --sort --diffstat -p1</tt> creates/refreshes such patches, sorted, with a diffstat and in the wanted -p1 format.<br/><br />
Common fields encountered:<br />
<br />
* '''From:''' shall specify the e-mail address of the original author of the patch.<br />
* '''Date:''' when this patch was first created. Preferably an ISO-8601 timestamp with timezone. If a new patch was just created and has none, you can use `<tt>stat your.patch</tt>` to determine a timestamp.<br />
* '''References:''' links to mailing list posts, bugzillas, etc. No fixed format, though URLs are preferred for they are easy to copy&paste into the browser. See the below section “[[#Current set of abbreviations]]” for details.<br />
* '''Upstream:''' the disposition of the patch. No fixed format, though common options are “never”/“no” (openSUSE-specific), “to be done” (tbd), “sent”/“submitted” (sent to upstream developers; provide Reference if possible), “merged” (upstream has accepted it; provide Reference if possible) and “dead” (no activity in upstream project).<br />
* '''Subject:''' A short one-line summary of the patch.<br />
<br />
'''Patches are to provide a description.''' The description shall describe _why_ it is needed. Be as thorough as you like, because it will influence the decision what a different developer should do with the patch should it not apply anymore. The three questions “what command did you execute?”, “what did you observe?”, “what did you expect to see instead?” can give some guidance. If a related error message is available, e.g. when creating a patch to fix a syntactical error in a source file that causes the compilation to abort, it should be included, trimmed to the important parts. Furthermore, a summary on the how the solution is implemented can help readers grok larger patches.<br />
<br />
Reading material (from the mailing lists) that shows the need for this kind of tagging: [http://lists.opensuse.org/opensuse-factory/2012-08/msg00683.html (1)] [http://lists.opensuse.org/opensuse-factory/2012-08/msg00719.html (2)] [http://lists.opensuse.org/opensuse-factory/2012-08/msg00749.html (3)]<br />
<br />
== Patch naming ==<br />
<br />
All new patches should end with the extension '.patch'.<br />
<br />
Whether a patch's name should start with the name of the package it applies to is a matter of debate or style. When in doubt, follow the convention used in the package you are hacking on.<br />
<br />
Do '''NOT''' use <code>%{version}</code> macro in <code>Patch:</code> line, specify the version by hand. Using the macro:<br />
* causes lots of renames on version update<br />
* makes it easy to overlook patches that are no longer needed<br />
* makes it hard to determine when the patch was touch for the last time<br />
* makes it easy to find out when the patch broke (package archaelogy)<br />
<br />
An exception to this exists: patches that fix warnings that the compiler emits due to bogus code are frequently named <tt>abuild.patch</tt>.<br />
<br />
The preferred patchlevel is <tt>-p1</tt> as it makes importing using tools like ''quilt'' more straightforward.<br />
<br />
----<br />
== Current set of abbreviations ==<br />
To avoid confusion and double burden, referencing to other issue trackers is allowed. Here are some shortcuts for often used issue trackers, which should be added before the "#" of the issue id. Note there is no whitespace between the shortcut and the issue id.<br />
<br />
NOTE: this list is not authoritative, please check with the Open Build Service how they are defined there (osc api /issue_trackers). You can also request new trackers via the [https://github.com/openSUSE/open-build-service OBS github project].<br />
<br />
{| border="1" <br />
!Shortcut<br />
!Issue-Tracker-URL<br />
!Example<br />
|-<br />
| '''openSUSE Bug tracker'''<br />
| http://bugzilla.opensuse.org/show_bug.cgi?id=123456<br />
| (boo#123456)<br />
|-<br />
| Boost<br />
| https://svn.boost.org/trac/boost/<br />
| (boost#123456)<br />
|-<br />
| Clutter Project Bugzilla<br />
| http://bugzilla.clutter-project.org/<br />
| (bco#123)<br />
|-<br />
| CPAN Public Bug Tracker<br />
| http://rt.cpan.org/Public/<br />
| (RT#123456)<br />
|-<br />
| Debian<br />
| http://bugs.debian.org/<br />
| (deb#123456)<br />
|-<br />
| freedesktop.org<br />
| http://bugs.freedesktop.org/<br />
| (fdo#123456)<br />
|-<br />
| GCC<br />
| http://gcc.gnu.org/bugzilla/<br />
| (GCC#123456)<br />
|-<br />
| GNOME<br />
| http://bugzilla.gnome.org/<br />
| (bgo#123456)<br />
|-<br />
| ICCULUS<br />
| http://bugzilla.icculus.org/<br />
| (bio#123456)<br />
|-<br />
| Kernel or K<br />
| http://bugzilla.kernel.org/<br />
| (bko#123456)<br />
|-<br />
| KDE <br />
| http://bugs.kde.org/<br />
| (kde#123456)<br />
|-<br />
| Launchpad (Ubuntu)<br />
| https://bugs.launchpad.net/<br />
| (lp#123456)<br />
|-<br />
| MeeGo<br />
| http://bugs.meego.com<br />
| (MeeGo#123456)<br />
|-<br />
| Mozilla<br />
| http://bugzilla.mozilla.org/<br />
| (bmo#123456)<br />
|-<br />
| Novell<br />
| https://bugzilla.novell.com/<br />
| (bnc#123456)<br />
|-<br />
| SUSE bugs<br />
| https://bugzilla.suse.com/<br />
| (bsc#123456)<br />
|-<br />
| OpenLDAP<br />
| http://www.openldap.org/its/<br />
| (ITS#123456)<br />
|-<br />
| OpenOffice.org Issuezilla (obsolete)<br />
| http://qa.openoffice.org/issues/<br />
| (i#123456)<br />
|-<br />
| Fate (Feature tracking tool)<br />
| https://features.opensuse.org/ | https://fate.suse.com<br />
| (fate#123456)<br />
|-<br />
| RedHat<br />
| https://bugzilla.redhat.com/<br />
| (rh#123456)<br />
|-<br />
| Samba<br />
| https://bugzilla.samba.org/<br />
| (bso#123456)<br />
|-<br />
| Sourceforge<br />
| http://sf.net/support/tracker.php?aid=1234567<br />
| (sf#1234567); number is in the "aid=" part in an URL<br />
|-<br />
| Xamarin<br />
| http://bugzilla.xamarin.com/<br />
| (bxc#4321)<br />
|-<br />
| CVE entries (please add the number, even if there is an additional bugzilla for it)<br />
| http://cve.mitre.org<br />
| (CVE-2009-0067)<br />
|-<br />
| Xfce<br />
| https://bugzilla.xfce.org/<br />
| (bxo#123456)<br />
|-<br />
| OBS GitHub Issues<br />
| https://api.github.com/repos/openSUSE/open-build-service/issues<br />
| (obs#123)<br />
|-<br />
| OBS build script Issues<br />
| https://api.github.com/repos/openSUSE/obs-build/issues<br />
| (build#123)<br />
|-<br />
| OBS CLI Issues<br />
| https://api.github.com/repos/openSUSE/osc/issues<br />
| (osc#123)<br />
|-<br />
| Progress openSUSE issue<br />
| https://progress.opensuse.org/issues<br />
| (poo#123)<br />
|-<br />
| Linux Foundation<br />
| https://developerbugs.linux-foundation.org/<br />
| (lf#1234)<br />
|-<br />
| SUSE SLE features<br />
| https://jira.suse.com/ | https://jira.suse.de<br />
| (jsc#SLE-1234)<br />
|}<br />
<br />
For other issue ids, please use the full URL to the coresponding issue tracker at the beginning of the patch file. For example:<br />
* http://developer.berlios.de/bugs/?func=detailbug&bug_id=12707&group_id=769<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Paketbau Richtlinien für Patches]]<br />
[[el:openSUSE:Packaging Patches guidelines]]<br />
[[ja:openSUSE:パッケージング修正ガイドライン]]<br />
[[ru:openSUSE:Руководство по оформлению патчей]]<br />
[[zh:openSUSE:Packaging_Patches_guidelines]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=User:Thomas-schraitle&diff=136714User:Thomas-schraitle2019-09-25T06:51:08Z<p>Thomas-schraitle: Amend RELAX NG and photos</p>
<hr />
<div>Since 2000 I am an writer and wanna-be-developer at SUSE and in charge of XML related topics around our books (RELAX NG/DTD, stylesheets and the like.) I've also attacked the layout in LaTeX from 7.0 till 9.x and was involved into the 10.x release too. From time to time I write scripts in my favorite language Python.<br />
<br />
When I don't write books I enjoy to read them, listen to various music or visit friends and interesting places to shoot photos.<br />
<br />
See my [http://lizards.opensuse.org/author/thomas-schraitle/ technical musings] at the Lizard side, or go to [https://www.xing.com/profile/Thomas_Schraitle Xing] or [http://de.linkedin.com/in/tomschr LinkedIn].</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Python&diff=131020openSUSE:Packaging Python2018-12-30T12:07:18Z<p>Thomas-schraitle: Add code tags to make macros more readable</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging Python''' is a step by step introduction on how to build Python software packages for openSUSE and others using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== The fast and automated way ==<br />
<br />
Lets suppose you want to package zope.interface and you don't know how it is named exactly or where to download from. First of all, you can search for it with [https://github.com/openSUSE/py2pack py2pack], which can be found in the [https://software.opensuse.org/package/python-py2pack python-py2pack] package and download the source tarball automatically with it if you found the correct module:<br />
<br />
$ py2pack search zope.interface<br />
searching for module zope.interface...<br />
found zope.interface-3.6.1<br />
<br />
$ py2pack fetch zope.interface<br />
downloading package zope.interface-3.6.1...<br />
from http://pypi.python.org/packages/source/z/zope.interface/zope.interface-3.6.1.tar.gz<br />
<br />
As a next step you may want to generate a package recipe for your distribution. For RPM-based distributions, you want to generate a spec file named python-zopeinterface.spec:<br />
<br />
$ py2pack generate zope.interface -f python-zope.interface.spec<br />
<br />
The source tarball and package recipe is all you need to generate the RPM file. This final step may depend on which distribution you use. Again, for openSUSE (and by using the openSUSE Build Service), the complete recipe becomes:<br />
<br />
$ osc mkpac python-zope.interface<br />
$ cd python-zope.interface<br />
$ py2pack fetch zope.interface<br />
$ py2pack generate zope.interface -f python-zope.interface.spec<br />
$ vi *.spec<br />
BuildRequires: python-setuptools<br />
ZZ<br />
$ osc build<br />
$ osc vc<br />
$ osc add *<br />
$ osc commit<br />
<br />
The first line uses osc, the Build Service command line tool to generate a new package (preferrably in your Build Service home project). The py2pack steps are known already.<br />
<br />
It is always a good idea to review all the dependencies specified in the spec file accordingly to upstream manifest and requirements. Ie. dropping devel dependency in a case where package does not compile anything or adding python-setuptools if needed.<br />
Finally, the package is tested (built locally), a changes (package changelog) file is generated (with ‘osc vc’) and the result is sent back to the Build Service for public consumption. However, depending on the Python module, you may have to adapt the generated spec file slightly. Py2pack is quite clever and tries to auto-generate as much as it can, but it depends on the metadata that the module provides. Thus, bad metadata implies mediocre results. To get further help about py2pack usage, issue the following command:<br />
<br />
$ py2pack help<br />
<br />
Often, the first run of 'osc build' will fail with build error messages, due to missing python modules. Look for the keyword 'import', this should give you a hint, what needs to be added to the 'BuildRequires:' of you spec-file.<br />
<br />
----<br />
<br />
== Hints on how to package Python modules manually ==<br />
<br />
Manual packaging is discouraged since we have tools to do that. If you insist on having fun, please consider any package spec file in [https://build.opensuse.org/project/show/devel:languages:python devel:languages:python]. [https://build.opensuse.org/package/show/devel:languages:python/python-pbr python-pbr], [https://build.opensuse.org/package/show/devel:languages:python/python-mock python-mock] or [https://build.opensuse.org/package/show/devel:languages:python/python-Twisted python-Twisted] are few examples.<br />
<br />
In general we are using python single-spec packaging.<br />
<br />
=== What is single-spec? ===<br />
<br />
'Single-spec' (or 'Singlespec') is an approach for packaging both python2 and python3 variants of a Python module from a single source spec file.<br />
<br />
=== Compatibility shims ===<br />
If your packages are targeted for anything other than Leap 15 or newer, the spec file must include two things:<br />
<br />
<ul><br />
<li><p>Redefinition of <code>%python_module</code> macro.</p><br />
<pre>%{?!python_module:%define python_module() python-%{**} python3-%{**}}</pre></li><br />
<li><p>Build requirement on <code>python-rpm-macros</code>:</p><br />
<pre>BuildRequires: python-rpm-macros</pre></li></ul><br />
-----<br />
<br />
=== Naming policy ===<br />
<br />
SUSE has a policy for names of Python module packages. A ''module'' is to Python what shared libraries are to C - a piece of code that doesn't work by itself, but provides functionality to other Python programs.<br />
<br />
All Python module packages, whether pure Python or C-based, should be called '''python-'''modulename. '''modulename''' should be the name of this module on the [https://pypi.org/ Python Package Index].<br />
<br />
Previously, Python packages have been named after directories in the <tt>site-packages</tt> hierarchy. Often, this was an arbitrary choice, several modules install more than one directory there. Also, the Python universe includes modules that share the same directory name (search for "daemon" on PyPI) and it was not always easy to find out the right package name. Furthermore, the new approach has several advantages:<br />
<br />
* Scripts (like py2pack) know where to fetch metadata and (new) release tarballs, PyPI has a stable API<br />
* Package names match [http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies install_required, etc. in setup.py files] and [http://www.pip-installer.org/en/latest/requirements.html pip requirements files] making it easy to find out (Build)Requires in your RPM specs<br />
* Users know where to look for API or usage documentation: http://pypi.python.org/pypi/$PYPYNAME<br />
<br />
This policy doesn't apply to end-user applications that are not designed and planned to be used as libraries - so if you're packaging something that is going to have an icon in the application menu, you should just call the package by its normal name (as found on the [https://pypi.org/ Python Package Index]).<br />
<br />
There are some corner cases as to what is an application and what is a module - for example, many modules come with simple command-line tools that allow you to use a subset of their functionality directly. The rule of thumb is this: if this package is going to be a dependency of some other Python application, apply the naming policy, otherwise keep it just as the module name.<br />
<br />
=== Source URLs ===<br />
<br />
For packages that are available from [https://pypi.org/ PyPI], the correct Source URL is the following:<br />
<br />
'''https://files.pythonhosted.org/packages/source/t/tox-%{version}.tar.gz'''<br />
<br />
The preferred hostname is '''files.pythonhosted.org'''. All other hostnames (like pypi.io, pypi.org, pypi.python.org) eventually redirect to it. In order to ease this transition you can put in the bellow mentioned link and it will be automatically converted to the proper format by spec-cleaner tool.<br />
<br />
The link you get from PyPI will point to some sort of hash, e.g., ''https://files.pythonhosted.org/packages/99/20/2fd208e75c05975bf6436258f469aa233045b93d195cdb442045de0923cc/tox-2.7.0.tar.gz''. We don't want that. The "semantic URL" is still available:<br/> '''/packages/source/<first letter>/<full name>/<full name>-<version>.<extension>'''<br />
<br />
=== BuildRequires ===<br />
BuildRequires are not conditional and apply for the whole spec file. There is no such thing as &quot;if I build for Python 2, I require package foo&quot;; you simply require package foo always.<br />
<br />
If you need a package for all available flavors of python, use the <code>%python_module</code> macro. To ilustrate converting from direct dependencies to <code>%python_module</code>:<br />
<br />
<pre>BuildRequires: python-setuptools<br />
BuildRequires: python-py &gt;= 1.4</pre><br />
to this:<br />
<br />
<pre>BuildRequires: %{python_module setuptools}<br />
BuildRequires: %{python_module py &gt;= 1.4}</pre><br />
Note that the version requirement goes ''inside'' the <code>%python_module</code> call.<br />
<br />
'''This is not intended for Requires tag.''' The <code>%python_module</code> macro is only for <code>BuildRequires</code><br />
<br />
If you only need the package for one flavor of python, simply ''don't'' use the macro and state the dependencies directly:<br />
<br />
<pre>BuildRequires: python2-enum34<br />
BuildRequires: python3-astroid</pre><br />
<br />
If you need to BuildRequire "python", you can instead use <code>%pythons</code>:<br />
<pre>BuildRequires: %{pythons}</pre><br />
{{Warning|This macro works only on openSUSE Leap 15.0 and newer.}}<br />
-----<br />
<br />
=== Requires, Provides and similar ===<br />
<br />
In many cases, you don't need to do anything. The single-spec rewriter will convert your Requires to match the generated package. Only make sure the Requires content really matches up setup.py or requirements.txt and there is nothing missing.<br /><br />
{{Warning|In particular, '''do not use <code>%python_module</code> for <code>Requires</code>'''.}}<br />
<br />
Package names in tags '''Requires''' (as well as "Requires(pre)" and all the others), '''Provides''', '''Recommends''', '''Suggests''', '''Obsoletes''', '''Conflicts''', '''Supplements''', and '''Enhances''' are automatically converted.<br /><br />
The converter takes into account the <code>packageand</code> expression, and <code>'''%requires_ge'''</code> and <code>'''%requires_eq'''</code> macros. However, support for these must be coded explicitly. If you find an expression that is not converted, please either post it on the packaging ML or file a bug against python-rpm-macros.<br />
<br />
If the requirement name starts with "<code>python-</code>", or with the same name as your package (so "<code>python3-bar</code>" in package "<code>python3-foo</code>"), the python name is changed to match that of the generated package.<br/><br />
This also works for "<code>python</code>" itself.<br/><br />
Packaged listed in <code>packageand</code> expression are also converted.<br />
<br />
==== Requirements specific for one python flavor ====<br />
<br />
You can specify that some packages should only be included for some python flavors, by wrapping them in <br />
conditionals using the <code>%python_flavor</code> variable<br />
<pre>Requires: python-idna<br />
%if "%{python_flavor}" == "python2"<br />
Requires: python2-enum34<br />
%endif</pre><br />
<br />
As a shortcut, for every flavor, there is a <code>%ifpython</code> macro: <code>%ifpython2</code>, <code>%ifpython3</code> or <code>%ifpypy3</code>.<br />
<pre>%ifpython2<br />
Requires: python2-enum34<br />
%endif</pre><br />
Note that the '''shortcuts must not be nested''' in other conditionals, otherwise you can get "%endif without %if" error message. If you need to nest conditionals, use the <code>%python_flavor</code> conditional.<br />
<br />
{{Warning|This does not work for <code>%prep, %build, %install, %check</code>.<br><br />
The <code>%ifpython</code> sections are copied (or not) to subpackage definitions. Subpackages have their own requirements, file lists and <code>%pre</code>/<code>%post</code>/etc. scriptlets. The scripts from <code>%prep</code> and others is shared. <code>%ifpython</code> will do the wrong thing.}}<br />
==== Obsoleting and Providing old symbols ====<br />
The following sequence:<br />
<br />
<pre>Obsoletes: python-distribute &lt; %{version}<br />
Provides: python-distribute = %{version}</pre><br />
would mean that your <code>python2-package</code> will obsolete/provide <code>python2-distribute</code> and your <code>python3-package</code> will obsolete/provide <code>python3-distribute</code> and your pypy3 package will obsolete/provide <code>pypy3-distribute</code>.<br /><br />
Often, this is not what you want.<br />
<br />
First of all, in many cases, this is only applicable for Python 2, so the sequence should be wrapped in <code>%ifpython2</code> conditional.<br />
<br />
Second, you will note that neither package obsoletes/provides '''<code>python-distribute</code>'''.<br /><br />
Here is how you do that:<br />
<br />
<pre>%define oldpython python<br />
%ifpython2<br />
Obsoletes: %{oldpython}-distribute &lt; %{version}<br />
Provides: %{oldpython}-distribute = %{version}<br />
%endif</pre><br />
<br />
<br />
==== <code>%python_module</code> in Provides ====<br />
If you are creating a subpackage that will be common for all flavors (could be a <code>-doc</code> subpackage), sometimes you need to provide a symbol for all flavors.<br />
<br />
E.g., your package <code>python-foo-doc</code> should also provide <code>python2-foo-doc</code>, <code>python3-foo-doc</code> etc.<br />
<br />
In such case, you use the <code>%python_module</code> macro:<br />
<br />
<pre>%package -n python-foo-doc<br />
Provides: %{python_module foo-doc = %{version}}</pre><br />
<br />
This is also the one case where you could use <code>%python_module</code> in Requires.<br />
<br />
(See below on declaring packages with <code>-n</code> to prevent autogeneration.)<br />
-----<br />
=== <code>%python_subpackages</code> ===<br />
<br />
Easy enough: place the <code>%python_subpackages</code> macro on a separate line at the end of the spec preamble (the part that ends where your package's <code>%description</code> begins).<br />
<br />
<pre>Provides: pylint<br />
BuildRoot: %{tmproot}/blabla<br />
BuildArch: noarch<br />
<br />
%python_subpackages<br />
<br />
%description</pre><br />
This macro emits all the subpackage descriptions, <code>%files</code> and scriptlet sections for the autogenerated parts.<br />
-----<br />
=== Subpackage declarations ===<br />
Subpackages are converted automatically. If you have a subpackage <code>%package foo</code>, singlespec will create <code>python3-yourpackage-foo</code> and all the rest from it.<br />
<br />
If you want to prevent this, use <code>%package -n %{name}-foo</code>. Or the full name, <code>%package -n python-yourpackage-foo</code>. This will ensure that the subpackage will be skipped.<br />
<br />
This also means that packages named <code>%package -n yourpackage-python</code> will not be processed. There will be a mechanism for these in the future.<br />
<br />
==== Common documentation packages ====<br />
It is very common that the shipped documentation and probably included examples are quire big and should be in a separate sub-package. The package could have - for example - these sections:<br />
<br />
<pre><br />
%package -n %{name}-docs<br />
Summary: Documentation files for %name<br />
Group: Documentation/Other<br />
<br />
%description -n %{name}-docs<br />
HTML Documentation and examples for %name.<br />
<br />
%files -n %{name}-docs<br />
%doc examples docs/_build/html/<br />
</pre><br />
-----<br />
=== Build macros ===<br />
For building the packages use <code>%python_build</code>.<br /><br />
For installing the packages use <code>%python_install</code>.<br />
<br />
These macros already contain the usual options (<code>--root</code>, <code>--prefix</code>), so in the typical case, you don't need to supply any options. If you have something specific, you can add it: <code>%python_build --enable-specific-feature</code>.<br />
<br />
If you set environment variables, export them first:<br />
<pre>export CFLAGS="-fwrapv"<br />
%python_build</pre><br />
<br />
For any other commands, you can use <code>%python_exec</code>. That is also a good way to run pythonic executables. For example:<br />
<pre>%check<br />
%python_exec setup.py test<br />
%python_exec %{_bindir}/nosetests<br />
%python_expand PYTHONPATH=%{buildroot}%{$python_sitelib} py.test-%{$python_version}</pre><br />
-----<br />
<br />
=== <code>%python_expand</code> ===<br />
For anything more complicated than executing all the interpreters, use the <code>%python_expand</code> macro. This will repeatedly expand the <code>%{$python}</code>, <code>%{$python_sitelib}</code> etc. strings to the currently used flavor.<br />
<br />
<pre>%python_expand rm -r %{buildroot}%{$python_sitelib}/file.txt</pre><br />
results in (apart from some build dir manipulations):<br />
<br />
<pre>rm -r %{buildroot}%{python2_sitelib}/file.txt<br />
rm -r %{buildroot}%{python3_sitelib}/file.txt<br />
rm -r %{buildroot}%{pypy3_sitelib}/file.txt</pre><br />
'''IMPORTANT''': you can use <code>%python_expand</code> to replace macro definitions, but make sure you use, e.g., <code>%{</code>'''<code>$python</code>'''<code>_sitelib}</code>, with the <code>$</code> sign.<br /><br />
If you use plain <code>%{python_sitelib}</code>, the macro will be expanded before <code>%python_expand</code> can modify it.<br />
<br />
A common use for <code>%python_expand</code> is with <code>fdupes</code>, as in:<br />
<br />
<pre>%python_expand %fdupes %{buildroot}%{$python_sitelib}/mymodule</pre><br />
<br />
You can use multiline <code>%python_expand</code> if you enclose the lines in <code>{}</code>. The only technical limitation is that the '''first line must not be empty''' (but can be a comment starting with <code>#</code>):<br />
<br />
<pre>%{python_expand # this will expand the following section<br />
%$python_install<br />
mv %{buildroot}%{_bindir}/exename %{buildroot}%{_bindir}/exename-%{$python_bin_suffix}<br />
}</pre><br />
<br />
This is eg useful when running tests and some pre-step is needed:<br />
<br />
<pre>%check<br />
%{python_expand rm -rf .testrepository<br />
$python setup.py test <br />
}</pre><br />
<br />
-----<br />
<br />
=== Naming flavor-specific files ===<br />
<br />
Executables specific to a particular flavor should use <code>%python_bin_suffix</code> instead of <code>%python_version</code> for names. This expands to <code>%python_version</code> for CPython, <code>pp%{python_version}</code> for PyPy. If we support Jython, it will get a specific <code>bin_suffix</code> too.<br />
<br />
Build directories specific to a particular flavor should use <code>%python_prefix</code>. This expands to the flavor name.<br />
-----<br />
<br />
=== Filelists ===<br />
If your package is called <code>python-something</code> (that is, the name prefix is &quot;python&quot; and not a specific flavor), you must mark your <code>%files</code> sections with <code>%{python_files}</code> macro.<br /><br />
<br />
<pre>%files %{python_files}<br />
%{python_sitelib}/foo<br />
<br />
%files %{python_files plugins}<br />
%{python_sitelib}/foo-plugins</pre><br />
You can use <code>%ifpython2</code> and similar to conditionally include some files only in some flavors. In addition, you can use shorthands:<br />
<br />
<pre>%files %{python_files}<br />
%{python_sitelib}/foo<br />
%{python_sitelib}/foorun.py*<br />
%python3_only %{_bindir}/foorun<br />
%pycache_only %{python_sitelib}/__pycache__</pre><br />
Use <code>%pycache_only</code> or <code>%ifpycache</code> to mark <code>__pycache__</code> directories.<br />
-----<br />
=== Executables ===<br />
For new packages that carry executables, it is preferred that these are marked <code>%python3_only</code>. That ensures that the executables are only installed for the preferred python flavor, which is Python 3.<br />
<br />
If your package functionality depends on version of Python (e.g., test harnesses, source code processors, installers, etc.), you should package executables for all flavors. This is easy if the package itself installs versioned executables. If not, use the '''<code>%python_clone</code>''' macro.<br />
<pre>%python_install<br />
%python_clone %{buildroot}%{_bindir}/executable</pre><br />
<br />
This macro will copy the <code>executable</code> as <code>executable-%python_bin_suffix</code> for all flavors, and change the shebang line to the appropriate interpreter.<br />
<br />
<code>%python_clone</code> works for all kinds of files. If it recognizes a man page extension, it will correctly rename <code>manpage.1</code> to <code>manpage-%python_bin_suffix.1</code>.<br />
<br />
When using <code>%python_clone</code>, you need to list both the original executable *and* the copied executables in your filelist:<br />
<pre>%{_bindir}/executable-%{python_bin_suffix}<br />
%python3_only %{_bindir}/executable</pre><br />
<br />
If changing the shebang line is not appropriate or sufficient, you will need to catch the executable after every installation, like this:<br />
<pre>%{python_expand %$python_install<br />
mv %{buildroot}%{_bindir}/executable %{buildroot}%{_bindir}/executable-%{$python_bin_suffix}<br />
}</pre><br />
<br />
==== Python 2 stacks ====<br />
<br />
The recommendation for preferring Python 3 is intended for new code.<br />
<br />
Existing packages that are parts of Python 2 stacks (such as the current (2017-03) OpenStack Cloud) need executables for Python 2 as well. For these, it is preferable to use the alternatives approach outlined below.<br />
<br />
==== update-alternatives ====<br />
<br />
Sometimes it is useful to let the user switch the unversioned executable name to one version of the package or another.<br />
<br />
Also, if you can't be sure that the user has a Python 3 stack, and want to provide unversioned executable names regardless, update-alternatives is the way to go.<br />
<br />
update-alternatives allows you to switch other things (usually man pages) along with executables.<br />
<br />
As a prerequisite, you need to have version-specific file names available -- that is, for every <code>file</code> you provide, <code>file-%python_bin_suffix</code> should exist for all flavors.<br />
(for <code>manpage.1</code>, the appropriate name is <code>manpage-%python_bin_suffix.1</code>)<br />
<br />
'''First''', you need to set up the alternatives in <code>%install</code> section.<br/><br />
* If you're using <code>%python_clone</code> to create the executable, simply pass '''-a''' option: '''<code>%python_clone -a %{buildroot}%{_bindir}/executable</code>'''<br />
* If not, and the file in question is <code>%{_bindir}/something</code>, call '''<code>%prepare_alternative something</code>'''<br />
* If the file is not in <code>%{_bindir}</code>, you have to specify the path: '''<code>%prepare_alternative -t /path/to/file file</code>'''. The path is without <code>%buildroot</code><br />
<br />
'''Second''', create the appropriate <code>%post</code> and <code>%postun</code> sections. Make sure that you have the proper requirements:<br />
<pre>Requires(post): update-alternatives<br />
Requires(postun): update-alternatives</pre><br />
Then use <code>%python_install_alternative</code> and <code>%python_uninstall_alternative</code> respectively.<br />
<pre>%post<br />
%python_install_alternative exename<br />
<br />
%postun<br />
%python_uninstall_alternative exename</pre><br />
<br />
'''Third''', mention the alternative, unversioned, in file list<br />
<pre>%python_alternative %{_bindir}/exename</pre><br />
<br />
You can examine a full spec file at [https://build.opensuse.org/package/view_file/devel:languages:python/python-pylint/python-pylint.spec?expand=1].<br />
<br />
==== Grouped alternatives ====<br />
The update-alternatives system allows for multiple files in the same group, to be switched together. This is useful if you want to install an executable along with its manpage, or multiple executables belonging to the same function group.<br />
<br />
To make use of this, simply specify the files as multiple arguments to <code>%python_install_alternative</code>:<br />
<pre>%{python_install_alternative pylint pylint.1 epylint epylint.1}</pre><br />
The macro can recognize manpage names and handle them correctly, but the first arguments needs '''always''' to the an executable. Or you can specify a full path to the file in question.<br />
<br />
The first argument to <code>%python_install_alternative</code> is the group name. This is the '''only''' argument for <code>%python_uninstall_alternative</code>; you uninstall the whole group by the one name.<br />
-----<br />
<br />
=== Packages for single Python version ===<br />
Packages that only exist for Python 2 should be left as is. New packages should be called <code>'''python2'''-foo</code>. Old packages should be left as <code>'''python'''-foo</code>, but you should add <code>Provides: python2-foo</code>. You should also make sure that all BuildRequires and Requires are for "python2" and "python2-foo".<br />
<br />
Packages that only exist for Python 3 can be left as is, or they can be converted to singlespec, with <b><code>%define skip_python2 1</code></b>. This is to ensure that they can build for PyPy or other flavors in the future. The definition should be made at the top of the spec-file.<br/><br />
-----<br />
<br />
=== Conditionals on Python versions ===<br />
If you need to differentiate between python versions you can use the following macros:<br />
<br />
{| class="wikitable"<br />
|-<br />
| Macros || Example<br />
|-<br />
| <code>%python2_version_nodots</code> || 27<br />
|-<br />
| <code>%python3_version_nodots</code> || 36<br />
|}<br />
<br />
For example:<br />
<pre><br />
%if %python3_version_nodots > 34<br />
...<br />
%endif<br />
</pre><br />
-----<br />
=== Common Gotchas ===<br />
<br />
Things to look out for (which can also get your submission declined):<br />
# If the <code>%python_module</code> redefinition is present, check that it has <code>"python-%{**}"</code> and not <code>"python-%1"</code><br />
# use <code>%python_module</code> for BuildRequires<br />
# do NOT use <code>%python_module</code> for Requires<br />
# make sure <code>%python_subpackages</code> macro is present<br />
# <code>%files sections</code> should be marked as <code>"%files %{python_files}"</code><br />
# in <code>%python_expand</code>, make sure you use <code>%$python_</code> macros instead of <code>%python_</code> macros<br />
# use <code>%python_bin_suffix</code> instead of <code>%python_version</code> for distinguishing executables or build directories<br />
-----<br />
<br />
=== Running tests ===<br />
The python code is not really compiled like C applications. As such it is really easy to distribute something that does not work at all. In order to prevent this all applications must run and pass their tests unless upstream is providing none themselves.<br />
<br />
The easiest way to run tests is using setuptools ''test'' subcommand:<br />
<pre><br />
%python_exec setup.py test<br />
</pre><br />
<br />
This of course only works, if ''test_suite'' or ''cmd_class'' is properly defined in your ''setup.py''. If the setup.py call fails or executes no tests one has to dig around checing various files in the development repository like <tt>.travis.yml</tt> or <tt>tox.ini</tt>.<br />
<br />
= All Macros =<br />
<br />
The '''full documentation''' for all macros defined for singlespec can be found at the GitHub page for [https://github.com/openSUSE/python-rpm-macros python-rpm-macros] package.<br />
<br />
<br />
[[Category:Packaging]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Java&diff=128948openSUSE:Packaging Java2018-09-23T12:18:00Z<p>Thomas-schraitle: jpackage-utils -> javapackages-tools</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging Java''' is a step by step introduction on how to build software packages of Java applications and libraries for openSUSE and others using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
==(Build)Requires ==<br />
<br />
Java (mean the usual bundle of runtime, compiler et al) is splitted into JRE — Java Runtime Environment and JDK — Java development kit. The first contains <code>java</code> command and is required for running of Java applications. As SUSE follows jpackage.org compatible naming scheme, runtime is represented by <code>java</code> symbol. The SDK uses <code>java-devel</code>. Both are versioned, so you can request a minimal version of Java to be used. Obviously you have to distinguish between GNU Java and others, so in a most common case, you will request Java higher than 1.6.0 (excluding gcj to be selected).<br />
<br />
<pre><br />
BuildRequires: java >= 1.6.0<br />
Requires: java >= 1.6.0<br />
</pre><br />
<br />
This will be expanded to the default implementation on each product. Using of full package name is <strong>prohibited</strong> as it will break dependencies on each Java update in SUSE.<br />
<br />
----<br />
<br />
== Starting the program ==<br />
Often, java applications do not provide a startscript to start the program from command line or to be used in connection with a desktop entry/icon.<br />
In this case, use the following code snippet in ''%install'' - section of your spec - file<br />
<br />
<pre><br />
# startscript<br />
cat > %{name} << 'EOF'<br />
#!/bin/sh<br />
#<br />
# <Program Name> startscript<br />
#<br />
echo Starting %{name} version %{version} ...<br />
echo with options : \${@}<br />
<br />
java -jar %{_datadir}/%{name}/%{name}.jar \${@}<br />
<br />
EOF<br />
</pre><br />
<br />
then install the script to ''/usr/bin'' with the following two lines<br />
<pre><br />
install -d -m 755 %{buildroot}%{_bindir}<br />
install -m 755 %{name} %{buildroot}%{_bindir}/<br />
</pre><br />
<br />
Now you should be able to launch the program from the command line and refer to it in the desktop file, by just giving the name.<br />
<br />
----<br />
<br />
== Java versions ==<br />
=== Sun Java ===<br />
Sun Java is not available in the openSUSE anymore. The last obsolete and insecure version we can distribute are in Java:sun:Factory. More recent releases have license prohibits us to distribute it.<br />
<br />
=== Java repositories ===<br />
<br />
* Java:packages - a devel project for all Java packages, you can find here the latest versions for Factory<br />
* Java:openjdk6:Factory - devel project for openjdk<br />
<br />
----<br />
<br />
== Examples ==<br />
===A standalone application ===<br />
<br />
As an example, we shall use "columba", an e-mail client that is completely written in Java. An example spec-file can be seen below.<br />
<br />
columba.spec<br />
<pre><br />
Name: columba<br />
Summary: eMail client written in Java<br />
Version: 1.4<br />
Release: 1<br />
License: GNU General Public License (GPL)<br />
Group: Productivity/Networking/Email/Clients<br />
Source: http://prdownloads.sourceforge.net/columba/columba-%version-src.zip<br />
URL: http://www.columbamail.org<br />
BuildRoot: %{_tmppath}/%{name}-%{version}-build<br />
BuildRequires:unzip<br />
BuildRequires:update-alternatives java-1_5_0-sun-devel<br />
BuildRequires:ant<br />
Requires: java >= 1.5.0<br />
BuildArchitectures: noarch<br />
<br />
%description<br />
Columba is an Email Client written in Java, featuring a user-friendly <br />
graphical interface with wizards and internationalization support. Its <br />
a powerful email management tool with features to enhance your <br />
productivity and communication.<br />
So, take control of your email before it takes control of you!<br />
Feature Highlights<br />
* Clean and Response User Interface<br />
* Cross Platform<br />
* Internationalization<br />
* Unlimited Functionality using Plugins<br />
* Safe and Secure<br />
* Glueing together Third-Party Tools<br />
* Multiple Accounts and Profiles<br />
<br />
%prep<br />
%setup -qn columba-%version-src<br />
<br />
# remove the third party jars<br />
find . -type f -iname "*.jar" -delete<br />
<br />
%build<br />
%ant jar<br />
<br />
%install<br />
# jars<br />
install -dm 0755 "%buildroot/%_datadir/%name"<br />
install -m 0644 columba.jar "%buildroot/%_datadir/%name/"<br />
<br />
# lib<br />
#install -dm 0755 "%buildroot/%_datadir/%name/lib/jpa"<br />
#install -m 0755 lib/jpa/* "%buildroot/%_datadir/%name/lib/"<br />
cp -rp lib "%buildroot/%_datadir/%name/"<br />
<br />
install -dm 0755 "%buildroot/%_datadir/%name/native"<br />
cp -rp native/linux "%buildroot/%_datadir/%name/native/"<br />
<br />
install -dm 0755 "%buildroot/%_datadir/%name/plugins"<br />
cp -rp plugins/* "%buildroot/%_datadir/%name/plugins/"<br />
<br />
# startscript<br />
install -dm 0755 "%buildroot/%_bindir"<br />
cat >"%buildroot/%_bindir/%name" << EOF<br />
#!/bin/sh<br />
exec java -jar "%_datadir/%name/%name.jar"<br />
EOF<br />
chmod 0755 "%buildroot/%_bindir/%name"<br />
<br />
%files<br />
%doc AUTHORS CHANGES LICENSE README<br />
%_bindir/%name<br />
%_datadir/%name<br />
<br />
%changelog<br />
</pre><br />
<br />
=== A Java library ===<br />
<br />
The columba was a standalone application. For the packaging of the libraries, there're some differences. The following skeleton for Java libraries is derived from [http://www.jpackage.org jpackage.org] spec files. The're some special macros like <code>%{_javadir}</code> - for details see [[openSUSE:Java_RPM_Macros]]. The convient scripts from jpackage-utils used for build (and run) are described on [[openSUSE:Java_jpackage-utils]].<br />
<br />
<pre><br />
### the skeleton for packaging of the java libraries<br />
### many of these techniques are based on approach of jpackage.org spec files<br />
Name:<br />
Version:<br />
Release:<br />
Summary:<br />
Group: Development/Libraries/Java<br />
License:<br />
URL:<br />
Source:<br />
BuildRoot: %{_tmppath}/%{name}-%{version}-build<br />
BuildArchitectures: noarch<br />
BuildRequires: java-devel<br />
BuildRequires: ant<br />
BuildRequires: javapackages-tools<br />
<br />
<br />
%description<br />
<br />
### Many of Java packages contains a javadoc and this is universal notation<br />
### usefull for majority of Java packages<br />
%package javadoc<br />
Summary: Javadoc for %name<br />
Group: Development/Libraries/Javam<br />
<br />
%description javadoc<br />
This package contains a javadoc.<br />
<br />
%prep<br />
%setup -q<br />
<br />
# remove all third party jars<br />
find . -type f -iname "*.jar" -delete<br />
<br />
### Many of Java software comes from Windows, so this sed edit the files with <br />
### Windows encoding - the shell scripts probably not works with the Windows end of lines!<br />
#perl -i -pe 's{\r\n$}{\n}gs'<br />
<br />
%build<br />
<br />
### Sometimes is necessary to set the CLASSPATH before build<br />
### build-classpath is a standard tool from jpackage-utils<br />
#export CLASSPATH=$(build-classpath foo)<br />
%ant<br />
<br />
%install<br />
### create of the directory for installing the jars<br />
install -dm 755 "%buildroot/%_javadir"<br />
# jars<br />
### make name of jars version agnostics<br />
(cd "%buildroot/%_javadir/%name" && for jar in *-%{version}*; do ln -sf "$jar" "${jar/-%version/}"; done)<br />
<br />
# javadoc<br />
install -dm 755 "%buildroot/%_javadocdir/%name-%version"<br />
cp -pr api/* "%buildroot/%_javadocdir/%name-%version/"<br />
<br />
%files<br />
%_javadir/%{name}*.jar<br />
<br />
%files javadoc<br />
%_javadocdir/%name-%version<br />
<br />
%changelog<br />
</pre><br />
<br />
=== Third party jars ===<br />
The Java upstream includes a libraries as a jars into the source archives. This approach has purpose for developers, which tends to quick build of the projects withouth needs to download/or compile all dependent files. Due the platform independence, there is no problem with using of the binary jars. But this is not very useful for package maintaners, and the convient approach in Linux distribution is the use of the system-wide jars (located in /usr/share/java) for build and run-time. There are some special cases (e.g. signed jars) for which is not possible to build own jar, but in the common case, there is no reason for using third-party binaries. <br />
<br />
Including external binaries is evil because: <br />
* They are useless for people trusting only self-built software. <br />
* They are useless for people who already have those binaries. <br />
* It makes tracking dependencies a nightmare. <br />
* It makes archives bigger.<br />
(from [[http://jpackage.org/jpprequest.php jpackage.org:Request to Java developers]]<br />
<br />
----<br />
== Troubleshooting ==<br />
<br />
=== bytecode version error ===<br />
<br />
Warning: this error exists only for SLE11 targets, more recent openSUSE releases do not limit the bytecode version.<br />
<br />
If you get an error<br />
<pre><br />
ERROR: the files above contain java bytecode for something later than java 1.5,<br />
ERROR: please set the javac target to 1.5 or lower<br />
</pre><br />
<br />
you can set the target to 1.5<br />
<br />
<pre><br />
-Dant.build.javac.source=1.5 -Dant.build.javac.target=1.5<br />
</pre><br />
<br />
For maven:<br />
<br />
<pre><br />
mvn-jpp -Dmaven.compile.target=1.5 -Dmaven.javadoc.source=1.5 ...<br />
</pre><br />
<br />
or suppress this test by:<br />
<br />
<pre><br />
export NO_BRP_CHECK_BYTECODE_VERSION=true<br />
</pre><br />
<br />
in the <code>%install</code> section.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
[[el:openSUSE:Packaging Java]]<br />
[[zh:openSUSE:Packaging Java]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Java_RPM_Macros&diff=128946openSUSE:Java RPM Macros2018-09-23T12:15:29Z<p>Thomas-schraitle: Clarified jpackage-utils vs. javapackages-tools</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|The RPM macros for Java packages came from http://www.jpackage.org jpackage project, so this naming and a structure is the same as on the other rpm-based distributions.}}<br />
<br />
= RPM macros =<br />
<br />
Those macros are mostly defined in the following packages:<br />
<br />
* <code>jpackage-utils</code> (<= openSUSE 12.3)<br />
* <code>javapackages-tools</code> (>= openSUSE Leap 42.1)<br />
<br />
Don't forget add it to BuildRequires tag!<br />
<br />
== %_jvmdir ==<br />
<br />
Root directory where all Java VMs/SDK/JREs are installed.<br />
<br />
%_jvmdir %{_libdir}/jvm<br />
<br />
== %_jvmjardir ==<br />
<br />
Root directory where all Java VMs/SDK/JREs expose their jars<br />
<br />
%_jvmjardir %{_libdir}/jvm-exports<br />
<br />
== %_jvmprivdir ==<br />
Root directory for all Java VM/SDK/JRE's private things.<br />
<br />
%_jvmprivdir %{_libdir}/jvm-private<br />
<br />
== %_jvmlibdir ==<br />
<br />
Root directory for all architecture dependent parts of Java VM/SDK/JRE's<br />
<br />
%_jvmlibdir %{_prefix}/lib/jvm<br />
<br />
== %_jvmdatadir ==<br />
<br />
Root directory for all architecture independent parts of Java VM/SDK/JRE's<br />
<br />
%_jvmdatadir %{_datadir}/jvm<br />
<br />
== %_jvmsysconfdir ==<br />
<br />
Root directory for all configurations parts of Java VM/SDK/JRE's<br />
<br />
%_jvmsysconfdir %{_sysconfdir}/jvm<br />
<br />
== %_jvmcommonlibdir ==<br />
<br />
Root directory for all common architecture dependent parts of Java VM/SDK/JRE's<br />
<br />
%_jvmcommonlibdir %{_prefix}/lib/jvm-commmon<br />
<br />
== %_jvmcommondatadir ==<br />
<br />
Root directory for all common architecture independent parts of Java VM/SDK/JRE's<br />
<br />
%_jvmcommondatadir %{_datadir}/jvm-commmon<br />
<br />
== %_jvmcommonsysconfdir ==<br />
<br />
Root directory for all common configurations parts of Java VM/SDK/JRE's<br />
<br />
%_jvmcommonsysconfdir %{_sysconfdir}/jvm-commmon<br />
<br />
== %_javadir ==<br />
<br />
Directory where arch and version independent jars are installed.<br />
This has already been integrated in RH macros following our request.<br />
<br />
By extension:<br />
<br />
* <code>%{_javadir}-ext</code>: - version dependent jars<br />
* <code>%{_javadir}-x.y.z</code>: - jars for Java standard x.y.z (usually symlinks to %{_javadir}-ext)<br />
* <code>%{_javadir}-utils</code>: - Java-related scripts<br />
<br />
To simplify things only <code>%{_javadir}</code> is defined.<br />
<br />
%_javadir %{_datadir}/java<br />
<br />
== %_jnidir ==<br />
Directory where arch-specific (JNI) version-independent jars are installed.<br />
<br />
By extension:<br />
* <code>%{_jnidir}-ext</code>: - version dependent jars<br />
* <code>%{_jnidir}-x.y.z</code>:- jars for Java standard x.y.z (usually symlinks to <code>%{_jnidir}-ext</code>)<br />
<br />
To simplify things only <code>%{_jnidir}</code> is defined.<br />
<br />
%_jnidir %{_libdir}/java<br />
<br />
== %_javadocdir ==<br />
<br />
Root directory where all javadoc is installed. Also already in RH macros.<br />
<br />
%_javadocdir %{_datadir}/javadoc<br />
<br />
== %java_home ==<br />
<br />
Current default JVM home.<br />
<br />
%java_home %(. %{_javadir}-utils/java-functions; set_jvm; echo $JAVA_HOME)<br />
<br />
== default Java commands ==<br />
<br />
%ant JAVA_HOME=%{java_home} ant<br />
%jar %{java_home}/bin/jar<br />
%java %(. %{_javadir}-utils/java-functions; set_javacmd; echo $JAVACMD)<br />
%javac %{java_home}/bin/javac<br />
%javadoc %{java_home}/bin/javadoc<br />
<br />
== %add_jvm_extension ==<br />
<br />
<code>add_jvm_extension</code> should be used in %install by extension packages to declare<br />
what extension jars they provide.<br />
<br />
For example a package that provides foo.jar which is the bar extension<br />
under java 1.2 and 1.3 should do a:<br />
<br />
%install<br />
... # create foo.jar in %{javadir}-ext<br />
%add_jvm_extension foo bar 1.2 1.3<br />
<br />
%files<br />
%{javadir}-ext/foo.jar<br />
%{javadir}-*/bar.jar<br />
<br />
%add_jvm_extension JAVA_LIBDIR=%{buildroot}/%{_javadir} %{_bindir}/jvmjar -l<br />
<br />
<br />
== %_mavendepmapdir ==<br />
Directory for maven depmaps<br />
<br />
%_mavendepmapdir /etc/maven<br />
%_mavendepmapfragdir /etc/maven/fragments<br />
<br />
== %add_to_maven_depmap() ==<br />
add_to_depmap adds an entry to the depmap. The arguments are:<br />
<br />
* %1 the original groupid<br />
* %2 the original artifact id<br />
* %3 the version<br />
* %4 the new groupid<br />
* %5 the new artifactid<br />
<pre><br />
%add_to_maven_depmap() \<br />
install -dm 755 $RPM_BUILD_ROOT/%{_mavendepmapfragdir}\<br />
cat >>$RPM_BUILD_ROOT/%{_mavendepmapfragdir}/%{name}<< EOF\<br />
<dependency>\<br />
<maven>\<br />
<groupId>%1</groupId>\<br />
<artifactId>%2</artifactId>\<br />
<version>%3</version>\<br />
</maven>\<br />
<jpp>\<br />
<groupId>%4</groupId>\<br />
<artifactId>%5</artifactId>\<br />
<version>%3</version>\<br />
</jpp>\<br />
</dependency>\<br />
\<br />
EOF\<br />
%{nil}<br />
</pre><br />
<br />
== %update_maven_depmap() ==<br />
update_maven_depmap updates the main maven depmap<br />
<pre><br />
%update_maven_depmap() \<br />
echo -e "<dependencies>\\n" > %{_mavendepmapdir}/maven2-depmap.xml\<br />
if [ -d %{_mavendepmapfragdir} ] && [ -n "`find %{_mavendepmapfragdir} -type f`" ]; then\<br />
cat %{_mavendepmapfragdir}/* >> %{_mavendepmapdir}/maven2-depmap.xml\<br />
fi\<br />
echo -e "</dependencies>\\n" >> %{_mavendepmapdir}/maven2-depmap.xml\<br />
%{nil}<br />
</pre><br />
<br />
<br />
[[Category:Java]]<br />
[[Category:Packaging documentation]]<br />
[[zh:openSUSE:Java_RPM_Macros]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=124758openSUSE:Packaging XML Schemas and Stylesheets2018-04-16T07:45:15Z<p>Thomas-schraitle: Small minor textual fix</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependant.<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group</tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add another source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=124756openSUSE:Packaging XML Schemas and Stylesheets2018-04-16T07:44:19Z<p>Thomas-schraitle: Recommends <group> element</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependant.<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example. It's recommended to use a <tt>&lt;group</tt> element and add all identifiers as child elements.<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add the source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=124754openSUSE:Packaging XML Schemas and Stylesheets2018-04-16T07:39:56Z<p>Thomas-schraitle: Add some clarification which catalogs can be edited</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependant.<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>. Normally, you don't touch this.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them (<tt>PACKAGENAME.xml</tt>). This is the place where you add all your identifiers.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal. Never touch this catalog!<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example.<br />
<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add the source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Backports_Package_Submission_Process&diff=123136openSUSE:Backports Package Submission Process2018-01-23T08:58:21Z<p>Thomas-schraitle: Add link to SLE-15</p>
<hr />
<div>= Overview =<br />
<br />
This page outlines the technical process of building and maintaining packages for the SLE Backports repos.<br />
<br />
= Project Setup =<br />
<br />
Backported packages are built in the [https://build.opensuse.org/ openSUSE build service]<br />
<br />
The following '''default''' target exists:<br />
<br />
:'''[https://build.opensuse.org/project/show/openSUSE:Backports:SLE-12 openSUSE:Backports:SLE-12] (SUSE Linux Enterprise Server 12 "GA" release)'''<br />
<br />
'''The default target should be used for building and submitting all new packages.''' If a package requires a later service pack to build, use the appropriate target below:<br />
<br />
* [https://build.opensuse.org/project/show/openSUSE:Backports:SLE-12-SP1 openSUSE:Backports:SLE-12-SP1] (SUSE Linux Enterprise Server 12 Service Pack 1)<br />
* [https://build.opensuse.org/project/show/openSUSE:Backports:SLE-12-SP2 openSUSE:Backports:SLE-12-SP2] (SUSE Linux Enterprise Server 12 Service Pack 2)<br />
* [https://build.opensuse.org/project/show/openSUSE:Backports:SLE-12-SP3 openSUSE:Backports:SLE-12-SP3] (SUSE Linux Enterprise Server 12 Service Pack 3)<br />
* [https://build.opensuse.org/project/show/openSUSE:Backports:SLE-15 openSUSE:Backports:SLE-15] (SUSE Linux Enterprise Server 15 "GA")<br />
<br />
The packages in older releases should, in most cases, be forward compatible with the following service pack releases. Therefore it's not necessary to rebuild for each service pack. Packages in the openSUSE:Backports:SLE-12 target will not be automatically migrated and built in the service pack targets, though they will be available at build time where needed.<br />
<br />
= Packager workflow =<br />
<br />
The Backports project only allows packages that are already accepted in Factory. Ensure that you package is accepted and building there.<br />
<br />
You can build and locally test any checked out package:<br />
<br />
osc build --alternative-project openSUSE:Backports:SLE-12 standard<br />
<br />
If the package builds, it will build in backports as well. Proceed with submitting it as a single package below.<br />
<br />
Adding <code>openSUSE:Backports:SLE-12</code> as a build target to your project is possible, and will work for developing your new packages in a separate project. It is not suitable for the general case as packages will be set to automatically fail should they duplicate packages already in the SLES product.<br />
<br />
== Introducing a single new package ==<br />
<br />
A single package can be submitted as follows:<br />
<br />
osc sr devel:project hello openSUSE:Backports:SLE-12<br />
<br />
Note that the package may build in <code>devel:project</code> but not in <code>openSUSE:Backports:SLE-12</code>, it is hence recommended to check for that using <code>--alternative-project</code> as described above or a suitable project configuration.<br />
<br />
The build service will internally convert the <code>submit</code> type request into a <code>maintenance_incident</code>, and the following message is expected:<br />
''Project does not accept submit request, a NEW maintenance incident request will be created instead''<br />
<br />
== Introducing more than one package ==<br />
<br />
Consider a new package (e.g. <code>devel:project/newpackage</code>) that also requires a new library <code>devel:project/newlib</code>, none of which are already in backports.<br />
<br />
We will create a maintenance branch (<code>-M</code>) for a new package (<code>-N</code>):<br />
<br />
osc branch -M -N openSUSE:Backports:SLE-12/newlib<br />
osc branch -M -N openSUSE:Backports:SLE-12/newpackage<br />
osc co home:SLE_WIZARD:branches:openSUSE:Backports:SLE-12<br />
<br />
Now we can put in our sources. In this case, we copy the sources from the devel project. We need to extend the source link (<code>-e</code>) as well as keep the target link in case it exists (<code>-K</code>).<br />
<br />
osc copypac -e -K devel:project/newlib home:SLE_WIZARD:branches:openSUSE:Backports:SLE-12/newlib.openSUSE_Backports_SLE-12<br />
osc copypac -e -K devel:project/newpackage home:SLE_WIZARD:branches:openSUSE:Backports:SLE-12/newpackage.openSUSE_Backports_SLE-12<br />
<br />
When this is built and tested, we can submit a maintenance request for all packages together:<br />
<br />
cd home:SLE_WIZARD:branches:openSUSE:Backports:SLE-12<br />
osc mr<br />
<br />
A combination of new and updated packages is possible.<br />
<br />
== Branching existing package ==<br />
<br />
Just like with openSUSE maintenance a package can be branched directly from the destination project<br />
<br />
osc branch openSUSE:Backports:SLE-12 hello<br />
<br />
Alternatively, to automatically branch all maintained versions<br />
<br />
osc mbranch hello<br />
<br />
This command would set up a project that also contains all openSUSE versions of the same package so the maintainer can fix all instances at once.<br />
<br />
Note that the current policy requires that package sources for the Backports project and openSUSE Factory are identical.<br />
<br />
= Maintenance Workflow =<br />
<br />
The target project doesn't actually build the packages but behaves like an update project for released openSUSE distributions. I.e. the actual sources are built in so called "incident projects". The openSUSE maintenance team takes care of those incident projects.<br />
<br />
After the packager filed a request, they reviewed by automated review bots:<br />
<br />
* maintbot: checks if the submission was created by the package maintainer as defined in the devel project. maintbot will add the devel project as reviewer for submissions by non-maintainers.<br />
* factory-source: checks if the sources for submissions to the Backports project are actually accepted in factory. Rejects requests where this is not the case.<br />
* legal-auto: license checks<br />
<br />
The following further reviews are added as needed:<br />
<br />
* for Backports team: If the sources do not match those of <code>openSUSE:Factory</code> or a currently maintained stable Leap distribution, this deviation must be separately approved<br />
* for the Factory package maintainers. If the submission is by a person who is not in the list of regular maintainers of this package in Factory, they need to separately approve it. Note that if the maintainer accepts this reviews, this also indicates that they commit to maintain the package in PackageHub for future security or maintenance issues. The following message is used: ''Submission for PACKAGE by someone who is not maintainer in the devel project (PROJECT). Please review''.<br />
<br />
After successful automated and manual reviews the maintenance engineer takes over. If the request is ok he accepts it and therefore creates a maintenance incident. After the packages built successfully the maintenance engineer creates a release request. The release request in turn is checked again by factory-source.<br />
<br />
After the usual grace period for testing as used on openSUSE the maintenance engineer then accepts release requests to actually release the package.<br />
<br />
[[Category:Backports]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Build_Service_prjconf&diff=121222openSUSE:Build Service prjconf2017-08-23T06:50:14Z<p>Thomas-schraitle: Fix broken links to obsolete Git repo (now links to GitHub)</p>
<hr />
<div>{{Buildservice navbar}}<br />
[[Category:Build Service]]<br />
__TOC__<br />
<br />
= Description =<br />
<br />
The '''prjconf''' denotes the (build) configuration of a project. The main part of this file (''/usr/lib/build/configs/$distro.conf'') is the definition of the build environment. For simple projects, it may well be empty. But everything that normaly needs a user decision (like packages providing the same stuff) or special macros/packages/flags in the build environment is defined here.<br />
<br />
The syntax is basically the same as in rpm spec files, just the tags are different. Conditionaly like ''%if'', ''%ifarch'' etc also work.<br />
<br />
From web interface you can go on the tab advanced and then project config.<br />
Using OSC you can do a:<br />
{{shell|osc meta prjconf <projectname>}}<br />
<br />
A very similar listing can be seen with<br />
<br />
{{shell|osc buildconfig <projectname> <reponame>}}<br />
<br />
Have a look at project config of the ''openSUSE:Factory'' project to get an impression about what is possible.<br />
<br />
{{Info|The default package list for a build environment is:<br />
[[#Preinstall|Preinstall]] + [[#Required|Required]] + [[#Support|Support]] + Packages from dependency expansion.<br />
}}<br />
<br />
= Supported Tags =<br />
<br />
== Conflict ==<br />
<br />
If pkg A provides pkg1 pkg2 pkg3, for example for bootstrapping, if you set Prefer: pkg1, pkg1 will be installed before pkg, but because pkg2 is needed, pkg will be installed and it will conflict with pk1. The solution would have been to install from the beginning pkg until pk1, pkg2, pkg3 are fully built. This is not yet supported by the OBS solver. As a workaround you can explicitly define the conflict.<br />
<br />
Conflict:<pkg> <pkg1> ...<br />
<br />
== Preinstall ==<br />
The packages that need to be unpacked for build environment setup. This is basically everything that is needed to get rpm/dpkg running, i.e. glibc and the like.<br />
<br />
Preinstall: filesystem fillup glibc<br />
<br />
"Install" the filesystem package in the chroot environment, so rpm/dpkg can work. If you prefix a package name with a ! it will deselect a package from Preinstall: and prevent its installation.<br />
<br />
== Runscripts ==<br />
A subset of the preinstall packages. It describes which packages need to have their postinstall scripts run.<br />
<br />
Runscripts: aaa_base<br />
<br />
== Required ==<br />
These are the packages that make the "normal" build environment, i.e. stuff like gcc, autoconf, automake and the like.<br />
<br />
Required: autoconf automake binutils<br />
<br />
Install autoconf in the build environment - this is done via the normal packagemanager (rpm/dpkg).<br />
<br />
== Support ==<br />
Convenience packages, like "vim" or "strace". The difference to "Required" is that the automatic rebuild detection does not look at support packages, i.e. you don't get an automatic rebuild if "strace" is changed. <br />
<br />
This list also includes some "-devel" packages and other subpackages of the "Required" packages to keep the Required list small. (I.e. we don't need both "zlib" and "zlib-devel" in Required because both are built from the same source).<br />
<br />
Support: vim strace glibc-devel<br />
<br />
To remove a support package from an inherited config (e.g. openSUSE:11.3), use<br />
<br />
Support: !build-compare<br />
<br />
== Keep ==<br />
We really need those packages. Normally, subpackages of the package that we want to build don't get installed. But even if we want to build the "patch" package, we need a working patch program to apply patches from the specfile. So we have "Keep: patch". The preinstalled packages are automatically added to this list. <br />
<br />
Keep: gdbm glibc-devel glibc-locale<br />
<br />
== Prefer ==<br />
This information is used to break ambiguities.<br />
<br />
Ignoring a package (that has an 'have choice' issue):<br />
Prefer: -suse-build-key<br />
<br />
Choosing a package:<br />
Prefer: openSUSE-build-key <br />
<br />
This can also be done on package level:<br />
Prefer: tomboy:gconf-sharp<br />
For the dependency coming from binary package tomboy, choose gconf-sharp. The following example error message tells you that this comes from the binary package tomboy: '''have choice for gconf needed by tomboy: gconf gconf-sharp gconf-blunt'''; similar error messages, but without the 'needed by ...' part indicate that the issue came from your specfile instead.<br />
<br />
{{Info|This can also be done on package level in specfile via "BuildRequires" / "#!BuildIgnore":<br />
BuildRequires: openSUSE-Build-key<br />
#!BuildIgnore: suse-build-key<br />
}}<br />
A BuildRequires: java-devel >= 1.7.0 can also trigger the have-choice-error (e.g. between java-1_7_0-openjdk-devel and java-1_7_0-ibm-devel). This can be solved with a project wide<br />
Prefer: java-1_7_0-openjdk-devel<br />
but cannot be solved with<br />
Prefer: PACKAGENAME:java-1_7_0-openjdk-devel<br />
For a package-specific solution, you must refine the BuildRequires: in the specfile itself.<br />
<br />
== Substitute ==<br />
Packages get renamed or are named different for different distributions. You can specify per repository dependency rewrite rules.<br />
<br />
%if 0%{?fedora_version}<br />
Substitute: pwdutils shadow-utils<br />
%endif<br />
<br />
A bare Substitutes like that will strip any version detail, so for a "<tt>Requires: libkde4-devel >= 4.4</tt>" line to translate into "<tt>Requires: kdelibs-devel >= 4.4</tt>", a trailing equals sign needs to be specified for the replacement package:<br />
<br />
%if 0%{?suse_version}<br />
Substitute: libkde4-devel kdelibs-devel=<br />
%endif<br />
%if 0%{?fedora_version}<br />
Substitute: kdelibs-devel libkde4-devel=<br />
%endif<br />
<br />
On openSUSE, the package is named "libkde4-devel", so replace all requirements for "kdelibs-devel" to "libkde4-devel" — and vice versa for Fedora.<br />
<br />
== Ignore ==<br />
This breaks dependencies for the package expansion step. Means that we don't need an installed package if another package normally needs (Requires) it. <br />
<br />
Ignore: portmap:syslogd<br />
<br />
We don't need an installed syslogd if we have to install the portmap package.<br />
{{Info|This is also possible on package level: by adding "#!BuildIgnore" lines to the specfile:<br />
#!BuildIgnore: syslogd<br />
}}<br />
<br />
== ExportFilter ==<br />
Copy build binary package from one arch to another. This is mostly needed for packages only available on one architecture, but needed on other archs which can at least emulate the package arch.<br />
<br />
ExportFilter: ^wine.*\.i586.rpm$ . x86_64<br />
<br />
Copies the built wine package to the i586 and x86_64. The dot means the 'current' architecture where it was built for. By default, packages will always be copied to at least their own architecture, that is:<br />
<br />
ExportFilter: .+ .<br />
<br />
is implicitly in effect unless overriden by ExportFilter lines. Specifying no targets after the regex has the effect of not making files available to the worker at all, such as with:<br />
<br />
ExportFilter: -debuginfo-.*\.rpm$ <br />
ExportFilter: -debugsource-.*\.rpm$<br />
<br />
== PublishFilter ==<br />
Similar to ExportFilter, PublishFilter controls the copying of built packages into the repo space (e.g. /srv/obs/repos).<br />
<br />
== Order ==<br />
Some distributions might have problems during the chroot-setup<br />
when a cyclic dependency is found, eg A depends on B which depends<br />
on A. In this case the installer cannot know which to install first<br />
and manual intervention is needed. With this "Order"-Tag, you can<br />
specify an installation order.<br />
<br />
You may see a message like:<br />
cycle: libgtk2.0-0 -> libgtk2.0-bin<br />
breaking dependency libgtk2.0-0 -> libgtk2.0-bin<br />
<br />
If there is an error installing libgtk2.0-bin before libgtk2.0-0 then <br />
Order: libgtk2.0-0:libgtk2.0-bin<br />
will cause libgtk2.0-0 to be installed before libgtk2.0-bin<br />
<br />
Note that cycles can be longer A->B->C->D->A and you may need to say<br />
Order C:D A B<br />
Order D:A B<br />
This says that D, A and B depend on C but it doesn't say what order<br />
A and B should be installed in. That needs another rule.<br />
<br />
Another example:<br />
Order: libopenssl0_9_8:openssl-certs<br />
If openssl-certs needs to be installed, install libopenssl0_9_8 first.<br />
<br />
== VMinstall ==<br />
Like ''Support'': add these packages if you're "building" in a virtual machine. <br />
<br />
VMinstall: util-linux perl-base libdb-4_5 libvolume_id1 libsepol1<br />
<br />
== Optflags ==<br />
Default compiler flags. (Can be overwritten by specfile.)<br />
<br />
Optflags: i586 -march=i586 -mtune=i686 -fmessage-length=0<br />
<br />
== Release ==<br />
The BuildService sets the Release tag in spec files automatically. The format<br />
of the Release tag an be defined in the prjconf. Two magic strings are recognized:<br />
# CI_CNT is the number of commits<br />
# B_CNT is the number of rebuilds (when the rebuild is triggered).<br />
<br />
The default setting is<br />
<br />
Release: <CI_CNT>.<B_CNT><br />
<br />
Suppose the the rpm macro %{release_prefix} is defined in the spec<br />
file a custom format could look like this:<br />
<br />
Release: %%{?release_prefix}.<CI_CNT>.<B_CNT><br />
<br />
The same syntax can also directly be used from within your spec file. To insert a hard coded release-prefix 'j123', you can say<br />
<br />
Release: j123.<CI_CNT>.<B_CNT><br />
<br />
== FileProvides ==<br />
<br />
The build service ignores rpm file dependencies for performanane reasons. Since this may break some packages it's possible to manually add file provides via prjconf.<br />
<br />
Example: To make the build service believe that '/usr/bin/perl' is provided by<br />
the package 'camel' use the following line:<br />
FileProvides: /usr/bin/perl camel<br />
<br />
== Macros ==<br />
<br />
Macros are defined '''at the end''' of the prjconf to avoid misinterpretation (or in the Macros section between the Macros tag) <br />
<br />
Two options of Macro definitions are possible in the prjconf file:<br />
# Macro definition lines starting with %define are used inside the prjconf itself and for calculating the build dependencies of spec files. They are ''not'' available inside the build root.<br />
# Macro definitions after the '''Macros:''' are exported into the ''.rpmmacros'' file of the user used for building the package inside the build enviroment. Ie those are available for general use use in a spec file.<br />
<br />
=== %define Tag ===<br />
Use %define as usual with rpm, the user can define a variable and an associated value. </br><br />
All the features provided by rpm syntax are supported except :<br />
* cannot define a functions. <br />
* No call to an external command.<br />
<br />
%define _with_pulseaudio 1<br />
<br />
<br />
Defines a Macro %{_with_pulseaudio} with value 1. Useful for example to enable pulseaudio in your project. In that case you need to test the value of variable in your script.<br />
<br />
=== %bcond ===<br />
if the .spec file uses the following construct to enable conditional build:<br />
<br />
%bcond_with pulseaudio<br />
%if %{with pulseaudio}<br />
BuildRequires: pulseaudio-devel<br />
%endif<br />
<br />
'''WARNING''':<br />
<br />
The option is enabled because the variable is defined and this independently of what ever is its value.<br />
<br />
%define _with_pulseaudio 0 <span style="color: red">does '''not''' </span> disable the build option.<br />
#%%define _with_pulseaudio<br />
<br />
=== Macros after the ''Macros:''-Tag ===<br />
<br />
Macros defined in the Macros section or at the end of the prjconf are evaluated during the build process by opposition to the macros defined with %defined which are used by the OBS to calculate dependences before rpm build.<br />
<br />
Macros:<br />
... some macros ...<br />
:Macros<br />
<br />
in Macros sections and/or at the end of the prjconf contain a blocks macro definitions that are exported into the build environment. You can basically define anything here, including macros that are functions or call external commands since those macros are actually evaluated by rpmbuild. The ''define'' statement is not needed here, so just start with ''%macroname''.<br />
<br />
To stay with the simple example above, to not only tell the build service to install the pulseaudio-devel package but also have rpmbuild know to build with pulseaudio the following definition needs to be in the macro block as well:<br />
<br />
%_with_pulseaudio 1<br />
<br />
'''WARNING:'''<br />
<br />
rpm should follow common agreed rules which does not test the value of a given variable but the existence of the variable. I advise to prefer the same value that would be created by a %bcond and the rpm command line value. <br />
<br/><br />
I would also add command as setting a variable to "0", "no" or "--without-xxx" would still activate the option.<br />
# To deactivate that option comment the following line (changing variable value will have no effect) <br />
%_with_pulseaudio --with-pulseaudio<br />
<br />
* [http://rpm.org/user_doc/conditional_builds.html RPM conditional builds]<br />
* [https://github.com/rpm-software-management/rpm/blob/master/doc/manual/conditionalbuilds RPM manual conditional builds]<br />
<br />
* [https://github.com/rpm-software-management/rpm/blob/master/macros.in RPM manual macros]<br />
<br />
{{Info|Currently, those macro definitions can only be added at the end of the prjconf.}}</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=Fonts&diff=119611Fonts2017-06-06T08:25:19Z<p>Thomas-schraitle: Slightly rephrased paragraph</p>
<hr />
<div>{{Font navbar}}<br />
<br />
{{Intro|How to manage system fonts and configure font display results.}}<br />
<br />
{{Knowledge|<br />
*[[Portal:Tumbleweed|Tumbleweed]]<br />
*[[Portal:42.2|Leap 42.2]]<br />
*[[Portal:42.1|Leap 42.1]]<br />
*[[Portal:13.2|13.2]]<br />
|<br />
n/a<br />
|<br />
*[[openSUSE:Packaging_Fonts|Packaging Fonts]]<br />
}}<br />
<br />
== Fonts available in openSUSE ==<br />
<br />
openSUSE contains many high-quality, free and open source fonts.<br />
<br />
=== Installed by default ===<br />
<br />
=== Available in official repositories ===<br />
<br />
Since there are so many fonts and they can use a lot of disk space, most fonts are not installed by default. In YaST Software Management, you can search "font" or browse "Font" category to find all available fonts in official repositories.<br />
<br />
=== Available on openSUSE Build Service ===<br />
<br />
[[Package_repositories#Fonts|M17N:fonts]] repository provides a larger collection of fonts. If you would like to try new fonts, add the repository manually and update.<br />
<br />
== Manage fonts ==<br />
<br />
=== Find font files ===<br />
<br />
* System fonts must be installed in the <tt>/usr/share/fonts/</tt> directory. These fonts can be used by all users on the machine.<br />
<br />
* Personal fonts are usually installed in <tt>~/.fonts/</tt> directory. Only the user himself/herself can use it while other users cannot.<br />
<br />
=== Install fonts ===<br />
<br />
If the font you want to install is provided by openSUSE online repositories, use YaST or zypper to install the package.<br />
<br />
<pre><br />
sudo zypper install lato-fonts<br />
</pre><br />
<br />
If you have font files (*.otf, *.ttf), click to open the files with the font installation application. In KDE, The Font Install tool shows preview text of the font, and there are two buttons: install as system font and install as personal font. Installing as personal font is recommended if other users do not need it. You can also simply copy font files to ~/.fonts folder.<br />
<br />
Note: newly installed fonts are invisible until you restart applications or system.<br />
<br />
=== Manage fonts in KDE ===<br />
<br />
System Settings --> Fonts --> Font Management<br />
<br />
=== Manage fonts in GNOME ===<br />
<br />
GNOME doesn't officially have a font management tool. But there is a very good GTK+ font manager. You need to install the [http://software.opensuse.org/package/font-manager font-manager] package from OBS.<br />
<br />
== Configure default display fonts ==<br />
<br />
Your system is installed with a lot of fonts, but which one does the system use for your desktop user interface? What if you want to change it?<br />
<br />
The default font is selected by several conditions in the following order (later one overrides previous one):<br />
<br />
# Fontconfig<br />
## Configuration files of font packages <tt>/etc/fonts/config.d/</tt> (should NOT be edited)<br />
## Preset system font configuration file <tt>/etc/fonts/fonts.conf</tt> (should NOT be edited, edit <tt>/etc/fonts/local.conf</tt> instead)<br />
## Editable system font configuration file <tt>/etc/fonts/local.conf</tt><br />
## User font configuration file <tt>~/.config/fontconfig/fonts.conf</tt><br />
# KDE/GNOME desktop font settings. This will only affect Qt/GTK applications.<br />
# Application font settings.<br />
# Document / web page font settings.<br />
<br />
=== Fontconfig: sans, serif and mono fonts ===<br />
<br />
Sans Serif (sans-serif), Serif (serif) and Monospace (monospace) are three special font families. Usually, Sans Serif will be used as the default UI font while Monospace will be used for text editors and console.<br />
<br />
[[Fontconfig]] decides which actual font should be Sans Serif, Serif and Monospace font. It is a rule set in XML configuration files.<br />
<br />
If you don't want to edit the configuration files, you can use a GUI frontend of fontconfig:<br />
<br />
* YaST --> Fonts, modify system font configuration file.<br />
* [[Fontweak]], modify personal font configuration file.<br />
<br />
=== KDE user interface fonts ===<br />
<br />
System Settings --> Fonts --> Font Settings (ONLY affect KDE/Qt applications)<br />
<br />
System Settings --> Application Styles --> GNOME/GTK Application Styles (Change GNOME/GTK application default fonts)<br />
<br />
=== GNOME user interface fonts ===<br />
<br />
GNOME doesn't provide options to change default UI fonts and it doesn't follow fontconfig rules. You need to install [http://software.opensuse.org/package/gnome-tweak-tool GNOME Tweak Tool]. These settings only affect GTK applications.<br />
<br />
=== Firefox default display fonts ===<br />
<br />
Firefox respects fontconfig settings. By default, it uses the Sans Serif font of the system for UI and default web page font. You can also change different Sans Serif, Serif and Monospace fonts in Firefox Preferences.<br />
<br />
Note: most websites have their own font styles, so each web page can have different display fonts.<br />
<br />
=== LibreOffice default document fonts ===<br />
<br />
LibreOffice respects fontconfig settings. It uses the Sans Serif font of the system for UI and default document font. You can also change different fonts for default, paragraph, heading texts.<br />
<br />
Tools --> Options --> LibreOffice Writer Document --> Standard fonts (fonts of different text styles)<br />
<br />
Tools --> Options --> General --> Fonts (replace MS Windows fonts with system fonts, source code fonts)<br />
<br />
==See also==<br />
<br />
=== Related articles ===<br />
<br />
*[[openSUSE:Packaging_Fonts]]<br />
<br />
===External links===<br />
* [https://wiki.archlinux.org/index.php/fonts Fonts], ArchWiki<br />
* [https://wiki.ubuntu.com/Fonts Fonts], Ubuntu Wiki<br />
<br />
{{IW|Fonts}}</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=Fonts&diff=119610Fonts2017-06-06T08:22:41Z<p>Thomas-schraitle: Use <tt> for paths</p>
<hr />
<div>{{Font navbar}}<br />
<br />
{{Intro|How to manage system fonts and configure font display results.}}<br />
<br />
{{Knowledge|<br />
*[[Portal:Tumbleweed|Tumbleweed]]<br />
*[[Portal:42.2|Leap 42.2]]<br />
*[[Portal:42.1|Leap 42.1]]<br />
*[[Portal:13.2|13.2]]<br />
|<br />
n/a<br />
|<br />
*[[openSUSE:Packaging_Fonts|Packaging Fonts]]<br />
}}<br />
<br />
== Fonts available in openSUSE ==<br />
<br />
openSUSE contains many high-quality, free and open source fonts.<br />
<br />
=== Installed by default ===<br />
<br />
=== Available in official repositories ===<br />
<br />
Since there are so many fonts and they can use a lot of disk space, most fonts are not installed by default. In YaST Software Management, you can search "font" or browse "Font" category to find all available fonts in official repositories.<br />
<br />
=== Available on openSUSE Build Service ===<br />
<br />
[[Package_repositories#Fonts|M17N:fonts]] repository provides a larger collection of fonts. If you would like to try new fonts, add the repository manually and update.<br />
<br />
== Manage fonts ==<br />
<br />
=== Find font files ===<br />
<br />
* System fonts must be installed in the <tt>/usr/share/fonts/</tt> directory. These fonts can be used by all users on the machine.<br />
<br />
* Personal fonts are usually installed in <tt>~/.fonts/</tt> directory. Only the user himself/herself can use it while other users cannot.<br />
<br />
=== Install fonts ===<br />
<br />
If the font you want to install is provided by openSUSE online repositories, use YaST or zypper to install the package.<br />
<br />
<pre><br />
sudo zypper install lato-fonts<br />
</pre><br />
<br />
If you have font files (*.otf, *.ttf), click to open the files with the font installation application. In KDE, The Font Install tool shows preview text of the font, and there are two buttons: install as system font and install as personal font. Installing as personal font is recommended if other users do not need it. You can also simply copy font files to ~/.fonts folder.<br />
<br />
Note: newly installed fonts are invisible until you restart applications or system.<br />
<br />
=== Manage fonts in KDE ===<br />
<br />
System Settings --> Fonts --> Font Management<br />
<br />
=== Manage fonts in GNOME ===<br />
<br />
GNOME doesn't officially have a font management tool. But there is a very good GTK+ font manager. You need to install the [http://software.opensuse.org/package/font-manager font-manager] package from OBS.<br />
<br />
== Configure default display fonts ==<br />
<br />
Your system installed with a lot of fonts. But which one should the system use for your desktop user interface? What if you want to change it?<br />
<br />
The default font is decided by several conditions in the following order: (later one overrides previous one)<br />
<br />
# Fontconfig<br />
## Configuration files of font packages <tt>/etc/fonts/config.d/</tt> (should NOT be edited)<br />
## Preset system font configuration file <tt>/etc/fonts/fonts.conf</tt> (should NOT be edited, edit <tt>/etc/fonts/local.conf</tt> instead)<br />
## Editable system font configuration file <tt>/etc/fonts/local.conf</tt><br />
## User font configuration file <tt>~/.config/fontconfig/fonts.conf</tt><br />
# KDE/GNOME desktop font settings. This will only affect Qt/GTK applications.<br />
# Application font settings.<br />
# Document / web page font settings.<br />
<br />
=== Fontconfig: sans, serif and mono fonts ===<br />
<br />
Sans Serif (sans-serif), Serif (serif) and Monospace (monospace) are three special font families. Usually, Sans Serif will be used as the default UI font while Monospace will be used for text editors and console.<br />
<br />
[[Fontconfig]] decides which actual font should be Sans Serif, Serif and Monospace font. It is a rule set in XML configuration files.<br />
<br />
If you don't want to edit the configuration files, you can use a GUI frontend of fontconfig:<br />
<br />
* YaST --> Fonts, modify system font configuration file.<br />
* [[Fontweak]], modify personal font configuration file.<br />
<br />
=== KDE user interface fonts ===<br />
<br />
System Settings --> Fonts --> Font Settings (ONLY affect KDE/Qt applications)<br />
<br />
System Settings --> Application Styles --> GNOME/GTK Application Styles (Change GNOME/GTK application default fonts)<br />
<br />
=== GNOME user interface fonts ===<br />
<br />
GNOME doesn't provide options to change default UI fonts and it doesn't follow fontconfig rules. You need to install [http://software.opensuse.org/package/gnome-tweak-tool GNOME Tweak Tool]. These settings only affect GTK applications.<br />
<br />
=== Firefox default display fonts ===<br />
<br />
Firefox respects fontconfig settings. By default, it uses the Sans Serif font of the system for UI and default web page font. You can also change different Sans Serif, Serif and Monospace fonts in Firefox Preferences.<br />
<br />
Note: most websites have their own font styles, so each web page can have different display fonts.<br />
<br />
=== LibreOffice default document fonts ===<br />
<br />
LibreOffice respects fontconfig settings. It uses the Sans Serif font of the system for UI and default document font. You can also change different fonts for default, paragraph, heading texts.<br />
<br />
Tools --> Options --> LibreOffice Writer Document --> Standard fonts (fonts of different text styles)<br />
<br />
Tools --> Options --> General --> Fonts (replace MS Windows fonts with system fonts, source code fonts)<br />
<br />
==See also==<br />
<br />
=== Related articles ===<br />
<br />
*[[openSUSE:Packaging_Fonts]]<br />
<br />
===External links===<br />
* [https://wiki.archlinux.org/index.php/fonts Fonts], ArchWiki<br />
* [https://wiki.ubuntu.com/Fonts Fonts], Ubuntu Wiki<br />
<br />
{{IW|Fonts}}</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=Fonts&diff=119609Fonts2017-06-06T08:19:39Z<p>Thomas-schraitle: Correct title to make it consistent with other titles; use bullet list</p>
<hr />
<div>{{Font navbar}}<br />
<br />
{{Intro|How to manage system fonts and configure font display results.}}<br />
<br />
{{Knowledge|<br />
*[[Portal:Tumbleweed|Tumbleweed]]<br />
*[[Portal:42.2|Leap 42.2]]<br />
*[[Portal:42.1|Leap 42.1]]<br />
*[[Portal:13.2|13.2]]<br />
|<br />
n/a<br />
|<br />
*[[openSUSE:Packaging_Fonts|Packaging Fonts]]<br />
}}<br />
<br />
== Fonts available in openSUSE ==<br />
<br />
openSUSE contains many high-quality, free and open source fonts.<br />
<br />
=== Installed by default ===<br />
<br />
=== Available in official repositories ===<br />
<br />
Since there are so many fonts and they can use a lot of disk space, most fonts are not installed by default. In YaST Software Management, you can search "font" or browse "Font" category to find all available fonts in official repositories.<br />
<br />
=== Available on openSUSE Build Service ===<br />
<br />
[[Package_repositories#Fonts|M17N:fonts]] repository provides a larger collection of fonts. If you would like to try new fonts, add the repository manually and update.<br />
<br />
== Manage fonts ==<br />
<br />
=== Find font files ===<br />
<br />
* System fonts must be installed in the <tt>/usr/share/fonts/</tt> directory. These fonts can be used by all users on the machine.<br />
<br />
* Personal fonts are usually installed in <tt>~/.fonts/</tt> directory. Only the user himself/herself can use it while other users cannot.<br />
<br />
=== Install fonts ===<br />
<br />
If the font you want to install is provided by openSUSE online repositories, use YaST or zypper to install the package.<br />
<br />
<pre><br />
sudo zypper install lato-fonts<br />
</pre><br />
<br />
If you have font files (*.otf, *.ttf), click to open the files with the font installation application. In KDE, The Font Install tool shows preview text of the font, and there are two buttons: install as system font and install as personal font. Installing as personal font is recommended if other users do not need it. You can also simply copy font files to ~/.fonts folder.<br />
<br />
Note: newly installed fonts are invisible until you restart applications or system.<br />
<br />
=== Manage fonts in KDE ===<br />
<br />
System Settings --> Fonts --> Font Management<br />
<br />
=== Manage fonts in GNOME ===<br />
<br />
GNOME doesn't officially have a font management tool. But there is a very good GTK+ font manager. You need to install the [http://software.opensuse.org/package/font-manager font-manager] package from OBS.<br />
<br />
== Configure default display fonts ==<br />
<br />
Your system installed with a lot of fonts. But which one should the system use for your desktop user interface? What if you want to change it?<br />
<br />
The default font is decided by several conditions in the following order: (later one overrides previous one)<br />
<br />
# Fontconfig<br />
## Configuration files of font packages /etc/fonts/config.d (should NOT be edited)<br />
## Preset system font configuration file /etc/fonts/fonts.conf (should NOT be edited, edit local.conf instead)<br />
## Editable system font configuration file /etc/fonts/local.conf<br />
## User font configuration file ~/.config/fontconfig/fonts.conf<br />
# KDE/GNOME desktop font settings. This will only affect Qt/GTK applications.<br />
# Application font settings.<br />
# Document / web page font settings.<br />
<br />
=== Fontconfig: sans, serif and mono fonts ===<br />
<br />
Sans Serif (sans-serif), Serif (serif) and Monospace (monospace) are three special font families. Usually, Sans Serif will be used as the default UI font while Monospace will be used for text editors and console.<br />
<br />
[[Fontconfig]] decides which actual font should be Sans Serif, Serif and Monospace font. It is a rule set in XML configuration files.<br />
<br />
If you don't want to edit the configuration files, you can use a GUI frontend of fontconfig:<br />
<br />
* YaST --> Fonts, modify system font configuration file.<br />
* [[Fontweak]], modify personal font configuration file.<br />
<br />
=== KDE user interface fonts ===<br />
<br />
System Settings --> Fonts --> Font Settings (ONLY affect KDE/Qt applications)<br />
<br />
System Settings --> Application Styles --> GNOME/GTK Application Styles (Change GNOME/GTK application default fonts)<br />
<br />
=== GNOME user interface fonts ===<br />
<br />
GNOME doesn't provide options to change default UI fonts and it doesn't follow fontconfig rules. You need to install [http://software.opensuse.org/package/gnome-tweak-tool GNOME Tweak Tool]. These settings only affect GTK applications.<br />
<br />
=== Firefox default display fonts ===<br />
<br />
Firefox respects fontconfig settings. By default, it uses the Sans Serif font of the system for UI and default web page font. You can also change different Sans Serif, Serif and Monospace fonts in Firefox Preferences.<br />
<br />
Note: most websites have their own font styles, so each web page can have different display fonts.<br />
<br />
=== LibreOffice default document fonts ===<br />
<br />
LibreOffice respects fontconfig settings. It uses the Sans Serif font of the system for UI and default document font. You can also change different fonts for default, paragraph, heading texts.<br />
<br />
Tools --> Options --> LibreOffice Writer Document --> Standard fonts (fonts of different text styles)<br />
<br />
Tools --> Options --> General --> Fonts (replace MS Windows fonts with system fonts, source code fonts)<br />
<br />
==See also==<br />
<br />
=== Related articles ===<br />
<br />
*[[openSUSE:Packaging_Fonts]]<br />
<br />
===External links===<br />
* [https://wiki.archlinux.org/index.php/fonts Fonts], ArchWiki<br />
* [https://wiki.ubuntu.com/Fonts Fonts], Ubuntu Wiki<br />
<br />
{{IW|Fonts}}</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=Fonts&diff=119608Fonts2017-06-06T07:35:55Z<p>Thomas-schraitle: Cleaned up Knowledge table</p>
<hr />
<div>{{Font navbar}}<br />
<br />
{{Intro|How to manage system fonts and configure font display results.}}<br />
<br />
{{Knowledge|<br />
*[[Portal:Tumbleweed|Tumbleweed]]<br />
*[[Portal:42.2|Leap 42.2]]<br />
*[[Portal:42.1|Leap 42.1]]<br />
*[[Portal:13.2|13.2]]<br />
|<br />
n/a<br />
|<br />
*[[openSUSE:Packaging_Fonts|Packaging Fonts]]<br />
}}<br />
<br />
== Fonts available in openSUSE ==<br />
<br />
openSUSE contains many high-quality, free and open source fonts.<br />
<br />
=== Installed by default ===<br />
<br />
=== Available in official repositories ===<br />
<br />
Since there are so many fonts and they can use a lot of disk space, most fonts are not installed by default. In YaST Software Management, you can search "font" or browse "Font" category to find all available fonts in official repositories.<br />
<br />
=== Available on openSUSE Build Service ===<br />
<br />
[[Package_repositories#Fonts|M17N:fonts]] repository provides a larger collection of fonts. If you would like to try new fonts, add the repository manually and update.<br />
<br />
== Manage fonts ==<br />
<br />
=== Where are the font files? ===<br />
<br />
System fonts must be installed in the <tt>/usr/share/fonts/</tt> directory. These fonts can be used by all users on the machine.<br />
<br />
Personal fonts are usually installed in <tt>~/.fonts/</tt> directory. Only the user himself/herself can use it while other users cannot.<br />
<br />
=== Install fonts ===<br />
<br />
If the font you want to install is provided by openSUSE online repositories, use YaST or zypper to install the package.<br />
<br />
<pre><br />
sudo zypper install lato-fonts<br />
</pre><br />
<br />
If you have font files (*.otf, *.ttf), click to open the files with the font installation application. In KDE, The Font Install tool shows preview text of the font, and there are two buttons: install as system font and install as personal font. Installing as personal font is recommended if other users do not need it. You can also simply copy font files to ~/.fonts folder.<br />
<br />
Note: newly installed fonts are invisible until you restart applications or system.<br />
<br />
=== Manage fonts in KDE ===<br />
<br />
System Settings --> Fonts --> Font Management<br />
<br />
=== Manage fonts in GNOME ===<br />
<br />
GNOME doesn't officially have a font management tool. But there is a very good GTK+ font manager. You need to install the [http://software.opensuse.org/package/font-manager font-manager] package from OBS.<br />
<br />
== Configure default display fonts ==<br />
<br />
Your system installed with a lot of fonts. But which one should the system use for your desktop user interface? What if you want to change it?<br />
<br />
The default font is decided by several conditions in the following order: (later one overrides previous one)<br />
<br />
# Fontconfig<br />
## Configuration files of font packages /etc/fonts/config.d (should NOT be edited)<br />
## Preset system font configuration file /etc/fonts/fonts.conf (should NOT be edited, edit local.conf instead)<br />
## Editable system font configuration file /etc/fonts/local.conf<br />
## User font configuration file ~/.config/fontconfig/fonts.conf<br />
# KDE/GNOME desktop font settings. This will only affect Qt/GTK applications.<br />
# Application font settings.<br />
# Document / web page font settings.<br />
<br />
=== Fontconfig: sans, serif and mono fonts ===<br />
<br />
Sans Serif (sans-serif), Serif (serif) and Monospace (monospace) are three special font families. Usually, Sans Serif will be used as the default UI font while Monospace will be used for text editors and console.<br />
<br />
[[Fontconfig]] decides which actual font should be Sans Serif, Serif and Monospace font. It is a rule set in XML configuration files.<br />
<br />
If you don't want to edit the configuration files, you can use a GUI frontend of fontconfig:<br />
<br />
* YaST --> Fonts, modify system font configuration file.<br />
* [[Fontweak]], modify personal font configuration file.<br />
<br />
=== KDE user interface fonts ===<br />
<br />
System Settings --> Fonts --> Font Settings (ONLY affect KDE/Qt applications)<br />
<br />
System Settings --> Application Styles --> GNOME/GTK Application Styles (Change GNOME/GTK application default fonts)<br />
<br />
=== GNOME user interface fonts ===<br />
<br />
GNOME doesn't provide options to change default UI fonts and it doesn't follow fontconfig rules. You need to install [http://software.opensuse.org/package/gnome-tweak-tool GNOME Tweak Tool]. These settings only affect GTK applications.<br />
<br />
=== Firefox default display fonts ===<br />
<br />
Firefox respects fontconfig settings. By default, it uses the Sans Serif font of the system for UI and default web page font. You can also change different Sans Serif, Serif and Monospace fonts in Firefox Preferences.<br />
<br />
Note: most websites have their own font styles, so each web page can have different display fonts.<br />
<br />
=== LibreOffice default document fonts ===<br />
<br />
LibreOffice respects fontconfig settings. It uses the Sans Serif font of the system for UI and default document font. You can also change different fonts for default, paragraph, heading texts.<br />
<br />
Tools --> Options --> LibreOffice Writer Document --> Standard fonts (fonts of different text styles)<br />
<br />
Tools --> Options --> General --> Fonts (replace MS Windows fonts with system fonts, source code fonts)<br />
<br />
==See also==<br />
<br />
=== Related articles ===<br />
<br />
*[[openSUSE:Packaging_Fonts]]<br />
<br />
===External links===<br />
* [https://wiki.archlinux.org/index.php/fonts Fonts], ArchWiki<br />
* [https://wiki.ubuntu.com/Fonts Fonts], Ubuntu Wiki<br />
<br />
{{IW|Fonts}}</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=Fonts&diff=119607Fonts2017-06-06T07:27:18Z<p>Thomas-schraitle: Cleaned up "Related articles" section, add link to Packaging Fonts</p>
<hr />
<div>{{Font navbar}}<br />
<br />
{{Intro|How to manage system fonts and configure font display results.}}<br />
<br />
{{Knowledge|<br />
*[[Portal:Tumbleweed|Tumbleweed]]<br />
*[[Portal:42.2|Leap 42.2]]<br />
*[[Portal:42.1|Leap 42.1]]<br />
*[[Portal:13.2|13.2]]<br />
|<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
|<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
}}<br />
<br />
== Fonts available in openSUSE ==<br />
<br />
openSUSE contains many high-quality, free and open source fonts.<br />
<br />
=== Installed by default ===<br />
<br />
=== Available in official repositories ===<br />
<br />
Since there are so many fonts and they can use a lot of disk space, most fonts are not installed by default. In YaST Software Management, you can search "font" or browse "Font" category to find all available fonts in official repositories.<br />
<br />
=== Available on openSUSE Build Service ===<br />
<br />
[[Package_repositories#Fonts|M17N:fonts]] repository provides a larger collection of fonts. If you would like to try new fonts, add the repository manually and update.<br />
<br />
== Manage fonts ==<br />
<br />
=== Where are the font files? ===<br />
<br />
System fonts must be installed in the <tt>/usr/share/fonts/</tt> directory. These fonts can be used by all users on the machine.<br />
<br />
Personal fonts are usually installed in <tt>~/.fonts/</tt> directory. Only the user himself/herself can use it while other users cannot.<br />
<br />
=== Install fonts ===<br />
<br />
If the font you want to install is provided by openSUSE online repositories, use YaST or zypper to install the package.<br />
<br />
<pre><br />
sudo zypper install lato-fonts<br />
</pre><br />
<br />
If you have font files (*.otf, *.ttf), click to open the files with the font installation application. In KDE, The Font Install tool shows preview text of the font, and there are two buttons: install as system font and install as personal font. Installing as personal font is recommended if other users do not need it. You can also simply copy font files to ~/.fonts folder.<br />
<br />
Note: newly installed fonts are invisible until you restart applications or system.<br />
<br />
=== Manage fonts in KDE ===<br />
<br />
System Settings --> Fonts --> Font Management<br />
<br />
=== Manage fonts in GNOME ===<br />
<br />
GNOME doesn't officially have a font management tool. But there is a very good GTK+ font manager. You need to install the [http://software.opensuse.org/package/font-manager font-manager] package from OBS.<br />
<br />
== Configure default display fonts ==<br />
<br />
Your system installed with a lot of fonts. But which one should the system use for your desktop user interface? What if you want to change it?<br />
<br />
The default font is decided by several conditions in the following order: (later one overrides previous one)<br />
<br />
# Fontconfig<br />
## Configuration files of font packages /etc/fonts/config.d (should NOT be edited)<br />
## Preset system font configuration file /etc/fonts/fonts.conf (should NOT be edited, edit local.conf instead)<br />
## Editable system font configuration file /etc/fonts/local.conf<br />
## User font configuration file ~/.config/fontconfig/fonts.conf<br />
# KDE/GNOME desktop font settings. This will only affect Qt/GTK applications.<br />
# Application font settings.<br />
# Document / web page font settings.<br />
<br />
=== Fontconfig: sans, serif and mono fonts ===<br />
<br />
Sans Serif (sans-serif), Serif (serif) and Monospace (monospace) are three special font families. Usually, Sans Serif will be used as the default UI font while Monospace will be used for text editors and console.<br />
<br />
[[Fontconfig]] decides which actual font should be Sans Serif, Serif and Monospace font. It is a rule set in XML configuration files.<br />
<br />
If you don't want to edit the configuration files, you can use a GUI frontend of fontconfig:<br />
<br />
* YaST --> Fonts, modify system font configuration file.<br />
* [[Fontweak]], modify personal font configuration file.<br />
<br />
=== KDE user interface fonts ===<br />
<br />
System Settings --> Fonts --> Font Settings (ONLY affect KDE/Qt applications)<br />
<br />
System Settings --> Application Styles --> GNOME/GTK Application Styles (Change GNOME/GTK application default fonts)<br />
<br />
=== GNOME user interface fonts ===<br />
<br />
GNOME doesn't provide options to change default UI fonts and it doesn't follow fontconfig rules. You need to install [http://software.opensuse.org/package/gnome-tweak-tool GNOME Tweak Tool]. These settings only affect GTK applications.<br />
<br />
=== Firefox default display fonts ===<br />
<br />
Firefox respects fontconfig settings. By default, it uses the Sans Serif font of the system for UI and default web page font. You can also change different Sans Serif, Serif and Monospace fonts in Firefox Preferences.<br />
<br />
Note: most websites have their own font styles, so each web page can have different display fonts.<br />
<br />
=== LibreOffice default document fonts ===<br />
<br />
LibreOffice respects fontconfig settings. It uses the Sans Serif font of the system for UI and default document font. You can also change different fonts for default, paragraph, heading texts.<br />
<br />
Tools --> Options --> LibreOffice Writer Document --> Standard fonts (fonts of different text styles)<br />
<br />
Tools --> Options --> General --> Fonts (replace MS Windows fonts with system fonts, source code fonts)<br />
<br />
==See also==<br />
<br />
=== Related articles ===<br />
<br />
*[[openSUSE:Packaging_Fonts]]<br />
<br />
===External links===<br />
* [https://wiki.archlinux.org/index.php/fonts Fonts], ArchWiki<br />
* [https://wiki.ubuntu.com/Fonts Fonts], Ubuntu Wiki<br />
<br />
{{IW|Fonts}}</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=Fonts&diff=119606Fonts2017-06-06T07:23:34Z<p>Thomas-schraitle: Use <tt> for paths</p>
<hr />
<div>{{Font navbar}}<br />
<br />
{{Intro|How to manage system fonts and configure font display results.}}<br />
<br />
{{Knowledge|<br />
*[[Portal:Tumbleweed|Tumbleweed]]<br />
*[[Portal:42.2|Leap 42.2]]<br />
*[[Portal:42.1|Leap 42.1]]<br />
*[[Portal:13.2|13.2]]<br />
|<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
|<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
}}<br />
<br />
== Fonts available in openSUSE ==<br />
<br />
openSUSE contains many high-quality, free and open source fonts.<br />
<br />
=== Installed by default ===<br />
<br />
=== Available in official repositories ===<br />
<br />
Since there are so many fonts and they can use a lot of disk space, most fonts are not installed by default. In YaST Software Management, you can search "font" or browse "Font" category to find all available fonts in official repositories.<br />
<br />
=== Available on openSUSE Build Service ===<br />
<br />
[[Package_repositories#Fonts|M17N:fonts]] repository provides a larger collection of fonts. If you would like to try new fonts, add the repository manually and update.<br />
<br />
== Manage fonts ==<br />
<br />
=== Where are the font files? ===<br />
<br />
System fonts must be installed in the <tt>/usr/share/fonts/</tt> directory. These fonts can be used by all users on the machine.<br />
<br />
Personal fonts are usually installed in <tt>~/.fonts/</tt> directory. Only the user himself/herself can use it while other users cannot.<br />
<br />
=== Install fonts ===<br />
<br />
If the font you want to install is provided by openSUSE online repositories, use YaST or zypper to install the package.<br />
<br />
<pre><br />
sudo zypper install lato-fonts<br />
</pre><br />
<br />
If you have font files (*.otf, *.ttf), click to open the files with the font installation application. In KDE, The Font Install tool shows preview text of the font, and there are two buttons: install as system font and install as personal font. Installing as personal font is recommended if other users do not need it. You can also simply copy font files to ~/.fonts folder.<br />
<br />
Note: newly installed fonts are invisible until you restart applications or system.<br />
<br />
=== Manage fonts in KDE ===<br />
<br />
System Settings --> Fonts --> Font Management<br />
<br />
=== Manage fonts in GNOME ===<br />
<br />
GNOME doesn't officially have a font management tool. But there is a very good GTK+ font manager. You need to install the [http://software.opensuse.org/package/font-manager font-manager] package from OBS.<br />
<br />
== Configure default display fonts ==<br />
<br />
Your system installed with a lot of fonts. But which one should the system use for your desktop user interface? What if you want to change it?<br />
<br />
The default font is decided by several conditions in the following order: (later one overrides previous one)<br />
<br />
# Fontconfig<br />
## Configuration files of font packages /etc/fonts/config.d (should NOT be edited)<br />
## Preset system font configuration file /etc/fonts/fonts.conf (should NOT be edited, edit local.conf instead)<br />
## Editable system font configuration file /etc/fonts/local.conf<br />
## User font configuration file ~/.config/fontconfig/fonts.conf<br />
# KDE/GNOME desktop font settings. This will only affect Qt/GTK applications.<br />
# Application font settings.<br />
# Document / web page font settings.<br />
<br />
=== Fontconfig: sans, serif and mono fonts ===<br />
<br />
Sans Serif (sans-serif), Serif (serif) and Monospace (monospace) are three special font families. Usually, Sans Serif will be used as the default UI font while Monospace will be used for text editors and console.<br />
<br />
[[Fontconfig]] decides which actual font should be Sans Serif, Serif and Monospace font. It is a rule set in XML configuration files.<br />
<br />
If you don't want to edit the configuration files, you can use a GUI frontend of fontconfig:<br />
<br />
* YaST --> Fonts, modify system font configuration file.<br />
* [[Fontweak]], modify personal font configuration file.<br />
<br />
=== KDE user interface fonts ===<br />
<br />
System Settings --> Fonts --> Font Settings (ONLY affect KDE/Qt applications)<br />
<br />
System Settings --> Application Styles --> GNOME/GTK Application Styles (Change GNOME/GTK application default fonts)<br />
<br />
=== GNOME user interface fonts ===<br />
<br />
GNOME doesn't provide options to change default UI fonts and it doesn't follow fontconfig rules. You need to install [http://software.opensuse.org/package/gnome-tweak-tool GNOME Tweak Tool]. These settings only affect GTK applications.<br />
<br />
=== Firefox default display fonts ===<br />
<br />
Firefox respects fontconfig settings. By default, it uses the Sans Serif font of the system for UI and default web page font. You can also change different Sans Serif, Serif and Monospace fonts in Firefox Preferences.<br />
<br />
Note: most websites have their own font styles, so each web page can have different display fonts.<br />
<br />
=== LibreOffice default document fonts ===<br />
<br />
LibreOffice respects fontconfig settings. It uses the Sans Serif font of the system for UI and default document font. You can also change different fonts for default, paragraph, heading texts.<br />
<br />
Tools --> Options --> LibreOffice Writer Document --> Standard fonts (fonts of different text styles)<br />
<br />
Tools --> Options --> General --> Fonts (replace MS Windows fonts with system fonts, source code fonts)<br />
<br />
==See also==<br />
<br />
=== Related articles ===<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
*[[Main Page]]<br />
<br />
===External links===<br />
* [https://wiki.archlinux.org/index.php/fonts Fonts], ArchWiki<br />
* [https://wiki.ubuntu.com/Fonts Fonts], Ubuntu Wiki<br />
<br />
{{IW|Fonts}}</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=119443openSUSE:Packaging XML Schemas and Stylesheets2017-05-01T22:30:46Z<p>Thomas-schraitle: Add paragraph to query the main catalog only</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependant.<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal.<br />
<br />
Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example.<br />
<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add the source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=119442openSUSE:Packaging XML Schemas and Stylesheets2017-05-01T22:26:59Z<p>Thomas-schraitle: Slightly rephrase wording</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependant.<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>"-//OASIS//DTD DocBook XML V4.5//EN"</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, query the XML catalog and use the command <tt>xmlcatalog</tt>:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal.<br />
<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example.<br />
<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add the source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=119389openSUSE:Packaging XML Schemas and Stylesheets2017-04-26T12:38:59Z<p>Thomas-schraitle: Add some benefits of XML catalogs</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
Accessing resources as paths can give you some problems:<br />
<br />
* Paths are platform dependant.<br />
* Some (older) operating systems does not distinguish between uppercase or lowercase paths.<br />
* Paths can change<br />
<br />
XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:<br />
<br />
* '''Speed''': You don't download resources each time you process your XML documents, but are redirected to a local path.<br />
* '''Exchangeability''': it makes exchange between different operating systems much easier as you can rely on general URIs.<br />
* '''Centralization''': with XML catalogs, you have ''one'' central place to configure your generic URIs<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>-//OASIS//DTD DocBook XML V4.5//EN</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, use this command:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
Whenever a XML document refers to this public identifier, it will receive the local path <tt>/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd</tt>.<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal.<br />
<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example.<br />
<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
<ol><li>Add the source line with the name of your XML catalog file, for example:<br />
<pre>Source1: %{name}.xml</pre></li><br />
<li>Require at least <tt>sgml-skel >= 0.7</tt>:<br />
<pre>Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7</pre></li><br />
<li>Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
<pre>%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog</pre></li><br />
<li>Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
<pre>%config %{xml_sysconf_dir}/catalog.d/%{name}.xml</pre></li></ol><br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=119377openSUSE:Packaging XML Schemas and Stylesheets2017-04-25T10:06:08Z<p>Thomas-schraitle: Fix some numbering problems.</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
XML catalogs are meant as a "mapping table" between URIs and local paths.<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>-//OASIS//DTD DocBook XML V4.5//EN</tt>. However, this is an ''identifier'' which does not define ''where'' the DTD is really stored. To get the real path, use this command:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt>.<br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names to distinguish them.<br />
* a generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal.<br />
<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>foo</tt>, name your catalog file <tt>foo.xml</tt>.<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example.<br />
<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
# Add the source line with the name of your XML catalog file, for example:<br />
Source1: %{name}.xml<br />
# Require at least <tt>sgml-skel >= 0.7</tt>:<br />
Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7<br />
# Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog<br />
# Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
%config %{xml_sysconf_dir}/catalog.d/%{name}.xml<br />
<br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_XML_Schemas_and_Stylesheets&diff=119376openSUSE:Packaging XML Schemas and Stylesheets2017-04-25T10:02:05Z<p>Thomas-schraitle: Add new packaging guide about how to use XML catalogs with schemas and stylesheets</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging XML Schemas and Stylesheets''' is a step by step introduction on how to build packages for openSUSE which XML catalog support using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.<br />
<br />
== XML Catalogs ==<br />
XML catalogs are meant as a "mapping table" between URIs and local paths.<br />
<br />
For example, the official public identifier for DocBook V4.5 is <tt>-//OASIS//DTD DocBook XML V4.5//EN</tt>. However, this is an *identifier* which does not define *where* the DTD is really stored. To get the real path, use this command:<br />
<br />
<pre><br />
$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"<br />
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd<br />
</pre><br />
<br />
<br />
== Concept ==<br />
The XML catalog concept on SUSE consists of three catalogs:<br />
<br />
* a main catalog, located in <tt>/etc/xml/catalog</tt><br />
* subcatalogs, which are placed under the directory <tt>/etc/xml/catalog.d/</tt>. The subcatalogs are usually named after their package names.<br />
* generated XML catalog <tt>/etc/xml/catalog-d.xml</tt> which is rewritten during installation, update, and removal.<br />
<br />
<br />
== Add XML Catalog Support ==<br />
Use the following steps to add XML catalog support to your package:<br />
<br />
=== Step 1: Prepare Your XML Catalog ===<br />
<br />
# Create a XML catalog file and name it like your RPM package. For example, if your RPM package is <tt>docbook_5</tt>, name your catalog file <tt>docbook_5.xml</tt>.<br />
<br />
# Insert the URIs, public identifiers etc. in your catalog. See [https://build.opensuse.org/package/view_file/Publishing/docbook_5/docbook_5.xml docbook_5.xml] as an example.<br />
<br />
<br />
=== Step 2: Change your Spec File ===<br />
<br />
# Add the source line with the name of your XML catalog file, for example:<br />
Source1: %{name}.xml<br />
# Require at least <tt>sgml-skel >= 0.7</tt>:<br />
Requires: sgml-skel >= 0.7<br />
Requires(post): sgml-skel >= 0.7<br />
Requires(postun): sgml-skel >= 0.7<br />
# Add <tt>%post</tt> and <tt>%postun</tt> sections:<br />
%post<br />
update-xml-catalog<br />
%postun<br />
update-xml-catalog<br />
# Add the XML catalog as <tt>%config</tt> in the <tt>%files</tt> section:<br />
%config %{xml_sysconf_dir}/catalog.d/%{name}.xml<br />
<br />
<br />
=== Step 3: Build and Test it ===<br />
<br />
# Install your RPM package and query the catalog with <tt>xmlcatalog</tt> (see above).<br />
# Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.<br />
# Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Python&diff=119145openSUSE:Packaging Python2017-03-13T11:35:44Z<p>Thomas-schraitle: Integrate into Packaging category</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging Python''' is a step by step introduction on how to build Python software packages for openSUSE and others using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== python single-spec ==<br />
{{Warning|Recently the maintainers of devel:languages:python, the main development project for python packages within openSUSE, changed to a 'single-spec' approach for providing python2 + python3 variants from a single source spec file. The wiki has not yet been fully updated, see the separate page [[openSUSE:Packaging Python Singlespec]]}}<br />
<br />
== The fast and automated way ==<br />
<br />
Lets suppose you want to package zope.interface and you don't know how it is named exactly or where to download from. First of all, you can search for it with py2pack, which can be found in the python-py2pack package and download the source tarball automatically with it if you found the correct module:<br />
<br />
<div class="shell">$ py2pack search zope.interface<pre>searching for module zope.interface...<br />
found zope.interface-3.6.1</pre><!--<br />
-->$ py2pack fetch zope.interface<pre>downloading package zope.interface-3.6.1...<br />
from http://pypi.python.org/packages/source/z/zope.interface/zope.interface-3.6.1.tar.gz</pre></div><br />
<br />
As a next step you may want to generate a package recipe for your distribution. For RPM-based distributions, you want to generate a spec file named python-zopeinterface.spec:<br />
<br />
<div class="shell">$ py2pack generate zope.interface -f python-zopeinterface.spec</div><br />
<br />
The source tarball and package recipe is all you need to generate the RPM file. This final step may depend on which distribution you use. Again, for openSUSE (and by using the openSUSE Build Service), the complete recipe becomes:<br />
<br />
<div class="shell">$ osc mkpac python-zopeinterface<br /><!--<br />
-->$ cd python-zopeinterface<br /><!--<br />
-->$ py2pack fetch zope.interface<br /><!--<br />
-->$ py2pack generate zope.interface -f python-zopeinterface.spec<br /><!--<br />
-->$ vi *.spec<br /><!--<br />
--> BuildRequires: python-setuptools<br /><!--<br />
-->ZZ <br /><!--<br />
-->$ osc build<br /><!--<br />
-->$ osc vc <br /><!--<br />
-->$ osc add *<br /><!--<br />
-->$ osc commit</div><br />
<br />
The first line uses osc, the Build Service command line tool to generate a new package (preferrably in your Build Service home project). The py2pack steps are known already. <br />
It is always good to review the BuildRequires (with 'vi *.spec') and e.g. add python-setuptools if needed.<br />
Finally, the package is tested (built locally), a changes (package changelog) file is generated (with ‘osc vc’) and the result is sent back to the Build Service for public consumption. However, depending on the Python module, you may have to adapt the generated spec file slightly. Py2pack is quite clever and tries to auto-generate as much as it can, but it depends on the metadata that the module provides. Thus, bad metadata implies mediocre results. To get further help about py2pack usage, issue the following command:<br />
<br />
<div class="shell">$ py2pack help</div><br />
<br />
Often, the first run of 'osc build' will fail with build error messages, due to missing python modules. Look for the keyword 'import', this should give you a hint, what needs to be added to the 'BuildRequires:' of you spec-file.<br />
<br />
----<br />
<br />
== Hints on how to package Python modules manually ==<br />
<br />
Manual packaging is discouraged since we have tools to do that. If you insist on having fun, please consider any package spec file in [https://build.opensuse.org/project/show/devel:languages:python devel:languages:python3]. [https://build.opensuse.org/package/show/devel:languages:python/python-nose python-nose], [https://build.opensuse.org/package/show/devel:languages:python/python-pip python-pip] or [https://build.opensuse.org/package/show/devel:languages:python/python-Sphinx python-Sphinx] are good examples.<br />
<br />
=== Naming policy ===<br />
<br />
SUSE has a policy for names of Python module packages. A ''module'' is to Python what shared libraries are to C - a piece of code that doesn't work by itself, but provides functionality to other Python programs.<br />
<br />
All Python module packages, whether pure Python or C-based, should be called '''python-'''modulename. '''modulename''' should be the name of this module on the [http://pypi.python.org/pypi Python Package Index],<br />
the official third-party software repository for the Python programming language.<br />
<br />
Previously, Python packages have been named after directories in the <tt>site-packages</tt> hierarchy. Often, this was an arbitrary choice, several modules install more than one directory there. Also, the Python universe includes modules that share the same directory name (search for "daemon" on PyPI) and it was not always easy to find out the right package name. Furthermore, the new approach has several advantages:<br />
<br />
* Scripts (like py2pack) know where to fetch metadata and (new) release tarballs, PyPI has a stable API<br />
* Package names match [http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies install_required, etc. in setup.py files] and [http://www.pip-installer.org/en/latest/requirements.html pip requirements files] making it easy to find out (Build)Requires in your RPM specs<br />
* Users know where to look for API or usage documentation: http://pypi.python.org/pypi/$PYPYNAME<br />
<br />
This policy doesn't apply to end-user applications - so if you're packaging something that is going to have an icon in the application menu, you should just call the package by its normal name (as found on the Python Package Index).<br />
<br />
There are some corner cases as to what is an application and what is a module - for example, many modules come with simple command-line tools that allow you to use a subset of their functionality directly. The rule of thumb is this: if you think that the users will install your package to use the command line tool, call it by its normal name. If this package is going to be a dependency of some other Python application, apply the naming policy.<br />
<br />
=== BuildRequires ===<br />
<br />
In all cases, use '''BuildRequires: python-devel'''. Technically '''BuildRequires: python-base''' is sufficient for Python-only modules (i.e. no C code), but it increases consistency and doesn't add much overhead. <br />
<br />
Some modules require [http://pypi.python.org/pypi/setuptools setuptools] to build. In this case add the package '''BuilRequires: python-setuptools''' <del>or preferably it's succcessor as BuildRequires: python-distribute</del><span style="color:red;">2013-10-16: distribute is a setuptools fork that was done because development stalled. meanwhile, the project was taken over by distribute devs and they merged. Nowadays, setuptools is pretty active again and obsoleted distribute (again). -- quoted Saschpe</span>. <br />
<br />
Due to how the Python interpreter is spread across the packages "python" and "python-base", you sometimes need to say '''BuildRequires: python''' in your spec files. This is especially true if you need one of the following Python modules at build time: ssl, _ssl, md5, sha.<br />
<br />
=== Python version ===<br />
<br />
In openSUSE, even version-agnostic python packages need to depend on a specific python series. A python series is denoted by python's major and minor version. For example, the current (as of 3.4.2013) python series is 2.7 for the legacy line and 3.3 for Python 3.<br><br />
This is because you are installing into version-specific directory <tt>/usr/lib(64)/pythonX.Y/site-packages</tt>, where X.Y is the series.<br />
<br />
=== File locations ===<br />
<br />
All python source and bytecode files should go into <tt>/usr/lib(64)/pythonX.Y/site-packages</tt>, or maybe <tt>/usr/lib(64)/yourapp</tt>. FHS says that <tt>/usr/share</tt> hierarchy should only contain data, so don't install sources in there.<br><br />
This is not a strict requirement, though, only a recommendation. If your package's upstream is bent on installing to <tt>/usr/share</tt>, please try to convince them of the error of their ways, but don't feel obliged to patch the package to death just so it installs into <tt>/usr/lib</tt>.<br />
<br />
=== File lists ===<br />
<br />
There are two useful macros to list files:<br />
* '''<tt>%python_sitelib</tt>''' expands to <tt>/usr/lib/pythonX.Y/site-packages</tt>. This is the install location for platform-independent modules.<br />
* '''<tt>%python_sitearch</tt>''' expands to <tt>%{_libdir}/pythonX.Y/site-packages</tt>, that is, either /usr/lib or /usr/lib64, depending on your architecture. This is the install location for platform-dependent modules.<br />
<br />
So, for platform-independent Python packages, the simplest example would look like this:<br />
<pre><br />
%install<br />
python setup.py install --prefix=%{_prefix} --root=%{buildroot}<br />
<br />
%files<br />
%defattr(-,root,root)<br />
%{python_sitelib}/*<br />
</pre><br />
<br />
To avoid file conflicts with packages for other Python interpreters, binaries and/or man-pages should be suffixed with the Interpreter versions, e.g.:<br />
<pre><br />
%{_bindir}/foo<br />
</pre><br />
<br />
should become<br />
<pre><br />
%{_bindir}/foo-%{py_ver}<br />
</pre><br />
<br />
Please check the Python3 / parallel installation section below.<br />
<br />
=== System Architecture ===<br />
<br />
If your package only contains python sources (.py), bytecode files (.pyc and .pyo) and platform-independent data, you should mark it as noarch. Include '''<tt>BuildArchitectures: noarch</tt>''' at the start of your spec file. Such module should install entirely into %python_sitelib.<br />
<br />
Otherwise, the whole module installs into %python_sitearch. Note that it is not possible to have part of a module in %python_sitelib and another part in %python_sitearch. And in most cases, even if package contains more than one module, all of them should be in one prefix.<br />
<br />
This is important so i'm going to stress it: '''the entire module is either platform-independent, or it isn't.''' Even one binary library or platform-specific config file in otherwise pure python module will mark the entire module as platform-dependent and you won't be able to use it as noarch. This is usually handled by distutils, so you shouldn't need to worry most of the time.<br />
<br />
Certain packages might install parts of themselves into %python_sitelib and parts into %python_sitearch. Such setup is a common source of bugs and problems. Unless you know exactly what you're doing, you should modify such packages so that ''everything'' goes into %python_sitearch.<br />
<br />
=== setuptools/eggs ===<br />
{{Warning|The following text was imported from [http://fedoraproject.org/wiki/Packaging/Python Fedora Guidelines] and not reviewed for use in openSUSE yet. Use at your own risk.}}<font color="red"><br />
In the past, Fedora has done the minimal amount to support eggs for upstream distros. As eggs are being adopted more widely upstream we need to have more comprehensive documentation on how to handle this. The following are a summary of the guidelines for reviewers to go over. The [[Packaging/Python/Eggs| complete policy]] includes examples and rationale for the way we do things.<br />
* '''Must''': Python eggs must be built from source. They cannot simply drop an egg from upstream into the proper directory.<br />
* '''Must''': Python eggs must not download any dependencies during the build process.<br />
* '''Must''': If egg-info files are generated by the modules build scripts they must be included in the package.<br />
* '''Must''': When building a compat package, it must install using easy_install -m so it won't conflict with the main package.<br />
* '''Must''': When building multiple versions (for a compat package) one of the packages must contain a default version that is usable via "import MODULE" with no prior setup.<br />
* '''Should''': A package which is used by another package via an egg interface should provide egg info.<br />
</font><br />
<br />
=== Byte Compiled Files ===<br />
<br />
Python will automatically try to byte compile files when it runs in order to speed up startup the next time it is run. These files are saved in files with the extension of .pyc (compiled python) or .pyo (optimized compiled python). These files are a byte code that is portable across OSes. If you do not include them in your packages, python will try to create them when the user runs the program. If the system administrator uses them, then the files will be successfully written. Later, when the package is removed, the .pyc and .pyo files will be left behind on the filesystem. To prevent that you need to byte compile the files when building your package and include the files in the %files section.<br />
<br />
Many packages install byte-compiled .pycs and .pyos by themselves. If your package doesn't do that, you should use the macro %{py_compile} in this way: '''<tt>%py_compile <directory></tt>''' to create .pyc and '''<tt>%py_compile -O <directory></tt>''' for .pyo files.<br />
<br />
Most of the time, .pyo files are exactly the same as .pyc. You can save space by running fdupes to hardlink them together.<br />
<pre><br />
BuildRequires: fdupes<br />
(...)<br />
<br />
%install<br />
(...)<br />
%fdupes $RPM_BUILD_ROOT%{py_sitedir}<br />
</pre><br />
<br />
=== Summary of useful rpm macros ===<br />
<br />
* '''%py_ver''' - python series denomination (major.minor version number)<br />
* '''%py_compile''' - byte-compiles python sources from the specified directory. Use <tt>%{py_compile -O}</tt> to produce optimized bytecode (.pyo)<br />
* '''%python_sitelib''' - <tt>site-packages</tt> directory for platform-independent modules. Expands to <tt>/usr/lib/python%{py_ver}/site-packages</tt><br />
* '''%python_sitearch''' - <tt>site-packages</tt> directory for platform-dependent modules. Expands to <tt>%{_libdir}/python%{py_ver}/site-packages</tt><br />
<br />
=== Compatibility with older distributions ===<br />
<br />
In 11.1, split python package was introduced. If you want to build a package for older distribution, you cannot require <tt>python-base</tt>. Note that <tt>python-base</tt> was introduced because it has almost no build-time or run-time dependencies. That means that it is unblocked sooner in the rebuild cycle, and conversely, if your package doesn't buildrequire <tt>python</tt>, it can be build sooner.<br />
<br />
The possibility to build noarch packages, along with <tt>%python_sitelib</tt> and <tt>%python_sitearch</tt>, was introduced in 11.2. If you need compatibility with older distributions, you must define the macros you are using. Place this at the start of your spec:<br />
<pre>%{!?python_sitelib: %global python_sitelib %(%{__python} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())")}<br />
%{!?python_sitearch: %global python_sitearch %(%{__python} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib(1))")}</pre><br />
<br />
If your package is noarch, you must wrap the noarch declaration in a conditional sequence.<br />
<br />
This would build your package as noarch only on openSUSE 11.2 and higher:<pre><br />
%if 0%{?suse_version} >= 1120<br />
BuildArchitectures: noarch<br />
%endif</pre><br />
And this would build your package as noarch on openSUSE 11.2 and higher, plus on any non-SUSE distro. (Useful when building packages for Fedora)<pre>%if %{?suse_version: %{suse_version} > 1110} %{!?suse_version:1}<br />
BuildArchitectures: noarch<br />
%endif</pre><br />
<br />
=== Running tests ===<br />
The easiest way to run tests is using setuptools ''test'' subcommand:<br />
<pre><br />
python setup.py test<br />
</pre><br />
<br />
This of course only works, if ''test_suite'' or ''cmd_class'' is properly defined in your ''setup.py''. E.g. if you use external modules to find the tests:<br />
* <pre>cmdclass = {'test': pytest}</pre><br />
* <pre>test_suite='nose.collector'</pre><br />
Or the tests can be run by directly calling a module in `tests/` or `packagename/tests`:<br />
* <pre>test_suite='tests'</pre><br />
* <pre>test_suite='packagename.tests'</pre><br />
<br />
This also works for packages with compiled components.<br />
<br />
<br />
[[Category:Packaging]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Java_jpackage-utils&diff=69597openSUSE:Java jpackage-utils2015-01-22T11:46:20Z<p>Thomas-schraitle: Typo fixed: readling -> readlink</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|The project [http://jpackage.org jpackage.org] brings the set of the common rules, [[openSUSE:Java_RPM_Macros | rpm macros]] and a scripts, which are be usefull (not only) for the package maintainers.}}<br />
<br />
== build-classpath ==<br />
<br />
<code>build-classpath</code> - Small utility to build a Java CLASSPATH with the named JARs. The CLASSPATH is returned to standard output. This script should be used in a <code>%pre</code>, <code>%build</code> section of spec file, or in the pre/post un/install scriplets, or in the wrapper scripts.<br />
<br />
The commons forms of usage are:<br />
<br />
Setup of the CLASSPATH <br />
<pre><br />
$ build-classpath ant<br />
/usr/share/java/ant.jar<br />
$ export CLASSPATH=$(build-classpath ant servletapi5)<br />
$ echo ${CLASSPATH}<br />
/usr/share/java/ant.jar:/usr/share/java/servletapi5.jar<br />
</pre><br />
<br />
When the jar is located in a subdirectory of a <code>%{_javadir}</code>, you'll need to write<br />
<pre><br />
$ build-classpath asm/asm<br />
/usr/share/java/asm/asm.jar<br />
</pre><br />
<br />
If you need all of the classes in a subdirectory, you should simply write<br />
<pre><br />
$ build-classpath asm/<br />
/usr/share/java/asm/asm-1.5.3.jar:/usr/share/java/asm/asm-analysis-1.5.3.jar:<br />
/usr/share/java/asm/asm-attrs-1.5.3.jar:/usr/share/java/asm/asm-tree-1.5.3.jar:<br />
/usr/share/java/asm/asm-util-1.5.3.jar:/usr/share/java/asm/asm-xml-1.5.3.jar:<br />
/usr/share/java/asm/kasm-1.5.3.jar<br />
</pre><br />
<br />
Note, that build-classpath will return the same output if there's some typo in the aruments, so the output of the build-classpath asm/foo will be the same as the example above!<br />
<br />
It's also possible to use the <code>build-classpath</code> to create symbolic links, if the program expects the jars in some external directory.<br />
<br />
<pre><br />
$ ln -s $(build-classpath ant)<br />
$ readlink ant.jar<br />
/usr/share/java/ant.jar<br />
$ ln -s $(build-classpath ant) libs/expected_jar_name-1.0.9.jar<br />
$ readlink libs/expected_jar_name-1.0.9.jar<br />
/usr/share/java/ant.jar<br />
</pre><br />
<br />
The combination of <code>build-classpath</code> and <code>ln</code> should produces a bad symlinks in cases, when the <code>build-classpath</code> returns a multiple paths.<br />
<br />
== build-classpath-directory ==<br />
Small script to build a classpath from a directory. This script find all the jar files in specified directory(ies) and produce a CLASSPATH.<br />
<br />
<pre><br />
build-classpath-directory /usr/share/java<br />
/usr/share/java/libgcj-4.3.jar:/usr/share/java/libgcj-tools-4.3.jar:<br />
/usr/share/java/ecj-3.3.jar:/usr/share/java/ecj.jar:<br />
/usr/share/java/tomcat6-servlet-2.5-api-6.0.16.jar:<br />
/usr/share/java/tomcat6-servlet-2.5-api.jar<br />
[snip]<br />
</pre><br />
<br />
== build-jar-repository ==<br />
<br />
Build a JAR repository in the named directory by copying files or creating symbolic links. This script is better solution how to produre a symlinks (or a copy of the jar file), than the combination of the <code>build-classpath</code> and a <code>ln</code> (or <code>cp</code>).<br />
<br />
If no option is specified the default action will be to create symbolic links. In other cases, the script has a following arguments:<br />
<br />
*<code>-c, --copy</code> copy files instead linking<br />
*<code>-h, --hard</code> create hard links<br />
*<code>-p, --preserve-naming</code> preserve the names of the original JAR files<br />
*<code>-s, --soft, --symbolic</code> create symbolic links (default)<br />
<br />
The common usage is simple<br />
<pre><br />
$ mkdir libs<br />
$ build-jar-repository libs ant asm/asm<br />
</pre><br />
<br />
The <code>build-jar-repository<code> do not produce symlinks like <code>build-classpath</code>, but add a brackets to the name of the file.<br />
<br />
<pre><br />
$ ls libs<br />
[ant].jar [asm][asm].jar<br />
</pre><br />
<br />
The purpose of brackets is to identify the symlinks created by script and is possible to re-run the script on the directory and link them to the new location. This behavior should be supressed by the <code>-p, --preserve-naming</code> argument.<br />
<br />
<pre><br />
$ build-jar-repository -p libs ant asm/asm<br />
ant.jar asm_asm.jar<br />
</pre><br />
<br />
In this case, the slash symbol was replaced by underscores and a default action was changed to the copy, so if you'd like to have a symlink of the jars, you've to add a <code>-s</code> argument.<br />
<br />
[[Category:Java]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Multiple_Version_guidelines&diff=66149openSUSE:Packaging Multiple Version guidelines2014-02-11T08:34:52Z<p>Thomas-schraitle: Used <pre>...</pre> tags to avoid linebreaks inbetween</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|Even if the standard behavior of RPM is to update a single package always to the highest version, it is possible for several programs fulfilling the same or similar functions to be installed on a single system at the same time.<br />
<br />
For example, many systems have several text editors installed at once. This gives choice to the users of a system, allowing each to use a<br />
different editor, if desired, but makes it difficult for a program to make a good choice of editor to invoke if the user has not specified a<br />
particular preference. Therefore, some standards can and should be defined, so programs can fall back to these standards.<br />
}}<br />
<br />
== Package naming ==<br />
<br />
For different versions of the same software, heed [[openSUSE:Package_naming_guidelines#Multiple_packages_for_the_same_software]].<br />
<br />
== Maintain default commands and libraries ==<br />
<br />
=== ''update-alternatives'' mechanism ===<br />
<br />
The '''update-alternatives''' package creates, removes, maintains and displays information about the symbolic links comprising the alternatives<br />
system. A packager can use this package to define default applications in a running system without getting in conflict with other packages.<br />
<br />
<pre><br />
Name: vim<br />
Requires(post): update-alternatives<br />
Requires(postun): update-alternatives<br />
<br />
%install<br />
# create a dummy target for /etc/alternatives/vim<br />
mkdir -p %{buildroot}%{_sysconfdir}/alternatives<br />
ln -s -f %{_sysconfdir}/alternatives/vim %{buildroot}/bin/vim<br />
<br />
%post<br />
"%_sbindir/update-alternatives" --install \<br />
/bin/vim vim /bin/vim-normal 15<br />
<br />
%post enhanced<br />
"%_sbindir/update-alternatives" --install \<br />
/bin/vim vim "%_bindir/vim-enhanced" 20<br />
<br />
%postun<br />
if [ "$1" = 0 ] ; then<br />
"%_sbindir/update-alternatives" --remove vim /bin/vim-normal<br />
fi<br />
<br />
%preun enhanced<br />
if [ "$1" = 0 ] ; then<br />
"%_sbindir/update-alternatives" --remove vim "%_bindir/vim-enhanced"<br />
fi<br />
<br />
%files<br />
%defattr(-,root,root)<br />
%_bindir/vim<br />
%ghost %_sysconfdir/alternatives/vim<br />
<br />
%files enhanced<br />
%defattr(-,root,root)<br />
%_bindir/vim-enhanced<br />
%ghost %_sysconfdir/alternatives/vim<br />
</pre><br />
<br />
[[de:openSUSE:Paketbau Richtlinien für mehrere Versionen]]<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Python&diff=65961openSUSE:Packaging Python2014-01-25T10:56:01Z<p>Thomas-schraitle: Added <tt> tags</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging Python''' is a step by step introduction on how to build Python software packages for openSUSE and others using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== The fast and automated way ==<br />
<br />
Lets suppose you want to package zope.interface and you don't know how it is named exactly or where to download from. First of all, you can search for it with py2pack, which can be found in the python-py2pack package and download the source tarball automatically with it if you found the correct module:<br />
<br />
<div class="shell">$ py2pack search zope.interface<pre>searching for module zope.interface...<br />
found zope.interface-3.6.1</pre><!--<br />
-->$ py2pack fetch zope.interface<pre>downloading package zope.interface-3.6.1...<br />
from http://pypi.python.org/packages/source/z/zope.interface/zope.interface-3.6.1.tar.gz</pre></div><br />
<br />
As a next step you may want to generate a package recipe for your distribution. For RPM-based distributions, you want to generate a spec file named python-zopeinterface.spec:<br />
<br />
<div class="shell">$ py2pack generate zope.interface -f python-zopeinterface.spec</div><br />
<br />
The source tarball and package recipe is all you need to generate the RPM file. This final step may depend on which distribution you use. Again, for openSUSE (and by using the openSUSE Build Service), the complete recipe becomes:<br />
<br />
<div class="shell">$ osc mkpac python-zopeinterface<br /><!--<br />
-->$ cd python-zopeinterface<br /><!--<br />
-->$ py2pack fetch zope.interface<br /><!--<br />
-->$ py2pack generate zope.interface -f python-zopeinterface.spec<br /><!--<br />
-->$ osc build<br /><!--<br />
-->$ osc vc<br /><!--<br />
-->$ osc commit</div><br />
<br />
The first line uses osc, the Build Service command line tool to generate a new package (preferrably in your Build Service home project). The py2pack steps are known already. Finally, the package is tested (built locally), a changes (package changelog) file is generated (with ‘osc vc’) and the result is sent back to the Build Service for public consumption. However, depending on the Python module, you may have to adapt the generated spec file slightly. Py2pack is quite clever and tries to auto-generate as much as it can, but it depends on the metadata that the module provides. Thus, bad metadata implies mediocre results. To get further help about py2pack usage, issue the following command:<br />
<br />
<div class="shell">$ py2pack help</div><br />
<br />
----<br />
<br />
== Hints on how to package Python modules manually ==<br />
<br />
Manual packaging is discouraged since we have tools to do that. If you insist on having fun, please consider any package spec file in [https://build.opensuse.org/project/show/devel:languages:python devel:languages:python3]. [https://build.opensuse.org/package/show/devel:languages:python/python-nose python-nose], [https://build.opensuse.org/package/show/devel:languages:python/python-pip python-pip] or [https://build.opensuse.org/package/show/devel:languages:python/python-Sphinx python-Sphinx] are good examples.<br />
<br />
=== Naming policy ===<br />
<br />
SUSE has a policy for names of Python module packages. A ''module'' is to Python what shared libraries are to C - a piece of code that doesn't work by itself, but provides functionality to other Python programs.<br />
<br />
All Python module packages, whether pure Python or C-based, should be called '''python-'''modulename. '''modulename''' should be the name of this module on the [http://pypi.python.org/pypi Python Package Index],<br />
the official third-party software repository for the Python programming language.<br />
<br />
Previously, Python packages have been named after directories in the <tt>site-packages</tt> hierarchy. Often, this was an arbitrary choice, several modules install more than one directory there. Also, the Python universe includes modules that share the same directory name (search for "daemon" on PyPI) and it was not always easy to find out which one was packages. Furthermore, the new approach has several advantages:<br />
<br />
* Scripts (like py2pack) know where to fetch metadata and (new) release tarballs, PyPI has a stable API<br />
* Package names match [http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies install_required, etc. in setup.py files] and [http://www.pip-installer.org/en/latest/requirements.html pip requirements files] making it easy to find out (Build)Requires in your RPM specs<br />
* Users know where to look for API or usage documentation: http://pypi.python.org/pypi/$PYPYNAME<br />
<br />
This policy doesn't apply to end-user applications - so if you're packaging something that is going to have an icon in the application menu, you should just call the package by its normal name (as found on the Python Package Index).<br />
<br />
There are some corner cases as to what is an application and what is a module - for example, many modules come with simple command-line tools that allow you to use a subset of their functionality directly. The rule of thumb is this: if you think that the users will install your package to use the command line tool, call it by its normal name. If this package is going to be a dependency of some other Python application, apply the naming policy.<br />
<br />
=== BuildRequires ===<br />
<br />
In all cases, use '''BuildRequires: python-devel'''. Technically '''BuildRequires: python-base''' is sufficient for Python-only modules (i.e. no C code), but it increases consistency and doesn't add much overhead. <br />
<br />
Some modules require [http://pypi.python.org/pypi/setuptools setuptools] to build. In this case add the package '''BuilRequires: python-setuptools''' <del>or preferably it's succcessor as BuildRequires: python-distribute</del><span style="color:red;">2013-10-16: distribute is a setuptools fork that was done because development stalled. meanwhile, the project was taken over by distribute devs and they merged. Nowadays, setuptools is pretty active again and obsoleted distribute (again). -- quoted Saschpe</span>. <br />
<br />
Due to how the Python interpreter is spread across the packages "python" and "python-base", you sometimes need to say '''BuildRequires: python''' in your spec files. This is especially true if you need one of the following Python modules at build time: ssl, _ssl, md5, sha.<br />
<br />
=== Python version ===<br />
<br />
In openSUSE, even version-agnostic python packages need to depend on a specific python series. A python series is denoted by python's major and minor version. For example, the current (as of 3.4.2013) python series is 2.7 for the legacy line and 3.3 for Python 3.<br><br />
This is because you are installing into version-specific directory <tt>/usr/lib(64)/pythonX.Y/site-packages</tt>, where X.Y is the series.<br />
<br />
=== File locations ===<br />
<br />
All python source and bytecode files should go into <tt>/usr/lib(64)/pythonX.Y/site-packages</tt>, or maybe <tt>/usr/lib(64)/yourapp</tt>. FHS says that <tt>/usr/share</tt> hierarchy should only contain data, so don't install sources in there.<br><br />
This is not a strict requirement, though, only a recommendation. If your package's upstream is bent on installing to <tt>/usr/share</tt>, please try to convince them of the error of their ways, but don't feel obliged to patch the package to death just so it installs into <tt>/usr/lib</tt>.<br />
<br />
=== File lists ===<br />
<br />
There are two useful macros to list files:<br />
* '''<tt>%python_sitelib</tt>''' expands to <tt>/usr/lib/pythonX.Y/site-packages</tt>. This is the install location for platform-independent modules.<br />
* '''<tt>%python_sitearch</tt>''' expands to <tt>%{_libdir}/pythonX.Y/site-packages</tt>, that is, either /usr/lib or /usr/lib64, depending on your architecture. This is the install location for platform-dependent modules.<br />
<br />
So, for platform-independent Python packages, the simplest example would look like this:<br />
<pre><br />
%install<br />
python setup.py install --prefix=%{_prefix} --root=%{buildroot}<br />
<br />
%files<br />
%defattr(-,root,root)<br />
%{python_sitelib}/*<br />
</pre><br />
<br />
To avoid file conflicts with packages for other Python interpreters, binaries and/or man-pages should be suffixed with the Interpreter versions, e.g.:<br />
<pre><br />
%{_bindir}/foo<br />
</pre><br />
<br />
should become<br />
<pre><br />
%{_bindir}/foo-%{py_ver}<br />
</pre><br />
<br />
Please check the Python3 / parallel installation section below.<br />
<br />
=== System Architecture ===<br />
<br />
If your package only contains python sources (.py), bytecode files (.pyc and .pyo) and platform-independent data, you should mark it as noarch. Include '''<tt>BuildArchitectures: noarch</tt>''' at the start of your spec file. Such module should install entirely into %python_sitelib.<br />
<br />
Otherwise, the whole module installs into %python_sitearch. Note that it is not possible to have part of a module in %python_sitelib and another part in %python_sitearch. And in most cases, even if package contains more than one module, all of them should be in one prefix.<br />
<br />
This is important so i'm going to stress it: '''the entire module is either platform-independent, or it isn't.''' Even one binary library or platform-specific config file in otherwise pure python module will mark the entire module as platform-dependent and you won't be able to use it as noarch. This is usually handled by distutils, so you shouldn't need to worry most of the time.<br />
<br />
Certain packages might install parts of themselves into %python_sitelib and parts into %python_sitearch. Such setup is a common source of bugs and problems. Unless you know exactly what you're doing, you should modify such packages so that ''everything'' goes into %python_sitearch.<br />
<br />
=== setuptools/eggs ===<br />
{{Warning|The following text was imported from [http://fedoraproject.org/wiki/Packaging/Python Fedora Guidelines] and not reviewed for use in openSUSE yet. Use at your own risk.}}<font color="red"><br />
In the past, Fedora has done the minimal amount to support eggs for upstream distros. As eggs are being adopted more widely upstream we need to have more comprehensive documentation on how to handle this. The following are a summary of the guidelines for reviewers to go over. The [[Packaging/Python/Eggs| complete policy]] includes examples and rationale for the way we do things.<br />
* '''Must''': Python eggs must be built from source. They cannot simply drop an egg from upstream into the proper directory.<br />
* '''Must''': Python eggs must not download any dependencies during the build process.<br />
* '''Must''': If egg-info files are generated by the modules build scripts they must be included in the package.<br />
* '''Must''': When building a compat package, it must install using easy_install -m so it won't conflict with the main package.<br />
* '''Must''': When building multiple versions (for a compat package) one of the packages must contain a default version that is usable via "import MODULE" with no prior setup.<br />
* '''Should''': A package which is used by another package via an egg interface should provide egg info.<br />
</font><br />
<br />
=== Byte Compiled Files ===<br />
<br />
Python will automatically try to byte compile files when it runs in order to speed up startup the next time it is run. These files are saved in files with the extension of .pyc (compiled python) or .pyo (optimized compiled python). These files are a byte code that is portable across OSes. If you do not include them in your packages, python will try to create them when the user runs the program. If the system administrator uses them, then the files will be successfully written. Later, when the package is removed, the .pyc and .pyo files will be left behind on the filesystem. To prevent that you need to byte compile the files when building your package and include the files in the %files section.<br />
<br />
Many packages install byte-compiled .pycs and .pyos by themselves. If your package doesn't do that, you should use the macro %{py_compile} in this way: '''<tt>%py_compile <directory></tt>''' to create .pyc and '''<tt>%py_compile -O <directory></tt>''' for .pyo files.<br />
<br />
Most of the time, .pyo files are exactly the same as .pyc. You can save space by running fdupes to hardlink them together.<br />
<pre><br />
BuildRequires: fdupes<br />
(...)<br />
<br />
%install<br />
(...)<br />
%fdupes $RPM_BUILD_ROOT%{py_sitedir}<br />
</pre><br />
<br />
=== Summary of useful rpm macros ===<br />
<br />
* '''%py_ver''' - python series denomination (major.minor version number)<br />
* '''%py_compile''' - byte-compiles python sources from the specified directory. Use <tt>%{py_compile -O}</tt> to produce optimized bytecode (.pyo)<br />
* '''%python_sitelib''' - <tt>site-packages</tt> directory for platform-independent modules. Expands to <tt>/usr/lib/python%{py_ver}/site-packages</tt><br />
* '''%python_sitearch''' - <tt>site-packages</tt> directory for platform-dependent modules. Expands to <tt>%{_libdir}/python%{py_ver}/site-packages</tt><br />
<br />
=== Compatibility with older distributions ===<br />
<br />
In 11.1, split python package was introduced. If you want to build a package for older distribution, you cannot require <tt>python-base</tt>. Note that <tt>python-base</tt> was introduced because it has almost no build-time or run-time dependencies. That means that it is unblocked sooner in the rebuild cycle, and conversely, if your package doesn't buildrequire <tt>python</tt>, it can be build sooner.<br />
<br />
The possibility to build noarch packages, along with <tt>%python_sitelib</tt> and <tt>%python_sitearch</tt>, was introduced in 11.2. If you need compatibility with older distributions, you must define the macros you are using. Place this at the start of your spec:<br />
<pre>%{!?python_sitelib: %global python_sitelib %(%{__python} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())")}<br />
%{!?python_sitearch: %global python_sitearch %(%{__python} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib(1))")}</pre><br />
<br />
If your package is noarch, you must wrap the noarch declaration in a conditional sequence.<br />
<br />
This would build your package as noarch only on openSUSE 11.2 and higher:<pre><br />
%if 0%{?suse_version} >= 1120<br />
BuildArchitectures: noarch<br />
%endif</pre><br />
And this would build your package as noarch on openSUSE 11.2 and higher, plus on any non-SUSE distro. (Useful when building packages for Fedora)<pre>%if %{?suse_version: %{suse_version} > 1110} %{!?suse_version:1}<br />
BuildArchitectures: noarch<br />
%endif</pre><br />
<br />
== Hints on how to Package Python3 modules ==<br />
<br />
Historically, Python-2.7 has been the default Interpreter version. Beginning from openSUSE-13.1 it will be Python-3.3. Packages for Python-2.x are developed in the OBS project [https://build.opensuse.org/project/show?project=devel%3Alanguages%3Apython devel:languages:python], whereas Python-3.x packages are developed in [https://build.opensuse.org/project/show?project=devel%3Alanguages%3Apython3 devel:languages:python3]. <br />
<br />
It is recommended to create packages for both versions. Here is a small procedure how to do this:<br />
<br />
# Start packaging <tt>python-$FOO</tt> with [https://build.opensuse.org/package/show/devel:languages:python/python-py2pack py2pack].<br />
# Submit it to <tt>devel:languages:python</tt>. Wait if your package is accepted. If not, fix the remaining problems.<br />
# Create a separate package <tt>python3-$FOO</tt> by copying <tt>python-$FOO</tt> with <tt>osc copypac</tt>.<br />
# Rename all files from <tt>python-*</tt> to <tt>python3-*</tt> .<br />
# Open the <tt>python3-$FOO.spec</tt> file and:<br />
## Replace any dependency with their python3 counterpart.<br />
## Change <tt>%py_ver</tt> into <tt>%py3_ver</tt>.<br />
## Change <tt>%python_sitelib</tt> into <tt>%python3_sitelib</tt>.<br />
# Drop any compatibility macros for openSUSE versions older than 12.2.<br />
# Build your package locally.<br />
# Submit your package to [https://build.opensuse.org/project/show?project=devel%3Alanguages%3Apython3 devel:languages:python3].<br />
<br />
To stay in line with the above example, consider [https://build.opensuse.org/package/show/devel:languages:python3/python3-Sphinx python3-Sphinx].<br />
<br />
<br />
=== Parallel installation ===<br />
<br />
In order to be able to install the Python-2.x and Python-3.x version of a package in parallel, file conflicts need to be avoided. In general this includes all files not installed into <tt>%{python_sitelib}</tt> / <tt>%{python_sitearch}</tt> (and their Py3k equivalents) nor files marked as %doc. In other words, check your <tt>%files</tt> section(s) for the following:<br />
<pre><br />
%{_bindir}/foo<br />
%{_mandir}/man1/foo.1.gz<br />
</pre><br />
Icons, <tt>*.desktop</tt> files and application data in <tt>%{_datadir}</tt> may also conflict. The correct solution is to use <tt>update-alternatives</tt>. The already mentioned package examples all implement proper <tt>update-alternatives</tt>, so please consider those.<br />
<br />
<br />
<br />
See [[openSUSE:Python 3 Status]] for a list of Python packages and their Python3 status on openSUSE.<br />
<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Paketbau von Python-Software]]<br />
[[el:openSUSE:Packaging Python]]<br />
[[zh:openSUSE:Packaging_Python]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Python&diff=65960openSUSE:Packaging Python2014-01-25T10:54:28Z<p>Thomas-schraitle: Created procedure to make it more clear</p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging Python''' is a step by step introduction on how to build Python software packages for openSUSE and others using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== The fast and automated way ==<br />
<br />
Lets suppose you want to package zope.interface and you don't know how it is named exactly or where to download from. First of all, you can search for it with py2pack, which can be found in the python-py2pack package and download the source tarball automatically with it if you found the correct module:<br />
<br />
<div class="shell">$ py2pack search zope.interface<pre>searching for module zope.interface...<br />
found zope.interface-3.6.1</pre><!--<br />
-->$ py2pack fetch zope.interface<pre>downloading package zope.interface-3.6.1...<br />
from http://pypi.python.org/packages/source/z/zope.interface/zope.interface-3.6.1.tar.gz</pre></div><br />
<br />
As a next step you may want to generate a package recipe for your distribution. For RPM-based distributions, you want to generate a spec file named python-zopeinterface.spec:<br />
<br />
<div class="shell">$ py2pack generate zope.interface -f python-zopeinterface.spec</div><br />
<br />
The source tarball and package recipe is all you need to generate the RPM file. This final step may depend on which distribution you use. Again, for openSUSE (and by using the openSUSE Build Service), the complete recipe becomes:<br />
<br />
<div class="shell">$ osc mkpac python-zopeinterface<br /><!--<br />
-->$ cd python-zopeinterface<br /><!--<br />
-->$ py2pack fetch zope.interface<br /><!--<br />
-->$ py2pack generate zope.interface -f python-zopeinterface.spec<br /><!--<br />
-->$ osc build<br /><!--<br />
-->$ osc vc<br /><!--<br />
-->$ osc commit</div><br />
<br />
The first line uses osc, the Build Service command line tool to generate a new package (preferrably in your Build Service home project). The py2pack steps are known already. Finally, the package is tested (built locally), a changes (package changelog) file is generated (with ‘osc vc’) and the result is sent back to the Build Service for public consumption. However, depending on the Python module, you may have to adapt the generated spec file slightly. Py2pack is quite clever and tries to auto-generate as much as it can, but it depends on the metadata that the module provides. Thus, bad metadata implies mediocre results. To get further help about py2pack usage, issue the following command:<br />
<br />
<div class="shell">$ py2pack help</div><br />
<br />
----<br />
<br />
== Hints on how to package Python modules manually ==<br />
<br />
Manual packaging is discouraged since we have tools to do that. If you insist on having fun, please consider any package spec file in [https://build.opensuse.org/project/show/devel:languages:python devel:languages:python3]. [https://build.opensuse.org/package/show/devel:languages:python/python-nose python-nose], [https://build.opensuse.org/package/show/devel:languages:python/python-pip python-pip] or [https://build.opensuse.org/package/show/devel:languages:python/python-Sphinx python-Sphinx] are good examples.<br />
<br />
=== Naming policy ===<br />
<br />
SUSE has a policy for names of Python module packages. A ''module'' is to Python what shared libraries are to C - a piece of code that doesn't work by itself, but provides functionality to other Python programs.<br />
<br />
All Python module packages, whether pure Python or C-based, should be called '''python-'''modulename. '''modulename''' should be the name of this module on the [http://pypi.python.org/pypi Python Package Index],<br />
the official third-party software repository for the Python programming language.<br />
<br />
Previously, Python packages have been named after directories in the <tt>site-packages</tt> hierarchy. Often, this was an arbitrary choice, several modules install more than one directory there. Also, the Python universe includes modules that share the same directory name (search for "daemon" on PyPI) and it was not always easy to find out which one was packages. Furthermore, the new approach has several advantages:<br />
<br />
* Scripts (like py2pack) know where to fetch metadata and (new) release tarballs, PyPI has a stable API<br />
* Package names match [http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies install_required, etc. in setup.py files] and [http://www.pip-installer.org/en/latest/requirements.html pip requirements files] making it easy to find out (Build)Requires in your RPM specs<br />
* Users know where to look for API or usage documentation: http://pypi.python.org/pypi/$PYPYNAME<br />
<br />
This policy doesn't apply to end-user applications - so if you're packaging something that is going to have an icon in the application menu, you should just call the package by its normal name (as found on the Python Package Index).<br />
<br />
There are some corner cases as to what is an application and what is a module - for example, many modules come with simple command-line tools that allow you to use a subset of their functionality directly. The rule of thumb is this: if you think that the users will install your package to use the command line tool, call it by its normal name. If this package is going to be a dependency of some other Python application, apply the naming policy.<br />
<br />
=== BuildRequires ===<br />
<br />
In all cases, use '''BuildRequires: python-devel'''. Technically '''BuildRequires: python-base''' is sufficient for Python-only modules (i.e. no C code), but it increases consistency and doesn't add much overhead. <br />
<br />
Some modules require [http://pypi.python.org/pypi/setuptools setuptools] to build. In this case add the package '''BuilRequires: python-setuptools''' <del>or preferably it's succcessor as BuildRequires: python-distribute</del><span style="color:red;">2013-10-16: distribute is a setuptools fork that was done because development stalled. meanwhile, the project was taken over by distribute devs and they merged. Nowadays, setuptools is pretty active again and obsoleted distribute (again). -- quoted Saschpe</span>. <br />
<br />
Due to how the Python interpreter is spread across the packages "python" and "python-base", you sometimes need to say '''BuildRequires: python''' in your spec files. This is especially true if you need one of the following Python modules at build time: ssl, _ssl, md5, sha.<br />
<br />
=== Python version ===<br />
<br />
In openSUSE, even version-agnostic python packages need to depend on a specific python series. A python series is denoted by python's major and minor version. For example, the current (as of 3.4.2013) python series is 2.7 for the legacy line and 3.3 for Python 3.<br><br />
This is because you are installing into version-specific directory <tt>/usr/lib(64)/pythonX.Y/site-packages</tt>, where X.Y is the series.<br />
<br />
=== File locations ===<br />
<br />
All python source and bytecode files should go into <tt>/usr/lib(64)/pythonX.Y/site-packages</tt>, or maybe <tt>/usr/lib(64)/yourapp</tt>. FHS says that <tt>/usr/share</tt> hierarchy should only contain data, so don't install sources in there.<br><br />
This is not a strict requirement, though, only a recommendation. If your package's upstream is bent on installing to <tt>/usr/share</tt>, please try to convince them of the error of their ways, but don't feel obliged to patch the package to death just so it installs into <tt>/usr/lib</tt>.<br />
<br />
=== File lists ===<br />
<br />
There are two useful macros to list files:<br />
* '''<tt>%python_sitelib</tt>''' expands to <tt>/usr/lib/pythonX.Y/site-packages</tt>. This is the install location for platform-independent modules.<br />
* '''<tt>%python_sitearch</tt>''' expands to <tt>%{_libdir}/pythonX.Y/site-packages</tt>, that is, either /usr/lib or /usr/lib64, depending on your architecture. This is the install location for platform-dependent modules.<br />
<br />
So, for platform-independent Python packages, the simplest example would look like this:<br />
<pre><br />
%install<br />
python setup.py install --prefix=%{_prefix} --root=%{buildroot}<br />
<br />
%files<br />
%defattr(-,root,root)<br />
%{python_sitelib}/*<br />
</pre><br />
<br />
To avoid file conflicts with packages for other Python interpreters, binaries and/or man-pages should be suffixed with the Interpreter versions, e.g.:<br />
<pre><br />
%{_bindir}/foo<br />
</pre><br />
<br />
should become<br />
<pre><br />
%{_bindir}/foo-%{py_ver}<br />
</pre><br />
<br />
Please check the Python3 / parallel installation section below.<br />
<br />
=== System Architecture ===<br />
<br />
If your package only contains python sources (.py), bytecode files (.pyc and .pyo) and platform-independent data, you should mark it as noarch. Include '''<tt>BuildArchitectures: noarch</tt>''' at the start of your spec file. Such module should install entirely into %python_sitelib.<br />
<br />
Otherwise, the whole module installs into %python_sitearch. Note that it is not possible to have part of a module in %python_sitelib and another part in %python_sitearch. And in most cases, even if package contains more than one module, all of them should be in one prefix.<br />
<br />
This is important so i'm going to stress it: '''the entire module is either platform-independent, or it isn't.''' Even one binary library or platform-specific config file in otherwise pure python module will mark the entire module as platform-dependent and you won't be able to use it as noarch. This is usually handled by distutils, so you shouldn't need to worry most of the time.<br />
<br />
Certain packages might install parts of themselves into %python_sitelib and parts into %python_sitearch. Such setup is a common source of bugs and problems. Unless you know exactly what you're doing, you should modify such packages so that ''everything'' goes into %python_sitearch.<br />
<br />
=== setuptools/eggs ===<br />
{{Warning|The following text was imported from [http://fedoraproject.org/wiki/Packaging/Python Fedora Guidelines] and not reviewed for use in openSUSE yet. Use at your own risk.}}<font color="red"><br />
In the past, Fedora has done the minimal amount to support eggs for upstream distros. As eggs are being adopted more widely upstream we need to have more comprehensive documentation on how to handle this. The following are a summary of the guidelines for reviewers to go over. The [[Packaging/Python/Eggs| complete policy]] includes examples and rationale for the way we do things.<br />
* '''Must''': Python eggs must be built from source. They cannot simply drop an egg from upstream into the proper directory.<br />
* '''Must''': Python eggs must not download any dependencies during the build process.<br />
* '''Must''': If egg-info files are generated by the modules build scripts they must be included in the package.<br />
* '''Must''': When building a compat package, it must install using easy_install -m so it won't conflict with the main package.<br />
* '''Must''': When building multiple versions (for a compat package) one of the packages must contain a default version that is usable via "import MODULE" with no prior setup.<br />
* '''Should''': A package which is used by another package via an egg interface should provide egg info.<br />
</font><br />
<br />
=== Byte Compiled Files ===<br />
<br />
Python will automatically try to byte compile files when it runs in order to speed up startup the next time it is run. These files are saved in files with the extension of .pyc (compiled python) or .pyo (optimized compiled python). These files are a byte code that is portable across OSes. If you do not include them in your packages, python will try to create them when the user runs the program. If the system administrator uses them, then the files will be successfully written. Later, when the package is removed, the .pyc and .pyo files will be left behind on the filesystem. To prevent that you need to byte compile the files when building your package and include the files in the %files section.<br />
<br />
Many packages install byte-compiled .pycs and .pyos by themselves. If your package doesn't do that, you should use the macro %{py_compile} in this way: '''<tt>%py_compile <directory></tt>''' to create .pyc and '''<tt>%py_compile -O <directory></tt>''' for .pyo files.<br />
<br />
Most of the time, .pyo files are exactly the same as .pyc. You can save space by running fdupes to hardlink them together.<br />
<pre><br />
BuildRequires: fdupes<br />
(...)<br />
<br />
%install<br />
(...)<br />
%fdupes $RPM_BUILD_ROOT%{py_sitedir}<br />
</pre><br />
<br />
=== Summary of useful rpm macros ===<br />
<br />
* '''%py_ver''' - python series denomination (major.minor version number)<br />
* '''%py_compile''' - byte-compiles python sources from the specified directory. Use <tt>%{py_compile -O}</tt> to produce optimized bytecode (.pyo)<br />
* '''%python_sitelib''' - <tt>site-packages</tt> directory for platform-independent modules. Expands to <tt>/usr/lib/python%{py_ver}/site-packages</tt><br />
* '''%python_sitearch''' - <tt>site-packages</tt> directory for platform-dependent modules. Expands to <tt>%{_libdir}/python%{py_ver}/site-packages</tt><br />
<br />
=== Compatibility with older distributions ===<br />
<br />
In 11.1, split python package was introduced. If you want to build a package for older distribution, you cannot require <tt>python-base</tt>. Note that <tt>python-base</tt> was introduced because it has almost no build-time or run-time dependencies. That means that it is unblocked sooner in the rebuild cycle, and conversely, if your package doesn't buildrequire <tt>python</tt>, it can be build sooner.<br />
<br />
The possibility to build noarch packages, along with <tt>%python_sitelib</tt> and <tt>%python_sitearch</tt>, was introduced in 11.2. If you need compatibility with older distributions, you must define the macros you are using. Place this at the start of your spec:<br />
<pre>%{!?python_sitelib: %global python_sitelib %(%{__python} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())")}<br />
%{!?python_sitearch: %global python_sitearch %(%{__python} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib(1))")}</pre><br />
<br />
If your package is noarch, you must wrap the noarch declaration in a conditional sequence.<br />
<br />
This would build your package as noarch only on openSUSE 11.2 and higher:<pre><br />
%if 0%{?suse_version} >= 1120<br />
BuildArchitectures: noarch<br />
%endif</pre><br />
And this would build your package as noarch on openSUSE 11.2 and higher, plus on any non-SUSE distro. (Useful when building packages for Fedora)<pre>%if %{?suse_version: %{suse_version} > 1110} %{!?suse_version:1}<br />
BuildArchitectures: noarch<br />
%endif</pre><br />
<br />
== Hints on how to Package Python3 modules ==<br />
<br />
Historically, Python-2.7 has been the default Interpreter version. Beginning from openSUSE-13.1 it will be Python-3.3. Packages for Python-2.x are developed in the OBS project [https://build.opensuse.org/project/show?project=devel%3Alanguages%3Apython devel:languages:python], whereas Python-3.x packages are developed in [https://build.opensuse.org/project/show?project=devel%3Alanguages%3Apython3 devel:languages:python3]. <br />
<br />
It is recommended to create packages for both versions. Here is a small procedure how to do this:<br />
<br />
# Start packaging <tt>python-$FOO</tt> with [https://build.opensuse.org/package/show/devel:languages:python/python-py2pack py2pack].<br />
# Submit it to <tt>devel:languages:python</tt>. Wait if your package is accepted. If not, fix the remaining problems.<br />
# Create a separate package <tt>python3-$FOO</tt> by copying <tt>python-$FOO</tt> with <tt>osc copypac</tt>.<br />
# Rename all files from <tt>python-*</tt> to <tt>python3-*</tt> .<br />
# Open the <tt>python3-$FOO.spec</tt> file and:<br />
## Replace any dependency with their python3 counterpart.<br />
## Change <tt>%py_ver</tt> into <tt>%py3_ver</tt>.<br />
## Change <tt>%python_sitelib</tt> into <tt>%python3_sitelib</tt>.<br />
# Drop any compatibility macros for openSUSE versions older than 12.2.<br />
# Build your package locally.<br />
# Submit your package to [https://build.opensuse.org/project/show?project=devel%3Alanguages%3Apython3 devel:languages:python3].<br />
<br />
To stay in line with the above example, consider [https://build.opensuse.org/package/show/devel:languages:python3/python3-Sphinx python3-Sphinx].<br />
<br />
<br />
=== Parallel installation ===<br />
<br />
In order to be able to install the Python-2.x and Python-3.x version of a package in parallel, file conflicts need to be avoided. In general this includes all files not installed into %{python_sitelib} / %{python_sitearch} (and their Py3k equivalents) nor files marked as %doc. In other words, check your %files section(s) for the following:<br />
<pre><br />
%{_bindir}/foo<br />
%{_mandir}/man1/foo.1.gz<br />
</pre><br />
Icons, *.desktop files and application data in %{_datadir} may also conflict. The correct solution is to use <tt>update-alternatives</tt>. The already mentioned package examples all implement proper <tt>update-alternatives</tt>, so please consider those.<br />
<br />
<br />
<br />
See [[openSUSE:Python 3 Status]] for a list of Python packages and their Python3 status on openSUSE.<br />
<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Paketbau von Python-Software]]<br />
[[el:openSUSE:Packaging Python]]<br />
[[zh:openSUSE:Packaging_Python]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Python_team&diff=65174openSUSE:Python team2013-12-03T07:40:21Z<p>Thomas-schraitle: Added link to about page of Python.org</p>
<hr />
<div><div class="center"><br />
[[Image:Python.png|128px]]<br />
</div><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Introduction ===<br />
</div><br />
<br />
According to [http://python.org python.org]:<br />
“Python is a programming language that lets you work more quickly and integrate your systems more effectively. You can learn to use Python and see almost immediate gains in productivity and lower maintenance costs.”<br />
<br />
Some of its key distinguishing features include:<br />
* very clear, readable syntax<br />
* strong introspection capabilities<br />
* intuitive object orientation<br />
* natural expression of procedural code<br />
* full modularity, supporting hierarchical packages<br />
* exception-based error handling<br />
* very high level dynamic data types<br />
* extensive standard libraries and third party modules for virtually every task<br />
* extensions and modules easily written in C, C++ (or Java for Jython, or .NET languages for IronPython)<br />
* embeddable within applications as a scripting interface<br />
<br />
Find more at http://www.python.org/about/.<br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Communicate ===<br />
</div><br />
<br />
{{Mailinglist|opensuse-packaging|openSUSE-Packaging Mailinglist}}<br />
<br />
<br />
<!--<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== How to join ===<br />
</div><br />
--><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== Repository setup ===<br />
</div><br />
<br />
* Python 2: [https://build.opensuse.org/project/show/devel:languages:python devel:languages:python]<br />
* Python 3: [https://build.opensuse.org/project/show/devel:languages:python3 devel:languages:python3]<br />
<br />
[[Category:Team pages]]<br />
__NOTOC__</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Python_team&diff=65173openSUSE:Python team2013-12-03T07:37:35Z<p>Thomas-schraitle: Added links to repository</p>
<hr />
<div><div class="center"><br />
[[Image:Python.png|128px]]<br />
</div><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Introduction ===<br />
</div><br />
<br />
According to [http://python.org python.org]:<br />
“Python is a programming language that lets you work more quickly and integrate your systems more effectively. You can learn to use Python and see almost immediate gains in productivity and lower maintenance costs.”<br />
<br />
Some of its key distinguishing features include:<br />
* very clear, readable syntax<br />
* strong introspection capabilities<br />
* intuitive object orientation<br />
* natural expression of procedural code<br />
* full modularity, supporting hierarchical packages<br />
* exception-based error handling<br />
* very high level dynamic data types<br />
* extensive standard libraries and third party modules for virtually every task<br />
* extensions and modules easily written in C, C++ (or Java for Jython, or .NET languages for IronPython)<br />
* embeddable within applications as a scripting interface<br />
<br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Communicate ===<br />
</div><br />
<br />
{{Mailinglist|opensuse-packaging|openSUSE-Packaging Mailinglist}}<br />
<br />
<br />
<!--<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== How to join ===<br />
</div><br />
--><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== Repository setup ===<br />
</div><br />
<br />
* Python 2: [https://build.opensuse.org/project/show/devel:languages:python devel:languages:python]<br />
* Python 3: [https://build.opensuse.org/project/show/devel:languages:python3 devel:languages:python3]<br />
<br />
[[Category:Team pages]]<br />
__NOTOC__</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Python_team&diff=65172openSUSE:Python team2013-12-03T07:35:28Z<p>Thomas-schraitle: Added some key features</p>
<hr />
<div><div class="center"><br />
[[Image:Python.png|128px]]<br />
</div><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Introduction ===<br />
</div><br />
<br />
According to [http://python.org python.org]:<br />
“Python is a programming language that lets you work more quickly and integrate your systems more effectively. You can learn to use Python and see almost immediate gains in productivity and lower maintenance costs.”<br />
<br />
Some of its key distinguishing features include:<br />
* very clear, readable syntax<br />
* strong introspection capabilities<br />
* intuitive object orientation<br />
* natural expression of procedural code<br />
* full modularity, supporting hierarchical packages<br />
* exception-based error handling<br />
* very high level dynamic data types<br />
* extensive standard libraries and third party modules for virtually every task<br />
* extensions and modules easily written in C, C++ (or Java for Jython, or .NET languages for IronPython)<br />
* embeddable within applications as a scripting interface<br />
<br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Communicate ===<br />
</div><br />
<br />
{{Mailinglist|opensuse-packaging|openSUSE-Packaging Mailinglist}}<br />
<br />
<br />
<!--<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== How to join ===<br />
</div><br />
--><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== Repository setup ===<br />
</div><br />
<br />
<br />
<br />
[[Category:Team pages]]<br />
__NOTOC__</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Python_team&diff=65171openSUSE:Python team2013-12-03T07:29:28Z<p>Thomas-schraitle: Added first draft</p>
<hr />
<div><div class="center"><br />
[[Image:Python.png|128px]]<br />
</div><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Introduction ===<br />
</div><br />
<br />
According to [http://python.org python.org]:<br />
“Python is a programming language that lets you work more quickly and integrate your systems more effectively. You can learn to use Python and see almost immediate gains in productivity and lower maintenance costs.”<br />
<br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#000000"><br />
=== Communicate ===<br />
</div><br />
<br />
{{Mailinglist|opensuse-packaging|openSUSE-Packaging Mailinglist}}<br />
<br />
<br />
<!--<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== How to join ===<br />
</div><br />
--><br />
<br />
<div style="background-color:#E5E5E6;text-align:center;color:#0b5147"><br />
=== Repository setup ===<br />
</div><br />
<br />
<br />
<br />
[[Category:Team pages]]<br />
__NOTOC__</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Packaging_Fonts&diff=64129openSUSE:Packaging Fonts2013-11-11T07:28:05Z<p>Thomas-schraitle: Added <tt>...</tt></p>
<hr />
<div>{{Packaging_navbar}}<br />
{{Intro|The '''Packaging Fonts''' is an overview on how to build font packages for openSUSE and others using the [[Portal:Build Service|openSUSE Build Service]].}}<br />
<br />
== Purpose ==<br />
This page is intended to define a common set of rules for package names, its content, and other related information.<br />
<br />
== How to Select a New Font ==<br />
There are lots of "free" fonts out there which ''could'' theoretically be packaged. However, we should strive for ''quality'', not quantity. Therefore, here are some guidelines you should answer first before you package a new font at all:<br />
<br />
* '''Is the font open source?''' <br/> You should focus on free fonts released under the OFL, GPL, or any other open or free source license. Although it should be clear, but commercial fonts '''MUST NOT''' be packaged at all!<br />
* '''Is the font already packaged?''' <br/> Before you package a new font, ''always'' look into M17N:fonts repository first. Search for similar package names.<br />
* '''How many font styles does the font bring with?''' <br/> Try to package fonts which have at least a regular and italic style. Preferably the font has also bold and italic+bold (that would make four styles). Sometimes, a font comes with small caps, other brings a condensed or wider variant, but this is not the usual case. <br />
* '''Can the font be used for different languages?''' <br/> Although you rarely will find a font which contains ''all'' possible languages, look for fonts which supports at least European languages. Some contains also Greek or Cyrillic glyphs. Others may support Asian characters. The more languages a font supports, the better will it be for the majority of users.<br />
* '''How many glyphs does the font have?''' <br/> This question is related to the previous one. However, there are more useful glyphs like arrows, dingbats, mathematical symbols, etc. Additional glyphs make it easier to use them for other purposes, like programming or specific texts.<br />
<br />
== Naming and Central Font Repository ==<br />
<br />
Think of a good font name. The general syntax is this (all lower-case):<br />
<pre>[foundryname-]projectname[-fontfamilyname][-fonttype]-fonts</pre><br />
<br />
Here is more detailed explanation<br />
<br />
* '''foundryname''': Usually the name of the designer or a type foundry<br />
* '''projectname''': the name of the font project<br />
* '''fontfamilyname''': if the project contains different font families, specify it here<br />
* '''fonttype''': subsitute 'bitmap' in case you package a bitmap font<br />
<br />
In most cases, the package name is pretty short. For example, if you have a font project "foo", the package name will be "foo-fonts". <br />
<br />
Almost all font packages are located in the [https://build.opensuse.org/project/show?project=M17N%3Afonts M17N:fonts] repository now.<br />
<br />
See discussion on opensuse-packaging mailinglist [http://lists.opensuse.org/opensuse-packaging/2011-12/msg00093.html RFC: Fonts Repo and Renaming Questions]. It also evolved from FATE #313035 ([https://features.opensuse.org/313035 Invent Consistent Font Naming Schema/Central Font Repository]).<br />
<br />
See [https://build.opensuse.org/project/show?project=M17N%3Afonts M17N:fonts] for names of packages and subpackages or the list of renamed packages in [[openSUSE:Packaging Fonts:Fontlist]].<br />
<br />
== Package content ==<br />
Fonts are different and so the project pages and their archives. Some projects just publish an archive and nothing else, others bring a specimen or additional information.<br />
<br />
If possible, try to package these additional information in <tt>%{_docdir}/PACKAGENAME</tt>.<br />
<br />
== Package Layout for Fonts ==<br />
<br />
Consider how you split your package into subpackages. Best practices are<br />
# to spent one (noarch) rpm for one family and<br />
# do not spread font files of one family over more rpms.<br />
These rules are not binding though, you will meet some counterexamples in M17N:fonts for sure.<br />
<br />
== How to Create a New Font Package ==<br />
The following procedure shows how to create a new font package.<br />
<br />
<ol><br />
<li>Create a new package in your home repository (in our case "foo-fonts"):<br />
<pre>osc mkpac foo-fonts</pre><br />
</li><br />
<li>Download the font package archive from the project's home page and save it to your newly created foo-fonts directory.</li><br />
<li>Create a spec file (in our case, it's foo-fonts.spec) and fill in the gaps. Usually, such file looks like this:<br />
<pre><br />
#<br />
# spec file for package foo-fonts<br />
#<br />
# Copyright (c) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.<br />
# <br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owner, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
#<br />
# Please submit bugfixes or comments via http://bugs.opensuse.org/<br />
<br />
# Definitions<br />
%define fontname foo<br />
<br />
Name: foo-fonts<br />
Summary: ...<br />
License: OFL-1.1<br />
Group: System/X11/Fonts<br />
BuildArch: noarch<br />
Version: 1.0<br />
Release: 0<br />
Source: %{fontname}-%{version}.tar.bz2<br />
## If the font supports several languages (denoted as X and Y), it's recommended<br />
## to add the following lines:<br />
# Provides: scalable-font-X<br />
# Provides: scalable-font-Y<br />
# Provides: locale(X;Y)<br />
# You can do it conveniently with<br />
# %{lua: <br />
# l = "X;Y;" <br />
# print (string .gsub (l, "(%a+);", "Provides: scalable-font-%1\n"), "\n") <br />
# print (string .sub (l, 1, string .len (l) - 1)) }<br />
BuildRequires: fontpackages-devel <br />
BuildRequires: unzip # only if zipped<br />
%reconfigure_fonts_prereq<br />
URL: http://www.example.org/foo-font<br />
<br />
%description<br />
Foo fonts is...<br />
<br />
Designer: Add the name of the font designer<br />
<br />
%prep<br />
%setup -n %{fontname}-%{version}<br />
# Usually empty, but insert fixes here, if necessary<br />
<br />
# Zipped fonts require unzip and prepare like this:<br />
# %setup -cT<br />
# %{uncompress:%{S:0}}<br />
<br />
%build<br />
# Usually nothing to do<br />
<br />
%install<br />
install -d '%{buildroot}%{_ttfontsdir}<br />
install '-t%{buildroot}%{_ttfontsdir}' -m 644 *.ttf <br />
<br />
# call fonts-config after installation or deinstallation of this package<br />
%reconfigure_fonts_scriptlets<br />
<br />
%files<br />
%defattr(-, root, root)<br />
# Include additional content for the font package, if available<br />
# %doc METADATA FONTLOG.txt OFL.txt<br />
%{_ttfontsdir}<br />
<br />
%changelog<br />
</pre><br />
</li><br />
<li>Create a changelog and write your comment:<br />
<pre>osc vc</pre><br />
</li><br />
<li>Build the package locally:<br />
<pre>osc build --local-package openSUSE_12.1 foo-fonts.spec</pre><br />
</li><br />
<li>If there are no errors, commit the font package:<br />
<pre>osc ci</pre><br />
</li><br />
<li>Check if everything is built correctly:<br />
<pre>osc r</pre><br />
</li><br />
<li>Submit your package to our M17N:fonts repository:<br />
<pre>osc sr YOUR_REPO foo-fonts M17N:fonts</pre><br />
</li><br />
</ol><br />
<br />
=== RPM macros ===<br />
<br />
Using rpm macros in font packages is highly recomended. Every font package should buildrequire <br />
fontpackages-devel and use macros defined in <br />
[https://build.opensuse.org/package/view_file?file=rpm-macros.fonts-config&package=fontpackages&project=M17N%3Afonts /etc/rpm/macros-fontconfig].<br />
That is because:<br />
# changing common font package behaviour is centralized that way on one place and<br />
# spec files using them can be more clear (compare stix-fonts spec file for openSUSE 12.2 and 12.3).<br />
<br />
=== Examples ===<br />
<br />
Here are some example packages with simple spec files:<br />
* [https://build.opensuse.org/package/show?package=dejavu-fonts&project=M17N%3Afonts dejavu-fonts]<br />
* [https://build.opensuse.org/package/show?package=caslon-fonts&project=M17N%3Afonts caslon-fonts]<br />
* [https://build.opensuse.org/package/show?package=gdouros-musica-fonts&project=M17N%3Afonts gdouros-musica-fonts]<br />
<br />
== How to Update an Existing Font Package ==<br />
If you want to update a font to a newer version or you found a bug, the following procedure shows how to do it:<br />
<br />
<ol><br />
<li>Open a shell and branch the existing font package on <tt>M17N:fonts</tt>:<br />
<pre>osc bco M17N:fonts FONTPACKAGE</pre><br />
The <tt>osc</tt> script checks out the font package and saves it into <tt>home/USER/branches/M17N/fonts/FONTPACKAGE</tt> (if you have set <tt>checkout_no_colon=1</tt> in your <tt>~/.oscrc</tt> config file). This will be your current working directory.<br />
</li><br />
<li>Download the new package and save it into your working directory. Usually you can find the package from the project's homepage.</li><br />
<li>Change the version number in the spec file.</li><br />
<li>If needed, add patches or other requirements into the spec file (usually mostly not needed).</li><br />
<li>Write a meaningful changelog entry:<br />
<pre>osc vc</pre><br />
(Probably you find information about the changes in the <tt>Changelog</tt> file if included into the archive, or on the project's homepage).<br />
</li><br />
<li>Remove the old archive and add the new one:<br />
<pre>osc rm OLD_ARCHIVE<br />
osc add NEW_ARCHIVE</pre><br />
</li><br />
<li>Build your package and fix any errors (you may replace <tt>openSUSE_Factory</tt> with your preferred distribution):<br />
<pre>osc build openSUSE_Factory *.spec</pre><br />
</li><br />
<li>Commit all your changes:<br />
<pre>osc ci</pre><br />
</li><br />
<li>Submit your changes back to the <tt>M17N:fonts</tt> repository:<br />
<pre>osc sr -m"Updated to version x.y"</pre><br />
</li><br />
</ol><br />
<br />
Your submission will be reviewed and if it conforms to our packaging rules it will be accepted. In case it is declined, you will be informed about the reason. Fix the errors or problems and submit it again (probably you may want to combine the <tt>-s</tt> option (superseding another request by this one) with your <tt>sr</tt> command).<br />
<br />
== Font Package with More Families ==<br />
<br />
Many packages don't split into subpackages even if it contains more font families. Nevertheless, when you want to give users the chance to choose which family from your package to install, then you will have to split your font package in subpackages.<br />
<br />
As a general rule of thumb: split a font into several packages, if it's "big". For "big" there is no exact definition, but a font can be considered "big" if it contains more than one font families or has lots of files which lead to a monstrous file size.<br />
<br />
The spec file can look like:<br />
<br />
<pre># spec file for package bar-fonts<br />
#<br />
# Copyright (c) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.<br />
#<br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owners, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
<br />
# Please submit bugfixes or comments via http://bugs.opensuse.org/<br />
#<br />
<br />
%define projname bar<br />
<br />
Name: bar-fonts<br />
Version: 2.0<br />
Release: 0<br />
Summary: ...<br />
License: OFL.1.1<br />
Group: System/X11/Fonts<br />
Url: ...<br />
Source0: %{projname}-%{version}.tar.bz2<br />
BuildRequires: fontpackages-devel<br />
%reconfigure_fonts_prereq<br />
BuildRoot: %{_tmppath}/%{name}-%{version}-build<br />
BuildArch: noarch<br />
<br />
%description<br />
...<br />
<br />
%package -n %{projname}-family1-fonts<br />
Summary: ...<br />
Group: System/X11/Fonts<br />
<br />
%description -n %{projname}-family1-fonts<br />
...<br />
<br />
%package -n %{projname}-family2-fonts<br />
Summary: ...<br />
Group: System/X11/Fonts<br />
<br />
%description -n %{projname}-family2-fonts<br />
...<br />
<br />
%package -n %{projname}-family3-fonts<br />
Summary: ...<br />
Group: System/X11/Fonts<br />
<br />
%description -n %{projname}-family3-fonts<br />
...<br />
<br />
%prep<br />
%setup -q -n %{projname}-%{version}<br />
<br />
%build<br />
<br />
%install<br />
mkdir -p %{buildroot}%{_ttfontsdir}<br />
for i in *.ttf<br />
do<br />
install -m 644 $i %{buildroot}%{_ttfontsdir}<br />
done<br />
<br />
%reconfigure_fonts_scriptlets -c -n %{projname}-family1-fonts<br />
<br />
%reconfigure_fonts_scriptlets -c -n %{projname}-family2-fonts<br />
<br />
%reconfigure_fonts_scriptlets -c -n %{projname}-family3-fonts<br />
<br />
# main package can be also empty, then don't inclue %files section<br />
# at all<br />
%files<br />
%defattr(-,root,root)<br />
# Include common content for the font package, if available<br />
# %doc METADATA FONTLOG.txt OFL.txt<br />
<br />
%files -n %{projname}-family1-fonts<br />
%defattr(-,root,root)<br />
%dir %{_ttfontsdir}/<br />
%{_ttfontsdir}/family1.*<br />
<br />
%files -n %{projname}-family2-fonts<br />
%defattr(-,root,root)<br />
%dir %{_ttfontsdir}/<br />
%{_ttfontsdir}/family2.*<br />
<br />
%files -n %{projname}-family3-fonts<br />
%defattr(-,root,root)<br />
%dir %{_ttfontsdir}/<br />
%{_ttfontsdir}/family3.*<br />
<br />
%changelog<br />
<br />
</pre><br />
<br />
=== Examples ===<br />
<br />
* [https://build.opensuse.org/package/show?package=ipa-fonts&project=M17N%3Afonts ipa-fonts]<br />
* [https://build.opensuse.org/package/show?package=stix-fonts&project=M17N%3Afonts stix-fonts]<br />
<br />
== Packaging Fontconfig Files along Font Package ==<br />
<br />
It may happen that you want to package a fontconfig file along with your font files. There's no policy<br />
that the fontconfig file should be part of fontconfig package itself, so you are encouraged to include<br />
it in your font package. With one exception: mapping to generic names serif, sans-serif, <br />
monospace, cursive and fantasy. Especially <default> alias: it is intended to help fontconfig to find similar<br />
fonts to yours when yours are not installed, so packaging it along with your package will evidently not work. <br />
<br />
The fontconfig file can be shipped inside upstream tarball or you can add it as package source.<br />
<br />
There's no strict rules for the name of the fontconfig file except common ones for fontconfig files <br />
(see <tt>/etc/fonts/conf.d/README</tt>). If you want to use the RPM macro <tt>%install_fontsconf</tt>, you have to ensure that the name <br />
of the fontconfig file is identical to that one you want to have in <tt>/etc/fonts/conf.d</tt>. <br />
<br />
In following spec file example, <br />
we want to install <tt>/etc/fonts/conf.d/31-foo-fonts.conf</tt>, so the file name in package source is <tt>31-foo-fonts.conf</tt>. If the <br />
fontconfig file is part of the upstream tarball, you have to either rename it manually or don't use the <tt>%install_fontsconf</tt> RPM macro (i. e. install it manually).<br />
<br />
Example spec file follows; it packages one fontconfig file.<br />
<br />
<pre>#<br />
# spec file for package foo-fonts<br />
#<br />
# Copyright (c) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.<br />
#<br />
# All modifications and additions to the file contributed by third parties<br />
# remain the property of their copyright owners, unless otherwise agreed<br />
# upon. The license for this file, and modifications and additions to the<br />
# file, is the same license as for the pristine package itself (unless the<br />
# license for the pristine package is not an Open Source License, in which<br />
# case the license is the MIT License). An "Open Source License" is a<br />
# license that conforms to the Open Source Definition (Version 1.9)<br />
# published by the Open Source Initiative.<br />
<br />
# Please submit bugfixes or comments via http://bugs.opensuse.org/<br />
#<br />
<br />
<br />
%define fontname foo<br />
<br />
Name: foo-fonts<br />
Version: 3.0<br />
Release: 0<br />
Summary: ...<br />
License: GPL-2.0-with-font-exception<br />
Group: System/X11/Fonts<br />
Url: ...<br />
Source0: %{fontname}-%{version}.tar.bz2<br />
Source1: 31-%{fontname}-fonts.conf<br />
BuildRequires: fontconfig<br />
BuildRequires: fontpackages-devel<br />
%reconfigure_fonts_prereq<br />
BuildRoot: %{_tmppath}/%{name}-%{version}-build<br />
BuildArch: noarch<br />
<br />
%description<br />
...<br />
<br />
%prep<br />
%setup -q -n %{fontname}<br />
<br />
%build<br />
<br />
%install<br />
mkdir -p %{buildroot}%{_ttfontsdir}/<br />
install -m 0644 *.otf %{buildroot}%{_ttfontsdir}<br />
%install_fontsconf %{SOURCE1}<br />
<br />
%reconfigure_fonts_scriptlets<br />
<br />
%files<br />
%defattr(-,root,root,-)<br />
%doc COPYING README<br />
%{_ttfontsdir}<br />
%files_fontsconf_availdir<br />
%files_fontsconf_file -l 31-linux-libertine.conf<br />
<br />
%changelog<br />
</pre><br />
<br />
Note there are few essential additions compared to simple font package:<br />
<br />
* Adding configuration file into package sources <pre>Source1: 31-%{fontname}-fonts.conf</pre><br />
* Adding build requirements for fontconfig: <pre>BuildRequires: fontconfig</pre><br />
* Installing fontconfig file into availdir (currently <tt>/usr/share/%{name}/conf.avail</tt> defined in <tt>%{_fontsconfavaildir}</tt> RPM macro) and link it into confdir (currently <tt>/etc/fonts/conf.d</tt> defined in <tt>%{_fontsconfddir}</tt> RPM macro) with <pre>%install_fontsconf %{SOURCE1}</pre><br />
* Adding availdir to the package file list <pre>%files_fontsconf_availdir</pre><br />
* Adding configuration file itself into file list; <tt>-l</tt> switch tells macro to include confdir link: <pre>%files_fontsconf_file -l 31-linux-libertine.conf</pre><br />
<br />
Including fontconfig files in fontpackage is not very common, though. At the time of writing, only 9 packages out of 141 in [https://build.opensuse.org/project/show?project=M17N%3Afonts M17N:fonts] do so.<br />
<br />
=== Examples ===<br />
<br />
* [https://build.opensuse.org/package/files?package=linux-libertine-fonts&project=M17N%3Afonts linux-libertine-fonts] -- includes one fontconfig file as package source<br />
* [https://build.opensuse.org/package/files?package=wqy-bitmap-fonts&project=M17N%3Afonts wqy-bitmap-fonts] -- installs one fontconfig file shipped in upstream tarball<br />
* [https://build.opensuse.org/package/files?package=wqy-zenhei-fonts&project=M17N%3Afonts wqy-zenhei-fonts] -- installs three fontconfig files (manually) but links only one to the system config<br />
* [https://build.opensuse.org/package/files?package=stix-fonts&project=M17N%3Afonts stix-fonts] -- includes more fontconfig files as package source, installs one per subpackage<br />
* [https://build.opensuse.org/package/files?package=thai-fonts&project=M17N%3Afonts thai-fonts] -- includes two fontconfig files but doesn't link them in confddir<br />
* [https://build.opensuse.org/package/files?package=cantarell-fonts&project=M17N%3Afonts cantarell-fonts] -- installs one fontconfig file through native build process and link it into system config<br />
<br />
== Notes ==<br />
<br />
=== How to Rename a Font ===<br />
The following procedures show how to rename font package.<br />
<br />
==== Preparing ====<br />
<br />
<ol><br />
<li>Check out the <tt>M17N:fonts</tt> repository:<br />
<pre>osc co M17N:fonts</pre><br />
</li><br />
<li>Open the [https://admin.fedoraproject.org/pkgdb/acls/list/*-fonts*?tg_paginate_limit=0&_csrf_token=db62e614973bacf84613db186a51a2d24fa90950 Fedora Font Package List] in your browser</li><br />
<li>Get a listing of the M17N repository with:<br />
<pre>osc ls M17N</pre></li><br />
<li>Grab a font in this list, for example <tt>LinuxLibertine</tt>.</li><br />
<li>Search the name in the above link to see which is the new name. In this case, it's <tt>linux-libertine-fonts</tt>. <br/><br />
<br />
If you cannot find an equivalent package name, use the following naming schema:<br />
<pre>[foundryname-]projectname[-fontfamilyname][-fonttype]-fonts</pre> <br />
</li><br />
</ol><br />
<br />
==== Copying and Renaming ====<br />
<br />
<ol><br />
<li>Copy the LinuxLibertine font to the new font repository M17N:fonts and use the new name:<br />
<pre>osc copypac M17N LinuxLibertine M17N:fonts linux-libertine-fonts</pre><br />
</li><br />
<li>Update your <tt>M17N:fonts</tt> repository. You will get the new renamed font package:<br />
<pre>osc update<br />
cd linux-libertine-fonts</pre><br />
</li><br />
<li>Rename the <tt>.spec</tt> and <tt>.changes</tt> files to their new names:<br />
<pre>mv LinuxLibertine.spec linux-libertine-fonts.spec<br />
mv LinuxLibertine.changes linux-libertine-fonts.changes</pre><br />
</li><br />
<li>Open the file <tt>linux-libertine-fonts.spec</tt>. The important lines of the <tt>.spec</tt> file looks like this:<br />
<pre>Name: LinuxLibertine<br />
...<br />
Version: 5.1.3<br />
</pre><br />
</li><br />
<li>Change the content of the <tt>Name</tt> keyword to <tt>linux-libertine-fonts</tt>.</li><br />
<li>Copy the version number from the <tt>Version</tt> keyword and insert it into the <tt>Obsoletes</tt> keyword. Add the following lines:<br />
<pre># FIXME: This causes a rpmlint warning; change &lt;= to &lt; once there's a new upstream version<br />
Obsoletes: LinuxLibertine <= 5.1.3<br />
Provides: LinuxLibertine = %{version}</pre><br />
</li><br />
<li>Save the <tt>.spec</tt> file.</li><br />
</ol><br />
<br />
You can also see plenty examples in the [https://build.opensuse.org/project/show?project=M17N%3Afonts M17N:fonts] repository.<br />
<br />
==== Finishing ====<br />
<ol><br />
<li>Build the package, the warning is normal and is expected:<br />
<pre>$ osc build openSUSE_12.1 *.spec<br />
[...]<br />
RPMLINT report:<br />
===============<br />
linux-libertine-fonts.noarch: W: self-obsoletion LinuxLibertine <= 5.1.3 obsoletes LinuxLibertine = 5.1.3<br />
The package obsoletes itself. This is known to cause errors in various tools<br />
and should thus be avoided, usually by using appropriately versioned Obsoletes<br />
and/or Provides and avoiding unversioned ones.<br />
<br />
2 packages and 0 specfiles checked; 0 errors, 1 warnings.</pre><br />
</li><br />
<li>Run <tt>osc vc</tt> to open an editor.</li><br />
<li>Write some changelog lines and save it. We used the following wording:<br />
<pre>Renamed LinuxLibertine -> linux-libertine-fonts according to<br />
Fedora packaging guidelines and FATE#313035<br />
Adjusted Obsoletes and Provides accordingly</pre><br />
</li><br />
<li>Commit your changes:<br />
<pre>osc ci</pre></li><br />
<br />
<li>Submit your changes to factory:<br />
<pre>osc submitreq -m"... some meaningful message ..." openSUSE:Factory</pre><br />
</li><br />
<li>Wait until your submit request is accepted. If your submit request was declined, fix the problems. :-)<br />
</li><br />
<li>Change the devel repository of the old font to the new repository:<br />
<pre>osc changedevelreq openSUSE:Factory LinuxLibertine M17N:fonts linux-libertine-fonts</pre><br />
</li><br />
</ol><br />
<br />
=== BuildRequires Changes since 12.2 (bdftopcf,xmkmf,imake, mkfontdir) ===<br />
<br />
Since openSUSE 12.2, X11:XOrg project split and changed some packages. The packages bdftopcf, imake (includes xmkmf), and mkfontdir are now split into separate subpackages. It's good for end users for a minimal system, but such changes now breaks the old automatic build requirement chain, and makes BuildRequires more complicated.<br />
<br />
If your build fails in openSUSE 12.2 or Factory with error messages like<br />
<br />
<pre>bdftopcf/xmkmf/mkfontdir: Command not found.</pre><br />
<br />
or<br />
<br />
<pre>Imakefile.c:34:0: fatal error: Imake.tmpl: No such file or directory.</pre><br />
<br />
you need the tweaks in this section.<br />
<br />
The common BuildRequires used to package fonts before: <br />
<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
<br />
need to make some changes.<br />
<br />
=== Explanations of the old BuildRequires ===<br />
<br />
xorg-x11 provides <tt>/usr/bin/bdftopcf</tt>,and xorg-x11-devel is actually used to call in xorg-x11-utils-devel,which includes xmkmf, imake and mkfontdir. so xorg-x11 can't be ignored.<br />
<br />
*If the error message is about bdftopcf, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: bdftopcf<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about xmkmf/imake, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: imake //includes xmkmf<br />
BuildRequires: xorg-cf-files //includes Imake.tmpl<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about mkfontdir, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: mkfontdir //this is a "fake" package points to mkfontscale<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about fc-cache, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: fontconfig<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
*If the error message is about libfreetype6.so, you need:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: freetype2-devel<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
<br />
In Fedora, bdftopcf and mkfontdir are in xorg-x11-font-utils, so needs some more changes:<br />
<br />
%if 0%{?suse_version} >= 1220<br />
BuildRequires: bdftopcf<br />
BuildRequires: mkfontdir<br />
%else<br />
%if 0%{?fedora_version}<br />
BuildRequires: xorg-x11-font-utils<br />
%else<br />
BuildRequires: xorg-x11<br />
BuildRequires: xorg-x11-devel<br />
%endif<br />
%endif<br />
<br />
<br />
[[zh:openSUSE:Packaging_Fonts]]<br />
<br />
<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Package_naming_guidelines&diff=62957openSUSE:Package naming guidelines2013-09-20T06:53:22Z<p>Thomas-schraitle: Fixed some punctuation issues</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|The openSUSE package naming guidelines will help you to decide how to name your package and your specfile correctly.}}<br />
<br />
== Common Character Set for Package Naming ==<br />
While openSUSE is an international community, for consistency and usability, there needs to be a common character set for package naming.<br />
<br />
Specifically, all openSUSE packages must be named using only the following ASCII characters:<br />
<br />
<pre><br />
abcdefghijklmnopqrstuvwxyz<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZ<br />
0123456789-._+<br />
</pre><br />
<br />
=== When Upstream Naming is outside of the specified character set ===<br />
openSUSE recognizes that the task of converting text to the specified ASCII character set (aka transliteration) is difficult. Accordingly, when the upstream name is outside of the specified ASCII character set, the openSUSE package maintainer should first contact the upstream for that software and ask them for a transliteration of the name for openSUSE to use.<br />
<br />
If (and only if) the upstream project is unable, unwilling, or unavailable to provide a transliterated name, the openSUSE packager<br />
<br />
* must choose to either perform their own transliteration, or withdraw the package from consideration in openSUSE.<br />
<br />
* should look what other distributions have done for that package's name, and take that into account.<br />
<br />
Transliterated packages may Provide: the original, non-transliterated name, but are not required to do so.<br />
<br />
== General Naming ==<br />
When naming a package, the name should match the upstream tarball or project name from which this software came. In some cases, this naming choice may be more complicated. If this package has been packaged by other distributions/packagers in the past, then you should try to match their name for consistency. In any case, try to use your best judgement, and other developers will help in the final decision.<br />
<br />
Additionally, it is possible that the upstream name does not fall into the [[#CommonCharacterSet| Common Character Set]]. If this is the case, refer to the section [[#Transliteration| When Upstream Naming is outside of the specified character set]] .<br />
<br />
=== Separators ===<br />
When naming packages for openSUSE, the maintainer must use the dash '-' as the delimiter for name parts. The maintainer must NOT use an underscore '_', a plus '+', or a period '.' as a delimiter.<br />
<br />
There are a few exceptions to the no underscore '_' rule:<br />
* httpd, pam, and SDL addon packages are excluded, refer to [[#Addon_Packages_.28httpd.2C_pam.2C_and_SDL.29| Addon Packages (httpd, pam and SDL)]].<br />
* packages that are locale specific, and use the locale in the name are excluded, refer to [[#Addon_Packages_.28locales.29| Addon Packages (locale)]].<br />
* packages where the upstream name naturally contains an underscore are excluded from this. <br />
<br />
Examples of these packages include:<br />
<pre><br />
java_cup<br />
libart_lgpl<br />
microcode_ctl<br />
nss_ldap<br />
sg3_utils<br />
</pre><br />
<br />
If in doubt, ask on the [http://lists.opensuse.org/opensuse-packaging/ opensuse-packaging] mailing list.<br />
<br />
=== Multiple packages for the same software ===<br />
For many reasons, it is sometimes advantageous or necessary to keep multiple versions of a package in openSUSE to be installed simultaneously. The following applies both to package source names and names of binary packages, with the exception of shared library binary packages&nbsp;— those have [[openSUSE:Shared library packaging policy|their own guidelines]].<br />
<br />
When providing multiple versions of a software, the package name should reflect this fact. The package with the most recent version should use the principal name with no versions and all other addons should note their version in the name. There are some exceptions where all packages have a version attached to the package name (e.g. <tt>sqlite</tt>), i.e. there is no package without version in the name. As you can see, some package names have removed delimiters (e.g. <tt>celt051</tt>); doing so however leads to somewhat odd names when numbers go beyond an order of magnitude&nbsp;— think <tt>celt010</tt> (0.10 or 0.1.0?). Applying the Shared Library Packaging Guidelines's recommendations (replacing delimiters by underscores) is therefore a possible alternative (<tt>love-0_7_2</tt>).<br />
<br />
Examples:<br />
<br />
* simultaneously installable development packages: <tt>celt051-devel</tt>, <tt>libcelt-devel</tt>; <tt>sqlite2-devel</tt>, <tt>sqlite3-devel</tt><br />
* simultaneously installable application software: <tt>love-0_7_2</tt>, <tt>love</tt>; <tt>autoconf213</tt>, <tt>autoconf</tt><br />
<br />
=== Case Sensitivity ===<br />
In openSUSE packaging, the maintainer should use his/her best judgement when considering how to name the package. While case sensitivity is not a mandatory requirement, case should only be used where necessary. Keep in mind to respect the wishes of the upstream maintainers. If they refer to their application as "ORBit", you should use "ORBit" as the package name, and not "orbit". However, if they do not express any preference of case, you should default to lowercase naming.<BR><br />
<BR><br />
The exception to this is for perl module packaging. The CPAN Group and Type should be capitalized in the name, as if they were proper nouns . (Refer to '''[[#AddonPerl| Addon Packages (perl modules)]] ''' for details.)<br />
<br />
=== Spec file name ===<br />
The spec file should be named using the %{name}.spec scheme. If your package is named foo-1.0-1.src.rpm, then the spec file should be named foo.spec.<br />
<br />
== Handling special version strings ==<br />
The Version should follow the upstream tarball version. <br />
<br />
If this is not possible, please check if one of the solutions below can address your case.<br />
<br />
=== SCM snapshots ===<br />
<br />
When creating tarballs from an SCM repository, use the nearest applicable release version, append a delimiter (often, '<tt>+</tt>' is used, but '<tt>.</tt>' is visually pleasant too), a short tag identifying the SCM type and an SCM-specific monotonically increasing identifier. Examples for common applications of this scheme:<br />
<br />
'''Git''' can express a commit as an offset from a tag to yield a relatively short identifier. For example, if `<tt>git describe</tt>` outputs <tt>v3.14.1-5-g9265358</tt>, the rpm version could be set to '''3.14.1+git5''' or, if more disambiguation is desired, '''3.14.1+git5.g9265358'''. You may need to use `<tt>git describe --tags</tt>` if the git repository maintainer uses only simple tags rather than annotated tags. If the maintainer provides no git tags, report that shortcoming. In the meantime, an alternative monotonically increasing identifier can be obtained by using the history root as a base (`<tt>git rev-list 9265358 | wc -l</tt>`), useful for when a project is in such an early stage that there have not been any releases yet (<tt>Version: 0~git123</tt>).<br />
<br />
'''Subversion''' has revision numbers which can directly be used. The base version however needs to be determined in other ways. Version: '''3.14.1+svn592'''.<br />
<br />
For '''CVS''', a timestamp seems the shortest unambiguous (to the developer, at least) snapshot identifier because all files have their own revision tree. Version: '''3.14.1+cvs20130621'''.<br />
<br />
=== Pre-Release packages ===<br />
<br />
Pre-release versions using the same version number as the final releases need some additional care. Different developers have different ideas about how to name their preleasess; "''1.8b''" could indicate either 1.8 beta that comes ''before'' 1.8, or it could indicate a release actually made ''after'' 1.8. As such, package utilities (correctly so) make no effort to special-case “alpha”, “beta”, “a”, “b”, or any other name for that matter, and usually sort by longest string such that "1.8" comes before "1.8b". A distro package maintainer is to tweak the <tt>Version:</tt> field in the .spec file in accordance with the sort order provided by our utilities. There are a number of ways to pick from, in the order of descending preference:<br />
<br />
* Some upstreams assign their prereleases sortable numbers (that no other normal release will obtain). For example, <tt>sssd-1.8.0beta2.tar.gz</tt> is defined to be “1.7.92”. Use <tt>Version: 1.7.92</tt>.<br />
* Starting with rpm-4.10 (and backported into openSUSE 12.2's rpm 4.9.1), rpm has adopted the so-called “tilde versions” from Debian. With this, the spec's Version: field can contain a tilde as a special marker that sorts before anything else, including the end-of-string ("1.8~" < "1.8"). <tt>Version: 1.8.0~beta2</tt>. Tildes can be used multiple times, should it really become necessary.<br />
* For the final release, choose a version string that sorts after the upstream final but before any future release. (Choices are indeed limited.) <tt>Version: 1.8.0.beta2</tt> for the prerelease, <tt>Version: 1.8.0.0</tt> for the final. This relies on the property that RPM sorts A–Z before 0–9. As you have noticed, rpm does not bluntly sort by ASCII value, and so, this variant may not necessarily work with non-RPM systems, should you plan to build for them too using OBS.<br />
* For the prerelease, choose a version that sorts before the final but after any potential future releases in the series, and use it to prefix the actual version. <tt>Version: 1.7.99_1.8.0beta2</tt> for the prerelease, <tt>Version: 1.8.0</tt> for the final.<br />
* Bumping the <tt>Epoch:</tt> field. Note that '''openSUSE does not use epochs''', one reaosn being that zypper can actually handle downgrades (unlike yum, presumably). In fact, '''Epoch is considered harmful''', citing the ''[http://www.rpm.org/max-rpm-snapshot/s1-rpm-depend-manual-dependencies.html Maximum RPM]'' book:<br />
<br />
{{Info|'''''Solution Number 2: Just Say No!''' If you have the option between changing the software's version-numbering scheme, or using epoch numbers in RPM, please consider changing the version-numbering scheme. Chances are, if RPM can't figure it out, most of the people using your software can't, either.''}}<br />
<br />
Do not attempt to abuse the rpm ''Release:'' tag for ''version'' information either. It is the wrong field to convey this information, and the Open Build Service will by default overwrite Release: anyway with checkin and build counters.<br />
<br />
=== Post-Release packages ===<br />
<br />
By and large, post releases generally pose no problem because upstreams generally version them such that they follow final releases.<br />
<br />
If upstream is using delimiters from the permitted character set, then just reuse that for the version string. Otherwise replace them by something permitted.<br />
<br />
* openssl-0.9.8p: <tt>Version: 0.9.8p</tt><br />
* suse-11-GA1: <tt>Version: 11.GA1</tt> # GA=General Availability<br />
<br />
Again, letter strings that only have meaning to humans (like GA here) may need to be prefixed by something like a number that helps ordering them the way upstream intended if the natural order of A–Z<br />
is not sufficient. Assuming FUBAR comes after GA, then<br />
<br />
* suse-11-GA1: <tt>Version: 11+0.GA1</tt><br />
* suse-11-FUBAR1: <tt>Version: 11+1.FUBAR1</tt><br />
<br />
would be a workable solution. You will notice '<tt>+</tt>' was chosen here by the wiki page editor instead of '<tt>.</tt>' as a delimiter here, for reason to avoid somewhat ambiguous versions (11.0.GA1 could either be interpreted as 11.0+GA1 or 11+0.GA1).<br />
<br />
For prereleases to postreleases, simply use the tilde mechanism as described above (“openssl-0.9.6q~betaX”).<br />
<br />
== Renaming/replacing existing packages ==<br />
<br />
Described in [[openSUSE:Package_dependencies#Renaming_a_package|Package dependencies: Renaming a package]].<br />
<br />
== Documentation SubPackages ==<br />
Large documentation files should go in a subpackage. This subpackage must be named with the format: <code>%{name}-doc</code> .<br />
The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity.<br />
<br />
== Addon packages (General) ==<br />
If a new package is considered an "addon" package that enhances or adds a new functionality to an existing openSUSE package without being useful on its own, its name should reflect this fact.<br />
<br />
The new package ("child") should prepend the "parent" package in its name, in the format: <code>%{parent}-%{child}</code>.<br />
<br />
'''Examples:'''<br />
<pre><br />
gnome-applet-netmon (netmon applet for gnome, relies on gnome)<br />
php-adodb (adodb functionality for php, relies on php)<br />
python-twisted (the twisted module for python, relies on python)<br />
xmms-cdread (direct cd read functionality for xmms, relies on xmms)<br />
</pre><br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Richtlinien zur Bezeichnung von Paketen]]<br />
[[el:openSUSE:Package naming guidelines]]<br />
[[zh:openSUSE:Packaging_naming_guidelines]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Package_naming_guidelines&diff=62956openSUSE:Package naming guidelines2013-09-20T06:50:32Z<p>Thomas-schraitle: Removed space; added "the section"</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|The openSUSE package naming guidelines will help you to decide how to name your package and your specfile correctly.}}<br />
<br />
== Common Character Set for Package Naming ==<br />
While openSUSE is an international community, for consistency and usability, there needs to be a common character set for package naming.<br />
<br />
Specifically, all openSUSE packages must be named using only the following ASCII characters:<br />
<br />
<pre><br />
abcdefghijklmnopqrstuvwxyz<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZ<br />
0123456789-._+<br />
</pre><br />
<br />
=== When Upstream Naming is outside of the specified character set ===<br />
openSUSE recognizes that the task of converting text to the specified ASCII character set (aka transliteration) is difficult. Accordingly, when the upstream name is outside of the specified ASCII character set, the openSUSE package maintainer should first contact the upstream for that software and ask them for a transliteration of the name for openSUSE to use.<br />
<br />
If (and only if) the upstream project is unable, unwilling, or unavailable to provide a transliterated name, the openSUSE packager<br />
<br />
* must choose to either perform their own transliteration, or withdraw the package from consideration in openSUSE.<br />
<br />
* should look what other distributions have done for that package's name, and take that into account.<br />
<br />
Transliterated packages may Provide: the original, non-transliterated name, but are not required to do so.<br />
<br />
== General Naming ==<br />
When naming a package, the name should match the upstream tarball or project name from which this software came. In some cases, this naming choice may be more complicated. If this package has been packaged by other distributions/packagers in the past, then you should try to match their name for consistency. In any case, try to use your best judgement, and other developers will help in the final decision.<br />
<br />
Additionally, it is possible that the upstream name does not fall into the [[#CommonCharacterSet| Common Character Set]]. If this is the case, refer to the section [[#Transliteration| When Upstream Naming is outside of the specified character set]] .<br />
<br />
=== Separators ===<br />
When naming packages for openSUSE, the maintainer must use the dash '-' as the delimiter for name parts. The maintainer must NOT use an underscore '_', a plus '+', or a period '.' as a delimiter.<br />
<br />
There are a few exceptions to the no underscore '_' rule.<br />
* httpd, pam, and SDL addon packages are excluded, refer to "'''[[#Addon_Packages_.28httpd.2C_pam.2C_and_SDL.29| Addon Packages (httpd, pam and SDL)]] '''".<br />
* packages that are locale specific, and use the locale in the name are excluded, refer to "'''[[#Addon_Packages_.28locales.29| Addon Packages (locale)]] '''".<br />
* packages where the upstream name naturally contains an underscore are excluded from this. <br />
<br />
Examples of these packages include:<br />
<pre><br />
java_cup<br />
libart_lgpl<br />
microcode_ctl<br />
nss_ldap<br />
sg3_utils<br />
</pre><br />
<br />
If in doubt, ask on [http://lists.opensuse.org/opensuse-packaging/ opensuse-packaging] mailing list list.<br />
<br />
=== Multiple packages for the same software ===<br />
For many reasons, it is sometimes advantageous or necessary to keep multiple versions of a package in openSUSE to be installed simultaneously. The following applies both to package source names and names of binary packages, with the exception of shared library binary packages&nbsp;— those have [[openSUSE:Shared library packaging policy|their own guidelines]].<br />
<br />
When providing multiple versions of a software, the package name should reflect this fact. The package with the most recent version should use the principal name with no versions and all other addons should note their version in the name. There are some exceptions where all packages have a version attached to the package name (e.g. <tt>sqlite</tt>), i.e. there is no package without version in the name. As you can see, some package names have removed delimiters (e.g. <tt>celt051</tt>); doing so however leads to somewhat odd names when numbers go beyond an order of magnitude&nbsp;— think <tt>celt010</tt> (0.10 or 0.1.0?). Applying the Shared Library Packaging Guidelines's recommendations (replacing delimiters by underscores) is therefore a possible alternative (<tt>love-0_7_2</tt>).<br />
<br />
Examples:<br />
<br />
* simultaneously installable development packages: <tt>celt051-devel</tt>, <tt>libcelt-devel</tt>; <tt>sqlite2-devel</tt>, <tt>sqlite3-devel</tt><br />
* simultaneously installable application software: <tt>love-0_7_2</tt>, <tt>love</tt>; <tt>autoconf213</tt>, <tt>autoconf</tt><br />
<br />
=== Case Sensitivity ===<br />
In openSUSE packaging, the maintainer should use his/her best judgement when considering how to name the package. While case sensitivity is not a mandatory requirement, case should only be used where necessary. Keep in mind to respect the wishes of the upstream maintainers. If they refer to their application as "ORBit", you should use "ORBit" as the package name, and not "orbit". However, if they do not express any preference of case, you should default to lowercase naming.<BR><br />
<BR><br />
The exception to this is for perl module packaging. The CPAN Group and Type should be capitalized in the name, as if they were proper nouns . (Refer to '''[[#AddonPerl| Addon Packages (perl modules)]] ''' for details.)<br />
<br />
=== Spec file name ===<br />
The spec file should be named using the %{name}.spec scheme. If your package is named foo-1.0-1.src.rpm, then the spec file should be named foo.spec.<br />
<br />
== Handling special version strings ==<br />
The Version should follow the upstream tarball version. <br />
<br />
If this is not possible, please check if one of the solutions below can address your case.<br />
<br />
=== SCM snapshots ===<br />
<br />
When creating tarballs from an SCM repository, use the nearest applicable release version, append a delimiter (often, '<tt>+</tt>' is used, but '<tt>.</tt>' is visually pleasant too), a short tag identifying the SCM type and an SCM-specific monotonically increasing identifier. Examples for common applications of this scheme:<br />
<br />
'''Git''' can express a commit as an offset from a tag to yield a relatively short identifier. For example, if `<tt>git describe</tt>` outputs <tt>v3.14.1-5-g9265358</tt>, the rpm version could be set to '''3.14.1+git5''' or, if more disambiguation is desired, '''3.14.1+git5.g9265358'''. You may need to use `<tt>git describe --tags</tt>` if the git repository maintainer uses only simple tags rather than annotated tags. If the maintainer provides no git tags, report that shortcoming. In the meantime, an alternative monotonically increasing identifier can be obtained by using the history root as a base (`<tt>git rev-list 9265358 | wc -l</tt>`), useful for when a project is in such an early stage that there have not been any releases yet (<tt>Version: 0~git123</tt>).<br />
<br />
'''Subversion''' has revision numbers which can directly be used. The base version however needs to be determined in other ways. Version: '''3.14.1+svn592'''.<br />
<br />
For '''CVS''', a timestamp seems the shortest unambiguous (to the developer, at least) snapshot identifier because all files have their own revision tree. Version: '''3.14.1+cvs20130621'''.<br />
<br />
=== Pre-Release packages ===<br />
<br />
Pre-release versions using the same version number as the final releases need some additional care. Different developers have different ideas about how to name their preleasess; "''1.8b''" could indicate either 1.8 beta that comes ''before'' 1.8, or it could indicate a release actually made ''after'' 1.8. As such, package utilities (correctly so) make no effort to special-case “alpha”, “beta”, “a”, “b”, or any other name for that matter, and usually sort by longest string such that "1.8" comes before "1.8b". A distro package maintainer is to tweak the <tt>Version:</tt> field in the .spec file in accordance with the sort order provided by our utilities. There are a number of ways to pick from, in the order of descending preference:<br />
<br />
* Some upstreams assign their prereleases sortable numbers (that no other normal release will obtain). For example, <tt>sssd-1.8.0beta2.tar.gz</tt> is defined to be “1.7.92”. Use <tt>Version: 1.7.92</tt>.<br />
* Starting with rpm-4.10 (and backported into openSUSE 12.2's rpm 4.9.1), rpm has adopted the so-called “tilde versions” from Debian. With this, the spec's Version: field can contain a tilde as a special marker that sorts before anything else, including the end-of-string ("1.8~" < "1.8"). <tt>Version: 1.8.0~beta2</tt>. Tildes can be used multiple times, should it really become necessary.<br />
* For the final release, choose a version string that sorts after the upstream final but before any future release. (Choices are indeed limited.) <tt>Version: 1.8.0.beta2</tt> for the prerelease, <tt>Version: 1.8.0.0</tt> for the final. This relies on the property that RPM sorts A–Z before 0–9. As you have noticed, rpm does not bluntly sort by ASCII value, and so, this variant may not necessarily work with non-RPM systems, should you plan to build for them too using OBS.<br />
* For the prerelease, choose a version that sorts before the final but after any potential future releases in the series, and use it to prefix the actual version. <tt>Version: 1.7.99_1.8.0beta2</tt> for the prerelease, <tt>Version: 1.8.0</tt> for the final.<br />
* Bumping the <tt>Epoch:</tt> field. Note that '''openSUSE does not use epochs''', one reaosn being that zypper can actually handle downgrades (unlike yum, presumably). In fact, '''Epoch is considered harmful''', citing the ''[http://www.rpm.org/max-rpm-snapshot/s1-rpm-depend-manual-dependencies.html Maximum RPM]'' book:<br />
<br />
{{Info|'''''Solution Number 2: Just Say No!''' If you have the option between changing the software's version-numbering scheme, or using epoch numbers in RPM, please consider changing the version-numbering scheme. Chances are, if RPM can't figure it out, most of the people using your software can't, either.''}}<br />
<br />
Do not attempt to abuse the rpm ''Release:'' tag for ''version'' information either. It is the wrong field to convey this information, and the Open Build Service will by default overwrite Release: anyway with checkin and build counters.<br />
<br />
=== Post-Release packages ===<br />
<br />
By and large, post releases generally pose no problem because upstreams generally version them such that they follow final releases.<br />
<br />
If upstream is using delimiters from the permitted character set, then just reuse that for the version string. Otherwise replace them by something permitted.<br />
<br />
* openssl-0.9.8p: <tt>Version: 0.9.8p</tt><br />
* suse-11-GA1: <tt>Version: 11.GA1</tt> # GA=General Availability<br />
<br />
Again, letter strings that only have meaning to humans (like GA here) may need to be prefixed by something like a number that helps ordering them the way upstream intended if the natural order of A–Z<br />
is not sufficient. Assuming FUBAR comes after GA, then<br />
<br />
* suse-11-GA1: <tt>Version: 11+0.GA1</tt><br />
* suse-11-FUBAR1: <tt>Version: 11+1.FUBAR1</tt><br />
<br />
would be a workable solution. You will notice '<tt>+</tt>' was chosen here by the wiki page editor instead of '<tt>.</tt>' as a delimiter here, for reason to avoid somewhat ambiguous versions (11.0.GA1 could either be interpreted as 11.0+GA1 or 11+0.GA1).<br />
<br />
For prereleases to postreleases, simply use the tilde mechanism as described above (“openssl-0.9.6q~betaX”).<br />
<br />
== Renaming/replacing existing packages ==<br />
<br />
Described in [[openSUSE:Package_dependencies#Renaming_a_package|Package dependencies: Renaming a package]].<br />
<br />
== Documentation SubPackages ==<br />
Large documentation files should go in a subpackage. This subpackage must be named with the format: <code>%{name}-doc</code> .<br />
The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity.<br />
<br />
== Addon packages (General) ==<br />
If a new package is considered an "addon" package that enhances or adds a new functionality to an existing openSUSE package without being useful on its own, its name should reflect this fact.<br />
<br />
The new package ("child") should prepend the "parent" package in its name, in the format: <code>%{parent}-%{child}</code>.<br />
<br />
'''Examples:'''<br />
<pre><br />
gnome-applet-netmon (netmon applet for gnome, relies on gnome)<br />
php-adodb (adodb functionality for php, relies on php)<br />
python-twisted (the twisted module for python, relies on python)<br />
xmms-cdread (direct cd read functionality for xmms, relies on xmms)<br />
</pre><br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Richtlinien zur Bezeichnung von Paketen]]<br />
[[el:openSUSE:Package naming guidelines]]<br />
[[zh:openSUSE:Packaging_naming_guidelines]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Package_naming_guidelines&diff=62955openSUSE:Package naming guidelines2013-09-20T06:48:30Z<p>Thomas-schraitle: Removed cruft</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|The openSUSE package naming guidelines will help you to decide how to name your package and your specfile correctly.}}<br />
<br />
== Common Character Set for Package Naming ==<br />
While openSUSE is an international community, for consistency and usability, there needs to be a common character set for package naming.<br />
<br />
Specifically, all openSUSE packages must be named using only the following ASCII characters:<br />
<br />
<pre><br />
abcdefghijklmnopqrstuvwxyz<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZ<br />
0123456789-._+<br />
</pre><br />
<br />
=== When Upstream Naming is outside of the specified character set ===<br />
openSUSE recognizes that the task of converting text to the specified ASCII character set (aka transliteration) is difficult. Accordingly, when the upstream name is outside of the specified ASCII character set, the openSUSE package maintainer should first contact the upstream for that software and ask them for a transliteration of the name for openSUSE to use.<br />
<br />
If (and only if) the upstream project is unable, unwilling, or unavailable to provide a transliterated name, the openSUSE packager<br />
<br />
* must choose to either perform their own transliteration, or withdraw the package from consideration in openSUSE.<br />
<br />
* should look what other distributions have done for that package's name, and take that into account.<br />
<br />
Transliterated packages may Provide: the original, non-transliterated name, but are not required to do so.<br />
<br />
== General Naming ==<br />
When naming a package, the name should match the upstream tarball or project name from which this software came. In some cases, this naming choice may be more complicated. If this package has been packaged by other distributions/packagers in the past, then you should try to match their name for consistency. In any case, try to use your best judgement, and other developers will help in the final decision.<br />
<br />
Additionally, it is possible that the upstream name does not fall into the [[#CommonCharacterSet| Common Character Set]] . If this is the case, refer to: [[#Transliteration| When Upstream Naming is outside of the specified character set]] .<br />
<br />
=== Separators ===<br />
When naming packages for openSUSE, the maintainer must use the dash '-' as the delimiter for name parts. The maintainer must NOT use an underscore '_', a plus '+', or a period '.' as a delimiter.<br />
<br />
There are a few exceptions to the no underscore '_' rule.<br />
* httpd, pam, and SDL addon packages are excluded, refer to "'''[[#Addon_Packages_.28httpd.2C_pam.2C_and_SDL.29| Addon Packages (httpd, pam and SDL)]] '''".<br />
* packages that are locale specific, and use the locale in the name are excluded, refer to "'''[[#Addon_Packages_.28locales.29| Addon Packages (locale)]] '''".<br />
* packages where the upstream name naturally contains an underscore are excluded from this. <br />
<br />
Examples of these packages include:<br />
<pre><br />
java_cup<br />
libart_lgpl<br />
microcode_ctl<br />
nss_ldap<br />
sg3_utils<br />
</pre><br />
<br />
If in doubt, ask on [http://lists.opensuse.org/opensuse-packaging/ opensuse-packaging] mailing list list.<br />
<br />
=== Multiple packages for the same software ===<br />
For many reasons, it is sometimes advantageous or necessary to keep multiple versions of a package in openSUSE to be installed simultaneously. The following applies both to package source names and names of binary packages, with the exception of shared library binary packages&nbsp;— those have [[openSUSE:Shared library packaging policy|their own guidelines]].<br />
<br />
When providing multiple versions of a software, the package name should reflect this fact. The package with the most recent version should use the principal name with no versions and all other addons should note their version in the name. There are some exceptions where all packages have a version attached to the package name (e.g. <tt>sqlite</tt>), i.e. there is no package without version in the name. As you can see, some package names have removed delimiters (e.g. <tt>celt051</tt>); doing so however leads to somewhat odd names when numbers go beyond an order of magnitude&nbsp;— think <tt>celt010</tt> (0.10 or 0.1.0?). Applying the Shared Library Packaging Guidelines's recommendations (replacing delimiters by underscores) is therefore a possible alternative (<tt>love-0_7_2</tt>).<br />
<br />
Examples:<br />
<br />
* simultaneously installable development packages: <tt>celt051-devel</tt>, <tt>libcelt-devel</tt>; <tt>sqlite2-devel</tt>, <tt>sqlite3-devel</tt><br />
* simultaneously installable application software: <tt>love-0_7_2</tt>, <tt>love</tt>; <tt>autoconf213</tt>, <tt>autoconf</tt><br />
<br />
=== Case Sensitivity ===<br />
In openSUSE packaging, the maintainer should use his/her best judgement when considering how to name the package. While case sensitivity is not a mandatory requirement, case should only be used where necessary. Keep in mind to respect the wishes of the upstream maintainers. If they refer to their application as "ORBit", you should use "ORBit" as the package name, and not "orbit". However, if they do not express any preference of case, you should default to lowercase naming.<BR><br />
<BR><br />
The exception to this is for perl module packaging. The CPAN Group and Type should be capitalized in the name, as if they were proper nouns . (Refer to '''[[#AddonPerl| Addon Packages (perl modules)]] ''' for details.)<br />
<br />
=== Spec file name ===<br />
The spec file should be named using the %{name}.spec scheme. If your package is named foo-1.0-1.src.rpm, then the spec file should be named foo.spec.<br />
<br />
== Handling special version strings ==<br />
The Version should follow the upstream tarball version. <br />
<br />
If this is not possible, please check if one of the solutions below can address your case.<br />
<br />
=== SCM snapshots ===<br />
<br />
When creating tarballs from an SCM repository, use the nearest applicable release version, append a delimiter (often, '<tt>+</tt>' is used, but '<tt>.</tt>' is visually pleasant too), a short tag identifying the SCM type and an SCM-specific monotonically increasing identifier. Examples for common applications of this scheme:<br />
<br />
'''Git''' can express a commit as an offset from a tag to yield a relatively short identifier. For example, if `<tt>git describe</tt>` outputs <tt>v3.14.1-5-g9265358</tt>, the rpm version could be set to '''3.14.1+git5''' or, if more disambiguation is desired, '''3.14.1+git5.g9265358'''. You may need to use `<tt>git describe --tags</tt>` if the git repository maintainer uses only simple tags rather than annotated tags. If the maintainer provides no git tags, report that shortcoming. In the meantime, an alternative monotonically increasing identifier can be obtained by using the history root as a base (`<tt>git rev-list 9265358 | wc -l</tt>`), useful for when a project is in such an early stage that there have not been any releases yet (<tt>Version: 0~git123</tt>).<br />
<br />
'''Subversion''' has revision numbers which can directly be used. The base version however needs to be determined in other ways. Version: '''3.14.1+svn592'''.<br />
<br />
For '''CVS''', a timestamp seems the shortest unambiguous (to the developer, at least) snapshot identifier because all files have their own revision tree. Version: '''3.14.1+cvs20130621'''.<br />
<br />
=== Pre-Release packages ===<br />
<br />
Pre-release versions using the same version number as the final releases need some additional care. Different developers have different ideas about how to name their preleasess; "''1.8b''" could indicate either 1.8 beta that comes ''before'' 1.8, or it could indicate a release actually made ''after'' 1.8. As such, package utilities (correctly so) make no effort to special-case “alpha”, “beta”, “a”, “b”, or any other name for that matter, and usually sort by longest string such that "1.8" comes before "1.8b". A distro package maintainer is to tweak the <tt>Version:</tt> field in the .spec file in accordance with the sort order provided by our utilities. There are a number of ways to pick from, in the order of descending preference:<br />
<br />
* Some upstreams assign their prereleases sortable numbers (that no other normal release will obtain). For example, <tt>sssd-1.8.0beta2.tar.gz</tt> is defined to be “1.7.92”. Use <tt>Version: 1.7.92</tt>.<br />
* Starting with rpm-4.10 (and backported into openSUSE 12.2's rpm 4.9.1), rpm has adopted the so-called “tilde versions” from Debian. With this, the spec's Version: field can contain a tilde as a special marker that sorts before anything else, including the end-of-string ("1.8~" < "1.8"). <tt>Version: 1.8.0~beta2</tt>. Tildes can be used multiple times, should it really become necessary.<br />
* For the final release, choose a version string that sorts after the upstream final but before any future release. (Choices are indeed limited.) <tt>Version: 1.8.0.beta2</tt> for the prerelease, <tt>Version: 1.8.0.0</tt> for the final. This relies on the property that RPM sorts A–Z before 0–9. As you have noticed, rpm does not bluntly sort by ASCII value, and so, this variant may not necessarily work with non-RPM systems, should you plan to build for them too using OBS.<br />
* For the prerelease, choose a version that sorts before the final but after any potential future releases in the series, and use it to prefix the actual version. <tt>Version: 1.7.99_1.8.0beta2</tt> for the prerelease, <tt>Version: 1.8.0</tt> for the final.<br />
* Bumping the <tt>Epoch:</tt> field. Note that '''openSUSE does not use epochs''', one reaosn being that zypper can actually handle downgrades (unlike yum, presumably). In fact, '''Epoch is considered harmful''', citing the ''[http://www.rpm.org/max-rpm-snapshot/s1-rpm-depend-manual-dependencies.html Maximum RPM]'' book:<br />
<br />
{{Info|'''''Solution Number 2: Just Say No!''' If you have the option between changing the software's version-numbering scheme, or using epoch numbers in RPM, please consider changing the version-numbering scheme. Chances are, if RPM can't figure it out, most of the people using your software can't, either.''}}<br />
<br />
Do not attempt to abuse the rpm ''Release:'' tag for ''version'' information either. It is the wrong field to convey this information, and the Open Build Service will by default overwrite Release: anyway with checkin and build counters.<br />
<br />
=== Post-Release packages ===<br />
<br />
By and large, post releases generally pose no problem because upstreams generally version them such that they follow final releases.<br />
<br />
If upstream is using delimiters from the permitted character set, then just reuse that for the version string. Otherwise replace them by something permitted.<br />
<br />
* openssl-0.9.8p: <tt>Version: 0.9.8p</tt><br />
* suse-11-GA1: <tt>Version: 11.GA1</tt> # GA=General Availability<br />
<br />
Again, letter strings that only have meaning to humans (like GA here) may need to be prefixed by something like a number that helps ordering them the way upstream intended if the natural order of A–Z<br />
is not sufficient. Assuming FUBAR comes after GA, then<br />
<br />
* suse-11-GA1: <tt>Version: 11+0.GA1</tt><br />
* suse-11-FUBAR1: <tt>Version: 11+1.FUBAR1</tt><br />
<br />
would be a workable solution. You will notice '<tt>+</tt>' was chosen here by the wiki page editor instead of '<tt>.</tt>' as a delimiter here, for reason to avoid somewhat ambiguous versions (11.0.GA1 could either be interpreted as 11.0+GA1 or 11+0.GA1).<br />
<br />
For prereleases to postreleases, simply use the tilde mechanism as described above (“openssl-0.9.6q~betaX”).<br />
<br />
== Renaming/replacing existing packages ==<br />
<br />
Described in [[openSUSE:Package_dependencies#Renaming_a_package|Package dependencies: Renaming a package]].<br />
<br />
== Documentation SubPackages ==<br />
Large documentation files should go in a subpackage. This subpackage must be named with the format: <code>%{name}-doc</code> .<br />
The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity.<br />
<br />
== Addon packages (General) ==<br />
If a new package is considered an "addon" package that enhances or adds a new functionality to an existing openSUSE package without being useful on its own, its name should reflect this fact.<br />
<br />
The new package ("child") should prepend the "parent" package in its name, in the format: <code>%{parent}-%{child}</code>.<br />
<br />
'''Examples:'''<br />
<pre><br />
gnome-applet-netmon (netmon applet for gnome, relies on gnome)<br />
php-adodb (adodb functionality for php, relies on php)<br />
python-twisted (the twisted module for python, relies on python)<br />
xmms-cdread (direct cd read functionality for xmms, relies on xmms)<br />
</pre><br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Richtlinien zur Bezeichnung von Paketen]]<br />
[[el:openSUSE:Package naming guidelines]]<br />
[[zh:openSUSE:Packaging_naming_guidelines]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Package_naming_guidelines&diff=62954openSUSE:Package naming guidelines2013-09-20T06:47:14Z<p>Thomas-schraitle: created list to make choices more visible; added "project" before upstream</p>
<hr />
<div>{{Packaging_docnav}}<br />
{{Intro|The openSUSE package naming guidelines will help you to decide how to name your package and your specfile correctly.}}<br />
<br />
== Common Character Set for Package Naming ==<br />
While openSUSE is an international community, for consistency and usability, there needs to be a common character set for package naming.<br />
<br />
Specifically, all openSUSE packages must be named using only the following ASCII characters. These characters are displayed here:<br />
<br />
<pre><br />
abcdefghijklmnopqrstuvwxyz<br />
ABCDEFGHIJKLMNOPQRSTUVWXYZ<br />
0123456789-._+<br />
</pre><br />
<br />
=== When Upstream Naming is outside of the specified character set ===<br />
openSUSE recognizes that the task of converting text to the specified ASCII character set (aka transliteration) is difficult. Accordingly, when the upstream name is outside of the specified ASCII character set, the openSUSE package maintainer should first contact the upstream for that software and ask them for a transliteration of the name for openSUSE to use.<br />
<br />
If (and only if) the upstream project is unable, unwilling, or unavailable to provide a transliterated name, the openSUSE packager<br />
<br />
* must choose to either perform their own transliteration, or withdraw the package from consideration in openSUSE.<br />
<br />
* should look what other distributions have done for that package's name, and take that into account.<br />
<br />
Transliterated packages may Provide: the original, non-transliterated name, but are not required to do so.<br />
<br />
== General Naming ==<br />
When naming a package, the name should match the upstream tarball or project name from which this software came. In some cases, this naming choice may be more complicated. If this package has been packaged by other distributions/packagers in the past, then you should try to match their name for consistency. In any case, try to use your best judgement, and other developers will help in the final decision.<br />
<br />
Additionally, it is possible that the upstream name does not fall into the [[#CommonCharacterSet| Common Character Set]] . If this is the case, refer to: [[#Transliteration| When Upstream Naming is outside of the specified character set]] .<br />
<br />
=== Separators ===<br />
When naming packages for openSUSE, the maintainer must use the dash '-' as the delimiter for name parts. The maintainer must NOT use an underscore '_', a plus '+', or a period '.' as a delimiter.<br />
<br />
There are a few exceptions to the no underscore '_' rule.<br />
* httpd, pam, and SDL addon packages are excluded, refer to "'''[[#Addon_Packages_.28httpd.2C_pam.2C_and_SDL.29| Addon Packages (httpd, pam and SDL)]] '''".<br />
* packages that are locale specific, and use the locale in the name are excluded, refer to "'''[[#Addon_Packages_.28locales.29| Addon Packages (locale)]] '''".<br />
* packages where the upstream name naturally contains an underscore are excluded from this. <br />
<br />
Examples of these packages include:<br />
<pre><br />
java_cup<br />
libart_lgpl<br />
microcode_ctl<br />
nss_ldap<br />
sg3_utils<br />
</pre><br />
<br />
If in doubt, ask on [http://lists.opensuse.org/opensuse-packaging/ opensuse-packaging] mailing list list.<br />
<br />
=== Multiple packages for the same software ===<br />
For many reasons, it is sometimes advantageous or necessary to keep multiple versions of a package in openSUSE to be installed simultaneously. The following applies both to package source names and names of binary packages, with the exception of shared library binary packages&nbsp;— those have [[openSUSE:Shared library packaging policy|their own guidelines]].<br />
<br />
When providing multiple versions of a software, the package name should reflect this fact. The package with the most recent version should use the principal name with no versions and all other addons should note their version in the name. There are some exceptions where all packages have a version attached to the package name (e.g. <tt>sqlite</tt>), i.e. there is no package without version in the name. As you can see, some package names have removed delimiters (e.g. <tt>celt051</tt>); doing so however leads to somewhat odd names when numbers go beyond an order of magnitude&nbsp;— think <tt>celt010</tt> (0.10 or 0.1.0?). Applying the Shared Library Packaging Guidelines's recommendations (replacing delimiters by underscores) is therefore a possible alternative (<tt>love-0_7_2</tt>).<br />
<br />
Examples:<br />
<br />
* simultaneously installable development packages: <tt>celt051-devel</tt>, <tt>libcelt-devel</tt>; <tt>sqlite2-devel</tt>, <tt>sqlite3-devel</tt><br />
* simultaneously installable application software: <tt>love-0_7_2</tt>, <tt>love</tt>; <tt>autoconf213</tt>, <tt>autoconf</tt><br />
<br />
=== Case Sensitivity ===<br />
In openSUSE packaging, the maintainer should use his/her best judgement when considering how to name the package. While case sensitivity is not a mandatory requirement, case should only be used where necessary. Keep in mind to respect the wishes of the upstream maintainers. If they refer to their application as "ORBit", you should use "ORBit" as the package name, and not "orbit". However, if they do not express any preference of case, you should default to lowercase naming.<BR><br />
<BR><br />
The exception to this is for perl module packaging. The CPAN Group and Type should be capitalized in the name, as if they were proper nouns . (Refer to '''[[#AddonPerl| Addon Packages (perl modules)]] ''' for details.)<br />
<br />
=== Spec file name ===<br />
The spec file should be named using the %{name}.spec scheme. If your package is named foo-1.0-1.src.rpm, then the spec file should be named foo.spec.<br />
<br />
== Handling special version strings ==<br />
The Version should follow the upstream tarball version. <br />
<br />
If this is not possible, please check if one of the solutions below can address your case.<br />
<br />
=== SCM snapshots ===<br />
<br />
When creating tarballs from an SCM repository, use the nearest applicable release version, append a delimiter (often, '<tt>+</tt>' is used, but '<tt>.</tt>' is visually pleasant too), a short tag identifying the SCM type and an SCM-specific monotonically increasing identifier. Examples for common applications of this scheme:<br />
<br />
'''Git''' can express a commit as an offset from a tag to yield a relatively short identifier. For example, if `<tt>git describe</tt>` outputs <tt>v3.14.1-5-g9265358</tt>, the rpm version could be set to '''3.14.1+git5''' or, if more disambiguation is desired, '''3.14.1+git5.g9265358'''. You may need to use `<tt>git describe --tags</tt>` if the git repository maintainer uses only simple tags rather than annotated tags. If the maintainer provides no git tags, report that shortcoming. In the meantime, an alternative monotonically increasing identifier can be obtained by using the history root as a base (`<tt>git rev-list 9265358 | wc -l</tt>`), useful for when a project is in such an early stage that there have not been any releases yet (<tt>Version: 0~git123</tt>).<br />
<br />
'''Subversion''' has revision numbers which can directly be used. The base version however needs to be determined in other ways. Version: '''3.14.1+svn592'''.<br />
<br />
For '''CVS''', a timestamp seems the shortest unambiguous (to the developer, at least) snapshot identifier because all files have their own revision tree. Version: '''3.14.1+cvs20130621'''.<br />
<br />
=== Pre-Release packages ===<br />
<br />
Pre-release versions using the same version number as the final releases need some additional care. Different developers have different ideas about how to name their preleasess; "''1.8b''" could indicate either 1.8 beta that comes ''before'' 1.8, or it could indicate a release actually made ''after'' 1.8. As such, package utilities (correctly so) make no effort to special-case “alpha”, “beta”, “a”, “b”, or any other name for that matter, and usually sort by longest string such that "1.8" comes before "1.8b". A distro package maintainer is to tweak the <tt>Version:</tt> field in the .spec file in accordance with the sort order provided by our utilities. There are a number of ways to pick from, in the order of descending preference:<br />
<br />
* Some upstreams assign their prereleases sortable numbers (that no other normal release will obtain). For example, <tt>sssd-1.8.0beta2.tar.gz</tt> is defined to be “1.7.92”. Use <tt>Version: 1.7.92</tt>.<br />
* Starting with rpm-4.10 (and backported into openSUSE 12.2's rpm 4.9.1), rpm has adopted the so-called “tilde versions” from Debian. With this, the spec's Version: field can contain a tilde as a special marker that sorts before anything else, including the end-of-string ("1.8~" < "1.8"). <tt>Version: 1.8.0~beta2</tt>. Tildes can be used multiple times, should it really become necessary.<br />
* For the final release, choose a version string that sorts after the upstream final but before any future release. (Choices are indeed limited.) <tt>Version: 1.8.0.beta2</tt> for the prerelease, <tt>Version: 1.8.0.0</tt> for the final. This relies on the property that RPM sorts A–Z before 0–9. As you have noticed, rpm does not bluntly sort by ASCII value, and so, this variant may not necessarily work with non-RPM systems, should you plan to build for them too using OBS.<br />
* For the prerelease, choose a version that sorts before the final but after any potential future releases in the series, and use it to prefix the actual version. <tt>Version: 1.7.99_1.8.0beta2</tt> for the prerelease, <tt>Version: 1.8.0</tt> for the final.<br />
* Bumping the <tt>Epoch:</tt> field. Note that '''openSUSE does not use epochs''', one reaosn being that zypper can actually handle downgrades (unlike yum, presumably). In fact, '''Epoch is considered harmful''', citing the ''[http://www.rpm.org/max-rpm-snapshot/s1-rpm-depend-manual-dependencies.html Maximum RPM]'' book:<br />
<br />
{{Info|'''''Solution Number 2: Just Say No!''' If you have the option between changing the software's version-numbering scheme, or using epoch numbers in RPM, please consider changing the version-numbering scheme. Chances are, if RPM can't figure it out, most of the people using your software can't, either.''}}<br />
<br />
Do not attempt to abuse the rpm ''Release:'' tag for ''version'' information either. It is the wrong field to convey this information, and the Open Build Service will by default overwrite Release: anyway with checkin and build counters.<br />
<br />
=== Post-Release packages ===<br />
<br />
By and large, post releases generally pose no problem because upstreams generally version them such that they follow final releases.<br />
<br />
If upstream is using delimiters from the permitted character set, then just reuse that for the version string. Otherwise replace them by something permitted.<br />
<br />
* openssl-0.9.8p: <tt>Version: 0.9.8p</tt><br />
* suse-11-GA1: <tt>Version: 11.GA1</tt> # GA=General Availability<br />
<br />
Again, letter strings that only have meaning to humans (like GA here) may need to be prefixed by something like a number that helps ordering them the way upstream intended if the natural order of A–Z<br />
is not sufficient. Assuming FUBAR comes after GA, then<br />
<br />
* suse-11-GA1: <tt>Version: 11+0.GA1</tt><br />
* suse-11-FUBAR1: <tt>Version: 11+1.FUBAR1</tt><br />
<br />
would be a workable solution. You will notice '<tt>+</tt>' was chosen here by the wiki page editor instead of '<tt>.</tt>' as a delimiter here, for reason to avoid somewhat ambiguous versions (11.0.GA1 could either be interpreted as 11.0+GA1 or 11+0.GA1).<br />
<br />
For prereleases to postreleases, simply use the tilde mechanism as described above (“openssl-0.9.6q~betaX”).<br />
<br />
== Renaming/replacing existing packages ==<br />
<br />
Described in [[openSUSE:Package_dependencies#Renaming_a_package|Package dependencies: Renaming a package]].<br />
<br />
== Documentation SubPackages ==<br />
Large documentation files should go in a subpackage. This subpackage must be named with the format: <code>%{name}-doc</code> .<br />
The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity.<br />
<br />
== Addon packages (General) ==<br />
If a new package is considered an "addon" package that enhances or adds a new functionality to an existing openSUSE package without being useful on its own, its name should reflect this fact.<br />
<br />
The new package ("child") should prepend the "parent" package in its name, in the format: <code>%{parent}-%{child}</code>.<br />
<br />
'''Examples:'''<br />
<pre><br />
gnome-applet-netmon (netmon applet for gnome, relies on gnome)<br />
php-adodb (adodb functionality for php, relies on php)<br />
python-twisted (the twisted module for python, relies on python)<br />
xmms-cdread (direct cd read functionality for xmms, relies on xmms)<br />
</pre><br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Richtlinien zur Bezeichnung von Paketen]]<br />
[[el:openSUSE:Package naming guidelines]]<br />
[[zh:openSUSE:Packaging_naming_guidelines]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Build_Service_Tutorial&diff=60832openSUSE:Build Service Tutorial2013-04-29T07:26:25Z<p>Thomas-schraitle: Fixed typo</p>
<hr />
<div>{{Buildservice_navbar}}<br />
{{Packaging docnav}}<br />
{{Intro|This document should give an overview of the Build Service and a tutorial on how to build packages for different distributions using this great tool. We will try to show all actions on an example application so you can follow the steps to produce your own packages. }}<br />
<br />
== Prerequisites ==<br />
<br />
You should have a general understanding about [http://en.wikipedia.org/wiki/RPM_Package_Manager RPMs] and how they are created. See the [[openSUSE:Packaging_guidelines|packaging guidelines]] for openSUSE or a similar document of another supported packaging system such as [http://en.wikipedia.org/wiki/Dpkg dpkg]. This document is not meant to be a replacement for packaging documentation, which can be found at the above links.<br />
<br />
You should be familiar with the source code environment your project is using for your package. The Build Service can work around some common mistakes and will try to guide you in case of failures. We have a [http://lists.opensuse.org/archive/opensuse-buildservice/ buildservice-mailinglist] which can be a source of help and advice. However, decisions on which patches to apply, what compiler flags to use, etc. are ultimately up to you.<br />
<br />
== Requirements ==<br />
<br />
To make full use of the [http://build.opensuse.org Build Service], you need '''to login with your openSUSE/SUSE account''' (same as wiki, bugzilla...). If you have no account yet, click on the "[https://build.opensuse.org/ICSLogin/?%22https://build.opensuse.org/%22 sign up]" link at the top of the page to create one. Keep in mind that if you change your password someday that you also need to change <tt>~/.oscrc</tt>, and if you fail to do so and run osc commands that involve the server nevertheless, the user account may be blocked after repeated tries with an incorrect password.<br />
<br />
Futhermore, if you start the build as normal user (good idea!), you will be asked for the root password of your local machine. You can avoid that if you add your user to <tt>/etc/sudoers</tt> with the following procedure:<br />
<br />
<ol><br />
<li>Open your configuration file <tt>~/.oscrc</tt>.</li><br />
<li>Add the following line and save it:<br />
<pre>su-wrapper = sudo</pre><br />
</li><br />
<li>Run the following command:<br />
<pre>sudo /usr/sbin/visudo</pre><br />
</li><br />
<li>Add the following line and replace the placeholder LOGIN with your login name:<br />
<pre>LOGIN ALL = NOPASSWD: /usr/bin/build<br />
LOGIN ALL = NOPASSWD: /usr/bin/osc</pre><br />
</li><br />
</ol><br />
<br />
== Terminology ==<br />
<br />
The Build Service contains '''projects''' (you can [https://build.opensuse.org/project/list_all view a list of them]). Each project contains the resources needed to build one or more '''packages''' (i.e. RPMs/DEBs/etc.). These resources include source archives, patch files, spec files, etc. The output of a project is one or more '''repositories'''. A repository is an old familiar concept: simply a bunch of RPMs organized in a directory hierarchy along with some index/meta-data files that make it easy for tools like '''zypper''' to search and resolve dependencies. The repositories a project outputs correspond to the different operating system versions such as openSUSE 11.2, etc.<br />
<br />
As far as the projects that exist, there are "official" openSUSE projects that build the RPMs provided in the standard openSUSE distributions. The "factory" project is the work-in-progress project that will become the next version of openSUSE. There are also lots of area-specific projects such as [https://build.opensuse.org/project/show?project=Apache Apache] and [https://build.opensuse.org/project/show?project=network%3Atelephony network:telephony]. Finally, each user has his own "playground" project named '''home:''username'''''.<br />
<br />
RPMs tend to have lots of dependencies on other RPMs, and often these RPMs come from different projects within the Build Service. This has two important implications.<br />
<br />
First, if your package depends on some other package at runtime ("Requires"), it will often also depend on it at build time (i.e., "BuildRequires"). The Build Service does not automatically go search and find build dependencies for you (other than what is included in the standard distribution you are building for). So somehow you have to tell the Build Service where to get the required package.<br />
<br />
Secondly, a nice goal is for a repository to be '''transitively closed''', i.e. any dependency of any package in the repository is also in the repository (packages in the standard distribution excepted). This makes life easier for people installing the RPMs your project provides. But this is not required: users can always find these dependencies manually using the [http://software.opensuse.org/search search interface].<br />
<br />
The Build Service provides a few different ways to facilitate handling of these dependencies.<br />
<br />
First, you can directly add the required package(s) to your repository. This is<br />
certainly the approach you must take if no other project builds the required<br />
packages. Typically though, those packages are already being built by some<br />
other project. Consider re-using their work.<br />
<br />
The second option is to link the other project's repository to your repository.<br />
This is called '''layering'''. It is done by editing the meta-data of your<br />
project. Add the other project/repository as an additional path. This simply<br />
adds to the list of repositories in which the Build Service will search for<br />
"BuildRequires" dependencies at build time. This will allow your package's<br />
build to succeed, addressing the first problem, but it does not address the<br />
"transitively closed" goal at all: users will have to go fetch the required<br />
package themselves. However, this is a good choice when there are several<br />
dependencies from your project into another project and/or users are likely to<br />
be pulling from both repositories anyway.<br />
<br />
The third option is called '''linking''' and is a way to allow your project to<br />
re-use a package that already exists in another project. When you link a<br />
package into your project, dependent packages will be able to build, and the<br />
package will also appear your project's repository, therefore solving both<br />
problems without duplicating any work.<br />
<br />
There are two types of linking: '''link''' and '''aggregate'''. When you<br />
'''link''', you can optionally modify the way the package is built. You can add patches, and enable the build for additional repositories. Your build<br />
of the package's RPM will have a different build number from the original<br />
project's build of it. Note, this could cause confusion for users. Really, you<br />
are building a different version of a package with the same name.<br />
<br />
Unless you need to modify the required package, you should '''aggregate'''<br />
instead of '''link'''. When you '''aggregate''', you are performing a<br />
"read-only" link. The package is not built within your project; instead, the<br />
already-built package is copied into your project from the original project. So<br />
the same RPM (with the same build number) will appear in both projects. For the<br />
user, there is less confusion because the RPMs are identical. <br />
<br />
The Build Service automatically detects changes in linked packages and triggers rebuilds of any packages depending on them.<br />
<br />
== Workflow ==<br />
<br />
The following steps outline a normal workflow to create a project and add packages to it. Of course, in a real world example you might fail at some steps and have to repeat it until it does not fail anymore. This outline is just to give you a feeling about what we are trying to achieve. <br />
<br />
We will show you two different ways if possible: <br />
* the '''[http://build.opensuse.org Web client]''' way<br />
* the '''[[openSUSE:OSC|Command line]]''' client way <br />
* An alternate method is the '''MonoOSC''' client way, a tutorial already exist [[openSUSE:MonoOSC_guide|here]], so no need to duplicate.<br />
<br />
=== Step One – Login and one time Local Project setup ===<br />
<br />
If you already have an openSUSE Account, this is the easiest step.<br />
<br />
* '''Web client''': Open http://build.opensuse.org/ and use the login link on the upper right to login. After that, your home project is available by clicking on your username.<br />
<br />
* '''Command line''': <br />
<br />
At first, you have to install the command-line client on your machine. You can find osc packages for different distributions in the [http://download.opensuse.org/repositories/openSUSE:/Tools/ openSUSE-Tools] software download repository (yes: this is also a Build Service Project). Use your favorite package manager to install the osc package.<br />
<br />
Afterwards, "cd" into the directory you want to use for your project files. Now everybody familiar with [[wikipedia:en:Apache_Subversion|SVN]] will feel "at home": try to checkout your home project using <br />
cd <directory_to_contain_project_root><br />
osc checkout home:&lt;username&gt;<br />
cd home:&lt;username&gt; <br />
: (please replace &lt;username&gt; with your login). You will be prompted for '''your username and password''' — afterwards, osc will try to checkout packages in your home project and create a new directory called home:&lt;username&gt;. You can edit your settings in the file <tt>~/.oscrc</tt>.<br />
<br />
=== Step Two – Create & Upload packages ===<br />
<br />
You can use your home project as a "playground" to test packages which will be transferred to other, more visible projects if everything is alright.<br />
<br />
* '''Web client''': Click on your username to open your home project, then click on "create new package" in the packages tab. You should fill out the following three textfields: "Name" (mandatory), "Title" and "Description". Just use the package name as "Name", the package summary as "Title" and the package description as "Description". <br />
<br />
After the package is created, go to the "Sources" tab to add the files for your package. You need to upload the source code of your package and at least a spec file (see also [[openSUSE:Packaging_guidelines]]).<br />
<br />
* '''Command line''':<br />
osc meta pkg -e home:&lt;username&gt; &lt;packagename&gt;<br />
<br />
osc will open a template xml file in your favorite editor (based on the <tt>EDITOR</tt> environment variable) and you can just add the same things (Name, Title and Description) as described above. <br />
<br />
Now call<br />
osc up<br />
and you will get a new directory with the name of your new package. To add files via the command line, just cd into the new directory, copy the relevant files (typically a .tar.xz and support files).<br />
<br />
openSUSE RPM packages have their build instructions in a specfile.<br />
See the [[openSUSE:Packaging_guidelines|packaging guidelines]] how to create this. An easier approach is to copy and adapt a specfile from a similar package, or from within the tar-ball, if available.<br />
When the files are ready call<br />
osc add *<br />
this will mark the files in the directory for the next submit. To submit the files, call<br />
osc commit<br />
A commit automatically triggers the build process. You may want to delay the commit, until after you successfully built the package locally, see below.<br />
<br />
=== Step Three – Choose build targets ===<br />
<br />
Now you have to select for which distributions (e.g. openSUSE 11.3, Ubuntu 10.04 etc.) your packages should get built. <br />
<br />
* '''Web client''': Go to the "Repositories" tab on your project, and click on ''add repositories'' and choose one of the available distributions and architectures.<br />
<br />
* '''Command line''': first get a list of available repositories<br />
osc ls<br />
then edit your project metadata:<br />
osc meta prj -e home:&lt;username&gt;<br />
and add the repository like:<br />
<br />
<repository name="openSUSE_Factory"><br />
<path project="openSUSE:Factory" repository="standard" /><br />
<arch>x86_64</arch><br />
<arch>i586</arch><br />
</repository><br />
<br />
'''project''' can be openSUSE:Factory, openSUSE:11.3, SUSE:SLE-11:SP1 and the like. The ''repository="standard"'' is just for future extensions (forks of a repository).<br />
<br />
=== Step Four – Build your package ===<br />
<br />
Your package is scheduled for build automatically after it is committed or some files have changed. If a required package is rebuilt, your package will automatically be rebuilt, too. <br />
<br />
You can also manually trigger a rebuild if you need: <br />
osc rebuildpac <project> <package> [<repo> [<arch>]]<br />
With the optional <repo> and <arch> arguments, the rebuild can be limited to a certain repository or architecture.<br />
<br />
If your project is named home:username, you can now find your project at http://download.opensuse.org/repositories/home:/username/<br />
<br />
==== Build your package locally ====<br />
<br />
Sometimes, it can be faster to build your package on your local machine instead of waiting for the results from the Build Service. <br />
osc supports local builds of your package if your local hardware supports it (on x86_64 you can build for i586 and x86_64, on i586 only for i586). <br />
<br />
===== Ensure you have the latest sources =====<br />
<br />
Use osc checkout (osc co) or osc up to ensure you have the latest version of the source.<br />
<br />
If it is project you don't have checkout at all:<br />
<br />
cd <your_obs_working_dir>;<br />
osc co <project> <package><br />
<br />
or<br />
<br />
cd <your_obs_working_dir>/<project>;<br />
osc co <package><br />
<br />
or<br />
<br />
cd <your_obs_working_dir>/<project>/<package>;<br />
osc up<br />
<br />
===== Perform the local build =====<br />
<br />
osc build <platform> <arch> <specfile> [--clean|--noinit]<br />
for example<br />
~/obs/home:user/project # osc build openSUSE_11.4 x86_64 project.spec<br />
<br />
osc will connect to the OBS repository server and download all needed RPMs to <tt>/var/tmp/osbuild-packagecache/''plattform''/''repository''/''arch''</tt> as cache directory. If you want to avoid network traffic, its possible to fill the cache beforehand with rpms from a DVD or iso. For that, copy the rpms from the DVD to the cache dir. <br />
<br />
For example, for openSUSE_12.1 repository you can use a DVD iso as below:<br />
<br />
mount openSUSE-12.1.iso /mnt/ -o loop<br />
mkdir -p /var/tmp/osbuild-packagecache/openSUSE\:12.1/standard<br />
cp -r /mnt/suse/* /var/tmp/osbuild-packagecache/openSUSE:12.1/standard<br />
<br />
Now fix the permissions as the DVD is not writeable, but osc will need to write data into the cache:<br />
<br />
find /var/tmp/osbuild-packagecache/openSUSE:12.1 -type d -exec chmod 755 {} \;<br />
find /var/tmp/osbuild-packagecache/openSUSE:12.1 -type f -exec chmod 644 {} \;<br />
<br />
Packages can be now built locally like this:<br />
<br />
osc build openSUSE_12.1 i586 <some-package-name>.spec<br />
<br />
<TT >osc</TT > will create a chroot environment in <TT >/var/tmp/build-root/</TT > and start the build of your package. If you only have minor changes, you can avoid the re-creation of the build environment with the option <TT >--noinit</TT >. If you suspect that your chroot environment is broken, you can trigger a complete rebuild with the option <TT >--clean</TT >. You can configure the chroot directory; see the comments in your <TT >~/.oscrc</TT > file.<br />
<br />
: <TT >osc</TT > will refuse to install packages from projects your system does not trust. This may happen when your package is linked to a development project and your system is not configured to use that repository. You can get the necessary GPG key by executing:<br />
<br />
sudo rpm --import - <<_END_KEY<br />
$(osc signkey <VAR >offending-project</VAR >)<br />
_END_KEY<br />
<br />
After your packages are built in this chroot environment, you can find the resulting packages in <tt>/var/tmp/build-root/home/abuild/rpmbuild/RPMS/</tt> (older versions of rpmbuild use <tt>/usr/src/packages/RPMS/</tt>.<br />
<br />
If your package uses a URL download service, you may have to execute the following command first:<br />
<br />
zypper ar -r http://download.opensuse.org/repositories/openSUSE:/Tools/openSUSE_11.3/openSUSE:Tools.repo<br />
<br />
The complete log file of your local build is stored in ''/var/tmp/build-root/.build.log''.<br />
<br />
===== Correct Errors in the Local Build Process =====<br />
<br />
The main reason why you would need to compile a new package for openSUSE or any other distro is to assert compatibility if your package has not yet been compiled for your operating system version and release. <br />
However, that way you may encounter new errors in the build process which need to be fixed.<br />
The easiest way to fix errors is to chroot to the build environment and create a fix there. You may want to use [http://www.elstel.com/openroot openroot] instead of chroot in order to get X11 access and all the other necessary directories mounted.<br />
<br />
osc chroot openSUSE_12.1 x86_64<br />
<br />
or old-fashioned and cumbersome<br />
<br />
chroot /var/tmp/build-root/<br />
cd /home/abuild/rpmbuild/BUILD/your-package-dir<br />
ls<br />
or:<br />
openroot /var/tmp/build-root/ 'cd /home/abuild/rpmbuild/ILD/your-package-dir; ls; bash'<br />
...<br />
exit<br />
<br />
===== Dependencies =====<br />
If you get a dependency error during your build, add a line containing the build dependencies, like:<br />
BuildRequires: cmake libkde4-devel<br />
In this case, cmake and libkde4-devel will be installed before your package is built.<br />
<br />
===== Install extra packages to build root =====<br />
For debugging purposes, you might need to install extra packages to your local build root to debug and fix build related problems. This can be done through the '''~/.oscrc''' file and variable '''extra-pkgs'''. For example:<br />
<br />
extra-pkgs = vim gdb strace valgrind<br />
<br />
===== install privileges =====<br />
If you get an error message like this:<br />
error: Bad exit status from /var/tmp/rpm-tmp.qrRAn2 (%install)<br />
this means that your %install step has failed (and all others before went well). This can be because of missing write privileges if you try to install to the wrong place. In this case add the following make install command to your spec file:<br />
make install DESTDIR=%buildroot<br />
<br />
===== submit your work back to OBS =====<br />
Once you have your <package> directory the way you want it, use the below commands to submit your work back to OBS.<br />
<br />
add a new file to the package<br />
osc add <br />
<br />
remove a file from the package<br />
osc rm <br />
<br />
update the change log (ie. *.changes)<br />
osc vc <br />
<br />
submit your updated files back to OBS<br />
osc commit <br />
<br />
==== Patches ====<br />
If you plan to patch a file copy it before editing to .orig, retry the desired step in the build process until it succeeds and then create a patch for it. <br />
To make the build more verbose you may want to insert a "set -x" in your specfile making bash recite all executed commands (set +x disables reciting afterwards).<br />
diff -Pdpru /var/tmp/build-root/home/abuild/rpmbuild/BUILD/your-package-dir/Makefile.orig \<br />
/var/tmp/build-root/home/abuild/rpmbuild/BUILD/your-package-dir/Makefile \<br />
>/osc/home:user/your-package-dir/my.patch<br />
<br />
Now add the patch to the .spec-file by listing "Patch67: my.patch" in the header and then let it be applied at the appropriate position (usually %setup) in the build process by "%patch67 -p7" (-p7 strips seven directory levels if you have not manually edited the file directories in the header of the patch file.).<br />
You may find it easier to use a special program for automatic patch generation like [http://nordisch.org/2009/3/20/quilt-a-really-quick-howto Quilt].<br />
<br />
=== Step Five: Check the logfiles ===<br />
<br />
The buildservice produces one big logfile for each build of a package.<br />
<br />
* '''Web client''': Just click on the status of the ''Build result'' tab in the package view.<br />
<br />
* '''Command line''': You have a few choices depending on your needs (<code>packagedir</code> is optional if you are in the package directory):<br />
<br />
osc prjresults [packagedir]<br />
<br />
Shows the aggregated build results of an entire project. Or you can do:<br />
<br />
osc results [packagedir]<br />
<br />
Shows the build results of a single package.<br />
<br />
osc buildlog <platform> <arch><br />
<br />
Shows the log file from a package (you need to be inside a package directory).<br />
<br />
===Create Patterns===<br />
<br />
Patterns are files which contain a list of packages together with a description of what they are useful for. Additionally the Build Service creates .ymp files for each generated repository pattern. These .ymp files can be used for a [[openSUSE:One_Click_Install_specification|One Click Install]] by the user. <br />
<br />
In short, patterns are useful for installing a set of software for a typical need without creating dependencies between packages.<br />
<br />
Submitting patterns is possible using the api directly, or using osc:<br />
<br />
* to open a pattern in $EDITOR (creating it if it doesn't exist yet)<br />
osc meta pattern -e <project> <pattern><br />
* to list existing patterns<br />
osc meta pattern <project><br />
* get an existing pattern<br />
osc meta pattern <project> <pattern><br />
* You can also submit an existing file as below:<br />
osc meta pattern --file <local_file> <project> <pattern><br />
<br />
To test: clicking on the .ymp in konqueror should launch the installer, if you do not have konqueror installed, you can try launching from shell as normal user:<br />
/sbin/yast2 MetaPackageHandler http://download.opensuse.org/repositories/<project>/<SUSE_Factory or openSUSE_10.2>/<pattern>.ymp<br />
<br />
The following file is an example pattern file from the KDE:KDE4 project. You can see the generated .ymp file from it [http://download.opensuse.org/repositories/KDE:/KDE4:/Factory:/Desktop/openSUSE_Factory/KDE4-GAMES.ymp here].<br />
<pre><br />
<pattern<br />
xmlns="http://novell.com/package/metadata/suse/pattern"<br />
xmlns:rpm="http://linux.duke.edu/metadata/rpm"<br />
><br />
<name>KDE 4 Games</name><br />
<summary>KDE 4 Games</summary><br />
<description>A number of games for KDE 4.</description><br />
<uservisible/><br />
<category lang="en">Desktop Functions</category><br />
<rpm:recommends><br />
<rpm:entry name="kde4-kpat"/><br />
<rpm:entry name="kde4-kmahjongg"/><br />
<rpm:entry name="kde4-kmines"/><br />
<rpm:entry name="kde4-kreversi"/><br />
<rpm:entry name="kde4-ksudoku"/><br />
</rpm:recommends><br />
<rpm:suggests><br />
<rpm:entry name="kde4-katomic"/><br />
<rpm:entry name="kde4-kbattleship"/><br />
<rpm:entry name="kde4-ksquares"/><br />
<rpm:entry name="kde4-bovo"/><br />
<rpm:entry name="kde4-kiriki"/><br />
<rpm:entry name="kde4-kwin4"/><br />
<rpm:entry name="kde4-kolf"/><br />
<rpm:entry name="kde4-klines"/><br />
<rpm:entry name="kde4-ksame"/><br />
<rpm:entry name="kde4-lskat"/><br />
<rpm:entry name="kde4-kgoldrunner"/><br />
<rpm:entry name="kde4-kblackbox"/><br />
<rpm:entry name="kde4-kbounce"/><br />
<rpm:entry name="kde4-ktuberling"/><br />
<rpm:entry name="kde4-knetwalk"/><br />
<rpm:entry name="kde4-kjumpingcube"/><br />
<rpm:entry name="kde4-kspaceduel"/><br />
<rpm:entry name="kde4-konquest"/><br />
<rpm:entry name="kde4-kshisen"/><br />
</rpm:suggests><br />
</pattern><br />
</pre><br />
<br />
Some Tag descriptions:<br />
{| border="1" cellpadding="5" cellspacing="0"<br />
! Tag !! Description<br />
|-<br />
| <pre><rpm:requires><br />
<rpm:entry name="example" /><br />
</rpm:requires></pre> || '''Requires''' RPM ''example'': this package must be installed - otherwise the pattern is not fulfilled.<br />
|-<br />
| <pre><rpm:recommends><br />
<rpm:entry name="example" /><br />
</rpm:recommends></pre> || '''Recommends''' RPM ''example'': if available and all dependencies of this package are fulfilled, the package would be installed. If the package is not available, there are not error messages. If the package dependencies are not met, the package would be visible but not installed. <br />
|-<br />
| <pre><rpm:suggests><br />
<rpm:entry name="example" /><br />
</rpm:suggests></pre> || '''Suggests''' RPM ''example'': would be shown in the pattern but not installed per default<br />
|}<br />
<br />
== A start to end example of a simple change ==<br />
<br />
{{Info|'''Note:''' There are at least two other wiki pages that document the branch/fix/submit patch workflow:<br />
* [[openSUSE:Fixing_bugs]]<br />
* [[openSUSE:Package maintenance]]<br />
<br />
The goal here is to have a specific example that can be used as a tutorial.<br />
}}<br />
<br />
<br />
<br />
{{Warning|DRAFT BELOW, not yet finished or tested}}<br />
<br />
A common activity is to branch an existing package in an existing project, make a change and submit that change back to the original package.<br />
<br />
The basic steps are:<br />
<br />
# Branch the original package: "osc branch &lt;original_project&gt; &lt;original_package&gt;" This creates a new branch project that is specific for you named home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt; and therein it creates a new package with the same name as original package that is basically a copy of the original package.<br />
# Checkout the branched package: "osc checkout home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt;/&lt;original_package_name&gt;" This downloads the source files of the branched package from the server into a local sub-directory named home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt;/&lt;original_package_name&gt;<br />
# Go to the local sub-directory: "cd home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt;/&lt;original_package_name&gt;" and set the usual default umask "umask 0022"<br />
# Work on your local copy of the package until it works for you:<br />
## Change the local source files (e.g. edit the specfile or create a patch)<br />
## Perform a local build <br />
## Do a local package installation<br />
## Test the local installed package<br />
# Update the changes file: "osc vc" This opens an editor (usually 'vi') and creates an appropriate header for a RPM changes entry. If there was a bug report it must be referenced as bnc#123456<br />
# If you added new files (e.g. new patches) or removed files (e.g. obsolete patches), update the version control status of the local source files: "osc addremove" and verify with "osc status" that there are no files with problematic version control status like '?' or '!'<br />
# Commit the local source files into the branched package: "osc commit" This uploads the local source files into the branched package on the server and that triggers an automated re-build of the branched package.<br />
# Review the build results of the branched package for all build repositories that are enabled for the original package: "osc results --verbose home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt; &lt;original_package_name&gt;" To list the build repositories that are enabled for the original package get its build results: "osc results &lt;original_project&gt; &lt;original_package&gt;"<br />
# If the re-build of the branched package "succeeded" for all build repositories that are enabled for the original package, create a request to submit the branched package back to the original package: "osc submitrequest --message='&lt;a short message that describes what you changed plus bnc#123456 if there exists a matching bug report&gt;' home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt; &lt;original_package_name&gt; &lt;original_project&gt; &lt;original_package&gt;" and remenber the request ID number.<br />
# From time to time check what happened with your request: "osc request show &lt;request_ID_number&gt;" If you need to get in direct contact with the maintainers of the original package: "osc maintainer &lt;original_project&gt; &lt;original_package&gt;" shows their user names and "osc whois &lt;user_name&gt;" shows fullname and email of a buildservice user.<br />
<br />
It's a few steps, but once you get a hang on it, it becomes second nature.<br />
<br />
This assumes you already have an account on OBS. If not, go ahead and set that up at http://build.opensuse.org/ and use the login link on the upper right to login. OBS uses the same authentication system as the rest of the openSUSE infrastructure like bugzilla, so you likely all ready have a account, you just need to login for the first time and the OBS account home project will be automatically created.<br />
<br />
Here's a real example:<br />
<br />
One time setup from the command line<br />
sudo zypper in osc<br />
mkdir ~/obs<br />
<br />
Then you need to branch a local copy of a package.<br />
cd ~/obs<br />
umask 0022<br />
osc branch security sleuthkit<br />
osc co home:<your_user_name>:branches:security/sleuthkit<br />
cd ~/obs/home:<your_user_name>:branches:security/sleuthkit<br />
<br />
Now that you an existing package already, it's as easy as:<br />
# this untars the tarball and does some magic<br />
quilt setup sleuthkit.spec<br />
# chdir to sources<br />
cd sleuthkit-3.2.3<br />
# apply all patches<br />
quilt push -a<br />
# add new patch<br />
quilt new testing.patch<br />
# add a file to the patch<br />
quilt add some-file<br />
vi <some-file><br />
# or alternatively:<br />
quilt edit <some-file><br />
# and finally<br />
quilt refresh -p1<br />
# copy the patch up to the project dir<br />
cp patches/testing.patch .. <br />
# and now handle the spec file<br />
cd ..<br />
vi sleuthkit.spec<br />
# Add patch to it by creating a Patch0 entry in the header area and a %patch0 -p1 line to the %prep section<br />
<br />
# tell OBS that the package now includes a new file<br />
osc add testing.patch<br />
# update the changes file<br />
osc vc -m "Fix some typos."<br />
# and build, install and test your work<br />
osc build<br />
# perform a local install. At the end of the osc build output the full path of the RPM file should be shown<br />
zypper in -f <full_path_to_rpm><br />
# repeat until happy. Go back to quilt edit if not happy.<br />
# send your edits back to OBS<br />
osc commit<br />
# wait a period of time for new packages to build on OBS<br />
# check the build status via the WebUI for your branched package<br />
# Once published, install the RPM from OBS and test again<br />
# submit your changes back to the original package. If there is a bugzilla entry, be sure to reference it<br />
<br />
== See also ==<br />
<br />
* [[openSUSE:Build_Service_Tips_and_Tricks|General Tips and Tricks for the buildservice]]<br />
* [[openSUSE:Build_Service_Collaboration|How to contribute to a package maintained by someone else]]<br />
* [[openSUSE:Build_Service_cross_distribution_howto|Cross distribution package how to]]<br />
* [[openSUSE:OSC_plugins|Writing osc plugins]]<br />
* [[openSUSE:Build_Service_Debian_builds|Sharing Debian packages]]<br />
<br />
[[Category:Build Service|Tutorial]]<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Build Service Anleitung]]<br />
[[el:openSUSE:Build Service Tutorial]]<br />
[[es:Build Service/Guía_básica]]<br />
[[fr:Build Service/Tutoriel]]<br />
[[it:Build Service/Tutorial]]<br />
[[ru:openSUSE:Руководство_по_использованию_службы_сборки]]<br />
[[zh:SDB:编译服务教程]]</div>Thomas-schraitlehttps://en.opensuse.org/index.php?title=openSUSE:Build_Service_Tutorial&diff=60831openSUSE:Build Service Tutorial2013-04-29T07:21:30Z<p>Thomas-schraitle: Add editing /etc/sudoers as requirements to be at a more prominent location. Hiding it when the user is trying to do its tasks isn't very helpful.</p>
<hr />
<div>{{Buildservice_navbar}}<br />
{{Packaging docnav}}<br />
{{Intro|This document should give an overview of the Build Service and a tutorial on how to build packages for different distributions using this great tool. We will try to show all actions on an example application so you can follow the steps to produce your own packages. }}<br />
<br />
== Prerequisites ==<br />
<br />
You should have a general understanding about [http://en.wikipedia.org/wiki/RPM_Package_Manager RPMs] and how they are created. See the [[openSUSE:Packaging_guidelines|packaging guidelines]] for openSUSE or a similar document of another supported packaging system such as [http://en.wikipedia.org/wiki/Dpkg dpkg]. This document is not meant to be a replacement for packaging documentation, which can be found at the above links.<br />
<br />
You should be familiar with the source code environment your project is using for your package. The Build Service can work around some common mistakes and will try to guide you in case of failures. We have a [http://lists.opensuse.org/archive/opensuse-buildservice/ buildservice-mailinglist] which can be a source of help and advice. However, decisions on which patches to apply, what compiler flags to use, etc. are ultimately up to you.<br />
<br />
== Requirements ==<br />
<br />
To make full use of the [http://build.opensuse.org Build Service], you need '''to login with your openSUSE/SUSE account''' (same as wiki, bugzilla...). If you have no account yet, click on the "[https://build.opensuse.org/ICSLogin/?%22https://build.opensuse.org/%22 sign up]" link at the top of the page to create one. Keep in mind that if you change your password someday that you also need to change <tt>~/.oscrc</tt>, and if you fail to do so and run osc commands that involve the server nevertheless, the user account may be blocked after repeated tries with an incorrect password.<br />
<br />
Futhermore, if you start the build as normal user (good idea!), you will be asked for the root password of your local machine. You can avoid that if you add your user to <tt>/etc/sudoers</tt> with the following procedure:<br />
<br />
<ol><br />
<li>Open your configuration file <tt>~/.oscrc</tt>.</li><br />
<li>Add the following line and save it:<br />
<pre>su-wrapper = sudo</pre><br />
</li><br />
<li>Run the following command:<br />
<pre>sudo /usr/sbin/visudoy</pre><br />
</li><br />
<li>Add the following line and replace the placeholder LOGIN with your login name:<br />
<pre>LOGIN ALL = NOPASSWD: /usr/bin/build<br />
LOGIN ALL = NOPASSWD: /usr/bin/osc</pre><br />
</li><br />
</ol><br />
<br />
== Terminology ==<br />
<br />
The Build Service contains '''projects''' (you can [https://build.opensuse.org/project/list_all view a list of them]). Each project contains the resources needed to build one or more '''packages''' (i.e. RPMs/DEBs/etc.). These resources include source archives, patch files, spec files, etc. The output of a project is one or more '''repositories'''. A repository is an old familiar concept: simply a bunch of RPMs organized in a directory hierarchy along with some index/meta-data files that make it easy for tools like '''zypper''' to search and resolve dependencies. The repositories a project outputs correspond to the different operating system versions such as openSUSE 11.2, etc.<br />
<br />
As far as the projects that exist, there are "official" openSUSE projects that build the RPMs provided in the standard openSUSE distributions. The "factory" project is the work-in-progress project that will become the next version of openSUSE. There are also lots of area-specific projects such as [https://build.opensuse.org/project/show?project=Apache Apache] and [https://build.opensuse.org/project/show?project=network%3Atelephony network:telephony]. Finally, each user has his own "playground" project named '''home:''username'''''.<br />
<br />
RPMs tend to have lots of dependencies on other RPMs, and often these RPMs come from different projects within the Build Service. This has two important implications.<br />
<br />
First, if your package depends on some other package at runtime ("Requires"), it will often also depend on it at build time (i.e., "BuildRequires"). The Build Service does not automatically go search and find build dependencies for you (other than what is included in the standard distribution you are building for). So somehow you have to tell the Build Service where to get the required package.<br />
<br />
Secondly, a nice goal is for a repository to be '''transitively closed''', i.e. any dependency of any package in the repository is also in the repository (packages in the standard distribution excepted). This makes life easier for people installing the RPMs your project provides. But this is not required: users can always find these dependencies manually using the [http://software.opensuse.org/search search interface].<br />
<br />
The Build Service provides a few different ways to facilitate handling of these dependencies.<br />
<br />
First, you can directly add the required package(s) to your repository. This is<br />
certainly the approach you must take if no other project builds the required<br />
packages. Typically though, those packages are already being built by some<br />
other project. Consider re-using their work.<br />
<br />
The second option is to link the other project's repository to your repository.<br />
This is called '''layering'''. It is done by editing the meta-data of your<br />
project. Add the other project/repository as an additional path. This simply<br />
adds to the list of repositories in which the Build Service will search for<br />
"BuildRequires" dependencies at build time. This will allow your package's<br />
build to succeed, addressing the first problem, but it does not address the<br />
"transitively closed" goal at all: users will have to go fetch the required<br />
package themselves. However, this is a good choice when there are several<br />
dependencies from your project into another project and/or users are likely to<br />
be pulling from both repositories anyway.<br />
<br />
The third option is called '''linking''' and is a way to allow your project to<br />
re-use a package that already exists in another project. When you link a<br />
package into your project, dependent packages will be able to build, and the<br />
package will also appear your project's repository, therefore solving both<br />
problems without duplicating any work.<br />
<br />
There are two types of linking: '''link''' and '''aggregate'''. When you<br />
'''link''', you can optionally modify the way the package is built. You can add patches, and enable the build for additional repositories. Your build<br />
of the package's RPM will have a different build number from the original<br />
project's build of it. Note, this could cause confusion for users. Really, you<br />
are building a different version of a package with the same name.<br />
<br />
Unless you need to modify the required package, you should '''aggregate'''<br />
instead of '''link'''. When you '''aggregate''', you are performing a<br />
"read-only" link. The package is not built within your project; instead, the<br />
already-built package is copied into your project from the original project. So<br />
the same RPM (with the same build number) will appear in both projects. For the<br />
user, there is less confusion because the RPMs are identical. <br />
<br />
The Build Service automatically detects changes in linked packages and triggers rebuilds of any packages depending on them.<br />
<br />
== Workflow ==<br />
<br />
The following steps outline a normal workflow to create a project and add packages to it. Of course, in a real world example you might fail at some steps and have to repeat it until it does not fail anymore. This outline is just to give you a feeling about what we are trying to achieve. <br />
<br />
We will show you two different ways if possible: <br />
* the '''[http://build.opensuse.org Web client]''' way<br />
* the '''[[openSUSE:OSC|Command line]]''' client way <br />
* An alternate method is the '''MonoOSC''' client way, a tutorial already exist [[openSUSE:MonoOSC_guide|here]], so no need to duplicate.<br />
<br />
=== Step One – Login and one time Local Project setup ===<br />
<br />
If you already have an openSUSE Account, this is the easiest step.<br />
<br />
* '''Web client''': Open http://build.opensuse.org/ and use the login link on the upper right to login. After that, your home project is available by clicking on your username.<br />
<br />
* '''Command line''': <br />
<br />
At first, you have to install the command-line client on your machine. You can find osc packages for different distributions in the [http://download.opensuse.org/repositories/openSUSE:/Tools/ openSUSE-Tools] software download repository (yes: this is also a Build Service Project). Use your favorite package manager to install the osc package.<br />
<br />
Afterwards, "cd" into the directory you want to use for your project files. Now everybody familiar with [[wikipedia:en:Apache_Subversion|SVN]] will feel "at home": try to checkout your home project using <br />
cd <directory_to_contain_project_root><br />
osc checkout home:&lt;username&gt;<br />
cd home:&lt;username&gt; <br />
: (please replace &lt;username&gt; with your login). You will be prompted for '''your username and password''' — afterwards, osc will try to checkout packages in your home project and create a new directory called home:&lt;username&gt;. You can edit your settings in the file <tt>~/.oscrc</tt>.<br />
<br />
=== Step Two – Create & Upload packages ===<br />
<br />
You can use your home project as a "playground" to test packages which will be transferred to other, more visible projects if everything is alright.<br />
<br />
* '''Web client''': Click on your username to open your home project, then click on "create new package" in the packages tab. You should fill out the following three textfields: "Name" (mandatory), "Title" and "Description". Just use the package name as "Name", the package summary as "Title" and the package description as "Description". <br />
<br />
After the package is created, go to the "Sources" tab to add the files for your package. You need to upload the source code of your package and at least a spec file (see also [[openSUSE:Packaging_guidelines]]).<br />
<br />
* '''Command line''':<br />
osc meta pkg -e home:&lt;username&gt; &lt;packagename&gt;<br />
<br />
osc will open a template xml file in your favorite editor (based on the <tt>EDITOR</tt> environment variable) and you can just add the same things (Name, Title and Description) as described above. <br />
<br />
Now call<br />
osc up<br />
and you will get a new directory with the name of your new package. To add files via the command line, just cd into the new directory, copy the relevant files (typically a .tar.xz and support files).<br />
<br />
openSUSE RPM packages have their build instructions in a specfile.<br />
See the [[openSUSE:Packaging_guidelines|packaging guidelines]] how to create this. An easier approach is to copy and adapt a specfile from a similar package, or from within the tar-ball, if available.<br />
When the files are ready call<br />
osc add *<br />
this will mark the files in the directory for the next submit. To submit the files, call<br />
osc commit<br />
A commit automatically triggers the build process. You may want to delay the commit, until after you successfully built the package locally, see below.<br />
<br />
=== Step Three – Choose build targets ===<br />
<br />
Now you have to select for which distributions (e.g. openSUSE 11.3, Ubuntu 10.04 etc.) your packages should get built. <br />
<br />
* '''Web client''': Go to the "Repositories" tab on your project, and click on ''add repositories'' and choose one of the available distributions and architectures.<br />
<br />
* '''Command line''': first get a list of available repositories<br />
osc ls<br />
then edit your project metadata:<br />
osc meta prj -e home:&lt;username&gt;<br />
and add the repository like:<br />
<br />
<repository name="openSUSE_Factory"><br />
<path project="openSUSE:Factory" repository="standard" /><br />
<arch>x86_64</arch><br />
<arch>i586</arch><br />
</repository><br />
<br />
'''project''' can be openSUSE:Factory, openSUSE:11.3, SUSE:SLE-11:SP1 and the like. The ''repository="standard"'' is just for future extensions (forks of a repository).<br />
<br />
=== Step Four – Build your package ===<br />
<br />
Your package is scheduled for build automatically after it is committed or some files have changed. If a required package is rebuilt, your package will automatically be rebuilt, too. <br />
<br />
You can also manually trigger a rebuild if you need: <br />
osc rebuildpac <project> <package> [<repo> [<arch>]]<br />
With the optional <repo> and <arch> arguments, the rebuild can be limited to a certain repository or architecture.<br />
<br />
If your project is named home:username, you can now find your project at http://download.opensuse.org/repositories/home:/username/<br />
<br />
==== Build your package locally ====<br />
<br />
Sometimes, it can be faster to build your package on your local machine instead of waiting for the results from the Build Service. <br />
osc supports local builds of your package if your local hardware supports it (on x86_64 you can build for i586 and x86_64, on i586 only for i586). <br />
<br />
===== Ensure you have the latest sources =====<br />
<br />
Use osc checkout (osc co) or osc up to ensure you have the latest version of the source.<br />
<br />
If it is project you don't have checkout at all:<br />
<br />
cd <your_obs_working_dir>;<br />
osc co <project> <package><br />
<br />
or<br />
<br />
cd <your_obs_working_dir>/<project>;<br />
osc co <package><br />
<br />
or<br />
<br />
cd <your_obs_working_dir>/<project>/<package>;<br />
osc up<br />
<br />
===== Perform the local build =====<br />
<br />
osc build <platform> <arch> <specfile> [--clean|--noinit]<br />
for example<br />
~/obs/home:user/project # osc build openSUSE_11.4 x86_64 project.spec<br />
<br />
osc will connect to the OBS repository server and download all needed RPMs to <tt>/var/tmp/osbuild-packagecache/''plattform''/''repository''/''arch''</tt> as cache directory. If you want to avoid network traffic, its possible to fill the cache beforehand with rpms from a DVD or iso. For that, copy the rpms from the DVD to the cache dir. <br />
<br />
For example, for openSUSE_12.1 repository you can use a DVD iso as below:<br />
<br />
mount openSUSE-12.1.iso /mnt/ -o loop<br />
mkdir -p /var/tmp/osbuild-packagecache/openSUSE\:12.1/standard<br />
cp -r /mnt/suse/* /var/tmp/osbuild-packagecache/openSUSE:12.1/standard<br />
<br />
Now fix the permissions as the DVD is not writeable, but osc will need to write data into the cache:<br />
<br />
find /var/tmp/osbuild-packagecache/openSUSE:12.1 -type d -exec chmod 755 {} \;<br />
find /var/tmp/osbuild-packagecache/openSUSE:12.1 -type f -exec chmod 644 {} \;<br />
<br />
Packages can be now built locally like this:<br />
<br />
osc build openSUSE_12.1 i586 <some-package-name>.spec<br />
<br />
<TT >osc</TT > will create a chroot environment in <TT >/var/tmp/build-root/</TT > and start the build of your package. If you only have minor changes, you can avoid the re-creation of the build environment with the option <TT >--noinit</TT >. If you suspect that your chroot environment is broken, you can trigger a complete rebuild with the option <TT >--clean</TT >. You can configure the chroot directory; see the comments in your <TT >~/.oscrc</TT > file.<br />
<br />
: <TT >osc</TT > will refuse to install packages from projects your system does not trust. This may happen when your package is linked to a development project and your system is not configured to use that repository. You can get the necessary GPG key by executing:<br />
<br />
sudo rpm --import - <<_END_KEY<br />
$(osc signkey <VAR >offending-project</VAR >)<br />
_END_KEY<br />
<br />
After your packages are built in this chroot environment, you can find the resulting packages in <tt>/var/tmp/build-root/home/abuild/rpmbuild/RPMS/</tt> (older versions of rpmbuild use <tt>/usr/src/packages/RPMS/</tt>.<br />
<br />
If your package uses a URL download service, you may have to execute the following command first:<br />
<br />
zypper ar -r http://download.opensuse.org/repositories/openSUSE:/Tools/openSUSE_11.3/openSUSE:Tools.repo<br />
<br />
The complete log file of your local build is stored in ''/var/tmp/build-root/.build.log''.<br />
<br />
===== Correct Errors in the Local Build Process =====<br />
<br />
The main reason why you would need to compile a new package for openSUSE or any other distro is to assert compatibility if your package has not yet been compiled for your operating system version and release. <br />
However, that way you may encounter new errors in the build process which need to be fixed.<br />
The easiest way to fix errors is to chroot to the build environment and create a fix there. You may want to use [http://www.elstel.com/openroot openroot] instead of chroot in order to get X11 access and all the other necessary directories mounted.<br />
<br />
osc chroot openSUSE_12.1 x86_64<br />
<br />
or old-fashioned and cumbersome<br />
<br />
chroot /var/tmp/build-root/<br />
cd /home/abuild/rpmbuild/BUILD/your-package-dir<br />
ls<br />
or:<br />
openroot /var/tmp/build-root/ 'cd /home/abuild/rpmbuild/ILD/your-package-dir; ls; bash'<br />
...<br />
exit<br />
<br />
===== Dependencies =====<br />
If you get a dependency error during your build, add a line containing the build dependencies, like:<br />
BuildRequires: cmake libkde4-devel<br />
In this case, cmake and libkde4-devel will be installed before your package is built.<br />
<br />
===== Install extra packages to build root =====<br />
For debugging purposes, you might need to install extra packages to your local build root to debug and fix build related problems. This can be done through the '''~/.oscrc''' file and variable '''extra-pkgs'''. For example:<br />
<br />
extra-pkgs = vim gdb strace valgrind<br />
<br />
===== install privileges =====<br />
If you get an error message like this:<br />
error: Bad exit status from /var/tmp/rpm-tmp.qrRAn2 (%install)<br />
this means that your %install step has failed (and all others before went well). This can be because of missing write privileges if you try to install to the wrong place. In this case add the following make install command to your spec file:<br />
make install DESTDIR=%buildroot<br />
<br />
===== submit your work back to OBS =====<br />
Once you have your <package> directory the way you want it, use the below commands to submit your work back to OBS.<br />
<br />
add a new file to the package<br />
osc add <br />
<br />
remove a file from the package<br />
osc rm <br />
<br />
update the change log (ie. *.changes)<br />
osc vc <br />
<br />
submit your updated files back to OBS<br />
osc commit <br />
<br />
==== Patches ====<br />
If you plan to patch a file copy it before editing to .orig, retry the desired step in the build process until it succeeds and then create a patch for it. <br />
To make the build more verbose you may want to insert a "set -x" in your specfile making bash recite all executed commands (set +x disables reciting afterwards).<br />
diff -Pdpru /var/tmp/build-root/home/abuild/rpmbuild/BUILD/your-package-dir/Makefile.orig \<br />
/var/tmp/build-root/home/abuild/rpmbuild/BUILD/your-package-dir/Makefile \<br />
>/osc/home:user/your-package-dir/my.patch<br />
<br />
Now add the patch to the .spec-file by listing "Patch67: my.patch" in the header and then let it be applied at the appropriate position (usually %setup) in the build process by "%patch67 -p7" (-p7 strips seven directory levels if you have not manually edited the file directories in the header of the patch file.).<br />
You may find it easier to use a special program for automatic patch generation like [http://nordisch.org/2009/3/20/quilt-a-really-quick-howto Quilt].<br />
<br />
=== Step Five: Check the logfiles ===<br />
<br />
The buildservice produces one big logfile for each build of a package.<br />
<br />
* '''Web client''': Just click on the status of the ''Build result'' tab in the package view.<br />
<br />
* '''Command line''': You have a few choices depending on your needs (<code>packagedir</code> is optional if you are in the package directory):<br />
<br />
osc prjresults [packagedir]<br />
<br />
Shows the aggregated build results of an entire project. Or you can do:<br />
<br />
osc results [packagedir]<br />
<br />
Shows the build results of a single package.<br />
<br />
osc buildlog <platform> <arch><br />
<br />
Shows the log file from a package (you need to be inside a package directory).<br />
<br />
===Create Patterns===<br />
<br />
Patterns are files which contain a list of packages together with a description of what they are useful for. Additionally the Build Service creates .ymp files for each generated repository pattern. These .ymp files can be used for a [[openSUSE:One_Click_Install_specification|One Click Install]] by the user. <br />
<br />
In short, patterns are useful for installing a set of software for a typical need without creating dependencies between packages.<br />
<br />
Submitting patterns is possible using the api directly, or using osc:<br />
<br />
* to open a pattern in $EDITOR (creating it if it doesn't exist yet)<br />
osc meta pattern -e <project> <pattern><br />
* to list existing patterns<br />
osc meta pattern <project><br />
* get an existing pattern<br />
osc meta pattern <project> <pattern><br />
* You can also submit an existing file as below:<br />
osc meta pattern --file <local_file> <project> <pattern><br />
<br />
To test: clicking on the .ymp in konqueror should launch the installer, if you do not have konqueror installed, you can try launching from shell as normal user:<br />
/sbin/yast2 MetaPackageHandler http://download.opensuse.org/repositories/<project>/<SUSE_Factory or openSUSE_10.2>/<pattern>.ymp<br />
<br />
The following file is an example pattern file from the KDE:KDE4 project. You can see the generated .ymp file from it [http://download.opensuse.org/repositories/KDE:/KDE4:/Factory:/Desktop/openSUSE_Factory/KDE4-GAMES.ymp here].<br />
<pre><br />
<pattern<br />
xmlns="http://novell.com/package/metadata/suse/pattern"<br />
xmlns:rpm="http://linux.duke.edu/metadata/rpm"<br />
><br />
<name>KDE 4 Games</name><br />
<summary>KDE 4 Games</summary><br />
<description>A number of games for KDE 4.</description><br />
<uservisible/><br />
<category lang="en">Desktop Functions</category><br />
<rpm:recommends><br />
<rpm:entry name="kde4-kpat"/><br />
<rpm:entry name="kde4-kmahjongg"/><br />
<rpm:entry name="kde4-kmines"/><br />
<rpm:entry name="kde4-kreversi"/><br />
<rpm:entry name="kde4-ksudoku"/><br />
</rpm:recommends><br />
<rpm:suggests><br />
<rpm:entry name="kde4-katomic"/><br />
<rpm:entry name="kde4-kbattleship"/><br />
<rpm:entry name="kde4-ksquares"/><br />
<rpm:entry name="kde4-bovo"/><br />
<rpm:entry name="kde4-kiriki"/><br />
<rpm:entry name="kde4-kwin4"/><br />
<rpm:entry name="kde4-kolf"/><br />
<rpm:entry name="kde4-klines"/><br />
<rpm:entry name="kde4-ksame"/><br />
<rpm:entry name="kde4-lskat"/><br />
<rpm:entry name="kde4-kgoldrunner"/><br />
<rpm:entry name="kde4-kblackbox"/><br />
<rpm:entry name="kde4-kbounce"/><br />
<rpm:entry name="kde4-ktuberling"/><br />
<rpm:entry name="kde4-knetwalk"/><br />
<rpm:entry name="kde4-kjumpingcube"/><br />
<rpm:entry name="kde4-kspaceduel"/><br />
<rpm:entry name="kde4-konquest"/><br />
<rpm:entry name="kde4-kshisen"/><br />
</rpm:suggests><br />
</pattern><br />
</pre><br />
<br />
Some Tag descriptions:<br />
{| border="1" cellpadding="5" cellspacing="0"<br />
! Tag !! Description<br />
|-<br />
| <pre><rpm:requires><br />
<rpm:entry name="example" /><br />
</rpm:requires></pre> || '''Requires''' RPM ''example'': this package must be installed - otherwise the pattern is not fulfilled.<br />
|-<br />
| <pre><rpm:recommends><br />
<rpm:entry name="example" /><br />
</rpm:recommends></pre> || '''Recommends''' RPM ''example'': if available and all dependencies of this package are fulfilled, the package would be installed. If the package is not available, there are not error messages. If the package dependencies are not met, the package would be visible but not installed. <br />
|-<br />
| <pre><rpm:suggests><br />
<rpm:entry name="example" /><br />
</rpm:suggests></pre> || '''Suggests''' RPM ''example'': would be shown in the pattern but not installed per default<br />
|}<br />
<br />
== A start to end example of a simple change ==<br />
<br />
{{Info|'''Note:''' There are at least two other wiki pages that document the branch/fix/submit patch workflow:<br />
* [[openSUSE:Fixing_bugs]]<br />
* [[openSUSE:Package maintenance]]<br />
<br />
The goal here is to have a specific example that can be used as a tutorial.<br />
}}<br />
<br />
<br />
<br />
{{Warning|DRAFT BELOW, not yet finished or tested}}<br />
<br />
A common activity is to branch an existing package in an existing project, make a change and submit that change back to the original package.<br />
<br />
The basic steps are:<br />
<br />
# Branch the original package: "osc branch &lt;original_project&gt; &lt;original_package&gt;" This creates a new branch project that is specific for you named home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt; and therein it creates a new package with the same name as original package that is basically a copy of the original package.<br />
# Checkout the branched package: "osc checkout home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt;/&lt;original_package_name&gt;" This downloads the source files of the branched package from the server into a local sub-directory named home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt;/&lt;original_package_name&gt;<br />
# Go to the local sub-directory: "cd home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt;/&lt;original_package_name&gt;" and set the usual default umask "umask 0022"<br />
# Work on your local copy of the package until it works for you:<br />
## Change the local source files (e.g. edit the specfile or create a patch)<br />
## Perform a local build <br />
## Do a local package installation<br />
## Test the local installed package<br />
# Update the changes file: "osc vc" This opens an editor (usually 'vi') and creates an appropriate header for a RPM changes entry. If there was a bug report it must be referenced as bnc#123456<br />
# If you added new files (e.g. new patches) or removed files (e.g. obsolete patches), update the version control status of the local source files: "osc addremove" and verify with "osc status" that there are no files with problematic version control status like '?' or '!'<br />
# Commit the local source files into the branched package: "osc commit" This uploads the local source files into the branched package on the server and that triggers an automated re-build of the branched package.<br />
# Review the build results of the branched package for all build repositories that are enabled for the original package: "osc results --verbose home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt; &lt;original_package_name&gt;" To list the build repositories that are enabled for the original package get its build results: "osc results &lt;original_project&gt; &lt;original_package&gt;"<br />
# If the re-build of the branched package "succeeded" for all build repositories that are enabled for the original package, create a request to submit the branched package back to the original package: "osc submitrequest --message='&lt;a short message that describes what you changed plus bnc#123456 if there exists a matching bug report&gt;' home:&lt;your_user_name&gt;:branches:&lt;original_project_name&gt; &lt;original_package_name&gt; &lt;original_project&gt; &lt;original_package&gt;" and remenber the request ID number.<br />
# From time to time check what happened with your request: "osc request show &lt;request_ID_number&gt;" If you need to get in direct contact with the maintainers of the original package: "osc maintainer &lt;original_project&gt; &lt;original_package&gt;" shows their user names and "osc whois &lt;user_name&gt;" shows fullname and email of a buildservice user.<br />
<br />
It's a few steps, but once you get a hang on it, it becomes second nature.<br />
<br />
This assumes you already have an account on OBS. If not, go ahead and set that up at http://build.opensuse.org/ and use the login link on the upper right to login. OBS uses the same authentication system as the rest of the openSUSE infrastructure like bugzilla, so you likely all ready have a account, you just need to login for the first time and the OBS account home project will be automatically created.<br />
<br />
Here's a real example:<br />
<br />
One time setup from the command line<br />
sudo zypper in osc<br />
mkdir ~/obs<br />
<br />
Then you need to branch a local copy of a package.<br />
cd ~/obs<br />
umask 0022<br />
osc branch security sleuthkit<br />
osc co home:<your_user_name>:branches:security/sleuthkit<br />
cd ~/obs/home:<your_user_name>:branches:security/sleuthkit<br />
<br />
Now that you an existing package already, it's as easy as:<br />
# this untars the tarball and does some magic<br />
quilt setup sleuthkit.spec<br />
# chdir to sources<br />
cd sleuthkit-3.2.3<br />
# apply all patches<br />
quilt push -a<br />
# add new patch<br />
quilt new testing.patch<br />
# add a file to the patch<br />
quilt add some-file<br />
vi <some-file><br />
# or alternatively:<br />
quilt edit <some-file><br />
# and finally<br />
quilt refresh -p1<br />
# copy the patch up to the project dir<br />
cp patches/testing.patch .. <br />
# and now handle the spec file<br />
cd ..<br />
vi sleuthkit.spec<br />
# Add patch to it by creating a Patch0 entry in the header area and a %patch0 -p1 line to the %prep section<br />
<br />
# tell OBS that the package now includes a new file<br />
osc add testing.patch<br />
# update the changes file<br />
osc vc -m "Fix some typos."<br />
# and build, install and test your work<br />
osc build<br />
# perform a local install. At the end of the osc build output the full path of the RPM file should be shown<br />
zypper in -f <full_path_to_rpm><br />
# repeat until happy. Go back to quilt edit if not happy.<br />
# send your edits back to OBS<br />
osc commit<br />
# wait a period of time for new packages to build on OBS<br />
# check the build status via the WebUI for your branched package<br />
# Once published, install the RPM from OBS and test again<br />
# submit your changes back to the original package. If there is a bugzilla entry, be sure to reference it<br />
<br />
== See also ==<br />
<br />
* [[openSUSE:Build_Service_Tips_and_Tricks|General Tips and Tricks for the buildservice]]<br />
* [[openSUSE:Build_Service_Collaboration|How to contribute to a package maintained by someone else]]<br />
* [[openSUSE:Build_Service_cross_distribution_howto|Cross distribution package how to]]<br />
* [[openSUSE:OSC_plugins|Writing osc plugins]]<br />
* [[openSUSE:Build_Service_Debian_builds|Sharing Debian packages]]<br />
<br />
[[Category:Build Service|Tutorial]]<br />
[[Category:Packaging]]<br />
[[Category:Packaging documentation]]<br />
<br />
[[de:openSUSE:Build Service Anleitung]]<br />
[[el:openSUSE:Build Service Tutorial]]<br />
[[es:Build Service/Guía_básica]]<br />
[[fr:Build Service/Tutoriel]]<br />
[[it:Build Service/Tutorial]]<br />
[[ru:openSUSE:Руководство_по_использованию_службы_сборки]]<br />
[[zh:SDB:编译服务教程]]</div>Thomas-schraitle