d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated some wording for 3.x.

Browse Source 
Added MASTER_STIE_LOCAL and updated it's location.
Added -N to diff options to ensure the diff includes new files.
Mentioned that USENET news ports should use ${PREFIX}/news.
Refromatted some of the comments w/in the sample Makefile so they wouldn't
	wrap in the latin1 format.
General updating and minor word changes.
This commit is contained in:
obrien 1997-05-23 08:19:19 +00:00
parent 341bb65e1b
commit 9f1ebfa29b
1 changed files with 51 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
share/doc/handbook/porting.sgml
View File

@ -1,10 +1,12 @@
<!-- $Id: porting.sgml,v 1.69 1997/03/10 11:55:17 asami Exp $ -->
<!-- $Id: porting.sgml,v 1.70 1997/05/18 03:35:01 asami Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect1><heading>Porting an existing piece of free software<label id="porting"></heading>
<p><em>Contributed by &a.jkh;, &a.gpalmer; and
&a.asami;.<newline>28 August 1996.</em>
<p><em>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and
&a.obrien;.<newline>28 August 1996.</em>
<p>The porting of freely available software, while perhaps not as
gratifying as developing your own from scratch, is still a vital part
@ -18,10 +20,11 @@ of the sources being ported, but merely those differences required for
running under FreeBSD.
<p>What follows are some guidelines for creating a new port for
FreeBSD 2.x. The bulk of the work is done by
FreeBSD 3.x. The bulk of the work is done by
<tt>/usr/share/mk/bsd.port.mk</tt>, which all port Makefiles include.
Please refer to that file for more details on the inner workings of
the ports collection.
the ports collection. Even if you don't hack Makefiles daily, it is
well commented, and you will still gain much knowledge from it.
<sect2>
<heading>Before Starting the Port<label id="porting:starting"></heading>
@ -30,8 +33,8 @@ the ports collection.
(<tt>&dollar;{..}</tt>) are mentioned in this document. Most
(if not all) are documented at the start of
<tt>bsd.port.mk</tt>. This file uses a non-standard tab
setting. <tt>Emacs</tt> should recognize the setting on
loading the file. <tt>vi</tt> or <tt>ex</tt> can be set to
setting. <tt>Emacs</tt> and <tt>Vim</tt> should recognize the setting
on loading the file. <tt>vi</tt> or <tt>ex</tt> can be set to
using the correct value by typing `<tt>:set tabstop=4</tt>'
once the file has been loaded.
@ -41,9 +44,9 @@ the ports collection.
for conditional compilation, make sure you make the changes as
general as possible so that we can back-port code to FreeBSD
1.x systems and cross-port to other BSD systems such as 4.4BSD
from CSRG, BSD/386, 386BSD and NetBSD.
from CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.
<p>The preferred way to tell 4.3BSD/Reno and newer versions of
<p>The preferred way to tell 4.3BSD/Reno (1990) and newer versions of
the BSD code apart is by using the `<tt>BSD</tt>' macro
defined in <tt>&lt;sys/param.h&gt;</tt>. Hopefully that file
is already included; if not, add the code:
@ -58,7 +61,8 @@ the ports collection.
system that defines these to symbols has sys/param.h. If you find
a system that doesn't, we would like to know. Please send mail to
<htmlurl url='mailto:ports@FreeBSD.org' name='ports@FreeBSD.org'>.
<p>Or you can use the GNU Autoconf style of doing this:
<p>Another way is to use the GNU Autoconf style of doing this:
<tscreen><verb>
#ifdef HAVE_SYS_PARAM_H
@ -105,15 +109,16 @@ the ports collection.
Berkeleyisms, not FreeBSD changes.
<item>In FreeBSD 2.x, <tt>__FreeBSD__</tt> is defined to be
<tt>2</tt>. In earlier versions, it is <tt>1</tt>.
<tt>2</tt>. In earlier versions, it is <tt>1</tt>. Later
versions will bump it to match their major version number.
<item>If you need to tell the difference between a FreeBSD 1.x
system and a FreeBSD 2.x system, usually the right answer is
system and a FreeBSD 2.x or 3.x system, usually the right answer is
to use the <tt>BSD</tt> macros described above. If there
actually is a FreeBSD specific change (such as special
shared library options when using `<tt>ld</tt>') then it is
OK to use <tt>__FreeBSD__</tt> and `<tt>#if __FreeBSD__ &gt;
1</tt>' to detect a FreeBSD 2.x system.
1</tt>' to detect a FreeBSD 2.x and later system.
If you need more granularity in detecting FreeBSD systems since
2.0-RELEASE you can use the following:
@ -236,8 +241,8 @@ A cat chasing a mouse all over the screen.
paragraphs concisely explaining what the port does is
sufficient. Note: This is <em>not</em> a manual nor an
in-depth description on how to use or compile the port.
In particular, please do not just copy the <tt>README</tt>
file here, unless, of course, it is a concise description
In particular, <em>please do not just copy the <tt>README</tt>
file here</em>, unless, of course, it is a concise description
of the port.
<p>It is recommended that you sign the name at the end of
@ -260,7 +265,8 @@ asami@cs.berkeley.edu
is also called the `packing list' because the package is
generated by packing the files listed here. The pathnames
are relative to the installation prefix (usually
<tt>/usr/local</tt> or <tt>/usr/X11R6</tt>).
<tt>/usr/local</tt> or <tt>/usr/X11R6</tt>) Also it is assumed
the manpages will be compressed.
<p>Here is a small example:
@ -438,9 +444,10 @@ ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/
non-standard formats, we can `house' it ourselves by putting
it on
<tscreen><verb>
ftp://freefall.FreeBSD.ORG/pub/FreeBSD/LOCAL_PORTS/
ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/
</verb></tscreen>
as the last resort. Send mail to the &a.ports
as the last resort. Please refer to this localation as
<tt>&dollar;{MASTER_SITE_LOCAL}</tt>. Send mail to the &a.ports
if you are not sure what to do.
<p>If your port requires some additional `patches' that are
@ -927,9 +934,10 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2
to us (i.e., if your modified ports directory is called
`<tt>superedit</tt>' and the original as in our tree is
`<tt>superedit.bak</tt>', then send us the result of `<tt>diff
-ru superedit.bak superedit</tt>'). Please examine the output
-ruN superedit.bak superedit</tt>'). Please examine the output
to make sure all the changes make sense. The best way to send
us the diff is by including it to <tt>send-pr(1)</tt>. Please
us the diff is by including it to <tt>send-pr(1)</tt> (category
`ports'). Please
mention any added or deleted files in the message, as they
have to be explicitly specified to CVS when doing a commit.
@ -945,14 +953,15 @@ FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2
<p>Do not leave anything valuable lying around in the
<tt>work</tt> subdirectory, `<tt>make clean</tt>' will
<em>nuke</em> it completely! If you need auxiliary files
that are not scripts or patches, put them in the subdirectory
<tt>files</tt> and use the <tt>post-extract</tt> target to
that are not scripts or patches, put them in the
<tt>&dollar;{FILESDIR}</tt> subdirectory (files/ by default)
and use the <tt>post-extract</tt> target to
copy them to the <tt>work</tt> subdirectory.
<sect3>
<heading>Package information</heading>
<p>Do install package information, i.e., the three files in
<p>Do include package information, i.e. COMMENT, DESCR, and PLIST, in
<tt>pkg</tt>. Note that these files are not used only for
packaging anymore, and are <em>mandatory</em> now, even if
<tt>&dollar;{NO_PACKAGE}</tt> is set.
@ -1007,7 +1016,7 @@ MAN8= baz.8
<item><tt>${INSTALL_DATA}</tt> is a command to install
sharable data.
<item><tt>${INSTALL_MAN}</tt> is a command to install
manpages (it doesn't do compression).
manpages and other documentation (it doesn't compress anything).
</itemize>
<p>These are basically the <tt>install</tt> command with all
@ -1064,7 +1073,7 @@ MAN8= baz.8
post-install:
.if !defined(NOPORTDOCS)
${MKDIR} ${PREFIX}/share/doc/xv
${INSTALL_DATA} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
.endif
</verb></tscreen>
@ -1128,11 +1137,12 @@ MAN8= baz.8
to generate patches is fine, but please take a look at the
resulting patches to make sure you don't have any
unnecessary junk in there. In particular, diffs between two
backup files, Makefiles when the port uses imake or GNU
backup files, Makefiles when the port uses Imake or GNU
configure, etc., are unnecessary and should be deleted.
Also, if you had to delete a file, then you can do it in the
<tt>post-extract</tt> target rather than as part of the
patch.
patch. Once you are happy with the resuling diff, please
split it up into one source file per patch file.
<sect3>
<heading>PREFIX</heading>
@ -1181,7 +1191,7 @@ MAN8= baz.8
incorrect. Also, many ports put everything except binaries,
header files and manual pages in the a subdirectory of
`<tt>lib</tt>', which does not bode well with the BSD
paradigm. Many of the files should me moved to one of the
paradigm. Many of the files should be moved to one of the
following: `<tt>etc</tt>' (setup/configuration files),
`<tt>libexec</tt>' (executables started internally),
`<tt>sbin</tt>' (executables for superusers/managers),
@ -1189,7 +1199,9 @@ MAN8= baz.8
`<tt>share</tt>' (architecture independent files). See man
<tt>hier(7)</tt> for details, the rule governing
<tt>/usr</tt> pretty much applies to <tt>/usr/local</tt>
too.
too. The exception are ports dealing with USENET `news'.
They may use <tt>&dollar;{PREFIX}/news</tt> as a destination
for their files.
<sect3>
<heading>ldconfig</heading>
@ -1265,7 +1277,8 @@ lib/libtcl.so.7.3
DISTNAME= xdvi
PKGNAME= xdvi-pl18
CATEGORIES= print
[do not forget the trailing slash ("/")!]
[do not forget the trailing slash ("/")!
if you aren't using MASTER_SITE_* macros]
MASTER_SITES= ${MASTER_SITE_XCONTRIB}
MASTER_SITE_SUBDIR= applications
[set this if the source is not in the standard ".tar.gz" form]
@ -1278,24 +1291,24 @@ lib/libtcl.so.7.3
[maintainer; *mandatory*! This is the person (preferably with commit
privileges) who a user can contact for questions and bug reports - this
person should be the porter or someone who can forward questions to the
original porter reasonably promptly. If you really do not want to have your
address here, set it to "ports@FreeBSD.ORG".]
original porter reasonably promptly. If you really do not want to have
your address here, set it to "ports@FreeBSD.ORG".]
MAINTAINER= asami@FreeBSD.ORG
[dependencies -- can be empty]
RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm
[this section is for other standard bsd.port.mk variables that do not belong
to any of the above]
[this section is for other standard bsd.port.mk variables that do not
belong to any of the above]
[If it asks questions during configure, build, install...]
IS_INTERACTIVE= yes
[If it extracts to a directory other than ${DISTNAME}...]
WRKSRC= ${WRKDIR}/xdvi-new
[If the distributed patches were not made relative to ${WRKSRC}, you may need
to tweak this]
[If the distributed patches were not made relative to ${WRKSRC}, you
may need to tweak this]
PATCH_DIST_STRIP= -p1
[If it requires a "configure" script generated by GNU autoconf to be run...]
[If it requires a "configure" script generated by GNU autoconf to be run]
GNU_CONFIGURE= yes
[If it requires GNU make, not /usr/bin/make, to build...]
USE_GMAKE= yes
@ -1341,8 +1354,9 @@ lib/libtcl.so.7.3
<item>FreeBSD strives to support the native language of its
users. The `&lt;language&gt;' part should be a two letter
abbreviation of the natural language if the port is specific
to a certain language. Examples are `jp' for Japanese and
`ru' for Russian.
to a certain language. Examples are `jp' for Japanese,
`ru' for Russian, `vn' for Vietnamese, `cn' for Chinese,
and `kr' for Korean.
<item>The `<tt>&lt;name&gt;</tt>' part should be all
lowercases, except for a really large package (with lots of