From 4637ebc72a66661613085993f33f9282b2fca030 Mon Sep 17 00:00:00 2001 From: obrien Date: Fri, 23 May 1997 08:19:19 +0000 Subject: 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. --- share/doc/handbook/porting.sgml | 88 ++++++++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 37 deletions(-) (limited to 'share/doc') 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 @@ - + Porting an existing piece of free software

Contributed by &a.jkh;, &a.gpalmer; and &a.asami;.28 August 1996. +

Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and + &a.obrien;.28 August 1996.

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.

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 /usr/share/mk/bsd.port.mk, 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. Before Starting the Port @@ -30,8 +33,8 @@ the ports collection. (${..}) are mentioned in this document. Most (if not all) are documented at the start of bsd.port.mk. This file uses a non-standard tab - setting. Emacs should recognize the setting on - loading the file. vi or ex can be set to + setting. Emacs and Vim should recognize the setting + on loading the file. vi or ex can be set to using the correct value by typing `:set tabstop=4' 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. -

The preferred way to tell 4.3BSD/Reno and newer versions of +

The preferred way to tell 4.3BSD/Reno (1990) and newer versions of the BSD code apart is by using the `BSD' macro defined in <sys/param.h>. 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 . -

Or you can use the GNU Autoconf style of doing this: + +

Another way is to use the GNU Autoconf style of doing this: #ifdef HAVE_SYS_PARAM_H @@ -105,15 +109,16 @@ the ports collection. Berkeleyisms, not FreeBSD changes. In FreeBSD 2.x, __FreeBSD__ is defined to be - 2. In earlier versions, it is 1. + 2. In earlier versions, it is 1. Later + versions will bump it to match their major version number. 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 BSD macros described above. If there actually is a FreeBSD specific change (such as special shared library options when using `ld') then it is OK to use __FreeBSD__ and `#if __FreeBSD__ > - 1' to detect a FreeBSD 2.x system. + 1' 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 not a manual nor an in-depth description on how to use or compile the port. - In particular, please do not just copy the README - file here, unless, of course, it is a concise description + In particular, please do not just copy the README + file here, unless, of course, it is a concise description of the port.

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 - /usr/local or /usr/X11R6). + /usr/local or /usr/X11R6) Also it is assumed + the manpages will be compressed.

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 -ftp://freefall.FreeBSD.ORG/pub/FreeBSD/LOCAL_PORTS/ +ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/ - as the last resort. Send mail to the &a.ports + as the last resort. Please refer to this localation as + ${MASTER_SITE_LOCAL}. Send mail to the &a.ports if you are not sure what to do.

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 `superedit' and the original as in our tree is `superedit.bak', then send us the result of `diff - -ru superedit.bak superedit'). Please examine the output + -ruN superedit.bak superedit'). 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 send-pr(1). Please + us the diff is by including it to send-pr(1) (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

Do not leave anything valuable lying around in the work subdirectory, `make clean' will nuke it completely! If you need auxiliary files - that are not scripts or patches, put them in the subdirectory - files and use the post-extract target to + that are not scripts or patches, put them in the + ${FILESDIR} subdirectory (files/ by default) + and use the post-extract target to copy them to the work subdirectory. Package information -

Do install package information, i.e., the three files in +

Do include package information, i.e. COMMENT, DESCR, and PLIST, in pkg. Note that these files are not used only for packaging anymore, and are mandatory now, even if ${NO_PACKAGE} is set. @@ -1007,7 +1016,7 @@ MAN8= baz.8 ${INSTALL_DATA} is a command to install sharable data. ${INSTALL_MAN} is a command to install - manpages (it doesn't do compression). + manpages and other documentation (it doesn't compress anything).

These are basically the install 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 @@ -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 post-extract 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. PREFIX @@ -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 `lib', 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: `etc' (setup/configuration files), `libexec' (executables started internally), `sbin' (executables for superusers/managers), @@ -1189,7 +1199,9 @@ MAN8= baz.8 `share' (architecture independent files). See man hier(7) for details, the rule governing /usr pretty much applies to /usr/local - too. + too. The exception are ports dealing with USENET `news'. + They may use ${PREFIX}/news as a destination + for their files. ldconfig @@ -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 FreeBSD strives to support the native language of its users. The `<language>' 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. The `<name>' part should be all lowercases, except for a really large package (with lots of -- cgit v1.1