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$
|
||||
-->
|
||||
<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
|
||||
many cases, it is not sufficient, so you will have to read
|
||||
further on into the document.</para>
|
||||
<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
|
||||
further on into the document.</para>
|
||||
|
||||
<para>First, get the original tarball and put it into
|
||||
<varname>DISTDIR</varname>, which defaults to
|
||||
<filename>/usr/ports/distfiles</filename>.</para>
|
||||
<para>First, get the original tarball and put it into
|
||||
<varname>DISTDIR</varname>, which defaults to
|
||||
<filename>/usr/ports/distfiles</filename>.</para>
|
||||
|
||||
<note>
|
||||
<para>The following assumes that the software compiled
|
||||
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
|
||||
change something, you will have to refer to the next section
|
||||
too.</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>The following assumes that the software compiled
|
||||
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
|
||||
change something, you will have to refer to the next section
|
||||
too.</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>It is recommended to set the <varname>DEVELOPER</varname>
|
||||
&man.make.1; variable in <filename>/etc/make.conf</filename>
|
||||
before getting into porting.</para>
|
||||
<note>
|
||||
<para>It is recommended to set the <varname>DEVELOPER</varname>
|
||||
&man.make.1; variable in <filename>/etc/make.conf</filename>
|
||||
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>
|
||||
that displays deprecation warnings and activates some further
|
||||
quality checks on calling <command>make</command>.</para>
|
||||
</note>
|
||||
<para>This setting enables the <quote>developer mode</quote>
|
||||
that displays deprecation warnings and activates some further
|
||||
quality checks on calling <command>make</command>.</para>
|
||||
</note>
|
||||
|
||||
<sect1 xml:id="porting-makefile">
|
||||
<title>Writing the <filename>Makefile</filename></title>
|
||||
<sect1 xml:id="porting-makefile">
|
||||
<title>Writing the <filename>Makefile</filename></title>
|
||||
|
||||
<para>The minimal <filename>Makefile</filename> would look
|
||||
something like this:</para>
|
||||
<para>The minimal <filename>Makefile</filename> would look
|
||||
something like this:</para>
|
||||
|
||||
<programlisting># $FreeBSD$
|
||||
<programlisting># $FreeBSD$
|
||||
|
||||
PORTNAME= oneko
|
||||
PORTVERSION= 1.1b
|
||||
|
|
@ -54,101 +56,100 @@ COMMENT= Cat chasing a mouse all over the screen
|
|||
|
||||
.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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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>
|
||||
|
||||
<sect1 xml:id="porting-desc">
|
||||
<title>Writing the Description Files</title>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<sect2>
|
||||
<title><filename>pkg-descr</filename></title>
|
||||
<para>The following example shows how your
|
||||
<filename>pkg-descr</filename> should look:</para>
|
||||
|
||||
<para>This is a longer description of the port. One to a few
|
||||
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
|
||||
<programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
|
||||
the screen.
|
||||
:
|
||||
(etc.)
|
||||
|
||||
WWW: http://www.oneko.org/</programlisting>
|
||||
</sect2>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title><filename>pkg-plist</filename></title>
|
||||
<sect2>
|
||||
<title><filename>pkg-plist</filename></title>
|
||||
|
||||
<para>This file lists all the files installed by the port. It
|
||||
is also called the <quote>packing list</quote> because the
|
||||
package is generated by packing the files listed here. The
|
||||
pathnames are relative to the installation prefix (usually
|
||||
<filename>/usr/local</filename>.
|
||||
If the
|
||||
port creates directories during installation, make sure to
|
||||
add <literal>@dirrm</literal> lines to remove them when the
|
||||
package is deleted.</para>
|
||||
<para>This file lists all the files installed by the port. It
|
||||
is also called the <quote>packing list</quote> because the
|
||||
package is generated by packing the files listed here. The
|
||||
pathnames are relative to the installation prefix (usually
|
||||
<filename>/usr/local</filename>. If the port creates
|
||||
directories during installation, make sure to add
|
||||
<literal>@dirrm</literal> lines to remove them when the
|
||||
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
|
||||
lib/X11/app-defaults/Oneko
|
||||
lib/X11/oneko/cat1.xpm
|
||||
|
|
@ -156,34 +157,34 @@ lib/X11/oneko/cat2.xpm
|
|||
lib/X11/oneko/mouse.xpm
|
||||
@dirrm lib/X11/oneko</programlisting>
|
||||
|
||||
<para>Refer to the &man.pkg-create.8; manual page for details
|
||||
on the packing list.</para>
|
||||
<para>Refer to the &man.pkg-create.8; manual page for details
|
||||
on the packing list.</para>
|
||||
|
||||
<note>
|
||||
<para>It is recommended that you keep all the filenames in
|
||||
this file sorted alphabetically. It will make verifying
|
||||
the changes when you upgrade the port much easier.</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>It is recommended that you keep all the filenames in
|
||||
this file sorted alphabetically. It will make verifying
|
||||
the changes when you upgrade the port much easier.</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>Creating a packing list manually can be a very tedious
|
||||
task. If the port installs a large numbers of files,
|
||||
<link linkend="plist-autoplist">creating the packing list
|
||||
automatically</link> might save time.</para>
|
||||
</note>
|
||||
<note>
|
||||
<para>Creating a packing list manually can be a very tedious
|
||||
task. If the port installs a large numbers of files,
|
||||
<link linkend="plist-autoplist">creating the packing list
|
||||
automatically</link> might save time.</para>
|
||||
</note>
|
||||
|
||||
<para>There is only one case when
|
||||
<filename>pkg-plist</filename> can be omitted from a port.
|
||||
If the port installs just a handful of files, and perhaps
|
||||
directories, the files and directories may be listed in the
|
||||
variables <varname>PLIST_FILES</varname> and
|
||||
<varname>PLIST_DIRS</varname>, respectively, within the
|
||||
port's <filename>Makefile</filename>. For instance, we
|
||||
could get along without <filename>pkg-plist</filename> in
|
||||
the above <filename>oneko</filename> port by adding the
|
||||
following lines to the <filename>Makefile</filename>:</para>
|
||||
<para>There is only one case when
|
||||
<filename>pkg-plist</filename> can be omitted from a port.
|
||||
If the port installs just a handful of files, and perhaps
|
||||
directories, the files and directories may be listed in the
|
||||
variables <varname>PLIST_FILES</varname> and
|
||||
<varname>PLIST_DIRS</varname>, respectively, within the
|
||||
port's <filename>Makefile</filename>. For instance, we
|
||||
could get along without <filename>pkg-plist</filename> in
|
||||
the above <filename>oneko</filename> port by adding the
|
||||
following lines to the <filename>Makefile</filename>:</para>
|
||||
|
||||
<programlisting>PLIST_FILES= bin/oneko \
|
||||
<programlisting>PLIST_FILES= bin/oneko \
|
||||
man/man1/oneko.1.gz \
|
||||
lib/X11/app-defaults/Oneko \
|
||||
lib/X11/oneko/cat1.xpm \
|
||||
|
|
@ -191,215 +192,211 @@ lib/X11/oneko/mouse.xpm
|
|||
lib/X11/oneko/mouse.xpm
|
||||
PLIST_DIRS= lib/X11/oneko</programlisting>
|
||||
|
||||
<para>Of course, <varname>PLIST_DIRS</varname> should be left
|
||||
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>
|
||||
<para>Of course, <varname>PLIST_DIRS</varname> should be left
|
||||
unset if a port installs no directories of its own.</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>
|
||||
<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>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>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>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>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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
<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