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 [email protected] (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 _______________________________________________ pld-cvs-commit mailing list [email protected] http://lists.pld-linux.org/mailman/listinfo/pld-cvs-commit
