pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc/guide/files Add some more GNOME-specific packaging...
details: https://anonhg.NetBSD.org/pkgsrc/rev/ef29810efcd5
branches: trunk
changeset: 518134:ef29810efcd5
user: jmmv <jmmv%pkgsrc.org@localhost>
date: Fri Sep 01 16:35:38 2006 +0000
description:
Add some more GNOME-specific packaging and porting information:
- Document how to handle .desktop files.
- Document how to handle icons for the hicolor theme.
- Add a chapter detailing the GNOME meta packages, the packaging of new
applications and the updatee procedure.
Also add some documentation on how to better handle and create patches.
diffstat:
doc/guide/files/chapters.ent | 3 +-
doc/guide/files/components.xml | 145 +++++++++++++++-
doc/guide/files/fixes.xml | 72 ++++++-
doc/guide/files/gnome.xml | 360 +++++++++++++++++++++++++++++++++++++++++
doc/guide/files/pkgsrc.xml | 5 +-
5 files changed, 563 insertions(+), 22 deletions(-)
diffs (truncated from 665 to 300 lines):
diff -r 904994354216 -r ef29810efcd5 doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent Fri Sep 01 15:44:44 2006 +0000
+++ b/doc/guide/files/chapters.ent Fri Sep 01 16:35:38 2006 +0000
@@ -1,7 +1,7 @@
<!--
Creates entities for each chapter in the pkgsrc book.
- $NetBSD: chapters.ent,v 1.14 2006/07/03 23:51:01 rillig Exp $
+ $NetBSD: chapters.ent,v 1.15 2006/09/01 16:35:38 jmmv Exp $
-->
<!ENTITY chap.intro SYSTEM "introduction.xml">
@@ -28,6 +28,7 @@
<!ENTITY chap.debug SYSTEM "debug.xml">
<!ENTITY chap.submit SYSTEM "submit.xml">
<!ENTITY chap.devfaq SYSTEM "devfaq.xml">
+<!ENTITY chap.gnome SYSTEM "gnome.xml">
<!-- The pkgsrc infrastructure -->
<!ENTITY chap.infr.design SYSTEM "infr.design.xml">
diff -r 904994354216 -r ef29810efcd5 doc/guide/files/components.xml
--- a/doc/guide/files/components.xml Fri Sep 01 15:44:44 2006 +0000
+++ b/doc/guide/files/components.xml Fri Sep 01 16:35:38 2006 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.26 2006/07/24 10:32:36 rillig Exp $ -->
+<!-- $NetBSD: components.xml,v 1.27 2006/09/01 16:35:38 jmmv Exp $ -->
<chapter id="components"> <?dbhtml filename="components.html"?>
<title>Package components - files, directories and contents</title>
@@ -239,12 +239,6 @@
for the patch files by using the <command>make makepatchsum</command>
command, see <xref linkend="components.distinfo"/>.</para>
- <para>When adding a patch that corrects a problem in the distfile (rather
- than e.g. enforcing pkgsrc's view of where man pages should go), send
- the patch as a bug report to the maintainer. This benefits
- non-pkgsrc users of the package, and usually enables removing
- the patch in future version.</para>
-
<para>Patch files that are distributed by the author or other
maintainers can be listed in
<varname>$PATCHFILES</varname>. </para>
@@ -261,6 +255,143 @@
it in <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
files in the named directory are expected to be patch files, and
<emphasis>they are applied after pkgsrc patches are applied</emphasis>.</para>
+
+ <sect2 id="components.patches.guidelines">
+ <title>Patching guidelines</title>
+
+ <para>When fixing a portability issue in the code do not use
+ preprocessor magic to check for the current operating system nor
+ platform. Doing so hurts portability to other platforms because
+ the OS-specific details are not abstracted appropriately.</para>
+
+ <para>The general rule to follow is: instead of checking for the
+ operating system the application is being built on, check for the
+ specific <emphasis>features</emphasis> you need. For example,
+ instead of assuming that kqueue is available under NetBSD and
+ using the <varname>__NetBSD__</varname> macro to conditionalize
+ kqueue support, add a check that detects kqueue itself —
+ yes, this generally involves patching the
+ <command>configure</command> script. There is absolutely nothing
+ that prevents some OSes from adopting interfaces from other OSes
+ (e.g. Linux implementing kqueue), something that the above checks
+ cannot take into account.</para>
+
+ <para>Of course, checking for features generally involves more
+ work on the developer's side, but the resulting changes are
+ clearner and there are chances they will work on many other
+ platforms. Not to mention that there are higher chances of being
+ later integrated into the mainstream sources. Remember:
+ <emphasis>It doesn't work unless it is right!</emphasis></para>
+
+ <para>Some typical examples:</para>
+
+ <table id="patch-examples">
+ <title>Patching examples</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Where</entry>
+ <entry>Incorrect</entry>
+ <entry>Correct</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>configure script</entry>
+ <entry>
+ <programlisting>case ${target_os} in
+ netbsd*) have_kvm=yes ;;
+ *) have_kvm=no ;;
+ esac</programlisting>
+ </entry>
+
+ <entry>
+ <programlisting>AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)</programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry>C source file</entry>
+ <entry>
+ <programlisting>#if defined(__NetBSD__)
+ # include <sys/event.h>
+ #endif</programlisting>
+ </entry>
+ <entry>
+ <programlisting>#if defined(HAVE_SYS_EVENT_H)
+ # include <sys/event.h>
+ #endif</programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry>C source file</entry>
+ <entry><programlisting>int
+ monitor_file(...)
+ {
+ #if defined(__NetBSD__)
+ int fd = kqueue();
+ ...
+ #else
+ ...
+ #endif
+ }</programlisting>
+ </entry>
+ <entry>
+ <programlisting>int
+ monitor_file(...)
+ {
+ #if defined(HAVE_KQUEUE)
+ int fd = kqueue();
+ ...
+ #else
+ ...
+ #endif
+ }</programlisting>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>For more information, please read the <emphasis>Making
+ packager-friendly software</emphasis> article (<ulink
+ url="http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html";>part
+ 1</ulink>, <ulink
+ url="http://www.oreillynet.com/pub/a/onlamp/2005/04/28/packaging2.html";>part
+ 2</ulink>). It summarizes multiple details on how to make
+ software easier to package; all the suggestions in it were
+ collected from our experience in pkgsrc work, so they are possibly
+ helpful when creating patches too.</para>
+
+ </sect2>
+
+ <sect2 id="components.patches.feedback">
+ <title>Feedback to the author</title>
+
+ <para>Always, always, <emphasis role="strong">always</emphasis>
+ feed back any <emphasis>portability fixes</emphasis> or
+ improvements you do to a package to the mainstream developers.
+ This is the only way to get their attention on portability issues
+ and to ensure that future versions can be built out-of-the box on
+ NetBSD. Furthermore, any user that gets newer distfiles will get
+ the fixes straight from the packaged code.</para>
+
+ <para>This generally involves cleaning up the patches as described
+ in the following section (because sometimes the patches that are
+ added to pkgsrc are quick hacks), filling bug reports in the
+ appropriate trackers for the projects and working with the
+ mainstream authors to accept your changes. It is
+ <emphasis>extremely important</emphasis> that you do it so that
+ the packages in pkgsrc are kept simple and thus further changes
+ can be done without much hassle.</para>
+
+ <para>Support the idea of free software!</para>
+
+ </sect2>
+
</sect1>
<sect1 id="other-mandatory-files">
diff -r 904994354216 -r ef29810efcd5 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Fri Sep 01 15:44:44 2006 +0000
+++ b/doc/guide/files/fixes.xml Fri Sep 01 16:35:38 2006 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.68 2006/08/12 21:29:40 wiz Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.69 2006/09/01 16:35:38 jmmv Exp $ -->
<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
<title>Making your package work</title>
@@ -1639,20 +1639,68 @@
</orderedlist>
</sect2>
- </sect1>
+
+ <sect2 id="hicolor-theme">
+ <title>Packages installing hicolor theme icons</title>
+
+ <para>If a package installs images under the
+ <filename>share/icons/hicolor</filename> and/or updates the
+ <filename>share/icons/hicolor/icon-theme.cache</filename> database,
+ you need to take some extra steps to make sure that the shared
+ theme directory is handled appropriately and that the cache
+ database is rebuilt:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Include
+ <filename>../../graphics/hicolor-icon-theme/buildlink3.mk</filename>
+ instead of its <filename>buildlink3.mk</filename> file.</para>
+ </listitem>
+
+ <listitem>
+ <para>Check the PLIST and remove the entry that refers to the
+ theme cache.</para>
+ </listitem>
+
+ <listitem>
+ <para>Ensure that the PLIST does not remove the shared icon
+ directories from the <filename>share/icons/hicolor</filename>
+ hierarchy because they will be handled automatically.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The best way to verify that the PLIST is correct with
+ respect to the last two points is to regenerate it using
+ <command>make print-PLIST</command>.</para>
+ </sect2>
- <sect1 id="feedback-to-author">
- <title>Feedback to the author</title>
+ <sect2 id="desktop-files">
+ <title>Packages installing desktop files</title>
+
+ <para>If a package installs <filename>.desktop</filename> files
+ under <filename>share/applications</filename> and these include
+ MIME information, you need to take extra steps to ensure that they
+ are registered into the MIME database:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Include
+ <filename>../../sysutils/desktop-file-utils/desktopdb.mk</filename>.</para>
+ </listitem>
- <para>If you have found any bugs in the package you make available,
- if you had to do special steps to make it run under NetBSD or
- if you enhanced the software in various other ways, be sure
- to report these changes back to the original author of the
- program! With that kind of support, the next release of the
- program can incorporate these fixes, and people not using the
- NetBSD packages system can win from your efforts.</para>
+ <listitem>
+ <para>Check the PLIST and remove the entry that refers to the
+ <filename>share/applications/mimeinfo.cache</filename> file.
+ It will be handled automatically.</para>
+ </listitem>
+ </orderedlist>
- <para>Support the idea of free software!</para>
+ <para>The best way to verify that the PLIST is correct with
+ respect to the last point is to regenerate it using <command>make
+ print-PLIST</command>.</para>
+ </sect2>
+
</sect1>
+
</chapter>
diff -r 904994354216 -r ef29810efcd5 doc/guide/files/gnome.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/gnome.xml Fri Sep 01 16:35:38 2006 +0000
@@ -0,0 +1,360 @@
+<!-- $NetBSD: gnome.xml,v 1.1 2006/09/01 16:35:39 jmmv Exp $ -->
+
+<chapter id="gnome"> <?dbhtml filename="gnome.html"?>
+<title>GNOME packaging and porting</title>
+
+<para>Quoting <ulink url="http://www.gnome.org/";>GNOME's web
+site</ulink>:</para>
+
+<blockquote>
+ <para>The GNOME project provides two things: The GNOME desktop
+ environment, an intuitive and attractive desktop for users, and the
+ GNOME development platform, an extensive framework for building
+ applications that integrate into the rest of the desktop.</para>
+</blockquote>
+
+<para>pkgsrc provides a seamless way to automatically build and install
+a complete GNOME environment <emphasis>under many different
+platforms</emphasis>. We can say with confidence that pkgsrc is one of
+the most advanced build and packaging systems for GNOME due to its
+included technologies buildlink3, the wrappers and tools framework and
+automatic configuration file management. Lots of efforts are put into
Home |
Main Index |
Thread Index |
Old Index