os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add some more details, and document a couple of undocumented variables

Browse source 
that specify the distribution files.

s/http/HTTP/ in a few places.
This commit is contained in:
Nik Clayton 2002-05-29 17:59:53 +00:00
parent 69af2ac521
commit c035787c2e
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=13269
1 changed files with 142 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

192
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

@ -524,9 +524,9 @@ lib/X11/oneko/mouse.xpm
<emphasis>mainstream</emphasis> sources when and where you
can.</para>
<para>If you cannot find a FTP/http site that is well-connected to the
<para>If you cannot find a FTP/HTTP site that is well-connected to the
net, or can only find sites that have irritatingly non-standard
formats, you might want to put a copy on a reliable FTP or http
formats, you might want to put a copy on a reliable FTP or HTTP
server that you control (e.g., your home page). Make sure you set
<makevar>MASTER_SITES</makevar> to reflect your choice.</para>
@ -676,20 +676,27 @@ lib/X11/oneko/mouse.xpm
default, though this should be rarely, if ever,
necessary.</para>
</sect1>
<sect1>
<title>Naming and categorisation</title>
<sect1>
<para>The first part of the port's <filename>Makefile</filename> names
the port, describes it's version number, and lists it in the correct
category.</para>
<sect2>
<title><makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar></title>
<para>You should set <makevar>PORTNAME</makevar> to the
base name of your port, and <makevar>PORTVERSION</makevar>
to the version number of the port.</para>
</sect1>
</sect2>
<sect1>
<sect2>
<title><makevar>PORTREVISION</makevar> and
<makevar>PORTEPOCH</makevar></title>
<sect2>
<sect3>
<title><makevar>PORTREVISION</makevar></title>
<para>The <makevar>PORTREVISION</makevar> variable is a
@ -787,9 +794,9 @@ lib/X11/oneko/mouse.xpm
automated tools (e.g. <command>pkg_version</command>)
will highlight the fact that a new package is
available.</para>
</sect2>
</sect3>
<sect2>
<sect3>
<title><makevar>PORTEPOCH</makevar></title>
<para>From time to time a software vendor or FreeBSD porter
@ -832,9 +839,9 @@ lib/X11/oneko/mouse.xpm
<makevar>PORTVERSION</makevar> of 1.2.20000917 or similar,
not 20000917, so that the succeeding release, say 1.3, is
still a numerically greater value.</para>
</sect2>
</sect3>
<sect2>
<sect3>
<title>Example of <makevar>PORTREVISION</makevar> and
<makevar>PORTEPOCH</makevar> usage</title>
@ -897,10 +904,10 @@ PORTEPOCH= 1</programlisting>
<literal>3</literal> is still numerically less than
<literal>10</literal>.</para>
</note>
</sect2>
</sect1>
</sect3>
</sect2>
<sect1>
<sect2>
<title><makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar></title>
<para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar> and
@ -919,9 +926,44 @@ PORTEPOCH= 1</programlisting>
<makevar>PKGNAMEPREFIX</makevar> and
<makevar>PKGNAMESUFFIX</makevar>, respectively. Do not make
them part of <makevar>PORTNAME</makevar>.</para>
</sect1>
</sect2>
<sect1>
<sect2>
<title><makevar>CATEGORIES</makevar></title>
<para>When a package is created, it is put under
<filename>/usr/ports/packages/All</filename> and links are made from
one or more subdirectories of
<filename>/usr/ports/packages</filename>. The names of these
subdirectories are specified by the variable
<makevar>CATEGORIES</makevar>. It is intended to make life easier
for the user when he is wading through the pile of packages on the
FTP site or the CDROM. Please take a look at the existing <link
linkend="porting-categories">categories</link> and pick the ones
that are suitable for your port.</para>
<para>This list also determines where in the ports tree the port is
imported. If you put more than one category here, it is assumed
that the port files will be put in the subdirectory with the name in
the first category. See the <link
linkend="porting-categories">categories</link> section for more
discussion about how to pick the right categories.</para>
<para>If your port truly belongs to something that is different from
all the existing ones, you can even create a new category name. In
that case, please send mail to the &a.ports; to propose a new
category.</para>
</sect2>
</sect1>
<sect1>
<title>The distribution files</title>
<para>The second part of the <filename>Makefile</filename> describes the
files that must be downloaded in order to build the port, and where
they can be downloaded from.</para>
<sect2>
<title><makevar>DISTNAME</makevar></title>
<para><makevar>DISTNAME</makevar> is the name of the port as
@ -950,39 +992,12 @@ PORTEPOCH= 1</programlisting>
<makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar>
(and possibly <makevar>EXTRACT_SUFX</makevar>).</para>
</note>
</sect1>
</sect2>
<sect1>
<title><makevar>CATEGORIES</makevar></title>
<para>When a package is created, it is put under
<filename>/usr/ports/packages/All</filename> and links are made from
one or more subdirectories of
<filename>/usr/ports/packages</filename>. The names of these
subdirectories are specified by the variable
<makevar>CATEGORIES</makevar>. It is intended to make life easier
for the user when he is wading through the pile of packages on the
FTP site or the CDROM. Please take a look at the existing <link
linkend="porting-categories">categories</link> and pick the ones
that are suitable for your port.</para>
<para>This list also determines where in the ports tree the port is
imported. If you put more than one category here, it is assumed
that the port files will be put in the subdirectory with the name in
the first category. See the <link
linkend="porting-categories">categories</link> section for more
discussion about how to pick the right categories.</para>
<para>If your port truly belongs to something that is different from
all the existing ones, you can even create a new category name. In
that case, please send mail to the &a.ports; to propose a new
category.</para>
</sect1>
<sect1>
<sect2>
<title><makevar>MASTER_SITES</makevar></title>
<para>Record the directory part of the FTP/http-URL pointing at the
<para>Record the directory part of the FTP/HTTP-URL pointing at the
original tarball in <makevar>MASTER_SITES</makevar>. Do not forget
the trailing slash (<filename>/</filename>)!</para>
@ -1019,13 +1034,47 @@ MASTER_SITE_SUBDIR= applications</programlisting>
variables in <filename>/etc/make.conf</filename> to override our
choices, and use their favorite mirrors of these popular archives
instead.</para>
</sect1>
</sect2>
<sect1 id="porting-patchfiles">
<sect2>
<title><makevar>DISTFILES</makevar></title>
<para>Sometimes the names of the files to be downloaded have no
resemblance to the name of the port. For example, it might be
called <filename>source.tar.gz</filename> or similar. In other
cases the application's source code might be in several different
archives, all of which must be downloaded.</para>
<para>If this is the case, set <makevar>DISTFILES</makevar> to be a
space separated list of all the files that must be
downloaded.</para>
<programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting>
</sect2>
<sect2>
<title><makevar>EXTRACT_ONLY</makevar></title>
<para>If only some of the <makevar>DISTFILES</makevar> must be
extracted&mdash;for example, one of them is the source code, while
another is an uncompressed document&mdash;list the filenames that
must be extracted in <makevar>EXTRACT_ONLY</makevar>.</para>
<programlisting>DISTFILES= source.tar.gz manual.html
EXTRACT_ONLY= source.tar.gz</programlisting>
<para>If <emphasis>none</emphasis> of the <makevar>DISTFILES</makevar>
should be uncompressed then set <makevar>EXTRACT_ONLY</makevar> to
the empty string.</para>
<programlisting>EXTRACT_ONLY=</programlisting>
</sect2>
<sect2 id="porting-patchfiles">
<title><makevar>PATCHFILES</makevar></title>
<para>If your port requires some additional patches that are available
by FTP or http, set <makevar>PATCHFILES</makevar> to the names of
by FTP or HTTP, set <makevar>PATCHFILES</makevar> to the names of
the files and <makevar>PATCH_SITES</makevar> to the URL of the
directory that contains them (the format is the same as
<makevar>MASTER_SITES</makevar>).</para>
@ -1054,7 +1103,7 @@ MASTER_SITE_SUBDIR= applications</programlisting>
not be writable.</para>
<note>
<para>Note that the tarball will have been extracted alongside the
<para>The tarball will have been extracted alongside the
regular source by then, so there is no need to explicitly extract
it if it is a regular gzip'd or compress'd tarball. If you do the
latter, take extra care not to overwrite something that already
@ -1062,7 +1111,50 @@ MASTER_SITE_SUBDIR= applications</programlisting>
remove the copied patch in the <maketarget>pre-clean</maketarget>
target.</para>
</note>
</sect1>
</sect2>
<sect2>
<title>Multiple distribution files from different sites</title>
<para>Some applications consist of multiple distribution files that
must be downloaded from a number of different sites. For example,
<application>Ghostscript</application> consists of the core of the
program, and then a large number of driver files that are used
depending on the user's printer. Some of these driver files are
supplied with the core, but many others must be downloaded from a
variety of different sites.</para>
<para>To support this, each entry in <makevar>DISTFILES</makevar> may
be followed by a colon and a <quote>tag name</quote>. Each site
listed in <makevar>MASTER_SITES</makevar> is then followed by a
colon, and the tag that indicates which distribution files should be
downloaded from this site.</para>
<para>For example, consider an application with the source split in to
<filename>source1.tar.gz</filename> and
<filename>source2.tar.gz</filename>, which must be downloaded from
two different sites. The port's <filename>Makefile</filename> would
include lines like this:</para>
<programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2</programlisting>
<para>Multiple distribution files can have the same tag. Continuing
the previous example, suppose that there was a third distfile,
<filename>source3.tar.gz</filename>, that should be downloaded from
<hostid>ftp.example2.com</hostid>. The
<filename>Makefile</filename> would then be written like
this.</para>
<programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2 \
source3.tar.gz:source2</programlisting>
</sect2>
</sect1>
<sect1>
<title><makevar>MAINTAINER</makevar></title>