Whitespace-only cleanup, translators please ignore.
This commit is contained in:
Warren Block
parent
21a4722a83
commit
60480178de
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=43952
1 changed files with 334 additions and 337 deletions
|
|
@ -4,45 +4,47 @@
|
||||||
|
|
||||||
$FreeBSD$
|
$FreeBSD$
|
||||||
-->
|
-->
|
||||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="quick-porting">
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||||
|
xml:id="quick-porting">
|
||||||
|
|
||||||
<title>Quick Porting</title>
|
<title>Quick Porting</title>
|
||||||
|
|
||||||
<para>This section tells you how to quickly create a new port. In
|
<para>This section tells you how to quickly create a new port. In
|
||||||
many cases, it is not sufficient, so you will have to read
|
many cases, it is not sufficient, so you will have to read
|
||||||
further on into the document.</para>
|
further on into the document.</para>
|
||||||
|
|
||||||
<para>First, get the original tarball and put it into
|
<para>First, get the original tarball and put it into
|
||||||
<varname>DISTDIR</varname>, which defaults to
|
<varname>DISTDIR</varname>, which defaults to
|
||||||
<filename>/usr/ports/distfiles</filename>.</para>
|
<filename>/usr/ports/distfiles</filename>.</para>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>The following assumes that the software compiled
|
<para>The following assumes that the software compiled
|
||||||
out-of-the-box, i.e., there was absolutely no change required
|
out-of-the-box, i.e., there was absolutely no change required
|
||||||
for the port to work on your &os; box. If you needed to
|
for the port to work on your &os; box. If you needed to
|
||||||
change something, you will have to refer to the next section
|
change something, you will have to refer to the next section
|
||||||
too.</para>
|
too.</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>It is recommended to set the <varname>DEVELOPER</varname>
|
<para>It is recommended to set the <varname>DEVELOPER</varname>
|
||||||
&man.make.1; variable in <filename>/etc/make.conf</filename>
|
&man.make.1; variable in <filename>/etc/make.conf</filename>
|
||||||
before getting into porting.</para>
|
before getting into porting.</para>
|
||||||
|
|
||||||
<screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen>
|
<screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen>
|
||||||
|
|
||||||
<para>This setting enables the <quote>developer mode</quote>
|
<para>This setting enables the <quote>developer mode</quote>
|
||||||
that displays deprecation warnings and activates some further
|
that displays deprecation warnings and activates some further
|
||||||
quality checks on calling <command>make</command>.</para>
|
quality checks on calling <command>make</command>.</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
<sect1 xml:id="porting-makefile">
|
<sect1 xml:id="porting-makefile">
|
||||||
<title>Writing the <filename>Makefile</filename></title>
|
<title>Writing the <filename>Makefile</filename></title>
|
||||||
|
|
||||||
<para>The minimal <filename>Makefile</filename> would look
|
<para>The minimal <filename>Makefile</filename> would look
|
||||||
something like this:</para>
|
something like this:</para>
|
||||||
|
|
||||||
<programlisting># $FreeBSD$
|
<programlisting># $FreeBSD$
|
||||||
|
|
||||||
PORTNAME= oneko
|
PORTNAME= oneko
|
||||||
PORTVERSION= 1.1b
|
PORTVERSION= 1.1b
|
||||||
|
|
@ -54,101 +56,100 @@ COMMENT= Cat chasing a mouse all over the screen
|
||||||
|
|
||||||
.include <bsd.port.mk></programlisting>
|
.include <bsd.port.mk></programlisting>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>In some cases, the <filename>Makefile</filename> of an
|
||||||
|
existing port may contain additional lines in the header,
|
||||||
|
such as the name of the port and the date it was created.
|
||||||
|
This additional information has been declared obsolete, and
|
||||||
|
is being phased out.</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<para>See if you can figure it out. Do not worry about the
|
||||||
|
contents of the <literal>$FreeBSD$</literal>
|
||||||
|
line, it will be filled in automatically by
|
||||||
|
<application>Subversion</application> when the port is
|
||||||
|
imported to our main ports tree. You can find a more detailed
|
||||||
|
example in the
|
||||||
|
<link linkend="porting-samplem">sample Makefile</link>
|
||||||
|
section.</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="porting-desc">
|
||||||
|
<title>Writing the Description Files</title>
|
||||||
|
|
||||||
|
<para>There are two description files that are required for
|
||||||
|
any port, whether they actually package or not. They are
|
||||||
|
<filename>pkg-descr</filename> and
|
||||||
|
<filename>pkg-plist</filename>. Their
|
||||||
|
<filename>pkg-</filename> prefix distinguishes them from other
|
||||||
|
files.</para>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title><filename>pkg-descr</filename></title>
|
||||||
|
|
||||||
|
<para>This is a longer description of the port. One to a few
|
||||||
|
paragraphs concisely explaining what the port does is
|
||||||
|
sufficient.</para>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>In some cases, the <filename>Makefile</filename> of an
|
<para>This is <emphasis>not</emphasis> a manual or an
|
||||||
existing port may contain additional lines in the header,
|
in-depth description on how to use or compile the port!
|
||||||
such as the name of the port and the date it was created.
|
<emphasis>Please be careful if you are copying from the
|
||||||
This additional information has been declared obsolete, and
|
<filename>README</filename> or manpage</emphasis>; too
|
||||||
is being phased out.</para>
|
often they are not a concise description of the port or
|
||||||
|
are in an awkward format (e.g., manpages have justified
|
||||||
|
spacing, which looks particularly bad with monospaced
|
||||||
|
fonts).</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
<para>See if you can figure it out. Do not worry about the
|
<para>A well-written <filename>pkg-descr</filename> describes
|
||||||
contents of the <literal>$FreeBSD$</literal>
|
the port completely enough that users would not have to
|
||||||
line, it will be filled in automatically by
|
consult the documentation or visit the website to understand
|
||||||
<application>Subversion</application> when the port is
|
what the software does, how it can be useful, or what
|
||||||
imported to our main ports tree. You can find a more detailed
|
particularly nice features it has. Mentioning certain
|
||||||
example in the
|
requirements like a graphical toolkit, heavy dependencies,
|
||||||
<link linkend="porting-samplem">sample Makefile</link>
|
runtime environment, or implementation languages help users
|
||||||
section.</para>
|
decide whether this port will work for them.</para>
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 xml:id="porting-desc">
|
<para>Include a URL to the official WWW homepage. Prepend
|
||||||
<title>Writing the Description Files</title>
|
<emphasis>one</emphasis> of the websites (pick the most
|
||||||
|
common one) with <literal>WWW:</literal> (followed by single
|
||||||
|
space) so that automated tools will work correctly. If the
|
||||||
|
URI is the root of the website or directory, it should be
|
||||||
|
terminated with a slash.</para>
|
||||||
|
|
||||||
<para>There are two description files that are required for
|
<note>
|
||||||
any port, whether they actually package or not. They are
|
<para>If the listed webpage for a port is not available, try
|
||||||
<filename>pkg-descr</filename> and
|
to search the Internet first to see if the official site
|
||||||
<filename>pkg-plist</filename>. Their
|
moved, was renamed, or is hosted elsewhere.</para>
|
||||||
<filename>pkg-</filename> prefix distinguishes them from other
|
</note>
|
||||||
files.</para>
|
|
||||||
|
|
||||||
<sect2>
|
<para>The following example shows how your
|
||||||
<title><filename>pkg-descr</filename></title>
|
<filename>pkg-descr</filename> should look:</para>
|
||||||
|
|
||||||
<para>This is a longer description of the port. One to a few
|
<programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
|
||||||
paragraphs concisely explaining what the port does is
|
|
||||||
sufficient.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>This is <emphasis>not</emphasis> a manual or an
|
|
||||||
in-depth description on how to use or compile the port!
|
|
||||||
<emphasis>Please be careful if you are copying from the
|
|
||||||
<filename>README</filename> or manpage</emphasis>; too
|
|
||||||
often they are not a concise description of the port or
|
|
||||||
are in an awkward format (e.g., manpages have justified
|
|
||||||
spacing, which looks particularly bad with monospaced
|
|
||||||
fonts).</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>A well-written <filename>pkg-descr</filename> describes
|
|
||||||
the port completely enough that users would not have to
|
|
||||||
consult the documentation or visit the website to understand
|
|
||||||
what the software does, how it can be useful, or what
|
|
||||||
particularly nice features it has. Mentioning certain
|
|
||||||
requirements like a graphical toolkit, heavy dependencies,
|
|
||||||
runtime environment, or implementation languages help users
|
|
||||||
decide whether this port will work for them.</para>
|
|
||||||
|
|
||||||
<para>Include a URL to the official WWW homepage. Prepend
|
|
||||||
<emphasis>one</emphasis> of the websites (pick the most
|
|
||||||
common one) with <literal>WWW:</literal> (followed by single
|
|
||||||
space) so that automated tools will work correctly. If the
|
|
||||||
URI is the root of the website or directory, it should be
|
|
||||||
terminated with a slash.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>If the listed webpage for a port is not available, try
|
|
||||||
to search the Internet first to see if the official site
|
|
||||||
moved, was renamed, or is hosted elsewhere.</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>The following example shows how your
|
|
||||||
<filename>pkg-descr</filename> should look:</para>
|
|
||||||
|
|
||||||
<programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
|
|
||||||
the screen.
|
the screen.
|
||||||
:
|
:
|
||||||
(etc.)
|
(etc.)
|
||||||
|
|
||||||
WWW: http://www.oneko.org/</programlisting>
|
WWW: http://www.oneko.org/</programlisting>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title><filename>pkg-plist</filename></title>
|
<title><filename>pkg-plist</filename></title>
|
||||||
|
|
||||||
<para>This file lists all the files installed by the port. It
|
<para>This file lists all the files installed by the port. It
|
||||||
is also called the <quote>packing list</quote> because the
|
is also called the <quote>packing list</quote> because the
|
||||||
package is generated by packing the files listed here. The
|
package is generated by packing the files listed here. The
|
||||||
pathnames are relative to the installation prefix (usually
|
pathnames are relative to the installation prefix (usually
|
||||||
<filename>/usr/local</filename>.
|
<filename>/usr/local</filename>. If the port creates
|
||||||
If the
|
directories during installation, make sure to add
|
||||||
port creates directories during installation, make sure to
|
<literal>@dirrm</literal> lines to remove them when the
|
||||||
add <literal>@dirrm</literal> lines to remove them when the
|
package is deleted.</para>
|
||||||
package is deleted.</para>
|
|
||||||
|
|
||||||
<para>Here is a small example:</para>
|
<para>Here is a small example:</para>
|
||||||
|
|
||||||
<programlisting>bin/oneko
|
<programlisting>bin/oneko
|
||||||
man/man1/oneko.1.gz
|
man/man1/oneko.1.gz
|
||||||
lib/X11/app-defaults/Oneko
|
lib/X11/app-defaults/Oneko
|
||||||
lib/X11/oneko/cat1.xpm
|
lib/X11/oneko/cat1.xpm
|
||||||
|
|
@ -156,34 +157,34 @@ lib/X11/oneko/cat2.xpm
|
||||||
lib/X11/oneko/mouse.xpm
|
lib/X11/oneko/mouse.xpm
|
||||||
@dirrm lib/X11/oneko</programlisting>
|
@dirrm lib/X11/oneko</programlisting>
|
||||||
|
|
||||||
<para>Refer to the &man.pkg-create.8; manual page for details
|
<para>Refer to the &man.pkg-create.8; manual page for details
|
||||||
on the packing list.</para>
|
on the packing list.</para>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>It is recommended that you keep all the filenames in
|
<para>It is recommended that you keep all the filenames in
|
||||||
this file sorted alphabetically. It will make verifying
|
this file sorted alphabetically. It will make verifying
|
||||||
the changes when you upgrade the port much easier.</para>
|
the changes when you upgrade the port much easier.</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>Creating a packing list manually can be a very tedious
|
<para>Creating a packing list manually can be a very tedious
|
||||||
task. If the port installs a large numbers of files,
|
task. If the port installs a large numbers of files,
|
||||||
<link linkend="plist-autoplist">creating the packing list
|
<link linkend="plist-autoplist">creating the packing list
|
||||||
automatically</link> might save time.</para>
|
automatically</link> might save time.</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
<para>There is only one case when
|
<para>There is only one case when
|
||||||
<filename>pkg-plist</filename> can be omitted from a port.
|
<filename>pkg-plist</filename> can be omitted from a port.
|
||||||
If the port installs just a handful of files, and perhaps
|
If the port installs just a handful of files, and perhaps
|
||||||
directories, the files and directories may be listed in the
|
directories, the files and directories may be listed in the
|
||||||
variables <varname>PLIST_FILES</varname> and
|
variables <varname>PLIST_FILES</varname> and
|
||||||
<varname>PLIST_DIRS</varname>, respectively, within the
|
<varname>PLIST_DIRS</varname>, respectively, within the
|
||||||
port's <filename>Makefile</filename>. For instance, we
|
port's <filename>Makefile</filename>. For instance, we
|
||||||
could get along without <filename>pkg-plist</filename> in
|
could get along without <filename>pkg-plist</filename> in
|
||||||
the above <filename>oneko</filename> port by adding the
|
the above <filename>oneko</filename> port by adding the
|
||||||
following lines to the <filename>Makefile</filename>:</para>
|
following lines to the <filename>Makefile</filename>:</para>
|
||||||
|
|
||||||
<programlisting>PLIST_FILES= bin/oneko \
|
<programlisting>PLIST_FILES= bin/oneko \
|
||||||
man/man1/oneko.1.gz \
|
man/man1/oneko.1.gz \
|
||||||
lib/X11/app-defaults/Oneko \
|
lib/X11/app-defaults/Oneko \
|
||||||
lib/X11/oneko/cat1.xpm \
|
lib/X11/oneko/cat1.xpm \
|
||||||
|
|
@ -191,215 +192,211 @@ lib/X11/oneko/mouse.xpm
|
||||||
lib/X11/oneko/mouse.xpm
|
lib/X11/oneko/mouse.xpm
|
||||||
PLIST_DIRS= lib/X11/oneko</programlisting>
|
PLIST_DIRS= lib/X11/oneko</programlisting>
|
||||||
|
|
||||||
<para>Of course, <varname>PLIST_DIRS</varname> should be left
|
<para>Of course, <varname>PLIST_DIRS</varname> should be left
|
||||||
unset if a port installs no directories of its own.</para>
|
unset if a port installs no directories of its own.</para>
|
||||||
|
|
||||||
<note>
|
|
||||||
|
|
||||||
<para>Several ports can share a common directory. In that
|
|
||||||
case, <varname>PLIST_DIRS</varname> should be replaced by
|
|
||||||
<varname>PLIST_DIRSTRY</varname> so that the directory is
|
|
||||||
removed only if empty, otherwise it is silently ignored.
|
|
||||||
<varname>PLIST_DIRS</varname> and
|
|
||||||
<varname>PLIST_DIRSTRY</varname> are equivalent to using
|
|
||||||
<literal>@dirrm</literal> and <literal>@dirrmtry</literal>
|
|
||||||
in <filename>pkg-plist</filename>, as described in
|
|
||||||
<xref linkend="plist-dir-cleaning"/>.</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>The price for this way of listing port's files and
|
|
||||||
directories is that you cannot use command sequences
|
|
||||||
described in &man.pkg-create.8;. Therefore, it is suitable
|
|
||||||
only for simple ports and makes them even simpler. At the
|
|
||||||
same time, it has the advantage of reducing the number of
|
|
||||||
files in the ports collection. Please consider using this
|
|
||||||
technique before you resort to
|
|
||||||
<filename>pkg-plist</filename>.</para>
|
|
||||||
|
|
||||||
<para>Later we will see how <filename>pkg-plist</filename>
|
|
||||||
and <varname>PLIST_FILES</varname> can be used to fulfill
|
|
||||||
<link linkend="plist">more sophisticated
|
|
||||||
tasks</link>.</para>
|
|
||||||
</sect2>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 xml:id="porting-checksum">
|
|
||||||
<title>Creating the Checksum File</title>
|
|
||||||
|
|
||||||
<para>Just type <command>make makesum</command>. The ports make
|
|
||||||
rules will automatically generate the file
|
|
||||||
<filename>distinfo</filename>.</para>
|
|
||||||
|
|
||||||
<para>If a file fetched has its checksum changed regularly and
|
|
||||||
you are certain the source is trusted (i.e., it comes from
|
|
||||||
manufacturer CDs or documentation generated daily), you should
|
|
||||||
specify these files in the <varname>IGNOREFILES</varname>
|
|
||||||
variable. Then the checksum is not calculated for that file
|
|
||||||
when you run <command>make makesum</command>, but set to
|
|
||||||
<literal>IGNORE</literal>.</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 xml:id="porting-testing">
|
|
||||||
<title>Testing the Port</title>
|
|
||||||
|
|
||||||
<para>You should make sure that the port rules do exactly what
|
|
||||||
you want them to do, including packaging up the port. These
|
|
||||||
are the important points you need to verify.</para>
|
|
||||||
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para><filename>pkg-plist</filename> does not contain
|
|
||||||
anything not installed by the port.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para><filename>pkg-plist</filename> contains everything
|
|
||||||
that is installed by the port.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>The port can be installed using the
|
|
||||||
<buildtarget>install</buildtarget> target. This verifies
|
|
||||||
that the install script works correctly.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>The port can be deinstalled properly using the
|
|
||||||
<buildtarget>deinstall</buildtarget> target. This
|
|
||||||
verifies that the deinstall script works correctly.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>Make sure that <command>make package</command> can be
|
|
||||||
run as a normal user (that is, not as
|
|
||||||
<systemitem class="username">root</systemitem>). If that
|
|
||||||
fails, <literal>NEED_ROOT=yes</literal> must be added to
|
|
||||||
the port <filename>Makefile</filename>.</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<procedure>
|
|
||||||
<title>Recommended Test Ordering</title>
|
|
||||||
|
|
||||||
<step>
|
|
||||||
<para><command>make stage</command></para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step>
|
|
||||||
<para><command>make check-orphans</command></para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step>
|
|
||||||
<para><command>make package</command></para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step>
|
|
||||||
<para><command>make install</command></para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step>
|
|
||||||
<para><command>make deinstall</command></para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step>
|
|
||||||
<para><command>pkg add package-filename</command></para>
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step>
|
|
||||||
<para><command>make package</command> (as user)</para>
|
|
||||||
</step>
|
|
||||||
</procedure>
|
|
||||||
|
|
||||||
<para>Make certain no warnings are shown in any of
|
|
||||||
the stages.</para>
|
|
||||||
|
|
||||||
<para>Thorough automated testing can be done with
|
|
||||||
<package role="port">ports-mgmt/tinderbox</package> or
|
|
||||||
<package role="port">ports-mgmt/poudriere</package> from the
|
|
||||||
Ports Collection. These applications maintain
|
|
||||||
<literal>jails</literal> where all of the steps shown above
|
|
||||||
can be tested without affecting the state of the host
|
|
||||||
system.</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 xml:id="porting-portlint">
|
|
||||||
<title>Checking Your Port with
|
|
||||||
<command>portlint</command></title>
|
|
||||||
|
|
||||||
<para>Please use <command>portlint</command> to see if your port
|
|
||||||
conforms to our guidelines. The
|
|
||||||
<package role="port">ports-mgmt/portlint</package>
|
|
||||||
program is part of the ports collection. In particular, you
|
|
||||||
may want to check if the
|
|
||||||
<link linkend="porting-samplem">Makefile</link> is in the
|
|
||||||
right shape and the
|
|
||||||
<link linkend="porting-pkgname">package</link> is named
|
|
||||||
appropriately.</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 xml:id="porting-submitting">
|
|
||||||
<title>Submitting the New Port</title>
|
|
||||||
|
|
||||||
<para>Before submitting the new port, read
|
|
||||||
the <link linkend="porting-dads">DOs and DON'Ts</link>
|
|
||||||
section.</para>
|
|
||||||
|
|
||||||
<para>Once happy with your port, the only thing remaining is to
|
|
||||||
put it in the main &os; ports tree and make everybody else
|
|
||||||
happy about it too. We do not need the
|
|
||||||
<filename>work</filename> directory or the
|
|
||||||
<filename>pkgname.tgz</filename> package, so delete them
|
|
||||||
now.</para>
|
|
||||||
|
|
||||||
<para>Next, build the &man.shar.1; file. Assuming the port is
|
|
||||||
called <literal>oneko</literal>, <command>cd</command> to the
|
|
||||||
directory above where the <literal>oneko</literal> directory
|
|
||||||
is located, and then type:
|
|
||||||
<command>shar `find oneko` > oneko.shar</command></para>
|
|
||||||
|
|
||||||
<para>Include <filename>oneko.shar</filename> in a bug
|
|
||||||
report and send it with &man.send-pr.1;. See
|
|
||||||
<link
|
|
||||||
xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
|
|
||||||
Reports and General Commentary</link> for more information
|
|
||||||
about &man.send-pr.1;.</para>
|
|
||||||
|
|
||||||
<para>Classify the bug report as Category
|
|
||||||
<literal>ports</literal> and Class
|
|
||||||
<literal>change-request</literal>. Do
|
|
||||||
<emphasis>not</emphasis> mark the report
|
|
||||||
<literal>confidential</literal>! Add a short description of
|
|
||||||
the program to the Description field of the PR (perhaps a
|
|
||||||
short version of the <varname>COMMENT</varname>), and add the
|
|
||||||
<filename>.shar</filename> file to the Fix field.</para>
|
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>Giving a good description in the synopsis of the problem
|
<para>Several ports can share a common directory. In that
|
||||||
report makes the work of port committers a lot easier. We
|
case, <varname>PLIST_DIRS</varname> should be replaced by
|
||||||
prefer something like <quote>New port:
|
<varname>PLIST_DIRSTRY</varname> so that the directory is
|
||||||
<category>/<portname> <short description of
|
removed only if empty, otherwise it is silently ignored.
|
||||||
the port></quote> for new ports. Using this
|
<varname>PLIST_DIRS</varname> and
|
||||||
scheme makes it easier and faster to begin the work of
|
<varname>PLIST_DIRSTRY</varname> are equivalent to using
|
||||||
committing the new port.</para>
|
<literal>@dirrm</literal> and <literal>@dirrmtry</literal>
|
||||||
|
in <filename>pkg-plist</filename>, as described in
|
||||||
|
<xref linkend="plist-dir-cleaning"/>.</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
<para>One more time, <emphasis>do not include the original
|
<para>The price for this way of listing port's files and
|
||||||
source distfile, the <filename>work</filename> directory, or
|
directories is that you cannot use command sequences
|
||||||
the package you built with
|
described in &man.pkg-create.8;. Therefore, it is suitable
|
||||||
<command>make package</command></emphasis>; and, do use
|
only for simple ports and makes them even simpler. At the
|
||||||
&man.shar.1; for new ports, not &man.diff.1;.</para>
|
same time, it has the advantage of reducing the number of
|
||||||
|
files in the ports collection. Please consider using this
|
||||||
|
technique before you resort to
|
||||||
|
<filename>pkg-plist</filename>.</para>
|
||||||
|
|
||||||
<para>After submitting the port, please be patient. The time
|
<para>Later we will see how <filename>pkg-plist</filename>
|
||||||
needed to include a new port in &os; can vary from a few days
|
and <varname>PLIST_FILES</varname> can be used to fulfill
|
||||||
to a few months. The list of pending port
|
<link linkend="plist">more sophisticated
|
||||||
<acronym>PR</acronym>s can be viewed at <link
|
tasks</link>.</para>
|
||||||
xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"></link>.</para>
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
<para>After looking at the new port, we will reply if necessary,
|
<sect1 xml:id="porting-checksum">
|
||||||
and put it in the tree. Your name will also be added to the
|
<title>Creating the Checksum File</title>
|
||||||
list of <link
|
|
||||||
xlink:href="&url.articles.contributors;/contrib-additional.html">Additional
|
|
||||||
&os; Contributors</link> and other files.</para>
|
|
||||||
</sect1>
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
|
<para>Just type <command>make makesum</command>. The ports make
|
||||||
|
rules will automatically generate the file
|
||||||
|
<filename>distinfo</filename>.</para>
|
||||||
|
|
||||||
|
<para>If a file fetched has its checksum changed regularly and
|
||||||
|
you are certain the source is trusted (i.e., it comes from
|
||||||
|
manufacturer CDs or documentation generated daily), you should
|
||||||
|
specify these files in the <varname>IGNOREFILES</varname>
|
||||||
|
variable. Then the checksum is not calculated for that file
|
||||||
|
when you run <command>make makesum</command>, but set to
|
||||||
|
<literal>IGNORE</literal>.</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="porting-testing">
|
||||||
|
<title>Testing the Port</title>
|
||||||
|
|
||||||
|
<para>You should make sure that the port rules do exactly what
|
||||||
|
you want them to do, including packaging up the port. These
|
||||||
|
are the important points you need to verify.</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para><filename>pkg-plist</filename> does not contain
|
||||||
|
anything not installed by the port.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para><filename>pkg-plist</filename> contains everything
|
||||||
|
that is installed by the port.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>The port can be installed using the
|
||||||
|
<buildtarget>install</buildtarget> target. This verifies
|
||||||
|
that the install script works correctly.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>The port can be deinstalled properly using the
|
||||||
|
<buildtarget>deinstall</buildtarget> target. This
|
||||||
|
verifies that the deinstall script works correctly.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Make sure that <command>make package</command> can be
|
||||||
|
run as a normal user (that is, not as
|
||||||
|
<systemitem class="username">root</systemitem>). If that
|
||||||
|
fails, <literal>NEED_ROOT=yes</literal> must be added to
|
||||||
|
the port <filename>Makefile</filename>.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<procedure>
|
||||||
|
<title>Recommended Test Ordering</title>
|
||||||
|
|
||||||
|
<step>
|
||||||
|
<para><command>make stage</command></para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step>
|
||||||
|
<para><command>make check-orphans</command></para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step>
|
||||||
|
<para><command>make package</command></para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step>
|
||||||
|
<para><command>make install</command></para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step>
|
||||||
|
<para><command>make deinstall</command></para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step>
|
||||||
|
<para><command>pkg add package-filename</command></para>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step>
|
||||||
|
<para><command>make package</command> (as user)</para>
|
||||||
|
</step>
|
||||||
|
</procedure>
|
||||||
|
|
||||||
|
<para>Make certain no warnings are shown in any of
|
||||||
|
the stages.</para>
|
||||||
|
|
||||||
|
<para>Thorough automated testing can be done with
|
||||||
|
<package role="port">ports-mgmt/tinderbox</package> or
|
||||||
|
<package role="port">ports-mgmt/poudriere</package> from the
|
||||||
|
Ports Collection. These applications maintain
|
||||||
|
<literal>jails</literal> where all of the steps shown above
|
||||||
|
can be tested without affecting the state of the host
|
||||||
|
system.</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="porting-portlint">
|
||||||
|
<title>Checking Your Port with
|
||||||
|
<command>portlint</command></title>
|
||||||
|
|
||||||
|
<para>Please use <command>portlint</command> to see if your port
|
||||||
|
conforms to our guidelines. The
|
||||||
|
<package role="port">ports-mgmt/portlint</package>
|
||||||
|
program is part of the ports collection. In particular, you
|
||||||
|
may want to check if the
|
||||||
|
<link linkend="porting-samplem">Makefile</link> is in the
|
||||||
|
right shape and the
|
||||||
|
<link linkend="porting-pkgname">package</link> is named
|
||||||
|
appropriately.</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="porting-submitting">
|
||||||
|
<title>Submitting the New Port</title>
|
||||||
|
|
||||||
|
<para>Before submitting the new port, read the
|
||||||
|
<link linkend="porting-dads">DOs and DON'Ts</link>
|
||||||
|
section.</para>
|
||||||
|
|
||||||
|
<para>Once happy with your port, the only thing remaining is to
|
||||||
|
put it in the main &os; ports tree and make everybody else
|
||||||
|
happy about it too. We do not need the
|
||||||
|
<filename>work</filename> directory or the
|
||||||
|
<filename>pkgname.tgz</filename> package, so delete them
|
||||||
|
now.</para>
|
||||||
|
|
||||||
|
<para>Next, build the &man.shar.1; file. Assuming the port is
|
||||||
|
called <literal>oneko</literal>, <command>cd</command> to the
|
||||||
|
directory above where the <literal>oneko</literal> directory
|
||||||
|
is located, and then type:
|
||||||
|
<command>shar `find oneko` > oneko.shar</command></para>
|
||||||
|
|
||||||
|
<para>Include <filename>oneko.shar</filename> in a bug
|
||||||
|
report and send it with &man.send-pr.1;. See <link
|
||||||
|
xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
|
||||||
|
Reports and General Commentary</link> for more information
|
||||||
|
about &man.send-pr.1;.</para>
|
||||||
|
|
||||||
|
<para>Classify the bug report as Category
|
||||||
|
<literal>ports</literal> and Class
|
||||||
|
<literal>change-request</literal>. Do <emphasis>not</emphasis>
|
||||||
|
mark the report <literal>confidential</literal>! Add a short
|
||||||
|
description of the program to the Description field of the PR
|
||||||
|
(perhaps a short version of the <varname>COMMENT</varname>), and
|
||||||
|
add the <filename>.shar</filename> file to the Fix field.</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>Giving a good description in the synopsis of the problem
|
||||||
|
report makes the work of port committers a lot easier. We
|
||||||
|
prefer something like <quote>New port:
|
||||||
|
<category>/<portname> <short description of
|
||||||
|
the port></quote> for new ports. Using this
|
||||||
|
scheme makes it easier and faster to begin the work of
|
||||||
|
committing the new port.</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<para>One more time, <emphasis>do not include the original
|
||||||
|
source distfile, the <filename>work</filename> directory, or
|
||||||
|
the package you built with
|
||||||
|
<command>make package</command></emphasis>; and, do use
|
||||||
|
&man.shar.1; for new ports, not &man.diff.1;.</para>
|
||||||
|
|
||||||
|
<para>After submitting the port, please be patient. The time
|
||||||
|
needed to include a new port in &os; can vary from a few days
|
||||||
|
to a few months. The list of pending port
|
||||||
|
<acronym>PR</acronym>s can be viewed at <link
|
||||||
|
xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"></link>.</para>
|
||||||
|
|
||||||
|
<para>After looking at the new port, we will reply if necessary,
|
||||||
|
and put it in the tree. Your name will also be added to the
|
||||||
|
list of <link
|
||||||
|
xlink:href="&url.articles.contributors;/contrib-additional.html">Additional
|
||||||
|
&os; Contributors</link> and other files.</para>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue