summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorobrien <obrien@FreeBSD.org>1997-05-23 08:19:19 +0000
committerobrien <obrien@FreeBSD.org>1997-05-23 08:19:19 +0000
commit4637ebc72a66661613085993f33f9282b2fca030 (patch)
treead865cf20a3b637f5f5b04ece5d5ad2fcfbfea49
parente1511e1aa24e90585f54ef122a053e861d9283a2 (diff)
downloadFreeBSD-src-4637ebc72a66661613085993f33f9282b2fca030.zip
FreeBSD-src-4637ebc72a66661613085993f33f9282b2fca030.tar.gz
Updated some wording for 3.x.
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.
-rw-r--r--share/doc/handbook/porting.sgml88
1 files changed, 51 insertions, 37 deletions
diff --git a/share/doc/handbook/porting.sgml b/share/doc/handbook/porting.sgml
index 6833286..de29944 100644
--- a/share/doc/handbook/porting.sgml
+++ b/share/doc/handbook/porting.sgml
@@ -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
OpenPOWER on IntegriCloud