PLD-doc: devel-hints-en.txt - introduced structural layout. rationale: it...
pawelz
pawelz at pld-linux.org
Sun Jun 6 12:24:38 CEST 2010
Author: pawelz Date: Sun Jun 6 10:24:38 2010 GMT
Module: PLD-doc Tag: HEAD
---- Log message:
- introduced structural layout.
rationale: it is easier to maintain language versions of document with
strict formal structure. At least it easier to compare pl and en version, if
each section has its name and number, so one can see, for example: section
1.2.2 is missing in pl, and 2.12.1 is only stubbed in -en so needs to be
translated from -pl.
- added some TODO tags
---- Files affected:
PLD-doc:
devel-hints-en.txt (1.47 -> 1.48)
---- Diffs:
================================================================
Index: PLD-doc/devel-hints-en.txt
diff -u PLD-doc/devel-hints-en.txt:1.47 PLD-doc/devel-hints-en.txt:1.48
--- PLD-doc/devel-hints-en.txt:1.47 Sat Jun 5 00:32:19 2010
+++ PLD-doc/devel-hints-en.txt Sun Jun 6 12:24:33 2010
@@ -6,6 +6,10 @@
other fings, used to talk over current CVS/SVN commits and discuss other
planned changes.
+1. General rules
+
+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).
@@ -15,19 +19,26 @@
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.
+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).
+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.
-Package naming:
+2. Package naming
+
Some package classes have a unified naming scheme.
Mainly:
- for Apache 2.x modules: apache-mod_<name>
@@ -38,7 +49,10 @@
- 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.)
-- for any non-native libraries: <lang_name>-<name>, examples:
+
+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>
@@ -52,7 +66,7 @@
<name>.spec (hint: use -n to create subpackage without <name>- prefix). See
ack.spec for an example of such package.
-Subpackages:
+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)
@@ -69,7 +83,10 @@
be included in the main package and _are_ needed for the application.
This fact _must_ be noted inside the spec file.
-Package versions:
+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
@@ -84,8 +101,8 @@
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
-Package epoches:
You shouldn't use %{epoch} when the package doesn't have Epoch: as such
defined.
@@ -102,10 +119,12 @@
Should be:
Requires: %{name} = %{version}-%{release}
+4. Group tag
-Package 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:
@@ -120,6 +139,10 @@
%{?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:
@@ -151,6 +174,8 @@
(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):
@@ -202,7 +227,7 @@
Of course you must add BuildRequires: automake then.
-Dependencies when building packages:
+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:
@@ -211,10 +236,12 @@
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
indirectly) by rpm-build or a package from the BuildRequires list of
package P, we don't add it to the buildRequires of package P - except,
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:
@@ -241,9 +268,15 @@
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:
+
You should also remember to set Obsoletes/Provides as appropriate when
your package is changing its name or when other distributions call it
something else.
+}}}
+
+8. %_sysconfdir macro
The %{_sysconfdir} macro shouldn't be used in paths to constant
system-wide directories:
@@ -257,7 +290,8 @@
/etc/skel
/etc/sysconfig
-Source preparation section (%prep)
+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:
@@ -308,7 +342,8 @@
Don't forget to add %undos BRs. See BuildRequires.txt for details.
-Build process section (%build):
+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.
@@ -356,7 +391,8 @@
And again added to %{__make}:
LDFLAGS="%{rpmldflags} -ldl -lGL -lX11 -lgthread"
-Installation section (%install):
+11. Installation section (%install)
+
This one serves for the commands that install what has been previously
built in the build section to the $RPM_BUILD_ROOT directory. It should
start by cleaning the directory:
@@ -405,7 +441,9 @@
(creating the package file itself) can be speeded up by defining the
macro %_binary_payload to w1.gzdio.
-File list (%files):
+12. File list (%files)
+
+12.1. Directories
When gathering the list files you shouldn't forget about the
directories. Each directory should belong to exactly one package among
those that can be simultaneously installed. It's an error to have a
@@ -431,6 +469,8 @@
If applnkdir is used somewhere, it should be removed as it's obsolete.
+12.2. Conflicting files
+
Sometimes by mistake one file would make its way to several packages
which should be all installable at once. poldek won't be able to
inform about the details of the problem, so the conflict should be
@@ -440,6 +480,8 @@
the inclusion of copies of the same file or directory to different
packages).
+12.3. Special file attributes
+
It's important to keep in mind some special attributes for files which
should be handled differently:
@@ -458,7 +500,8 @@
be created in the %post script, keeping in mind to grant them correct
permissions.
-%files section for shared libraries:
+12.4. %files section for shared libraries:
+
Consider an example library 'libexample.so.1.0.2' with SONAME
'libexample.so.1'. Correct %files sections should contain following lines:
@@ -474,7 +517,7 @@
SONAME symlink should be marked as %ghost, because this file is being created
by ldconfig in %post scriptlet.
-*.desktop files
+12.5. *.desktop files
Applications' main *.desktop files always get placed in %{_desktopdir}
(for KDE applications: in %{_desktopdir}/kde).
@@ -498,8 +541,7 @@
the desktop-file-utils package. More information about their contents
can be found on http://www.freedesktop.org/Standard/desktop-entry-spec/
-
-Documentation (%doc files):
+12.6. Documentation (%doc files):
Every package should, whenever possible, contain documentation files.
Documentation files should be marked with %doc, which makes it possible
@@ -513,6 +555,7 @@
- add files that contain the same documentation in various formats
- add standard license files, contained in the common-licenses package
+13. Updating a package
When updating a package you should browse the patches that are applied
to it. There is a reason for applying them, so don't you remove them
@@ -543,6 +586,7 @@
# TODO:
# - fix that and that
+{{{TODO: sf info seems outdated
Sources of sourceforge-hosted projects are best specified as:
http://dl.sourceforge.net/name/file
Links to prdownloads.sourceforge.net shouldn't be used, as these
@@ -550,10 +594,11 @@
a mirror. ftp://ftp.sourceforge.net/ isn't O.K. either, because some of
the servers reported as ftp.sourceforge.net don't support the FTP
protocol.
+}}}
+14. Package splits
-Package splits.
-
+{{{TODO: Seems bullshit to me. Use exact internal deps instead
When you decide to split a package, you should add Conflicts: on new package
before the split. This is to prevent two packages providing same files being
installed at same time. As the two packages don't have any relations between
@@ -566,14 +611,17 @@
Summary: PAM modules and libraries
Group: Libraries
Conflicts: pam < 0:0.80.1-2
+}}}
-CVS branches.
+15. CVS branches
A package is often developed in various branches (e.g. because there's
a new version, because another developer makes changes of his own which
we don't want to interfere with, because the package is meant for
another PLD release (Ra/Ac/Th/....)
+{{{TODO: outdated. After CVS structure migration it is easy to tag/branch
+using just cvs.
In order to create a branch it's best to use the builder script and
proceed as follows:
@@ -591,27 +639,33 @@
At this point, changes can be made and commited, and they will appear
in the newly-created branch.
+}}}
+{{{TODO: imo if someone just want to try different approach, or package app in
+different way it is enough reason to create a branch.
Branches shouldn't be created without a good reason. In order to make a
package buildable for different PLD versions (Ra/Ac/Th) it should be
placed in the right branch for the given PLD version.
+}}}
It's useful to take a glimpse at the beginning of builder script's
contents - it contains a description of the functions available.
+16. Tagging
-Tagging.
-
+{{{TODO: seems outdated. Since RA is dead, builders no longer create tags
+without auto- prefix
YOU MUST NOT TAG WITH A VERSION NUMBER (or create such branches), that
is, create tags consisting of the package name (e.g. bind-9_2_2-1).
It's the responsibility of people passing the package to builders.
+}}}
Also, don't use tags whose names start with auto- (e.g.
auto-ac-glibc-2_3_2-3). They are used for automated tagging by
builders. Not complying with the above can result in R/W revocation.
Other schemes of tagging are permitted but should be limited only to
justified cases.
-Tag moving, modification application.
+16.1 Tag moving, modification application
You should distinguish branch tags from symbolic tags (a common
situation for the patches).
@@ -629,8 +683,10 @@
# modifying <name>.patch
cvs tag -F <tag> <name>.patch
+17. Transition to UNSERMAKE in KDE applications
-Transition to UNSERMAKE in KDE applications.
+shadzik: Please, review, this paragraph seems to remember pre-kde4 times, and
+should be updated.
KDE application specs should be based on kdepackage-template.spec. It
is UNSERMAKE-enabled. Doing that implies:
@@ -639,7 +695,8 @@
export UNSERMAKE=/usr/share/unsermake/unsermake (thus enabling unsermake)
%{__make} -f Makefile.cvs (regenerating unsermake-aware buildsystem)
-Troubleshooting:
+17.1. Troubleshooting
+
1. If an error occurs regarding TOPDIRS = $(SUBDIRS), Makefile.am from
the sources' main directory must be modified to explicitly list the
subdirectories (most often they'll be src doc po).
@@ -672,7 +729,7 @@
can be overcome by replacing USE_AUTOMOC with AUTO.
-Apache version independant packages
+18. Apache version independant packages
NB: there's webapps framework now (template-webapp.spec)
http://cvs.pld-linux.org/cgi-bin/cvsweb/packages/webapps/webapps.README
@@ -685,8 +742,7 @@
should also add trigger when moving it. see CVS://template-specs/webapp.spec
for the samples.
-
-Naming files other than .spec
+19. Naming files other than .spec
A few unjustified conventions:
- NAME-foo.patch - patches
@@ -702,8 +758,7 @@
crontab, initscript or sysconfig files, then the files are easily located from
CVS.
-
-Perl.
+20. Perl
perllocal.pod
@@ -733,10 +788,13 @@
TODO to remove these:
/usr/lib/perl5/vendor_perl/5.8.0/i686-pld-linux-thread-multi/auto/gpg-ezmlm/.packlist
-
-PHP PEAR.
+21. PHP PEAR.
php-pear packages should be produced with 'pear makerpm PEARNAME' command. the
output is not perfect, so you need to tidy it up. you can get pear program
from php-pear-PEAR package. Additionally you should use ./pearize.sh script to
do some sanity checks and few automatics.
+
+22. Java
+
+TODO
================================================================
---- CVS-web:
http://cvs.pld-linux.org/cgi-bin/cvsweb.cgi/PLD-doc/devel-hints-en.txt?r1=1.47&r2=1.48&f=u
More information about the pld-cvs-commit
mailing list