Rewrite the PREFIX and DESTDIR section for clarity.
Expand the DESKTOP_ENTRIES section, including clarifications and instructions on installing predefined .desktop files. Reviewed by: eadler@, Benjamin Kaduk (earlier version of PREFIX) Reviewed by: eadler@ (earlier version of DESKTOP_ENTRIES) Approved by: gjb (mentor)
This commit is contained in:
Warren Block
parent
75e065b0fa
commit
e1af6d7f3a
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38172
1 changed files with 98 additions and 55 deletions
|
|
@ -5824,15 +5824,48 @@ USE_XORG= x11 xpm</programlisting>
|
|||
<sect2 id="desktop-entries">
|
||||
<title>Desktop entries</title>
|
||||
|
||||
<para>Desktop Entries (<ulink
|
||||
url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Freedesktop
|
||||
standard</ulink>) can be easily created in your port using
|
||||
<makevar>DESKTOP_ENTRIES</makevar> variable. These entries
|
||||
do show up in application menus of compliant desktop
|
||||
environments like GNOME or KDE. The
|
||||
<filename>.desktop</filename> file will be created,
|
||||
installed, and added to the <filename>pkg-plist</filename>
|
||||
automatically. Syntax is:</para>
|
||||
<para>Desktop entries (<ulink
|
||||
url="http://standards.freedesktop.org/desktop-entry-spec/latest/">a
|
||||
Freedesktop standard</ulink>) provide a way to
|
||||
automatically adjust desktop features when a new program is
|
||||
installed, without requiring user intervention. For
|
||||
example, newly-installed programs automatically appear in
|
||||
the application menus of compatible desktop environments.
|
||||
Desktop entries originated in the
|
||||
<application>GNOME</application> desktop environment, but
|
||||
are now a standard and also work with
|
||||
<application>KDE</application> and
|
||||
<application>Xfce</application>. This bit of automation
|
||||
provides a real benefit to the user, and desktop entries are
|
||||
encouraged for applications which can be used in a desktop
|
||||
environment.</para>
|
||||
|
||||
<sect3>
|
||||
<title>Using Predefined <filename>.desktop</filename>
|
||||
Files</title>
|
||||
|
||||
<para>Ports that include predefined
|
||||
<filename>*.desktop</filename> files should
|
||||
include those files in <filename>pkg-plist</filename>
|
||||
and install them in the
|
||||
<filename><makevar>$LOCALBASE</makevar>/share/applications</filename>
|
||||
directory. The <link
|
||||
linkend="INSTALL-MACROS"><makevar>INSTALL_DATA</makevar>
|
||||
macro</link> is useful for installing these
|
||||
files.</para>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="desktop-entries-macro">
|
||||
<title>Creating Desktop Entries with the
|
||||
<makevar>DESKTOP_ENTRIES</makevar> Macro</title>
|
||||
|
||||
<para>Desktop entries can be easily created for applications
|
||||
by using the <makevar>DESKTOP_ENTRIES</makevar> variable.
|
||||
A file named
|
||||
<filename><replaceable>name</replaceable>.desktop</filename>
|
||||
will be created, installed, and added to the
|
||||
<filename>pkg-plist</filename> automatically. Syntax
|
||||
is:</para>
|
||||
|
||||
<programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting>
|
||||
|
||||
|
|
@ -5840,8 +5873,18 @@ USE_XORG= x11 xpm</programlisting>
|
|||
<ulink
|
||||
url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop
|
||||
website</ulink>. <makevar>StartupNotify</makevar>
|
||||
indicates whether the application will clear the status in
|
||||
a startup notification-aware environment.</para>
|
||||
indicates whether the application is compatible with
|
||||
<emphasis>startup notifications</emphasis>. These are
|
||||
typically a graphic indicator like a clock that appear at
|
||||
the mouse pointer, menu, or panel to give the user an
|
||||
indication when a program is loading. A program that is
|
||||
compatible with startup notifications clears the indicator
|
||||
after it has started. Programs that are not compatible with
|
||||
startup notifications would never clear the indicator
|
||||
(potentially confusing and infuriating the user), and should
|
||||
have <makevar>StartupNotify</makevar> set to
|
||||
<literal>false</literal> so the indicator is not shown at
|
||||
all.</para>
|
||||
|
||||
<para>Example:</para>
|
||||
|
||||
|
|
@ -5849,6 +5892,8 @@ USE_XORG= x11 xpm</programlisting>
|
|||
"${DATADIR}/xtra/graf/tome-128.png" \
|
||||
"tome -v -g" "Application;Game;RolePlaying;" \
|
||||
false</programlisting>
|
||||
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
|
@ -9811,49 +9856,47 @@ as .putsy.conf and edit it.</programlisting>
|
|||
<title><makevar>PREFIX</makevar> and
|
||||
<makevar>DESTDIR</makevar></title>
|
||||
|
||||
<para><makevar>PREFIX</makevar> determines the location where
|
||||
the port will install. It is usually
|
||||
<filename>/usr/local</filename> or <filename>/opt</filename>,
|
||||
but can be set to a custom path. Your port must respect this
|
||||
variable.</para>
|
||||
<para><makevar>PREFIX</makevar> determines where the port will
|
||||
be installed. It defaults to <filename>/usr/local</filename>,
|
||||
but can be set by the user to a custom path like
|
||||
<filename>/opt</filename>. Your port must
|
||||
respect the value of this variable.</para>
|
||||
|
||||
<para><makevar>DESTDIR</makevar>, if set by user, determines the
|
||||
complete alternative environment, usually a jail, or an
|
||||
installed system mounted elsewhere than
|
||||
<para><makevar>DESTDIR</makevar>, if set by the user, determines the
|
||||
complete alternative environment, usually a jail or an
|
||||
installed system mounted somewhere other than
|
||||
<filename>/</filename>. A port will actually install into
|
||||
<makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar>, and
|
||||
<filename><makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar></filename>, and
|
||||
register with the package database in
|
||||
<makevar>DESTDIR</makevar>/var/db/pkg. As
|
||||
<filename><makevar>DESTDIR</makevar>/var/db/pkg</filename>. As
|
||||
<makevar>DESTDIR</makevar> is handled automatically by the
|
||||
ports infrastructure via calling &man.chroot.8;, you do not
|
||||
ports infrastructure with &man.chroot.8;, you do not
|
||||
need any modifications or any extra care to write
|
||||
<makevar>DESTDIR</makevar>-compliant ports.</para>
|
||||
|
||||
<para>The value of <makevar>PREFIX</makevar> will be set
|
||||
to <makevar>LOCALBASE</makevar> (default
|
||||
to <makevar>LOCALBASE</makevar> (defaulting to
|
||||
<filename>/usr/local</filename>). If
|
||||
<makevar>USE_LINUX_PREFIX</makevar> is set,
|
||||
<makevar>PREFIX</makevar> will be <makevar>LINUXBASE</makevar>
|
||||
(default <filename>/compat/linux</filename>).</para>
|
||||
(defaulting to <filename>/compat/linux</filename>).</para>
|
||||
|
||||
<para>Avoiding the hard-coding of
|
||||
<filename>/usr/local</filename> or
|
||||
<filename>/usr/X11R6</filename> anywhere in the source will
|
||||
make the port much more flexible and able to cater to the
|
||||
needs of other sites. For X ports that use
|
||||
<command>imake</command>, this is automatic; otherwise, this
|
||||
can often be done by simply replacing the occurrences of
|
||||
<filename>/usr/local</filename> (or
|
||||
<filename>/usr/X11R6</filename> for X ports that do not use
|
||||
imake) in the various <filename>Makefile</filename>s in the
|
||||
port to read <makevar>${PREFIX}</makevar>, as this variable is
|
||||
<para>Avoiding hard-coded <filename>/usr/local</filename>
|
||||
paths in the source
|
||||
makes the port much more flexible and able to cater to the
|
||||
needs of other sites.
|
||||
Often, this can be accomplished
|
||||
by simply replacing occurrences of
|
||||
<filename>/usr/local</filename>
|
||||
in the port's various <filename>Makefile</filename>s
|
||||
with <literal>${PREFIX}</literal>. This variable is
|
||||
automatically passed down to every stage of the build and
|
||||
install processes.</para>
|
||||
|
||||
<para>Make sure your application is not installing things in
|
||||
<filename>/usr/local</filename> instead of
|
||||
<makevar>PREFIX</makevar>. A quick test for this is to do this
|
||||
is:</para>
|
||||
<makevar>PREFIX</makevar>. A quick test for such hard-coded
|
||||
paths is:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen>
|
||||
|
||||
|
|
@ -9861,31 +9904,31 @@ as .putsy.conf and edit it.</programlisting>
|
|||
<makevar>PREFIX</makevar>, the package creation process will
|
||||
complain that it cannot find the files.</para>
|
||||
|
||||
<!-- XXX This paragraph is confusing. -->
|
||||
<para>This does not test for the existence of internal
|
||||
references, or correct use of <makevar>LOCALBASE</makevar> for
|
||||
references to files from other ports. Testing the
|
||||
installation in <filename>/var/tmp/`make -V
|
||||
PORTNAME`</filename> to do that while you have it installed
|
||||
would do that.</para>
|
||||
<para>This test will not find hard-coded paths inside the
|
||||
port's files, nor will it verify that
|
||||
<makevar>LOCALBASE</makevar> is being used to correctly refer
|
||||
to files from other ports. The temporarily-installed port in
|
||||
<filename>/var/tmp/`make -V PORTNAME`</filename> should be
|
||||
tested for proper operation to make sure there
|
||||
are no problems with paths.</para>
|
||||
|
||||
<para>The variable <makevar>PREFIX</makevar> can be reassigned
|
||||
in your <filename>Makefile</filename> or in the user's
|
||||
environment. However, it is strongly discouraged for
|
||||
individual ports to set this variable explicitly in the
|
||||
<filename>Makefile</filename>s.</para>
|
||||
<para><makevar>PREFIX</makevar> should not be set explicitly
|
||||
in a port's <filename>Makefile</filename>. Users installing
|
||||
the port may have set <makevar>PREFIX</makevar> to a custom
|
||||
location, and the port should respect that setting.</para>
|
||||
|
||||
<para>Also, refer to programs/files from other ports with the
|
||||
<para>Refer to programs and files from other ports with the
|
||||
variables mentioned above, not explicit pathnames. For
|
||||
instance, if your port requires a macro
|
||||
<literal>PAGER</literal> to be the full pathname of
|
||||
<command>less</command>, use the compiler flag:</para>
|
||||
<literal>PAGER</literal> to have the full pathname of
|
||||
<command>less</command>, do not use a literal path of
|
||||
<filename>/usr/local/bin/less</filename>. Instead, use
|
||||
<literal>${LOCALBASE}</literal>:</para>
|
||||
|
||||
<programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
|
||||
|
||||
<para>instead of
|
||||
<literal>-DPAGER=\"/usr/local/bin/less\"</literal>. This way
|
||||
it will have a better chance of working if the system
|
||||
<para>The path
|
||||
with <makevar>LOCALBASE</makevar> is more likely to still work if the system
|
||||
administrator has moved the whole
|
||||
<filename>/usr/local</filename> tree somewhere else.</para>
|
||||
</sect1>
|
||||
|
|
|
|||
Loading…
Reference in a new issue