PLD-doc: devel-hints-en.txt - changed layout for better readibility
pawelz
pawelz at pld-linux.org
Mon Jun 7 11:00:51 CEST 2010
Author: pawelz Date: Mon Jun 7 09:00:51 2010 GMT
Module: PLD-doc Tag: HEAD
---- Log message:
- changed layout for better readibility
---- Files affected:
PLD-doc:
devel-hints-en.txt (1.49 -> 1.50)
---- Diffs:
================================================================
Index: PLD-doc/devel-hints-en.txt
diff -u PLD-doc/devel-hints-en.txt:1.49 PLD-doc/devel-hints-en.txt:1.50
--- PLD-doc/devel-hints-en.txt:1.49 Sun Jun 6 13:19:30 2010
+++ PLD-doc/devel-hints-en.txt Mon Jun 7 11:00:46 2010
@@ -1,4 +1,4 @@
-Hints for PLD developers.
+ Hints for PLD developers
It's worth to remember that PLD is a team work; primary mailing lists
for developers are pld-devel-pl at lists.pld-linux.org (Polish) and
@@ -10,231 +10,231 @@
1.1. Spec file formatting: templates and adapter
-When adding a spec file which isn't based on template*.spec you should
-run adapter.awk on it (you can find more about using this script under
-http://www.pld-linux.org/ in the developer section).
-
-Spec files based on template*.spec can also be run through adapter, to
-correct line formating in the descriptions and preambles. Note: adapter
-must be run with some UTF-8 locale (e.g. en_GB.UTF-8 or en_US.UTF-8) in
-order to detect line lengths correctly.
+ When adding a spec file which isn't based on template*.spec you should run
+ adapter.awk on it (you can find more about using this script under
+ http://www.pld-linux.org/ in the developer section).
+
+ Spec files based on template*.spec can also be run through adapter, to
+ correct line formating in the descriptions and preambles. Note: adapter
+ must be run with some UTF-8 locale (e.g. en_GB.UTF-8 or en_US.UTF-8) in
+ order to detect line lengths correctly.
1.2. Build environment
-A package must be able to be built from a normal user account without
-any additional work.
+ A package must be able to be built from a normal user account without any
+ additional work.
1.3. Encoding
-.spec files are encoded in UTF-8, so any localized summaries and descriptions
-must follow it. Only main (C, i.e. Summary: and %description without -l LANG)
-descriptions should stay in plain ASCII (but you can add en_GB.UTF-8 or
-en_US.UTF-8 localization and use non-ASCII characters there).
+ .spec files are encoded in UTF-8, so any localized summaries and
+ descriptions must follow it. Only main (C, i.e. Summary: and %description
+ without -l LANG) descriptions should stay in plain ASCII (but you can add
+ en_GB.UTF-8 or en_US.UTF-8 localization and use non-ASCII characters
+ there).
1.4. %description section
-Any content in the %description section should be formatted to 70 chars.
-For guidelines regarding the Polish nomenclature refer to the Polish
-version of this manual.
+ Any content in the %description section should be formatted to 70 chars.
+ For guidelines regarding the Polish nomenclature refer to the Polish
+ version of this manual.
2. Package naming
-Some package classes have a unified naming scheme.
-Mainly:
-- for Apache 2.x modules: apache-mod_<name>
-- for Apache 1.3.x modules: apache1-mod_<name>
-- for PAM modules: pam-pam_<name>
-- for PEAR modules: php-pear-<name> (where <name> usually is
- Class[_Class[_Class...]])
-- for binary PECL modules, which are PHP extensions: php-pecl-<name>
-- for kernel modules: kernel-<type>-<name> (<type> is the same as the
- subdirectory inside drivers/ - eg. char, net etc.)
+ Some package classes have a unified naming scheme.
+ Mainly:
+ - for Apache 2.x modules: apache-mod_<name>
+ - for Apache 1.3.x modules: apache1-mod_<name>
+ - for PAM modules: pam-pam_<name>
+ - for PEAR modules: php-pear-<name> (where <name> usually is
+ Class[_Class[_Class...]])
+ - for binary PECL modules, which are PHP extensions: php-pecl-<name>
+ - for kernel modules: kernel-<type>-<name> (<type> is the same as the
+ subdirectory inside drivers/ - eg. char, net etc.)
2.1 Non-native libraries (perl, java, etc)
-All non-native libraries should follow <lang_name>-<name> scheme, examples:
- * for Perl modules: perl-<name> (for object modules the name usually
- is Class[-Class[-Class...]])
- * for Python modules: python-<name>
- * for Java libraries: java-<name>
- * for Ruby libraries: ruby-<name>
-Note that, some packages may contain library and application that uses this
-library. In such case you should split it into two packages: <name> and
-<lang_name>-<name>. If application is only tiny example on how to use library,
-spec should be named <lang_name>-<name>.spec. Otherwise, if it is real
-application and library is used mainly by given application, spec may be named
-<name>.spec (hint: use -n to create subpackage without <name>- prefix). See
-ack.spec for an example of such package.
+ All non-native libraries should follow <lang_name>-<name> scheme, examples:
+ * for Perl modules: perl-<name> (for object modules the name usually
+ is Class[-Class[-Class...]])
+ * for Python modules: python-<name>
+ * for Java libraries: java-<name>
+ * for Ruby libraries: ruby-<name>
+ Note that, some packages may contain library and application that uses this
+ library. In such case you should split it into two packages: <name> and
+ <lang_name>-<name>. If application is only tiny example on how to use
+ library, spec should be named <lang_name>-<name>.spec. Otherwise, if it is
+ real application and library is used mainly by given application, spec may
+ be named <name>.spec (hint: use -n to create subpackage without <name>-
+ prefix). See ack.spec for an example of such package.
2.2. Native libraries
-Packages containing shared libraries can be divided into:
-main package (containing lib*.so.*.*, documentation useful for the user
- and /sbin/ldconfig execution in %post/%postun sections)
--devel package (containig header files, lib*.so links, possibly
- files like *.la, *.m4, *.pc, *-config scripts and
- documentation for developers)
--static package (containig only static libraries (lib*.a) having their
- shared counterparts (sometimes maybe under a different
- name - only the ABI counts); libraries existing only
- in static version should be included in the -devel
- subpackage)
-
-WARNING: For some applications (mainly from KDE) the *.la files must
-be included in the main package and _are_ needed for the application.
-This fact _must_ be noted inside the spec file.
+
+ Packages containing shared libraries can be divided into:
+ main package (containing lib*.so.*.*, documentation useful for the user
+ and /sbin/ldconfig execution in %post/%postun sections)
+ -devel package (containig header files, lib*.so links, possibly
+ files like *.la, *.m4, *.pc, *-config scripts and
+ documentation for developers)
+ -static package (containig only static libraries (lib*.a) having their
+ shared counterparts (sometimes maybe under a different
+ name - only the ABI counts); libraries existing only
+ in static version should be included in the -devel
+ subpackage)
+
+ WARNING: For some applications (mainly from KDE) the *.la files must be
+ included in the main package and _are_ needed for the application. This
+ fact _must_ be noted inside the spec file.
3. Package versioning
3.1 Application version vs. package Version and Release tags
-For full releases the Version field contains the package version.
-For development or testing version (CVS snapshots, alpha, beta,
-gamma, pre, rc, etc. versions), to avoid Epoch bumping, in the Version
-field we write just the target version number and in the Release field
-we put a 0.<pre-version>.<real release> (eg. for rcX and/or beta
-versions it will look like 0.rcX.1 and for snapshots 0.2003.0303.1).
-An example definition (real version: 2.0rc1):
-Version: 2.0
-%define rcver rc1
-Release: 0.%{rcver}.1
+ For full releases the Version field contains the package version.
+ For development or testing version (CVS snapshots, alpha, beta,
+ gamma, pre, rc, etc. versions), to avoid Epoch bumping, in the Version
+ field we write just the target version number and in the Release field
+ we put a 0.<pre-version>.<real release> (eg. for rcX and/or beta
+ versions it will look like 0.rcX.1 and for snapshots 0.2003.0303.1).
+ An example definition (real version: 2.0rc1):
+ Version: 2.0
+ %define rcver rc1
+ Release: 0.%{rcver}.1
-In this case when we change the spec file for the same software version
-we must just bump the last digit in Release ("0" stays the same!)
+ In this case when we change the spec file for the same software version
+ we must just bump the last digit in Release ("0" stays the same!)
3.2 Package Epoch tag
-You shouldn't use %{epoch} when the package doesn't have Epoch: as such
-defined.
-
-This is wrong:
-Name: test
-Summary: example
-Version: 1
-Requires: foo
-
-%package subpackage
-Summary: subpackage
-Requires: %{name} = %{epoch}:%{version}-%{release}
+ You shouldn't use %{epoch} when the package doesn't have Epoch: as such
+ defined.
-Should be:
-Requires: %{name} = %{version}-%{release}
+ This is wrong:
+ Name: test
+ Summary: example
+ Version: 1
+ Requires: foo
+
+ %package subpackage
+ Summary: subpackage
+ Requires: %{name} = %{epoch}:%{version}-%{release}
+
+ Should be:
+ Requires: %{name} = %{version}-%{release}
4. Group tag
-A package must have a defined Group field according to packages/rpm.groups
+ A package must have a defined Group field according to packages/rpm.groups
5. Packaging external kernel modules
-We don't include "BuildRequires: kernel-headers" in packages cointaining
-user-space applications. Such dependency can only be included in packages
-cointaining kernel modules, always conditionally:
-%{?with_dist_kernel:BuildRequires: kernel-headers}
-
-Similarly we don't include kernel dependencies in packages not containing
-kernel modules; in packages containing modules we put them with
-a condition:
-%{?with_dist_kernel:%requires_releq_kernel_up}
- (for UP kernel modules)
-or
-%{?with_dist_kernel:%requires_releq_kernel_smp}
- (for SMP kernel modules)
+ We don't include "BuildRequires: kernel-headers" in packages cointaining
+ user-space applications. Such dependency can only be included in packages
+ cointaining kernel modules, always conditionally:
+ %{?with_dist_kernel:BuildRequires: kernel-headers}
+
+ Similarly we don't include kernel dependencies in packages not containing
+ kernel modules; in packages containing modules we put them with
+ a condition:
+ %{?with_dist_kernel:%requires_releq_kernel_up}
+ (for UP kernel modules)
+ or
+ %{?with_dist_kernel:%requires_releq_kernel_smp}
+ (for SMP kernel modules)
6. autotools
6.1. BuildRequires
-When adding invocations of the auto* and *ize tools, remember to add the
-appropriate dependency declarations:
+ When adding invocations of the auto* and *ize tools, remember to add the
+ appropriate dependency declarations:
-autoconf,autoheader BuildRequires: autoconf
-automake,aclocal BuildRequires: automake
-libtoolize BuildRequires: libtool
-gettextize BuildRequires: gettext-devel
-autopoint BuildRequires: gettext-autopoint
-intltoolize BuildRequires: intltool
-xml-i18n-toolize BuildRequires: intltool
-
-It's good to check the required versions of those packages - except the
-documentation they can be often found in those places:
-autoconf - in the AC_PREREQ(version) macro in configure.{ac,in} or *.m4
-automake - in AUTOMAKE_OPTIONS inside Makefile.am or AM_INIT_AUTOMAKE
- in configure.{ac,in} (only with the new syntax - in the old
- one there was just the name and version of the package)
-gettext - in the AM_GNU_GETTEXT_VERSION macro in configure.{ac,in}
-libtool:
- - when the package only contains shared libraries and at least
- one of them is linked with an other library from the same
- package then version >= 0:1.4.2-9 is required
- - when the package contains a shared library in C++ (which uses
- the standard library libstdc++) the required version is
- >= 2:1.4d
- - when all of those two conditions are present then >= 2:1.4d-3
- has to be used
- - in case that the macro AC_CONFIG_AUX_DIR in configure.ac
- (not configure.in) is specified then version >= 1:1.4.3
- (or >= 2:1.4e in case of C++ libraries) has to be used
+ autoconf,autoheader BuildRequires: autoconf
+ automake,aclocal BuildRequires: automake
+ libtoolize BuildRequires: libtool
+ gettextize BuildRequires: gettext-devel
+ autopoint BuildRequires: gettext-autopoint
+ intltoolize BuildRequires: intltool
+ xml-i18n-toolize BuildRequires: intltool
+
+ It's good to check the required versions of those packages - except the
+ documentation they can be often found in those places:
+ autoconf - in the AC_PREREQ(version) macro in configure.{ac,in} or *.m4
+ automake - in AUTOMAKE_OPTIONS inside Makefile.am or AM_INIT_AUTOMAKE
+ in configure.{ac,in} (only with the new syntax - in the old
+ one there was just the name and version of the package)
+ gettext - in the AM_GNU_GETTEXT_VERSION macro in configure.{ac,in}
+ libtool:
+ - when the package only contains shared libraries and at least
+ one of them is linked with an other library from the same
+ package then version >= 0:1.4.2-9 is required
+ - when the package contains a shared library in C++ (which uses
+ the standard library libstdc++) the required version is
+ >= 2:1.4d
+ - when all of those two conditions are present then >= 2:1.4d-3
+ has to be used
+ - in case that the macro AC_CONFIG_AUX_DIR in configure.ac
+ (not configure.in) is specified then version >= 1:1.4.3
+ (or >= 2:1.4e in case of C++ libraries) has to be used
6.2. Invoking autotools in specfile
-As far as it is possible, these applications should be run using macros
-(for your information explications of them are on the right):
+ As far as it is possible, these applications should be run using macros
+ (for your information explications of them are on the right):
-%{__autoconf} = autoconf
-%{__autoheader} = autoheader
-%{__automake} = automake -a -c -f --foreign
-%{__aclocal} = aclocal
-%{__libtoolize} = libtoolize --copy --force
-%{__intltoolize} = intltoolize --copy --force
-%{__gettextize} = gettextize --copy --force [--intl]
- (+other operations depending on the version
- of gettext being used)
-%{__autopoint} = autopoint --force
-
-Of course if it's needed you can specify other parameters after
-the macro (except gettextize).
-Sometimes there can be problems with automake if it's run in
-a subdirectory with --force set (included in the %{__automake} macro) -
-in that case you should use automake -a -c --foreign
-(the --foreign parameter is essential in most cases, because without it
-automake replaces files like COPYING or INSTALL with its own versions)
-
-Those tools are generally run in the beneath order:
-%{__gettextize}
-%{__libtoolize}
-%{__intltoolize}
-%{__aclocal}
-%{__autoconf}
-%{__autoheader}
-%{__automake}
-
-If any of the files generated by ac/am/lt/gt requires regeneration
-or refreshing (perchence with the exception of config.{guess,sub}),
-then all resources must be regenerated; running just for eg. autoconf
-when a package uses automake too can produce weird errors. Partial
-regeneration can be done only in justifiable incidents and only with
-a proper comment added.
-
-In many sources the config.sub is too old an it can't recognized some
-architectures. It is mostly shown by a message displayed by configure,
-eg. "machine amd64-pld is not known". In that case an up to date
-config.sub can be taken from the automake package. For projects which
-are using automake only regeneration of the files as shown before is
-needed. But config.sub is also used by programs which don't use automake
-or even autoconf. In such cases it must be copied over in the %build
-section of the spec file, for eg. in this way:
+ %{__autoconf} = autoconf
+ %{__autoheader} = autoheader
+ %{__automake} = automake -a -c -f --foreign
+ %{__aclocal} = aclocal
+ %{__libtoolize} = libtoolize --copy --force
+ %{__intltoolize} = intltoolize --copy --force
+ %{__gettextize} = gettextize --copy --force [--intl]
+ (+other operations depending on the version
+ of gettext being used)
+ %{__autopoint} = autopoint --force
+
+ Of course if it's needed you can specify other parameters after the macro
+ (except gettextize). Sometimes there can be problems with automake if it's
+ run in a subdirectory with --force set (included in the %{__automake}
+ macro) - in that case you should use automake -a -c --foreign (the
+ --foreign parameter is essential in most cases, because without it automake
+ replaces files like COPYING or INSTALL with its own versions)
+
+ Those tools are generally run in the beneath order:
+ %{__gettextize}
+ %{__libtoolize}
+ %{__intltoolize}
+ %{__aclocal}
+ %{__autoconf}
+ %{__autoheader}
+ %{__automake}
+
+ If any of the files generated by ac/am/lt/gt requires regeneration or
+ refreshing (perchence with the exception of config.{guess,sub}), then all
+ resources must be regenerated; running just for eg. autoconf when a package
+ uses automake too can produce weird errors. Partial regeneration can be
+ done only in justifiable incidents and only with a proper comment added.
+
+ In many sources the config.sub is too old an it can't recognized some
+ architectures. It is mostly shown by a message displayed by configure, eg.
+ "machine amd64-pld is not known". In that case an up to date config.sub can
+ be taken from the automake package. For projects which are using automake
+ only regeneration of the files as shown before is needed. But config.sub is
+ also used by programs which don't use automake or even autoconf. In such
+ cases it must be copied over in the %build section of the spec file, for
+ eg. in this way:
-cp /usr/share/automake/config.sub .
+ cp /usr/share/automake/config.sub .
-Of course you must add BuildRequires: automake then.
+ Of course you must add BuildRequires: automake then.
7. Dependencies when building packages
-All packages required to build package P (except the kernel headers)
-should be required publicly in one of three places:
-- in the BuildRequires of the spec file package P
-- in Requires of the rpm-build package (global requirements - packages
- needed for building most of the packages)
-- in Requires of the packages from the above list.
+ All packages required to build package P (except the kernel headers)
+ should be required publicly in one of three places:
+ - in the BuildRequires of the spec file package P
+ - in Requires of the rpm-build package (global requirements - packages
+ needed for building most of the packages)
+ - in Requires of the packages from the above list.
{{{TODO: bullshit
We try not to duplicate requirements - if something is required (also
@@ -243,30 +243,30 @@
when the version must be restricted.
}}}
-In case of shared libraries (and e.g. perl modules) dynamically linked
-on build time you have to remember that, apart from "BuildRequires:
-something[-devel] >= version", you also need to add "Requires:
-something >= version" - unless that dependency results from SONAME
-(in the case of shared libraries) or gets generated automatically (in
-the case of Perl modules).
-
-When a package P is built the standard way (no bconds, --nodeps, etc.),
-its dependencies, the patches applied and the commands invoked from the
-spec file (%configure options, make variables, etc.) should unambigously
-define the capabilities and dependencies of the package being built. The
-situation when the presence of another package Q (not mentioned in
-BuildRequires or BuildConflicts) makes P require Q or accept another
-build options is incorrect.
-
-Build process and generated dependencies should be predictable - If a
-given package detects some components during the build, and these aren't
-controlled with e.g. configure switches, than such package is borked and
-needs patching.
-
-It's a standard to link dynamically (with BuildRequires: library-devel).
-Static linking (and BuildRequires: library-static) can only be used
-when well justified. Neither "'cause it was easier" nor "the program does
-it by default" is a good justification.
+ In case of shared libraries (and e.g. perl modules) dynamically linked on
+ build time you have to remember that, apart from "BuildRequires:
+ something[-devel] >= version", you also need to add "Requires: something >=
+ version" - unless that dependency results from SONAME (in the case of
+ shared libraries) or gets generated automatically (in the case of Perl
+ modules).
+
+ When a package P is built the standard way (no bconds, --nodeps, etc.), its
+ dependencies, the patches applied and the commands invoked from the spec
+ file (%configure options, make variables, etc.) should unambigously define
+ the capabilities and dependencies of the package being built. The situation
+ when the presence of another package Q (not mentioned in BuildRequires or
+ BuildConflicts) makes P require Q or accept another build options is
+ incorrect.
+
+ Build process and generated dependencies should be predictable - If a given
+ package detects some components during the build, and these aren't
+ controlled with e.g. configure switches, than such package is borked and
+ needs patching.
+
+ It's a standard to link dynamically (with BuildRequires: library-devel).
+ Static linking (and BuildRequires: library-static) can only be used when
+ well justified. Neither "'cause it was easier" nor "the program does it by
+ default" is a good justification.
{{{TODO: do we really care how other distros call packages??? Also, sometimes
it's better to fix other packages than add P:
@@ -278,313 +278,310 @@
8. %_sysconfdir macro
-The %{_sysconfdir} macro shouldn't be used in paths to constant
-system-wide directories:
-/etc/cron.*
-/etc/crontab.d
-/etc/logrotate.d
-/etc/pam.d
-/etc/profile.d
-/etc/rc.d
-/etc/security
-/etc/skel
-/etc/sysconfig
+ The %{_sysconfdir} macro shouldn't be used in paths to constant system-wide
+ directories:
+ /etc/cron.*
+ /etc/crontab.d
+ /etc/logrotate.d
+ /etc/pam.d
+ /etc/profile.d
+ /etc/rc.d
+ /etc/security
+ /etc/skel
+ /etc/sysconfig
9. Source preparation section (%prep)
-This section prepares the program sources for being built by
-uncompressing them, applying patches, etc.
-The simplest form of this section is:
+ This section prepares the program sources for being built by uncompressing
+ them, applying patches, etc. The simplest form of this section is:
-%prep
-%setup -q
+ %prep
+ %setup -q
-It unpacks the Source0 file and goes to the %{name}-%{version} directory,
-which is the usual place for package sources. If the directory has
-another name, pass its name with the -n parameter:
+ It unpacks the Source0 file and goes to the %{name}-%{version} directory,
+ which is the usual place for package sources. If the directory has another
+ name, pass its name with the -n parameter:
-%prep
-%setup -q -n %{module}-%{fn_ver}
+ %prep
+ %setup -q -n %{module}-%{fn_ver}
-If you the sources aren't compressed but e.g. come from CVS the section
-looks as follows:
+ If you the sources aren't compressed but e.g. come from CVS the section
+ looks as follows:
-%prep
-%setup -q -c -T
-install %{SOURCE0} .
-install %{SOURCE1} .
+ %prep
+ %setup -q -c -T
+ install %{SOURCE0} .
+ install %{SOURCE1} .
-The above lines create the build directory and copies the Source0 and
-Source1 files to it.
+ The above lines create the build directory and copies the Source0 and
+ Source1 files to it.
-Do not add code to %prep that copies files from other packages, as builder -bp
-ignores BuildRequires. For example this should be in %build:
-cp -f /usr/share/automake/config.sub .
+ Do not add code to %prep that copies files from other packages, as builder
+ -bp ignores BuildRequires. For example this should be in %build:
+ cp -f /usr/share/automake/config.sub .
-All patches should be applied in %prep section using %patchN macros. For
-example:
+ All patches should be applied in %prep section using %patchN macros. For
+ example:
-%prep
-%setup -q
-%patch0 -p1
-%patch1 -p0
+ %prep
+ %setup -q
+ %patch0 -p1
+ %patch1 -p0
-CVS, at least PLD CVS, converts DOS ends of line (\r\n) to unix eols (\n). It
-may break some patches. If your patch does not apply after CVS commit /
-checkout, try to undos sources before patching using %undos macro. For
-example:
+ CVS, at least PLD CVS, converts DOS ends of line (\r\n) to unix eols (\n).
+ It may break some patches. If your patch does not apply after CVS commit /
+ checkout, try to undos sources before patching using %undos macro. For
+ example:
-%undos build.xml
+ %undos build.xml
-or
+ or
-%undos $(find -name '*.php')
+ %undos $(find -name '*.php')
-Don't forget to add %undos BRs. See BuildRequires.txt for details.
+ Don't forget to add %undos BRs. See BuildRequires.txt for details.
10. Build process section (%build)
-This section should contain everything that's necessary to build a
-package in the %{_topdir}/BUILD directory in the RPM build tree. In this
-section the $RPM_BUILD_ROOT directory shouldn't be used.
-
-Redefinitions of kde_* that used to appear here:
-
-kde_htmldir="%{_htmldir}"; export kde_htmldir
<<Diff was trimmed, longer than 597 lines>>
---- CVS-web:
http://cvs.pld-linux.org/cgi-bin/cvsweb.cgi/PLD-doc/devel-hints-en.txt?r1=1.49&r2=1.50&f=u
More information about the pld-cvs-commit
mailing list