From 83d07bea15e022e771f3ec56ac24a709f3e714da Mon Sep 17 00:00:00 2001 From: Igor Gnatenko Date: Sep 22 2018 06:50:13 +0000 Subject: trivial: remove outdated pages Signed-off-by: Igor Gnatenko --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index e215d0e..e4e3f04 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -17,22 +17,18 @@ * xref:Drupal7.adoc[Drupal7] * xref:EclipsePlugins.adoc[Eclipse plugins] * xref:Emacs.adoc[Emacs] -* xref:Emacs_Old.adoc[Emacs_Old] * xref:EnvironmentModules.adoc[EnvironmentModules] * https://fedoraproject.org/wiki/EPEL:Packaging[EPEL] * xref:FontsPolicy.adoc[Fonts] -* xref:FontsSpecTemplate.adoc[FontsSpecTemplate] * xref:Fortran.adoc[Fortran] * xref:FullExceptionList.adoc[FullExceptionList] * xref:GAP.adoc[GAP] * xref:GCJGuidelines.adoc[GCJGuidelines] * xref:Globus.adoc[Globus Toolkit] -* xref:GuidelinesTodo.adoc[GuidelinesTodo] * xref:Haskell.adoc[Haskell] * xref:Initial_Service_Setup.adoc[Initial_Service_Setup] * xref:Java.adoc[Java] * xref:JavaScript.adoc[JavaScript] -* xref:JPackagePolicy.adoc[JPackagePolicy] * xref:KernelModules.adoc[KernelModules] * xref:Langpacks.adoc[Language packs] * xref:LibreOfficeExtensions.adoc[LibreOffice Extensions] @@ -40,15 +36,12 @@ * xref:Lisp.adoc[Lisp] * xref:Meson.adoc[Meson] * xref:MinGW.adoc[MinGW] -* xref:MinGW_Old.adoc[MinGW_Old] * xref:Mono.adoc[Mono] * xref:MPI.adoc[MPI] * xref:Naming.adoc[Naming] * xref:Node.js.adoc[Node.js] * xref:OCaml.adoc[OCaml] * xref:Octave.adoc[Octave] -* xref:Old_Ruby.adoc[Old_Ruby] -* xref:OpenOffice.orgExtensions.adoc[OpenOffice.orgExtensions] * xref:PatchUpstreamStatus.adoc[PatchUpstreamStatus] * xref:Perl.adoc[Perl] * xref:Per-Product_Configuration.adoc[Per-Product_Configuration] @@ -58,7 +51,6 @@ * xref:Python.adoc[Python] * xref:Python_Appendix.adoc[Python_Appendix] * xref:Python_Eggs.adoc[Python_Eggs] -* xref:Python_Old.adoc[Python_Old] * xref:R.adoc[R] * xref:ReviewGuidelines.adoc[ReviewGuidelines] * xref:RPMMacros.adoc[RPMMacros] @@ -72,7 +64,6 @@ * xref:Systemd.adoc[Systemd] * xref:Tcl.adoc[Tcl/Tk extensions] * xref:Tmpfiles.d.adoc[Tmpfiles.d] -* xref:Treatment_Of_Bundled_Libraries.adoc[Treatment_Of_Bundled_Libraries] * xref:UnownedDirectories.adoc[UnownedDirectories] * xref:UsersAndGroups.adoc[UsersAndGroups] * xref:Versioning.adoc[Versioning] diff --git a/guidelines/modules/ROOT/pages/Emacs_Old.adoc b/guidelines/modules/ROOT/pages/Emacs_Old.adoc deleted file mode 100644 index c5f1291..0000000 --- a/guidelines/modules/ROOT/pages/Emacs_Old.adoc +++ /dev/null @@ -1,431 +0,0 @@ -= Packaging of add-ons for GNU Emacs and XEmacs - -== Purpose - -The purpose of this document is to promote good practice in packaging add-ons for GNU Emacs and XEmacs, and to encourage the submission of more Emacs add-on packages to the package collection by providing easy to use spec file templates. - -This document refers to packaging for Fedora 8 until Fedora 12, inclusive. Packaging:Emacs should be used for any modern Fedora version. - -== Packaging add-ons for (X)Emacs - -=== Executive summary of Guidelines - -The following list contains the key points of the guidelines. More detail on each of these may be found in the subsequent sections. - -\1. Where an add-on package foo is for both GNU Emacs and XEmacs, the main package should be called emacs-common-foo. This main package should contain files common to both GNU Emacs and XEmacs such as documentation etc. Files specific to each of GNU Emacs and XEmacs should be placed in sub-packages as detailed in points 4 and 5 below. - -\2. Where a package is specific only to one flavour of (X)Emacs, the main package should be called emacs-foo or xemacs-foo. In both cases, elisp source should be packaged in separate sub-packages as detailed below. - -\3. Where a package which is not primarily an (X)Emacs add-on package but contains auxillary (X)Emacs components, these should be placed in sub-packages following the guidelines below. - -\4. Files specific to GNU Emacs should be placed in two sub-packages: - -* emacs-foo: this sub-package should contain compiled elisp and other files needed to use the add-on package with GNU Emacs only. It should not contain any source elisp files which are not required to run the package. -* emacs-foo-el: this sub-package contains the source elisp files used to build the add-on package for GNU Emacs. Files in this package should not be required to use the add-on package. - -\5. Files specific to XEmacs should be placed in two sub-packages: - -* xemacs-foo: this sub-package should contain compiled elisp and other files needed to use the add-on package with XEmacs only. It should not contain any source elisp files which are not required to run the package. -* xemacs-foo-el: this sub-package contains the source elisp files used to build the add-on package for XEmacs. Files in this package should not be required to use the add-on package. - -\6. File locations for GNU Emacs add-on packages: - -* All elisp and related files for the add-on package should be installed in the directory /usr/share/emacs/site-lisp/foo. -* /usr/share/emacs/site-lisp/foo should be owned by the package emacs-foo. -* If the package requires a startup file this should be called foo-init.el and be placed in /usr/share/emacs/site-lisp/site-start.d/. - -\7. Files locations for XEmacs add-on packages: - -* All elisp and related files for the add-on package should be installed in the directory /usr/share/xemacs/site-packages/lisp. -* /usr/share/xemacs/site-packages/lisp should be owned by xemacs-foo. -* If the package requires a startup file this should be called foo-init.el and be placed in /usr/share/xemacs/site-packages/lisp/site-start.d/. - -\8. emacs-foo-el must have Requires: emacs-foo = %\{version}-%\{release}. - -\9. xemacs-foo-el must have Requires: xemacs-foo = %\{version}-%\{release}. - -\10. Where it is relevant, emacs-foo and xemacs-foo must have Requires: emacs-common-foo = %\{version}-%\{release}. - -\11. emacs-foo must have Requires: emacs(bin) >= X, where X is the version of GNU Emacs used to build the package. - -\12. xemacs-foo must have Requires: xemacs(bin) >= Y, where Y is the version of GNU Emacs used to build the package. - -\13. If an add-on package requires only byte compilation of elisp then BuildArch: noarch should be used. - -=== Principles - -The existence of the GNU Emacs and XEmacs variants makes packaging Emacs add-on packaging slightly complex. GNU Emacs and XEmacs have different philosophies regarding add-on packages. - -XEmacs has its own packaging system and maintains and distributes its own library of third party add-on modules. These are distributed in Fedora in the xemacs-packages-base and xemacs-packages-extra packages. GNU Emacs doesn't have any equivalent system, and third party add-ons are left for the user or distribution to install. - -The packaging naming guidelines state that: - -_Packages of emacs add-on components (code that adds additional functionality to emacs compatible editors) have their own naming scheme. It is often the case that a component will add functionality to several different compatible editors, such as GNU Emacs and XEmacs (and possibly development versions of these editors). The package name should take into account the upstream name of the emacs component._ - -_Where a component adds functionality to more than one emacs compatible editor, the package name should be of the form emacs-common-$NAME. In this case, the main package should contain only files common to all emacs compatible editors, and the code specific to each should be placed in a subpackage reflecting the specific editor $EDITOR-$NAME eg. xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An example of this scheme can be found in the package emacs-common-muse._ - -_Where a component is designed to add functionality to only a single emacs compatible editor, the main package name should reflect this by being called $EDITOR-$NAME. An example of this situation can be found in the package emacs-auctex, which is built only for GNU Emacs._ - -Wherever possible, we encourage making an add-on package available for both GNU Emacs and XEmacs. One common case where that is not desireable is when an add-on package is already available for XEmacs in either xemacs-packages-base or xemacs-packages-extra. For example VM (a mail reader for Emacs) is provided for XEmacs in the xemacs-packages-extra package, but is not included in the emacs or emacs-common packages. Therefore it is sensible to create a package called emacs-vm which is the VM package for GNU Emacs only. Another such example is AUCTeX. - -=== Location of installed files - -==== GNU Emacs - -For GNU Emacs, files for add-on package foo should be placed in /usr/share/emacs/site-lisp/foo. - -Usually an add-on package will require a startup file, and this should be called foo-init.el and be placed in /usr/share/emacs/site-lisp/site-start.d/. - -The following code snippet show how to use macros to determine these at package build time: - -.... -%if %($(pkg-config emacs) ; echo $?) -%global emacs_lispdir %{_datadir}/emacs/site-lisp -%global emacs_startdir %{_datadir}/emacs/site-lisp/site-start.d -%else -%global emacs_lispdir %(pkg-config emacs --variable sitepkglispdir) -%global emacs_startdir %(pkg-config emacs --variable sitestartdir) -%endif -... -BuildRequires: emacs-el -... -.... - -==== XEmacs - -For XEmacs, files for add-on package foo should be placed in /usr/share/xemacs/site-packages/lisp/foo. - -Usually an add-on package will require a startup file, and this should be called foo-init.el and be placed in /usr/share/xemacs/site-packages/lisp/site-start.d/. - -The following code snippet show how to use macros to determine these at package build time: - -.... -%if %($(pkg-config xemacs) ; echo $?) -%global xemacs_lispdir %{_datadir}/xemacs/site-packages/lisp -%global xemacs_startdir %{_datadir}/xemacs/site-packages/lisp/site-start.d -%else -%global xemacs_lispdir %(pkg-config xemacs --variable sitepkglispdir) -%global xemacs_startdir %(pkg-config xemacs --variable sitestartdir) -%endif -... -BuildRequires: xemacs-devel -... -.... - -=== Packaging of source elisp files - -Typically, an Emacs add-on package will be compiled from source elisp files. The resulting compiled elisp files will then be included in the relevant emacs-foo and xemacs-foo packages. However, these packages SHOULD NOT contain uncompiled elisp source files which are not required for the program to run. Rather, following the precedent set by GNU Emacs packaging, the elisp source files should be placed in their own sub-packages, named emacs-foo-el and xemacs-foo-el. - -The (x)emacs-foo-el packages are similar in many ways to the -devel subpackages for system libraries. It is often the case that byte compiling the elisp source for one add-on will require the presence of the elisp source for another add-on package at build time for example. - -=== BuildArch for (X)Emacs add-on packages - -You should set BuildArch: noarch for add-on packages which only compile elisp files during building. - -If the package building process also compiles programs in other languages, you may need to not set BuildArch. - -=== Requires for GNU Emacs and XEmacs - -Add-on packages should have appropriate Requires entries for the flavour of (X)Emacs they are targeted at. -Both GNU Emacs and XEmacs are available in two different packages - some details of these packages follow. -1. GNU Emacs is packaged as two variants. The emacs package is built with Xorg support to allow the user to run Emacs in a windowed environment. The emacs-nox package is built without Xorg support and hence allows Emacs to be run only in a console. Note: - -* Both the emacs and emacs-nox packages have Requires: emacs-common. -* Both emacs and emacs-nox have a virtual Provides: emacs(bin) - -\2. XEmacs is packaged as two variants. The xemacs package is built with Xorg support to allow the user to run Emacs in a windowed environment. The xemacs-nox package is built without Xorg support and hence allows Emacs to be run only in a console. Note: - -* Both the xemacs and xemacs-nox packages have Requires: xemacs-common. -* Both xemacs and xemacs-nox have a virtual Provides: xemacs(bin) - -Assuming your add-on package will work in both a windowed and a console (X)Emacs session, it is wrong to have Requires: emacs or Requires: xemacs as that would pull in a dependency on Xorg even if the console variants of (X)Emacs was installed. Rather you should use Requires: xemacs(bin) for XEmacs add-on packages, and Requires: emacs(bin) for GNU Emacs add-on packages. - -If the package ONLY works with Xorg support built into (X)Emacs, then the packages should have Requires: emacs or Requires: xemacs. This is very uncommon. - -==== Why we need versioned Requires - -Many elisp packages aim for backwards source level compatibility by checking whether some features exist in the (X)Emacs in use when the package is being run or byte-compiled. If yes, they use what's available. If no, they provide their own versions of missing functions, macros etc. This propagates into *.elc during byte compilation, and quite a few functions do get added between upstream (X)Emacs releases. - -So let's say I byte-compile a package into *.elc with XEmacs 21.5.28. Elisp package quux checks if the foo-bar function is available in the XEmacs being used to byte-compile it. Yes, it is, so the internal backwards compat version of foo-bar included in quux does not end up in the *.elc. Now, let's assume foo-bar was added in XEmacs 21.5.28 and didn't exist in 21.5.27 and we're trying to run the *.elc with 21.5.27 -> boom, foo-bar is not available. Note: this wouldn't happen if only *.el were shipped - *.elc are the potential and likely problem. Requiring >= version of the XEmacs used to byte-compile the *.elc is not the only solution (nor enough for all corner cases), but is the best one we currently have available. - -The main package and subpackages will need to have appropriately version Requires to ensure that a recent enough version of (X)Emacs is installed. (X)Emacs byte compiled lisp is usually forward compatible with later (X)Emacs versions, but is frequently not compatible with earlier versions of (X)Emacs. - -==== Determining the Required (X)Emacs version at package build time - -It is recommended to derive greater-than-or-equal-to valued versioned dependencies from the version of (X)Emacs used to byte-compile the package at package build time. The mechanism for doing so is provided by pkg-config (when available). - -For Emacs add-ons you will need to add BuildRequires: emacs-el and use the macro below - -.... -%if %($(pkg-config emacs) ; echo $?) -%global emacs_version 22.1 -%else -%global emacs_version %(pkg-config emacs --modversion) -%endif -... -Requires: emacs(bin) >= emacs_version -BuildRequires: emacs-el -... -.... - -For Xemacs you will need to add BuildRequires: xemacs-devel and use the macro below - -.... -%if %($(pkg-config xemacs) ; echo $?) -%global xemacs_version 21.5 -%else -%global xemacs_version %(pkg-config xemacs --modversion) -%endif -... -Requires: xemacs(bin) >= xemacs_version -BuildRequires: xemacs-devel -... -.... - -=== Other packages containing Emacsen add-ons - -It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for (X)Emacs. For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs. - -[cols="",] -|======================================================================================================================================================================================= -a| -Where a package contains add-on components for (X)Emacs, in general these components should be packaged in a sub-package consistent with the guidelines here for main (X)Emacs packages. - -|======================================================================================================================================================================================= - -In other words, if a package foo contains components for (X)Emacs, the subpackages containing the files to run the (X)Emmacs components should be called emacs-foo and emacs-foo-el, which own the directories /usr/share/emacs/site-lisp/foo and /usr/share/xemacs/site-packages/lisp/foo respectively. Elisp source files not needed for running the add-ons should be packaged in separate sub-packages emacs-foo-el and xemacs-foo-el, which should Require emacs-foo and xemacs-foo respectively. - -== Templates for Emacsen add-on package spec files - -=== Template for a package for both GNU Emacs and XEmacs - -This spec-file template for the add-on package "foo" creates 5 packages: - -\1. emacs-common-foo is the main package. This should contain files which are common to both the emacs-foo and xemacs-foo subpackages below. Examples of what this file would contain are the package documentation, the COPYING file, the CHANGELOG file etc. - -\2. emacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package owns the director /usr/share/emacs/site-lisp/foo. - -\3. emacs-foo-el. This sub-package contains the elisp source files corresponding to the compiled elisp files in package emacs-foo. This sub-package Requires: emacs-foo, as the directory in which the elisp source files are installed to is owned by emacs-foo. - -\4. xemacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package owns the director /usr/share/emacs/site-packages/lisp/foo. - -\5. xemacs-foo-el. This sub-package contains the elisp source files corresponding to the compiled elisp files in package xemacs-foo. This sub-package Requires: xemacs-foo, as the directory in which the elisp source files are installed to is owned by xemacs-foo. - -For the Requires mentioned in 1-5 above, the exact %\{version}-%\{release} should be matched. - -For convenience, there are two macros at the top of the file which you should customise to your package. You do not have to use the macros placed at the top of the file, but they help readability and make writing a spec file for a new package much quicker. - -.... -%global pkg foo -%global pkgname Foo - -%if %($(pkg-config emacs) ; echo $?) -%global emacs_version 22.1 -%global emacs_lispdir %{_datadir}/emacs/site-lisp -%global emacs_startdir %{_datadir}/emacs/site-lisp/site-start.d -%else -%global emacs_version %(pkg-config emacs --modversion) -%global emacs_lispdir %(pkg-config emacs --variable sitepkglispdir) -%global emacs_startdir %(pkg-config emacs --variable sitestartdir) -%endif - -%if %($(pkg-config xemacs) ; echo $?) -%global xemacs_version 21.5 -%global xemacs_lispdir %{_datadir}/xemacs/site-packages/lisp -%global xemacs_startdir %{_datadir}/xemacs/site-packages/lisp/site-start.d -%else -%global xemacs_version %(pkg-config xemacs --modversion) -%global xemacs_lispdir %(pkg-config xemacs --variable sitepkglispdir) -%global xemacs_startdir %(pkg-config xemacs --variable sitestartdir) -%endif - -Name: emacs-common-%{pkg} -Version: -Release: 1%{?dist} -Summary: - -Group: -License: -URL: -Source0: -BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) - -BuildArch: noarch -BuildRequires: emacs emacs-el -BuildRequires: xemacs xemacs-devel -Requires: - -%description -%{pkgname} is an add-on package for GNU Emacs and XEmacs. It does wonderful things... - -This package contains the files common to both the GNU Emacs and XEmacs %{pkgname} -packages. - -%package -n emacs-%{pkg} -Summary: Compiled elisp files to run %{pkgname} under GNU Emacs -Group: -Requires: emacs(bin) >= %{emacs_version} -Requires: emacs-common-%{pkg} = %{version}-%{release} - -%description -n emacs-%{pkg} -This package contains the byte compiled elisp packages to run %{pkgname} with GNU -Emacs. - - -%package -n emacs-%{pkg}-el -Summary: Elisp source files for %{pkgname} under GNU Emacs -Group: -Requires: emacs-%{pkg} = %{version}-%{release} - -%description -n emacs-%{pkg}-el -This package contains the elisp source files for %{pkgname} under GNU Emacs. You -do not need to install this package to run %{pkgname}. Install the emacs-%{pkg} -package to use %{pkgname} with GNU Emacs. - - -%package -n xemacs-%{pkg} -Summary: Compiled elisp files to run %{pkgname} under XEmacs -Group: -Requires: xemacs(bin) >= %{xemacs_version} -Requires: emacs-common-%{pkg} = %{version}-%{release} - -%description -n xemacs-%{pkg} -This package contains the byte compiled elisp packages to use %{pkgname} with -XEmacs. - - -%package -n xemacs-%{pkg}-el -Summary: Elisp source files for %{pkgname} under XEmacs -Group: -Requires: xemacs-%{pkg} = %{version}-%{release} - -%description -n xemacs-%{pkg}-el -This package contains the elisp source files for %{pkgname} under XEmacs. You do -not need to install this package to run %{pkgname}. Install the xemacs-%{pkg} -package to use %{pkgname} with XEmacs. - - -%prep -%setup -q -n %{pkg}-%{version} - -%build - - -%install -rm -rf $RPM_BUILD_ROOT - - -%clean -rm -rf $RPM_BUILD_ROOT - - -%post - - -%preun - - -%files -%doc - - -%files -n emacs-%{pkg} -%{emacs_lispdir}/%{pkg}/*.elc -%{emacs_startdir/*.el -%dir %{emacs_lispdir}/%{pkg} - - -%files -n emacs-%{pkg}-el -%{emacs_lispdir}/%{pkg}/*.el - - -%files -n xemacs-%{pkg} -%{xemacs_lispdir}/%{pkg}/*.elc -%{xemacs_startdir}/*.el -%dir %{xemacs_lispdir}/%{pkg} - - -%files -n xemacs-%{pkg}-el -%{xemacs_lispdir}/%{pkg}/*.el - - -%changelog -.... - -=== Template for a add-on package for GNU Emacs only - -This is a template for a package for GNU Emacs only. The main package is called emacs-foo and contains all files needed to run package foo with GNU Emacs. There is a subpackage called emacs-foo-el which installs the elisp source files. emacs-foo owns the directory into which it is installed (/usr/share/emacs/site-lisp/foo), and so emacs-foo-el Requires emacs-foo with the matching version and release tag. - -.... -%global pkg foo -%global pkgname Foo - -%if %($(pkg-config emacs) ; echo $?) -%global emacs_version 22.1 -%global emacs_lispdir %{_datadir}/emacs/site-lisp -%global emacs_startdir %{_datadir}/emacs/site-lisp/site-start.d -%else -%global emacs_version %(pkg-config emacs --modversion) -%global emacs_lispdir %(pkg-config emacs --variable sitepkglispdir) -%global emacs_startdir %(pkg-config emacs --variable sitestartdir) -%endif - -Name: emacs-%{pkg} -Version: -Release: 1%{?dist} -Summary: - -Group: -License: -URL: -Source0: -BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) - -BuildArch: noarch -BuildRequires: emacs emacs-el -Requires: emacs(bin) >= %{emacs_version} - -%description -%{pkgname} is an add-on package for GNU Emacs. It does wonderful things... - -%package -n %{name}-el -Summary: Elisp source files for %{pkgname} under GNU Emacs -Group: -Requires: %{name} = %{version}-%{release} - -%description -n %{name}-el -This package contains the elisp source files for %{pkgname} under GNU Emacs. You -do not need to install this package to run %{pkgname}. Install the %{name} -package to use %{pkgname} with GNU Emacs. - -%prep -%setup -q -n %{pkg}-%{version} - -%build - - -%install -rm -rf $RPM_BUILD_ROOT - - -%clean -rm -rf $RPM_BUILD_ROOT - - -%post - - -%preun - - -%files -%doc -%{emacs_lispdir}/%{pkg}/*.elc -%{emacs_startdir}/*.el -%dir %{emacs_lispdir}/%{pkg} - -%files -n %{name}-el -%{emacs_lispdir}/%{pkg}/*.el - -%changelog -.... diff --git a/guidelines/modules/ROOT/pages/FontsSpecTemplate.adoc b/guidelines/modules/ROOT/pages/FontsSpecTemplate.adoc deleted file mode 100644 index 8b13789..0000000 --- a/guidelines/modules/ROOT/pages/FontsSpecTemplate.adoc +++ /dev/null @@ -1 +0,0 @@ - diff --git a/guidelines/modules/ROOT/pages/GuidelinesTodo.adoc b/guidelines/modules/ROOT/pages/GuidelinesTodo.adoc deleted file mode 100644 index 8b13789..0000000 --- a/guidelines/modules/ROOT/pages/GuidelinesTodo.adoc +++ /dev/null @@ -1 +0,0 @@ - diff --git a/guidelines/modules/ROOT/pages/JPackagePolicy.adoc b/guidelines/modules/ROOT/pages/JPackagePolicy.adoc deleted file mode 100644 index 8b13789..0000000 --- a/guidelines/modules/ROOT/pages/JPackagePolicy.adoc +++ /dev/null @@ -1 +0,0 @@ - diff --git a/guidelines/modules/ROOT/pages/MinGW_Old.adoc b/guidelines/modules/ROOT/pages/MinGW_Old.adoc deleted file mode 100644 index b0f87b1..0000000 --- a/guidelines/modules/ROOT/pages/MinGW_Old.adoc +++ /dev/null @@ -1 +0,0 @@ -This page has been removed as the old MinGW guidelines are no longer relevant. diff --git a/guidelines/modules/ROOT/pages/Old_Ruby.adoc b/guidelines/modules/ROOT/pages/Old_Ruby.adoc deleted file mode 100644 index befb934..0000000 --- a/guidelines/modules/ROOT/pages/Old_Ruby.adoc +++ /dev/null @@ -1,131 +0,0 @@ -Each Ruby package *must* indicate the Ruby ABI version it depends on with a line like - -.... -Requires: ruby(abi) = 1.8 -.... - -Ruby packages *must* require ruby at build time with a `+BuildRequires: ruby+`, and *may* indicate the minimal ruby version they need for building. - -== Naming Guidelines - -These naming guidelines only apply to ruby packages whose main purpose is providing a Ruby library; packages that mainly provide user-level tools that happen to be written in Ruby do not need to follow these naming guidelines, and should follow the general link:Packaging/NamingGuidelines[ NamingGuidelines] instead. - -The name of a ruby extension/library package *must* be of the form `+ruby-UPSTREAM+`. If the upstream name `+UPSTREAM+` contains `+ruby+`, that *should* be dropped from the name. For example, the SQLite database driver for ruby is called `+sqlite3-ruby+`. The corresponding Fedora package should be called `+ruby-sqlite3+`, and not `+ruby-sqlite3-ruby+`. - -A ruby extension/library package *must* indicate what it provides with a `+Provides: ruby(LIBRARY) = VERSION+` declaration in the spec file. The string `+LIBRARY+` *should* be the same as what is used in the `+require+` statement in a Ruby script that uses the library. The `+VERSION+` *should* be the upstream version of the library, as long as upstream follows a sane versioning scheme. For example, a Ruby script using the SQLite database driver will include it with `+require 'sqlite3'+`. The specfile for the corresponding Fedora package must contain a line `+Provides: ruby(sqlite3) = 1.1.0+`, assuming the package contains version 1.1.0 of the library. - -== Build Architecture and File Placement - -The following only affects the files that the package installs into `+%{_libdir}/ruby+`, i.e., Ruby library files. All other files in a Ruby package must adhere to the general Fedora Extras packaging conventions. - -=== Pure Ruby packages - -Pure Ruby packages *must* be built as noarch packages. - -The Ruby library files in a pure Ruby package *must* be placed into `+Config::CONFIG["sitelibdir"]+`. The specfile *must* get that path using - -.... -%{!?ruby_sitelib: %global ruby_sitelib %(ruby -rrbconfig -e 'puts Config::CONFIG["sitelibdir"] ')} -.... - -=== Ruby packages with binary content/shared libraries - -For packages with binary content, e.g., database drivers or any other Ruby bindings to C libraries, the package *must* be architecture specific. - -The binary files in a Ruby package with binary content *must* be placed into `+Config::CONFIG["sitearchdir"]+`. The Ruby files in such a package *should* be placed into that directory, too. The specfile *must* get that path using - -.... -%{!?ruby_sitearch: %global ruby_sitearch %(ruby -rrbconfig -e 'puts Config::CONFIG["sitearchdir"] ')} -.... - -For packages which create C shared libraries using `+extconf.rb+` - -.... -export CONFIGURE_ARGS="--with-cflags='%{optflags}'" -.... - -*should* be used to pass `+CFLAGS+` to `+Makefile+` correctly. -This also applies to Ruby Gems. - -== Ruby Gems - -http://www.rubygems.org/[Ruby Gems] are Ruby's own packaging format. Gems contain a lot of the same metadata that RPM's need, making fairly smooth interoperation between RPM and Gems possible. This guideline ensures that Gems are packaged as RPM's in a way that ensures (1) that such RPM's fit cleanly with the rest of the distribution and (2) make it possible for the end user to satisfy dependencies of a Gem by installing the appropriate RPM-packaged Gem. - -Both RPM's and Gems use similar terminology --- there's specfiles, package names, dependencies etc. for both. To keep confusion to a minimum, whenever the term from the Gem world is meant, it is explicitly called the 'Gem specification'. An unqualified 'package' in the following always means an RPM. - -* Packages that contain Ruby Gems *must* be called `+rubygem-%{gemname}+` where `+gemname+` is the name from the Gem's specification. -* The `+Source+` of the package *must* be the full URL to the released Gem archive; the version of the package *must* be the Gem's version -* The package *must* have a `+Requires+` and a `+BuildRequires+` on `+rubygems+` -* The package *must* provide `+rubygem(%{gemname})+` where `+gemname+` is the name from the Gem's specification. For every dependency on a Gem named `+gemdep+`, the package must contain a `+Requires+` on `+rubygem(%{gemdep})+` with the same version constraints as the Gem -* The `+%prep+` and `+%build+` sections of the specfile *should* be empty. -* The Gem *must* be installed into `+%{gemdir}+` defined as - -.... -%global gemdir %(ruby -rubygems -e 'puts Gem::dir' 2>/dev/null) -.... - -The install *should* be performed with the command - -.... -gem install --local --install-dir %{buildroot}%{gemdir} --force %{SOURCE0} -.... - -* The package *must* own the following files and directories: - -.... -%{gemdir}/gems/%{gemname}-%{version}/ -%{gemdir}/cache/%{gemname}-%{version}.gem -%{gemdir}/specifications/%{gemname}-%{version}.gemspec -.... - -* Architecture-specific content *must not* be installed into `+%{gemdir}+` -* If the Gem only contains pure Ruby code, it *must* be marked as `+BuildArch: noarch+`. If the Gem contains binary content (e.g., for a database driver), it *must* be marked as architecture specific, and all architecture specific content *must* be moved from the `+%{gemdir}+` to the [#ruby_sitearch `+%{ruby_sitearch}+` directory] during `+%install+` - -=== Ruby Gem with extension libraries written in C - -When a Ruby Gem contains extension libraries written in C, - -* First, `+%prep+` stage *must* contain `+%setup -q -c -T+` to create the directory where C libraries are compiled. -* Then at %build stage the Ruby Gem *must* be installed under the directory created at %prep stage to get C libraries compiled under there. -* When `+gem install+` is used to install Gem file, using `+-V+` option is *recommend* to check if `+CFLAGS+` is correctly honored. -* Finally at `+%install+` stage the whole tree under the directory created at %prep stage *should* be *copied* (not moved) to under `+%{buildroot}%{gemdir}+`. -** When all tree under the directory created at %prep stage is moved to under `+%{buildroot}+`, `+find_debuginfo.sh+` will complain that the corresponding source files are missing. -* Installed C codes (usually under `+%{geminstdir}/etc+`) *may* be removed even if `+gem contents %{gemname}+` reports that installed C codes should be found there. - -==== Note - -The current guideline - -.... -If the Gem contains binary content (e.g., for a database driver), it must be marked -as architecture specific, and all architecture specific content must be moved -from the %{gemdir} to the [#ruby_sitearch %{ruby_sitearch} directory] during %install -.... - -must still apply. - -=== Packaging for Gem and non-Gem use - -If the same Ruby library is to be packaged for use as a Gem and as a straight Ruby library without Gem support, it *must* be packaged as a Gem first. To make it available to code that does not use Ruby Gems, a subpackage called `+ruby-%{gemname}+` *must* be created in the `+rubygem-%{gemname}+` package such that - -* The subpackage *must* require `+rubygem(%gemname) = %version+` -* The subpackage *must* provide `+ruby(LIBRARY) = %version+` where LIBRARY is the same as in the [#ruby_naming general Ruby guideline] above. -* All the toplevel library files of the Gem must be symlinked into `+ruby_sitelib+`. -* The subpackage *must* own these symbolic links. - -As an example, for `+activesupport+`, the `+rubygem-activesupport+` package would have a subpackge `+ruby-activesupport+`: - -.... -%package -n ruby-activesupport -... -Requires: rubygem(activesupport) = %version -Provides: ruby(active_support) = %version # The underscore is intentional, not a typo -... -%files -n ruby-activesupport -%{ruby_sitelib}/active_support -%{ruby_sitelib}/active_support.rb -.... - -=== Tips for Packagers - -Gems carry a lot of metadata; http://rubyforge.org/projects/gem2rpm/[gem2rpm] is a tool to generate an initial specfile and/or source RPM from a Gem. The generated specfile still needs some hand-editing, but conforms to 90% with this guideline. diff --git a/guidelines/modules/ROOT/pages/OpenOffice.orgExtensions.adoc b/guidelines/modules/ROOT/pages/OpenOffice.orgExtensions.adoc deleted file mode 100644 index e80f792..0000000 --- a/guidelines/modules/ROOT/pages/OpenOffice.orgExtensions.adoc +++ /dev/null @@ -1,41 +0,0 @@ -== OpenOffice.org extension rpm guidelines - -1. Extensions deinstalled with unopkg remove *Must* have a %postun of 'unopkg list --shared > /dev/null 2>&1' because the actual removal of files is deferred until the next start, so this ensures that this takes place under the control of your rpm on deinstallation. + -2. Extensions *Should* be both installed unpacked and then registered with 'unopkg --link' where possible to save disk-space. Otherwise during registration of a packed .oxt or .uno.pkg with unopkg the package is automatically unzipped and the contents copied into a persistent cache directory. Using -link and an unpacked .oxt/.uno.pkg dir allows this additional copy to be omitted and importantly allows the rest of the standard rpmbuild tooling to determine additional autorequires for a package or find flaws that cannot be seen in the opaque zip case. + -3. Unpacked Extensions *Must* be installed in a dir called http://extensions.openoffice.org/servlets/ReadMsg?list=dev&msgNo=142[NAME.oxt, NAME.uno.pkg or NAME.zip] + -4. An extension should normally just be able to just Require: an appropriate openoffice.org component e.g. openoffice.org-core, without a specific n-v-r as extensions use the stable UNO abi which rarely changes, and then only to add extra apis. So unless you require a specific feature of a openoffice.org release there is no need to require a specific n-v-r and force a rebuild on every n-v-r of openoffice.org. + -5. extensions *Must* be named openoffice.org-FOO. The location where an extension is unpacked *Must* be in an arch or arch-independent location depending on if the extension has been written in an arch or arch-independent language. e.g. StarBasic and Java only extensions are noarch and *Must* be unpacked under /usr/share/openoffice.org/extensions, while e.g. C++ extensions are arch-dependant and *Must* be unpacked under %\{_libdir}/openoffice.org/extensions. + -6. extensions are similar to e.g. xorg video drivers in that there exist proprietary or binary only extensions, but of course normal Fedora rules apply to what extensions can be packaged, i.e. see normal packaging licensing etc. rules. The license *Must* be acceptable, and the package *Must* be built from source. + -7. extensions can be written in any language that has a uno binding, e.g. C++, python, java or StarBasic. Consider the additional packaging guidelines of the language that the extension is written in if such guidelines exists. + -8. Some obsolete versions of openoffice.org < F9 had bugs in unopkg, so the minimum Requires are: 2.3.0-6.12 for F8, and 2.3.0-6.6 for F7 + - - + -.. + -An example is... + - -.... -Requires(pre): openoffice.org-core >= 2.3.0-6.6 -Requires(post): openoffice.org-core >= 2.3.0-6.6 -Requires(preun): openoffice.org-core >= 2.3.0-6.6 -Requires(postun): openoffice.org-core >= 2.3.0-6.6 - -%install -mkdir -p $RPM_BUILD_ROOT%{_datadir}/openoffice.org/extensions/writer2latex.uno.pkg -unzip target/lib/writer2latex.uno.pkg -d $RPM_BUILD_ROOT%{_datadir}/openoffice.org/extensions/writer2latex.uno.pkg - -%pre -if [ $1 -gt 1 ] ; then -unopkg remove --shared org.openoffice.legacy.writer2latex.uno.pkg || : -fi - -%post -unopkg add --shared --force --link %{_datadir}/writer2latex.uno.pkg || : - -%preun -if [ $1 -eq 0 ] ; then -unopkg remove --shared org.openoffice.legacy.writer2latex.uno.pkg || : -fi - -%postun -unopkg list --shared > /dev/null 2>&1 || : -.... diff --git a/guidelines/modules/ROOT/pages/Python_Old.adoc b/guidelines/modules/ROOT/pages/Python_Old.adoc deleted file mode 100644 index 105ceec..0000000 --- a/guidelines/modules/ROOT/pages/Python_Old.adoc +++ /dev/null @@ -1,499 +0,0 @@ -= Python guidelines for EPEL 6 and EPEL 5 - -Fedora 21 and EPEL7 have full support for python3 and additional macros which make packaging python modules much simpler, but EPEL 6 and 5 don't have python3 or the new macros at all. Keeping a single spec across all of these versions is significantly more verbose. This is a copy of the packaging guidelines from before the new macros were added; it may be updated to include additional changes which do not reference the functionality. - -== Python Version Support - -In Fedora we have multiple python runtimes, one for each supported major release. At this point that's one for python2.x and one for python3.x. If a piece of software supports python3, it must be packaged for python3. If it supports python2 as well, it may be packaged for python2. If it supports only python2 then it must not be packaged for python3. - -== Multiple Python Runtimes - -Each runtime corresponds to a binary of the form `+/usr/bin/python$MAJOR.$MINOR+` One of these python runtimes is the "system runtime" which is what is run when invoking `+/usr/bin/python+`. On Fedora 21 this is a link to `+/usr/bin/python2+` (which itself is a link to `+/usr/bin/python2.7+`). - -However, packages in Fedora should not depend on where `+/usr/bin/python+` happens to point but instead should call the proper executable for the needed python major version directly, either `+/usr/bin/python2+` or `+/usr/bin/python3+` as appropriate. - -All python runtimes have a virtual provide for `+python(abi) = $MAJOR-$MINOR+`. For example, the python-3.1 runtime rpm has: - -`+ $ rpm -q --provides python3 |grep -i abi+` + -`+ python(abi) = 3.1+` - -python modules using these runtimes should have a corresponding "Requires" line on the python runtime that they are used with. This is done automatically for files below `+/usr/lib[^/]*/python${PYVER}+` - -== BuildRequires - -To build a package containing python2 files, you need to have - -.... -BuildRequires: python2-devel -.... - -Similarly, when building a package which ships python3 files, you need - -.... -BuildRequires: python3-devel -.... - -A package that has both python2 and python3 files will need to BuildRequire both. - -== Provides - -Python2 packages need to provide a python2 version of their name. So, for example, a python package of the "foo" module needs to include `+Provides: python2-foo+`. - -== Macros - -In RHEL 6 and older, python2 packages that install python modules need to define `+__python2+`, `+python2_sitelib+`, and `+python2_sitearch+` macros. This is not needed in current Fedora or with python3 modules as the macros are defined by `+rpm+` and the `+python3-devel+` package. To define those conditionally you can use this: - -.... -%if 0%{?rhel} && 0%{?rhel} <= 6 -%{!?__python2: %global __python2 /usr/bin/python2} -%{!?python2_sitelib: %global python2_sitelib %(%{__python2} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())")} -%{!?python2_sitearch: %global python2_sitearch %(%{__python2} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib(1))")} -%endif -.... - -Note that the use of `+%{!? [...]}+` does allow this to work without the check for rhel versions but putting the conditional in documents when we can remove the entire stanza from the spec file. - -In Fedora, the following macros are defined for you: - -[cols=",,",options="header",] -|==================================================================================================================================================================================================================== -|Macro |Normal Definition |Notes -|__python |`+%{__python2}+` |Default Python interpreter. Currently links to Python2 interpreter -|__python2 |/usr/bin/python2 |Python 2 interpreter. Also the current default python interpreter -|__python3 |/usr/bin/python3 |Python 3 interpreter -|python_sitelib |`+%{python2_sitelib}+` |Where pure python modules are installed for the default Python implementation -|python_sitearch |`+%{python2_sitearch}+` |Where python extension modules that are compiled C are installed for the default Python implementation -|python2_sitelib |/usr/lib/python2.X/site-packages |Where pure python2 modules are installed -|python2_sitearch |/usr/lib64/python2.X/site-packages on x86_64 + -/usr/lib/python2.X/site-packages on x86 |Where python2 extension modules that are compiled C are installed -|python3_sitelib |/usr/lib/python3.X/site-packages |Where pure python3 modules are installed -|python3_sitearch |/usr/lib64/python3.X/site-packages on x86_64 + -/usr/lib/python3.X/site-packages on x86 |Where python3 extension modules that are compiled C are installed -|py_byte_compile |(script) |Defined in python3-devel. See the [#Bytecompiling_with_the_correct_python_version bytecompiling] section for usage -|python3_version |3.X |Defined in python3-devel. Useful when running programs with Python version in filename, such as nosetest-%\{python3_version} -|python3_version_nodots |3X |Defined in python3-devel since Fedora 21 / Python 3.4. Useful when listing files explicitly in %files section , such as %\{python3_sitelib}/foo/*.cpython-%\{python3_version_nodots}.pyo -|==================================================================================================================================================================================================================== - -During `+%install+` or when listing `+%files+` you can use the `+python2_sitearch+` and `+python2_sitelib+` macros to specify where the installed modules are to be found. For instance: - -.... -%files -# A pure python2 module -%{python2_sitelib}/foomodule/ -# A compiled python2 extension module -%{python2_sitearch}/barmodule/ -# A compiled python3 extension module -%{python3_sitearch}/bazmodule/ -.... - -Using the macros has several benefits. - -1. It ensures that the packages are installed correctly on multilib architectures. -2. Using these macros instead of hardcoding the directory in the specfile ensures your spec remains compatible with the installed python version even if the directory structure changes radically (for instance, if `+python2_sitelib+` moves into `+%{_datadir}+`) - -== Files to include - -When installing python modules we include several different types of files. - -* *.py source files because they are used when generating tracebacks -* *.pyc and *.pyo byte compiled files (and, if present, the enclosing __pycache__ directory in most cases) - -* python will try to create them at runtime if they don't exist which leads to spurious SELinux AVC denials in the logs -* If the system administrator invokes python with -OO, .pyos will be created with no docstrings. This can break some programs. - -*.egg-info files or directories. If these are generated by the module's build scripts they must be included in the package because they might be needed by other applications and modules at runtime. - -== Source files - -Source files (*.py) must be included in the same packages as the byte-compiled -versions of them. - -== Byte compiling - -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). With current versions of python 3, these files will be located inside a directory named `+__pycache__+`. Older versions of python will simply place them alongside the .py files. - -The .pyc and .pyo files contain byte code that is portable across OSes. If you do not include them in your packages, python will try (and generally fail) to create them when the user runs the program. If the system administrator runs the program, then the files will be successfully written, causing stray .pyc and .pyo files which will not be removed when the package is removed. To prevent that the byte compiled files need to be compiled and included in the `+%files+` section. Normally, byte compilation is done for you by the `+brp-python-bytecompile+` script. This script runs after the `+%install+` section of the spec file has been processed and byte compiles any .py files that it finds (this recompilation puts the proper filesystem paths into the modules otherwise tracebacks would include the `+%{buildroot}+` in them). - -You must include in your package the .pyc and .pyo files. If the build process creates a __pycache__ directory in a subdirectory of %\{python3_sitearch} or %\{python3_sitelib}, you must also include all items in the __pycache__ directory. (You should not include the directories %\{python3_sitearch}/__pycache__ or %\{python3_sitelib}/__pycache__ because they are already owned by the python3-libs package.) - -All that you need to do is include the files in the `+%files+` section (replacing %\{python3_sitelib} with the appropriate macro for your package): - -.... -%files -%{python3_sitelib}/foo/ -.... - -or, if the python code installs directly into %\{python3_sitelib}: - -.... -%files -%{python3_sitelib}/foo.py -%{python3_sitelib}/__pycache__/* -.... - -=== Optimization - -Fedora packages running with python < 3.5 (including any version of python 2) *must not* invoke python with the `+-OO+` option or set the environment variable `+PYTHONOPTIMIZE+` to 2 or greater. (Using -O or `+PYTHONOPTIMIZE+` less than 2 is fine, though unnecesary.) - -Similarly, any `+.pyo+` shipped in a Fedora package for python < 3.5 *must no* have been byte compiled using optimization level 2 or higher. - -=== Bytecompiling with the correct python version - -When byte compiling a .py file, python embeds a magic number in the byte compiled files that correspond to the runtime. Files in `+%{python?_sitelib}+` and `+%{python?_sitearch}+` must correspond to the runtime for which they were built. For instance, a pure python module compiled for the 3.1 runtime needs to be below `+%{_usr}/lib/python3.1/site-packages+` - -The `+brp-python-bytecompile+` script tries to figure this out for you. The script determines which interpreter to use when byte compiling the module by following these steps: - -1. what directory is the module installed in? If it's `+/usr/lib{,64}/pythonX.Y+`, then `+pythonX.Y+` is used to byte compile the module. If `+pythonX.Y+` is not installed, then an error is returned and the rpm build process will exit on an error so remember to `+BuildRequire+` the proper python package. -2. the script interpreter defined in `+%{__python}+` is used to compile the modules. This defaults to the latest python2 version on Fedora. If you need to compile this module for python3, set it to `+/usr/bin/python3+` instead: -+ -.... -%global __python %{__python3} -.... -+ -Doing this is useful when you have a python3 application that's installing a private module into its own directory. For instance, if the foobar application installs a module for use only by the command line application in `+%{_datadir}/foobar+`. Since these files are not in one of the python3 library paths (ie. `+/usr/lib/python3.1+`) you have to override `+%{__python}+` to tell `+brp-python-bytecompile+` to use the python3 interpreter for byte compiling. - -These settings are enough to properly byte compile any package that builds python modules in `+%{python?_sitelib}+` or `+%{python?_sitearch}+` or builds for only a single python interpreter. However, if the application you're packaging needs to build with both python2 and python3 and install into a private module directory (perhaps because it provides one utility written in python2 and a second utility written in python3) then you need to do this manually. Here's a sample spec file snippet that shows what to do: - -.... -# Turn off the brp-python-bytecompile script -%global __os_install_post %(echo '%{__os_install_post}' | sed -e 's!/usr/lib[^[:space:]]*/brp-python-bytecompile[[:space:]].*$!!g') -# Buildrequire both python2 and python3 -BuildRequires: python2-devel python3-devel -[...] - -%install -# Installs a python2 private module into %{buildroot}%{_datadir}/mypackage/foo -# and installs a python3 private module into %{buildroot}%{_datadir}/mypackage/bar -make install DESTDIR=%{buildroot} - -# Manually invoke the python byte compile macro for each path that needs byte -# compilation. -%py_byte_compile %{__python2} %{buildroot}%{_datadir}/mypackage/foo -%py_byte_compile %{__python3} %{buildroot}%{_datadir}/mypackage/bar -.... - -The `+%py_byte_compile+` macro takes two arguments. The first is the python interpreter to use for byte compiling. The second is a file or directory to byte compile. If the second argument is a directory, the macro will recursively byte compile any *.py file in the directory. - -== Common SRPM vs split SRPMs - -Many times when you package a python module you will want to create a module for python2 and a module for python3. There are two ways of doing this: either from a single SRPM or from multiple. The rule to choose which method is simple: if the python2 and python3 modules are distributed as a single tarball (many times as a single directory of source where the `+/usr/bin/2to3+` program is used to transform the code at buildtime) then you must package them as subpackages built from a single SRPM. If they come in multiple tarballs then package them from multiple SRPMs. - -=== Multiple SRPMS - -When upstream ships multiple tarballs with one tarball containing python2 code and a different tarball containing python3 code, we should ship those as multiple SRPMs. The two SRPMs could have different maintainers within Fedora and the two packages need not upgrade at the same time. Building from multiple SRPMs has some advantages and disadvantages: - -*Advantages*: - -* There can be separate maintainers for python2 and python3 so each maintainer can concentrate on one stack. -* The two packages can evolve separately; if 2 and 3 need to have different versions, they can. - -*Disadvantages*: - -* The two specfiles have to be maintained separately -* When upstream releases e.g. security fixes, they have to be tracked in two places - -The following practices are designed to help mitigate the disadvantages listed above: - -* When packaging a module for python3 contact the maintainers for the python2 module and try to coordinate with them. -* Request at least watchbugzilla and watchcommit acls on each other's packages so you're aware of outstanding bugs. -* Complete any python 2 Merge Review when doing the python 3 version. Doing this gets issues that apply to both packages addressed at the same time. -* Add a link to the python 2 Merge Review/Package Review to the python 3 Package Review - -=== Subpackages - -Sometimes upstream will ship one tarball that builds both a python2 and a python3 module. There's several ways that upstream can structure this. When upstream writes their build scripts to build both python2 and python3 modules in a single build this is just like building subpackages for any other package. You expand the tarball and patch the source in `+%prep+`, run upstream's build scripts to build the package in `+%build+`, and then run upstream's build scripts to install it in `+%install+`. - -*Advantages*: - -* Single src.rpm to review and build -* Avoids having to update multiple packages when things change. - -*Disadvantages*: - -* The Fedora maintainer needs to care about both python 2 and python 3 modules which makes more work to maintain that package. -* The 2 and 3 versions are in lockstep. Bugfixes need to apply to python2 while not breaking the translation into python3. -* Bugzilla components are set up according to source RPM, so they will have a single shared bugzilla component. This could be confusing to end-users, as it would be more difficult to figure out e.g. that a bug with python3-foo needs to be filed against python-foo. There's a similar problem with checking out package sources from CVS, though this is less serious as it is less visible to end users. - -Two other ways exist for the upstream to support building python3 modules from a single source: - -==== Building more than once - -One way that's currently very common is for the build scripts to create either a python2 or python3 module based on which interpreter is used to run the setup.py script. (The http://pkgs.fedoraproject.org/cgit/python-setuptools.git/tree/python-setuptools.spec[python-setuptools package] is currently built this way). - -===== Example spec file - -.... -%if 0%{?fedora} > 12 -%global with_python3 1 -%else -%{!?__python2: %global __python2 /usr/bin/python2} -%{!?python2_sitelib: %global python2_sitelib %(%{__python2} -c "from distutils.sysconfig import get_python_lib; print (get_python_lib())")} -%endif - -%global srcname distribute -.... - -At the top of our spec file we have the standard define for `+python2_sitelib+` on older RHEL releases. We also define `+with_python3+` which we'll use to conditionalize the build whenever we have a section that is only useful when building a python3 module. Using `+with_python3+` allows us to do two things: - -1. It makes it easy to turn off the python3 build when tracking down problems. -2. The conditionals also make it easy to use the same spec for older releases of Fedora and EPEL. - -. - -.... -Name: python-setuptools -Version: 0.6.10 -Release: 2%{?dist} -Summary: Easily build and distribute Python packages - -Group: Applications/System -License: Python or ZPLv2.0 -URL: http://pypi.python.org/pypi/%{srcname} -Source0: http://pypi.python.org/packages/source/d/%{srcname}/%{srcname}-%{version}.tar.gz -# Fix a failing test case -Patch0: python-setuptools-test.patch - -BuildArch: noarch -BuildRequires: python2-devel -%if 0%{?with_python3} -BuildRequires: python3-devel -%endif # if with_python3 -Provides: python2-setuptools -.... - -When we build the python3 module in addition to the python2 module we need both `+python2-devel+` and `+python3-devel+`. - -.... -%description -Setuptools is a collection of enhancements to the Python distutils that allow -you to more easily build and distribute Python packages, especially ones that -have dependencies on other packages. - -This package contains the runtime components of setuptools, necessary to -execute the software that requires pkg_resources.py. - -%if 0%{?with_python3} -%package -n python3-setuptools -Summary: Easily build and distribute Python 3 packages -Group: Applications/System - -%description -n python3-setuptools -Setuptools is a collection of enhancements to the Python 3 distutils that allow -you to more easily build and distribute Python 3 packages, especially ones that -have dependencies on other packages. - -This package contains the runtime components of setuptools, necessary to -execute the software that requires pkg_resources.py. -%endif # with_python3 -.... - -Here we define the python3 subpackage. Note that we use `+%package -n+` to name the module appropriately. - -.... -%prep -%setup -qc -mv %{srcname}-%{version} python2 -pushd python2 -%patch0 -p1 -b .testfix - -find -name '*.txt' | xargs chmod -x -# copy common doc files to top dir -cp -pr docs psfl.txt zpl.txt ../ -popd - -%if 0%{?with_python3} -cp -a python2 python3 -find python3 -name '*.py' | xargs sed -i '1s|^#!python|#!%{__python3}|' -%endif # with_python3 - -find python2 -name '*.py' | xargs sed -i '1s|^#!python|#!%{__python2}|' -.... - -Our method in building from the same code to make the two separate modules is to keep each build as independent as possible. To do that, we copy the source tree to `+python3+` so that the python 2 sources are entirely independent from the python 3 sources. Some things to watch out for: - -* Make sure that you are copying the correct code. The example is copying the code from within the top directory of the untarred source. If the `+%prep+` has changed directory you will need to change back to the tarball location. -* Patching the source code is done before copying to `+python3+`. Since you have both a python2 and a python3 directory you might be tempted to patch each one separately. *Resist!* Upstream for your package has chosen to distribute a single source tree that builds for both python2 and python3. For your patches to link:Staying_close_to_upstream_projects[ get into upstream], you need to write patches that work with both as well.}} - -`+rpmbuild+` resets the directory at the end of each phase, so you don't need to restore the directory at the end of `+%prep+`. - -.... -%build -pushd python2 -CFLAGS="$RPM_OPT_FLAGS" %{__python2} setup.py build -popd - -%if 0%{?with_python3} -pushd python3 -CFLAGS="$RPM_OPT_FLAGS" %{__python3} setup.py build -popd -%endif # with_python3 - -%install -# Must do the python3 install first because the scripts in /usr/bin are -# overwritten with every setup.py install (and we want the python2 version -# to be the default for now). -%if 0%{?with_python3} -pushd python3 -%{__python3} setup.py install --skip-build --root %{buildroot} - -rm -rf %{buildroot}%{python3_sitelib}/setuptools/tests - -find %{buildroot}%{python3_sitelib} -name '*.exe' | xargs rm -f -chmod +x %{buildroot}%{python3_sitelib}/setuptools/command/easy_install.py -popd -%endif # with_python3 - -pushd python2 -%{__python2} setup.py install --skip-build --root %{buildroot} -popd - -rm -rf %{buildroot}%{python2_sitelib}/setuptools/tests - -find %{buildroot}%{python2_sitelib} -name '*.exe' | xargs rm -f -chmod +x %{buildroot}%{python2_sitelib}/setuptools/command/easy_install.py - -%check -pushd python2 -%{__python2} setup.py test -popd - -%if 0%{?with_python3} -pushd python3 -%{__python3} setup.py test -popd -%endif # with_python3 -.... - -You'll notice that the `+%build+`, `+%install+`, and `+%check+` sections follow a common pattern. They do the normal steps for building the python2 module but then they switch to `+python3+` and run the same steps for python3. Creating the new sections is generally pretty easy. First copy the existing code. Then wrap it with a `+pushd/popd+` to `+python3+`. The usage of `+pushd/popd+` commands will ensure that the directories are logged. Finally, convert all macro references: - -* `+%{__python2}+` becomes `+%{__python3}+` -* `+%{python2_sitelib}+` becomes `+%{python3_sitelib}+` -* `+%{python2_sitearch}+` becomes `+%{python3_sitearch}+` - -.... -%files -%license psfl.txt zpl.txt -%doc docs -%{python2_sitelib}/* -%{_bindir}/easy_install -%{_bindir}/easy_install-2.6 - -%if 0%{?with_python3} -%files -n python3-setuptools -%license psfl.txt zpl.txt -%doc docs -%{python3_sitelib}/* -%{_bindir}/easy_install-3.1 -%endif # with_python3 - -%changelog -.... - -In this final section, you can see that we once again switch macros from `+%{python2_sitelib}+` to `+%{python3_sitelib}+`. Since we chose to install the python2 version of `+%{_bindir}/easy_install+` earlier we need to include that file in the python2 package rather than the python3 subpackage. - -==== Running 2to3 from the spec file - -Sometimes, upstream hasn't integrated running 2to3 on the code into their build scripts but they support making a python3 module from it if you manually run 2to3 on the source. This is the case when it's documented on the upstream's website, in a file in the tarball, or even when email with the module's author has instructions for building a python3 module from the python2 source and the authors are willing to support the result. In these cases it's usually just a matter of the upstream not having written the build script that can turn the python2 source into python3. When this happens you can run `+2to3+` from the spec file. Once you have it working, you can also help upstream integrate it into their build scripts which will benefit everyone in the long term. - -You should usually follow upstream's directions on how to run `+2to3+` and build the python3 module in these cases but there's a few things you should check to make sure upstream is doing it correctly. - -* Since the code is being built from a unified source, you need to copy the code to a new directory before invoking 2to3 just like the link:#Building_more_than_once[ building more than once] method. -* If the `+2to3+` program is invoked instead of using the `+lib2to3+` library functions, make sure it's invoked with `+--write --nobackups+`. `+--write+` is needed to make `+2to3+` actually change the files. `+--nobackups+` avoids leaving `+foo.py.bak+` files in the module directories that then make it into the final package payload. -* Be sure to run 2to3 on the correct directory. When you run `+2to3+` you need to run it on the whole tree. A common mistake here for distutils packages has been to run it on the directory below `+setup.py+`, missing the `+setup.py+` file itself. This leads to errors when `+python3+` tries to execute `+setup.py+` -* If you need to run `+2to3+` to fix code, use `+2to3+` or `+/usr/bin/2to3+`. At the moment, this program is coming from the `+python-tools+` rpm. Using `+2to3+` means that you'll be using a name that is supported upstream and across distros rather than `+/usr/bin/python3-2to3+` which we have renamed in Fedora to avoid filesystem conflicts. This also makes it easier for us to test and eventually change from using the python2 `+2to3+` to the python3 `+2to3+`. We just need to change the python3 package to provide the `+/usr/bin/2to3+` program instead of python and all of our python packages will start using that version instead. -* If `+2to3+` runs into a problem, please https://bugzilla.redhat.com/enter_bug.cgi?component=python&product=Fedora[file a Fedora bug]. Please try to isolate a minimal test case that reproduces the problem when doing so. - -== Avoiding collisions between the python 2 and python 3 stacks - -The python 2 and python 3 stacks are intended to be fully-installable in parallel. When generalizing the package for both python 2 and python 3, it is important to ensure that two different built packages do not attempt to place different payloads into the same path. - -=== Executables in `+/usr/bin+` - -==== The problem - -Many existing python packages install executables into `+/usr/bin+`. - -For example if we have a `+console_scripts+` in a `+setup.py+` shared between -python 2 and python 3 builds: these will spit out files in `+/usr/bin/+`, -and these will collide. - -For example `+python-coverage+` has a `+setup.py+` that contains: - -.... - entry_points = { - 'console_scripts': [ - 'coverage = coverage:main', - ] - }, -.... - -which thus generates a `+/usr/bin/coverage+` executable (this is a python -script that runs another python script whilst generating code-coverage -information on the latter). - -Similarly for the 'scripts' clause; see e.g. `+python-pygments+`: -`+Pygments-1.1.1/setup.py+` has: - -.... - scripts = ['pygmentize'], -.... - -which generates a `+/usr/bin/pygmentize+` (this is a python script that leverages the pygments syntax-highlighting module, giving a simple command-line interface for generating syntax-highlighted files) - -==== Guidelines - -If the executables provide the same functionality independent of whether they are run on top of Python 2 or Python 3, then only one version of the executable should be packaged. On releases up to and including F21, this was the python 2 implementation. Python3 should be used in F22 and later if supported by upstream. Be sure to test the new implementation. Transitioning from python2 to python3 is left to individual package maintainers except for packages in Fedora's critical path. For these, we want to port to python3 versions in the same Fedora release if possible. - -Examples of this: - -* `+/usr/bin/pygmentize+` ought to generate the same output regardless of whether it's implemented via Python 2 or Python 3, so only one version needs to be shipped. - -If the executables provide different functionality for Python 2 and Python 3, then both versions should be packaged. - -Examples of this: - -* `+/usr/bin/coverage+` runs a python script, augmenting the interpreter with code-coverage information. Given that the interpreter itself is the thing being worked with, it's reasonable to package both versions of the executable. -* `+/usr/bin/bpython+` augments the interpreter with a "curses" interface. Again, it's reasonable to package both versions of this. -* `+/usr/bin/easy_install+` installs a module into one of the Python runtimes: we need a version for each runtime. - -As an exception, for the rpms that are part of a python runtime itself, we plan to package both versions of the executables, so that e.g. both the python 2 and python 3 versions of `+2to3+` are packaged. - -==== Naming - -Many executables already contain a "-MAJOR.MINOR" suffix, for example `+/usr/bin/easy_install-3.1+`. These obviously can be used as-is, as they won't conflict. - -For other executables, the general rule is: - -* If only one executable is to be shipped, then it owns its own slot and should use /usr/bin/python3 from Fedora 22 on. -* If executables are to be shipped for both python 2 and python 3: -** Both python 2 and python 3 variants must provide symlinks with a '-X' and '-X.Y' suffix (python runtime major version, or python runtime major.minor version), unless upstream already provides appropriately versioned executables without the dash. -** The unversioned executable *must* be the python 2 version. -** For example, the python 2 version of "coverage" *must* ship executables `+/usr/bin/coverage+`, `+/usr/bin/coverage-2+` and `+/usr/bin/coverage-2.7+`, while the python 3 version *must* provide `+/usr/bin/coverage-3+` and `+/usr/bin/coverage-3.4+` (assuming python3 is Python 3.4). -** For compatibility packages, the Python version is appended *after* the specific package version, for example `+/usr/bin/coverage-v1.2-3+` and `+/usr/bin/coverage-v1.2-3.4+` for python3-coverage1.2 compat package. - -See http://lists.fedoraproject.org/pipermail/devel/2010-January/129217.html[this thread] and a newer thread https://lists.fedoraproject.org/pipermail/packaging/2014-December/010360.html[1] for discussions of this. - -== Packaging eggs and setuptools concerns - -Eggs can mean several different things because they can be placed on disk in several formats: - -* A module and a file with a .egg-info extension that contains the metadata. Created by distutils in Fedora 9 and above. -* As a module and a directory with a .egg-info extension that contains the metadata. Created using setuptools and also the invocation of setup.py in our examples below. -* As a directory with a .egg extension that contains the module and egg metadata. Created when we use easy_install -m to allow installing multiple versions of a module. -* As a single zip file with a .egg extension that contains the module and the egg metadata. - -In Fedora packages, these will be installed to %\{python2_sitelib} or %\{python2_sitearch} directories. We do not install the single zip file version of eggs in Fedora but the three other formats are used. - -=== How to package - -The following are a summary of the guidelines for reviewers to go over when a python module is packaged. The Packaging:Python_Eggs[ complete policy] includes examples and rationale for the way we do things. - -* *Must*: Python eggs must be built from source. They cannot simply drop an egg from upstream into the proper directory. (See Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries[ prebuilt binaries Guidelines] for details) -* *Must*: Python eggs must not download any dependencies during the build process. -* *Must*: When building a compat package, it must install using easy_install -m so it won't conflict with the main package. -* *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. -* *Should*: A package which is used by another package via an egg interface should provide egg info. - -== Filtering Requires: and Provides: - -RPM's dependency generator can often throw in additional dependencies and will often think packages provide functionality contrary to reality. To fix this, the dependency generator needs to be overriden so that the additional dependencies can be filtered out. See Packaging:AutoProvidesAndRequiresFiltering for details. diff --git a/guidelines/modules/ROOT/pages/Treatment_Of_Bundled_Libraries.adoc b/guidelines/modules/ROOT/pages/Treatment_Of_Bundled_Libraries.adoc deleted file mode 100644 index 843967b..0000000 --- a/guidelines/modules/ROOT/pages/Treatment_Of_Bundled_Libraries.adoc +++ /dev/null @@ -1 +0,0 @@ -This page has been rendered irrelevant by updates to the bundling policy. The previous content is of course available in the page history.