[gnome-panel/wip/segeiger/reference-documentation] Doc: Update Registration, Installation and Build System section
- From: Sebastian Geiger <segeiger src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-panel/wip/segeiger/reference-documentation] Doc: Update Registration, Installation and Build System section
- Date: Fri, 11 Sep 2015 17:03:38 +0000 (UTC)
commit 09829a2a623f2e49af02ea395044315f1885386e
Author: Sebastian Geiger <sbastig gmx net>
Date: Fri Sep 11 19:03:24 2015 +0200
Doc: Update Registration, Installation and Build System section
doc/reference/panel-applet/panel-applet-docs.sgml | 373 ++++++++++++---------
1 files changed, 206 insertions(+), 167 deletions(-)
---
diff --git a/doc/reference/panel-applet/panel-applet-docs.sgml
b/doc/reference/panel-applet/panel-applet-docs.sgml
index 4a29372..32430c2 100644
--- a/doc/reference/panel-applet/panel-applet-docs.sgml
+++ b/doc/reference/panel-applet/panel-applet-docs.sgml
@@ -671,7 +671,7 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
</chapter>
<chapter id="getting-started.install">
- <title>Panel Applet Files</title>
+ <title>Applet Registration, Installation and Build System</title>
<para>
Simply installing the applet binary will obviously not be enough. The applet also needs to be
registered to the
@@ -686,7 +686,13 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
</simpara>
</warning>
- <sect2 id="getting-started.install.panel-applet">
+ <para>
+ This chapter explains the syntax of <constant>.panel-applet</constant> files and gives the
necessary
+ information to setup the build system in order to install all the required parts of the applet on
the system.
+ For the build system part it is assumed that GNU Autotools (e.g. autoconf and automake) are used.
+ </para>
+
+ <sect1 id="getting-started.install.panel-applet">
<title>Panel Applet File Syntax</title>
<para>
@@ -695,25 +701,25 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
<link linkend="getting-started.concepts.applet-types">applet types</link> this factory can create.
</para>
- <sect3>
- <title>Example</title>
+ <sect2>
+ <title>Panel Applet File Example</title>
<informalexample>
<programlisting>
-[Applet Factory]
-Id=HelloWorldFactory
-Name=Hello World Applet Factory
-Description=Factory for the our example applets
-
-[HelloWorldApplet]
-Name=Hello World
-Description=Factory for the Hello World example applet
-Icon=hello-world-icon
+ [Applet Factory]
+ Id=HelloWorldFactory
+ Name=Hello World Applet Factory
+ Description=Factory for the our example applets
+
+ [HelloWorldApplet]
+ Name=Hello World
+ Description=Factory for the Hello World example applet
+ Icon=hello-world-icon
</programlisting>
</informalexample>
- </sect3>
+ </sect2>
- <sect3>
- <title>Format</title>
+ <sect2>
+ <title>File Format and well known Fields</title>
<para>
The file must contain a <constant>Applet Factory</constant> group with the following keys:
</para>
@@ -767,25 +773,197 @@ Icon=hello-world-icon
</para>
</listitem>
</itemizedlist>
+ </sect2>
- </sect3>
-
- <sect3>
+ <sect2>
<title>Installation</title>
<para>
- The <filename>.panel-applet</filename> file must be installed in a specific directory to be
discoverable by the panel. You can fetch this directory during <constant>configure</constant> withe following
code:
+ The <filename>.panel-applet</filename> file must be installed in a specific directory to be
discoverable by the panel. The exact path of this directory can be queried with
<constant>pkg-config</constant>:
+
+ <informalexample>
+ <programlisting>
+ pkg-config --variable=libpanel_applet_dir libpanel-applet
+ </programlisting>
+ </informalexample>
+
+ By default it is <constant>/usr/share/gnome-panel/5.0/applets</constant>. Please see the
+ <link linkend="getting-started.install.build-system">Build System</link> section for more
information.
</para>
- <informalexample>
- <programlisting>
-LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanel-applet`
-AC_SUBST(LIBPANEL_APPLET_DIR)
- </programlisting>
- </informalexample>
+ </sect2>
- </sect3>
+ </sect1>
- </sect2>
+ <sect1 id="getting-started.in-out-process">
+ <title>Out-of-Process vs In-Process</title>
+
+ <para>
+ Applets can either live in their own process ("out-of-process") or in the panel process
("in-process").
+ The decision to choose one or the other is done at build time, with the macro that you use to
define the applet
+ factory:
+ <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
+ <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function>
+ </link>
+ is used for out-of-process applets while
+ <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS">
+ <function>PANEL_APPLET_IN_PROCESS_FACTORY()</function>
+ </link> is used for in-process applets. Obviously, only one of those two macros can be used.
If both
+ types should be supported, then each macro must be placed between preprocessor conditions and
switched on
+ through a configure option. For example:
+
+ <informalexample>
+ <programlisting>
+ #ifdef MY_APPLET_OUT_PROCESS_ENABLED
+ PANEL_APPLET_OUT_PROCESS_FACTORY (...)
+ #else
+ PANEL_APPLET_IN_PROCESS_FACTORY (...)
+ #endif
+ </programlisting>
+ </informalexample>
+
+ </para>
+
+ <para>
+ For most practical matters, from the applet perspective, the two options are the same.
+ In-process applets do offer a slightly better performance when the applet is loaded, but this
should not have
+ much effect on the user experience. However, an in-process applet can potentially affect the
whole behavior of
+ the panel, especially in case of crashes or memory corruptions: a crash in an in-process
applet will crash the
+ whole panel. It is therefore recommended to use out-of-process applets.
+ </para>
+
+ <para>
+ The communication between the panel and the applet factory is done over D-Bus. When creating
an applet,
+ the panel will send a message to the D-Bus service of the applet factory. If the D-Bus
service is not
+ running yet, it must be started automatically. We use D-Bus activation for this, which
requires install a
+ standard D-Bus service file. This is only needed for, because in-process applets do no need
to have their
+ binary autostarted for obvious reasons.
+ </para>
+
+ <note>
+ <simpara>
+ Please refer to the
+ <ulink
url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services";>
+ D-Bus documentation</ulink> for more information about D-Bus service files.
+ </simpara>
+ </note>
+
+ <para>
+ Here is an example for a D-Bus Service file. It should be named
<constant>org.gnome.panel.applet.HelloWorldFactory.service.in</constant>
+ </para>
+ <informalexample>
+ <programlisting>
+ [D-BUS Service]
+ Name=org.gnome.panel.applet.HelloWorldFactory
+ Exec= LOCATION@
+ </programlisting>
+ </informalexample>
+ <para>
+ Additionally you should adjust the build system to replace <constant>@LOCATION@</constant> by
the install location of the applet binary. The file itself must be installed into
+ <constant>$(datadir)/dbus-1/services/</constant>.
+ </para>
+
+ <para>
+ The next section contains an explanation how to setup the Makefile in order to install the
service file
+ to the correct location on the system.
+ </para>
+ </sect1>
+
+
+
+ <sect1 id="getting-started.install.build-system">
+ <title>Build system</title>
+
+ <sect2>
+ <title>Configure</title>
+
+ <para>
+ In <constant>configure.ac</constant> a variable should be defined that contains the
location
+ where the .panel-applet files are installed.
+
+ You can fetch this directory during <constant>configure</constant> with the following
code:
+ </para>
+
+ <informalexample>
+ <programlisting>
+ LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanel-applet`
+ AC_SUBST(LIBPANEL_APPLET_DIR)
+ </programlisting>
+ </informalexample>
+
+ </sect2>
+
+ <sect2>
+ <title>Makefiles</title>
+
+ A typical Makefile for that is used to build and install an applet contains the following
declarations:
+ <itemizedlist>
+ <listitem>
+ <para>A rule to install the <constant>.panel-applet</constant> file.</para>
+ </listitem>
+ <listitem>
+ <para>A rule to install the D-Bus service file if the applet is an out process
applet.</para>
+ </listitem>
+ <listitem>
+ <para>The <constant>.panel-applet</constant> file and the D-Bus
<constant>.service</constant> file
+ are added to EXTRA_DIST and CLEANFILES.</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect3>
+ <title>Installing the Panel Applet File</title>
+ <informalexample>
+ <programlisting language="bash">
+ appletdir = $(LIBPANEL_APPLET_DIR)
+ applet_in_files = org.gnome.HelloWorld.panel-applet.in
+ applet_DATA = $(applet_in_files:.panel-applet.in=.panel-applet)
+
+ $(applet_in_files): $(applet_in_files).in Makefile
+ $(AM_V_GEN)sed \
+ -e "s|\ LIBEXECDIR\@|$(libexecdir)|" \
+ -e "s|\ VERSION\@|$(PACKAGE_VERSION)|" \
+ $< > $@
+
+ %.panel-applet: %.panel-applet.in \
+ $(INTLTOOL_MERGE) $(wildcard $(top_srcdir)/po/*po) ; \
+ $(INTLTOOL_MERGE) $(top_srcdir)/po $< $@ -d -u -c
$(top_builddir)/po/.intltool-merge-cache
+ </programlisting>
+ </informalexample>
+ </sect3>
+
+ <sect3>
+ <title>Installing the D-Bus service file</title>
+
+ <para>To install the service file the following rule can be placed in the applets
Makefile:</para>
+ <informalexample>
+ <programlisting>
+ servicedir = $(datadir)/dbus-1/services
+ service_in_files = org.gnome.panel.applet.HelloWorldFactory.service.in
+ service_DATA = $(service_in_files:.service.in=.service)
+
+ org.gnome.panel.applet.HelloWorldFactory.service: $(service_in_files)
+ $(AM_V_GEN) sed -e "s|\ LOCATION\@|$(APPLET_LOCATION)|" $< > $@
+ </programlisting>
+ </informalexample>
+ </sect3>
+
+ <sect3>
+ <title>Distribution and Cleanup</title>
+ <para>Add panel-applet .in.in and service file to EXTRA_DIST and $(applet_DATA)
$(applet_DATA).in to CLEANFILES</para>
+ <informalexample>
+ <programlisting>
+ EXTRA_DIST = \
+ GNOME_MixerApplet.panel-applet.in.in \
+ $(service_in_files) \
+ $(ui_DATA) \
+ $(schemas_in_files)
+
+ CLEANFILES = $(applet_DATA) $(applet_DATA).in $(service_DATA) $(schemas_DATA)
+ </programlisting>
+ </informalexample>
+ </sect3>
+
+ </sect2>
+ </sect1>
</chapter>
@@ -862,88 +1040,6 @@ g_object_bind_property (applet, "locked-down",
</chapter>
- <chapter id="getting-started.in-out-process">
- <title>Out-of-Process vs In-Process</title>
-
- <para>
- Applets can either live in their own process ("out-of-process") or in the panel process ("in-process").
- The decision to choose one or the other is done at build time, with the macro that you use to define
the applet
- factory:
- <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
- <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function>
- </link>
- is used for out-of-process applets while
- <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS">
- <function>PANEL_APPLET_IN_PROCESS_FACTORY()</function>
- </link> is used for in-process applets. Obviously, only one of those two macros can be used. If both
- types should be supported, then each macro must be placed between preprocessor conditions and
switched on
- through a configure option. For example:
-
- <informalexample>
- <programlisting>
- #ifdef MY_APPLET_OUT_PROCESS_ENABLED
- PANEL_APPLET_OUT_PROCESS_FACTORY (...)
- #else
- PANEL_APPLET_IN_PROCESS_FACTORY (...)
- #endif
- </programlisting>
- </informalexample>
-
- </para>
-
- <para>
- For most practical matters, from the applet perspective, the two options are the same.
- In-process applets do offer a slightly better performance when the applet is loaded, but this should
not have
- much effect on the user experience. However, an in-process applet can potentially affect the whole
behavior of
- the panel, especially in case of crashes or memory corruptions: a crash in an in-process applet will
crash the
- whole panel. It is therefore recommended to use out-of-process applets.
- </para>
-
- <para>
- The communication between the panel and the applet factory is done over D-Bus. When creating an
applet,
- the panel will send a message to the D-Bus service of the applet factory. If the D-Bus service is
not
- running yet, it must be started automatically. We use D-Bus activation for this, which requires
install a
- standard D-Bus service file. This is only needed for, because in-process applets do no need to
have their
- binary autostarted for obvious reasons.
- </para>
-
- <note>
- <simpara>
- Please refer to the
- <ulink
url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services";>
- D-Bus documentation</ulink> for more information about D-Bus service files.
- </simpara>
- </note>
-
- <para>
- Here is an example for a D-Bus Service file. It should be named
<constant>org.gnome.panel.applet.HelloWorldFactory.service.in</constant>
- </para>
- <informalexample>
- <programlisting>
- [D-BUS Service]
- Name=org.gnome.panel.applet.HelloWorldFactory
- Exec= LOCATION@
- </programlisting>
- </informalexample>
- <para>
- Additionally you should adjust the build system to replace <constant>@LOCATION@</constant> by the
install location of the applet binary. The file itself must be installed into
- <constant>/usr/share/dbus-1/services/</constant>.
- </para>
-
- To install the service file the following rule can be placed in the applets Makefile:
- <informalexample>
- <programlisting>
- servicedir = $(datadir)/dbus-1/services
- service_in_files = org.gnome.panel.applet.HelloWorldFactory.service.in
- service_DATA = $(service_in_files:.service.in=.service)
-
- org.gnome.panel.applet.FishAppletFactory.service: $(service_in_files)
- $(AM_V_GEN) sed -e "s|\ LOCATION\@|$(APPLET_LOCATION)|" $< > $@
- </programlisting>
- </informalexample>
-
- </chapter>
-
<chapter id="getting-started.introspection">
<title>Writing an applet in languages other than C</title>
@@ -1233,63 +1329,6 @@ PanelApplet.Applet.factory_main("HelloWorldFactory",
Manual.
</para>
</sect1>
-
- <sect1 id="port-gnome2.dbus.build-system-changes">
- <title>Build system changes</title>
- Build system (configure)
-
- Check for libpanel-applet-4 in your configure file, and get the directory where .panel-applet
files should go from the pkg-config file, with something like:
-
- LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanelapplet-4.0`
-
- Build system (Makefile.am)
-
- Add the ui xml path to the CFLAGS:
-
- -DWNCK_MENU_UI_DIR=\""$(xmluidir)"\" \
-
- This is the macro you use when setting up the applet menu
-
- Panel-applet file:
-
- appletdir = $(LIBPANEL_APPLET_DIR)
- applet_in_files = GNOME_MixerApplet.panel-applet.in
- applet_DATA = $(applet_in_files:.panel-applet.in=.panel-applet)
-
- $(applet_in_files): $(applet_in_files).in Makefile
- $(AM_V_GEN)sed \
- -e "s|\ LIBEXECDIR\@|$(libexecdir)|" \
- -e "s|\ VERSION\@|$(PACKAGE_VERSION)|" \
- $< > $@
-
- %.panel-applet: %.panel-applet.in $(INTLTOOL_MERGE) $(wildcard $(top_srcdir)/po/*po) ;
$(INTLTOOL_MERGE) $(top_srcdir)/po $< $@ -d -u -c $(top_builddir)/po/.intltool-merge-cache
-
- This rule should probably be moved to intltool as something like:
-
- INTLTOOL_PANEL_APPLET_RULE='%.panel-applet: %.panel-applet.in $(INTLTOOL_MERGE) $(wildcard
$(top_srcdir)/po/*.po) ; $(AM_V_GEN) LC_ALL=C $(INTLTOOL_MERGE) -d -u -c
$(top_builddir)/po/.intltool-merge-cache $(top_srcdir)/po $< [$]@'
-
- D-Bus service file:
-
- servicedir = $(datadir)/dbus-1/services
- service_in_files = org.gnome.panel.applet.FishAppletFactory.service.in
- service_DATA = $(service_in_files:.service.in=.service)
-
- org.gnome.panel.applet.FishAppletFactory.service: $(service_in_files)
- $(AM_V_GEN)sed \
- -e "s|\ LOCATION\@|$(APPLET_LOCATION)|" \
- $< > $@
-
- Add panel-applet .in.in and service file to EXTRA_DIST and $(applet_DATA) $(applet_DATA).in to
CLEANFILES
-
- EXTRA_DIST = \
- GNOME_MixerApplet.panel-applet.in.in \
- $(service_in_files) \
- $(ui_DATA) \
- $(schemas_in_files)
- CLEANFILES = $(applet_DATA) $(applet_DATA).in $(service_DATA) $(schemas_DATA)
- </sect1>
-
-
</chapter>
<chapter>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
