From e9328d1ba4e83c36796d158c8607a9f0566b0358 Mon Sep 17 00:00:00 2001 From: John Fieber Date: Sat, 19 Aug 1995 15:38:25 +0000 Subject: [PATCH] Placed a link to the XFree86 Project WWW pages as a placeholder for our X11 documentation. Vastly improved documentation for porting applications, courtesy of asami@freebsd.org. Submitted by: asami@freebsd.org --- share/doc/handbook/handbook.sgml | 9 +- share/doc/handbook/porting.sgml | 1188 ++++++++++++++++++++++-------- 2 files changed, 882 insertions(+), 315 deletions(-) diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml index eef6c6aecb5e..2d227b9e5cae 100644 --- a/share/doc/handbook/handbook.sgml +++ b/share/doc/handbook/handbook.sgml @@ -1,4 +1,4 @@ - + The FreeBSD Documentation Project - August 8, 1995 + August 19, 1995 Welcome to FreeBSD! This handbook covers the installation and day to day use of FreeBSD Release @@ -116,7 +116,10 @@ OUTLINE: Sean Kelly for more information. - * The X-Window System + The X-Window System +

Pending the completion of this section, please refer to + documentation supplied by the . Managing hardware &scsi; diff --git a/share/doc/handbook/porting.sgml b/share/doc/handbook/porting.sgml index cb76cd608b4a..abbbd91c3cec 100644 --- a/share/doc/handbook/porting.sgml +++ b/share/doc/handbook/porting.sgml @@ -1,11 +1,12 @@ - + Porting applications -

Contributed by &a.jkh;. +

Contributed by &a.jkh;, &a.gpalmer; and + &a.asami;.19 August 1995. -Here are the guidelines one should follow in + Here are the guidelines one should follow in creating a new port for FreeBSD 2.x . This documentation will change as this process is progressively refined, so watch this space for details. The ${..} @@ -15,31 +16,29 @@ Here are the guidelines one should follow in that file for more details. - Before starting the port + Before Starting the Port -

Note: Only a fraction of the overridable variables - are mentioned in this document. Most (if not all) are - documented at the start of the bsd.port.mk - file which can be found in /usr/share/mk. This file - uses a non-standard tab setting. Emacs should - recognise 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. - &a.gpalmer; +

Note: Only a fraction of the overridable variables are + mentioned in this document. Most (if not all) are documented + at the start of the bsd.port.mk file which can be + found in /usr/share/mk. This file uses a non-standard tab + setting. Emacs should recognise 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. - You may come across code that needs modifications or - conditional compilation based upon what version of UNIX - it's running under. If you need to make such changes to - the code 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. +

You may come across code that needs modifications or + conditional compilation based upon what version of UNIX it's + running under. If you need to make such changes to the code + 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. - The preferred way to tell 4.3BSD/Reno 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: +

The preferred way to tell 4.3BSD/Reno 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: #ifdef _HAVE_PARAM_H @@ -57,9 +56,9 @@ Here are the guidelines one should follow in #if (defined(BSD) && (BSD >= 199103)) - to detect if the code is being compiled on a 4.3 Net2 - code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD - 0.9, 386BSD, BSD/386 1.0). + to detect if the code is being compiled on a 4.3 Net2 code + base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, + BSD/386 1.1 and below). Use: @@ -67,348 +66,913 @@ Here are the guidelines one should follow in #if (defined(BSD) && (BSD >= 199306)) - to detect if the code is being compiled on a 4.4 code - base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, - BSD/386 1.1). + to detect if the code is being compiled on a 4.4 code base or + newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or + above). - Use sparingly: +

Use sparingly: - - __FreeBSD__ is defined in all - versions of FreeBSD. Use it if the change you - are making ONLY affects FreeBSD. Porting gotchas - like the use of sys_errlist[] vs - strerror() are Berkeleyisms, not FreeBSD - changes. + + __FreeBSD__ is defined in all versions of + FreeBSD. Use it if the change you are making ONLY affects + FreeBSD. Porting gotchas like the use of + sys_errlist[] vs strerror() are + Berkeleyisms, not FreeBSD changes. - In FreeBSD 2.x, __FreeBSD__ is - defined to be 2. In earlier versions, - it's 1. + In FreeBSD 2.x, __FreeBSD__ is defined to be + 2. In earlier versions, it's 1. - If you need to tell the difference between a - FreeBSD 1.x system and a FreeBSD 2.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's OK to use - __FreeBSD__ and "#if __FreeBSD_ > - 1" to detect a FreeBSD 2.x system. + If you need to tell the difference between a FreeBSD 1.x + system and a FreeBSD 2.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's + OK to use __FreeBSD__ and `#if __FreeBSD_ > + 1' to detect a FreeBSD 2.x system. - + - In the dozens of ports that have been done, there have +

In the dozens of ports that have been done, there have only been one or two cases where __FreeBSD__ should have been used. Just because an earlier port screwed up and used it in the wrong place doesn't mean you should do so too. - Doing the port + Quick Porting -

NOTE: If your sources work without change under FreeBSD, - skip to the next section. +

This section tells you how to do a quick port. In many + cases, it is not enough, but we'll see. + +

First, get the original tarball and put it into + ${DISTDIR}, which defaults to + /usr/ports/distfiles. + +

Note: 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 FreeBSD box. If you needed to + change something, you'll have to refer to the next section + too. + + + Writing the Makefile + +

The minimal Makefile would look something like this: + + +# New ports collection makefile for: oneko +# Version required: 1.1b +# Date created: 5 December 1994 +# Whom: asami +# +# $Id: Makefile,v 1.5 1995/04/11 00:20:20 asami Exp $ +# + +DISTNAME= oneko-1.1b +CATEGORIES+= games +MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ + +MAINTAINER= asami@FreeBSD.ORG + +USE_IMAKE= yes + +.include + + +

See if you can figure it out. Don't worry about the contents + of the $Id$ line, it will be filled in + automatically by CVS when the port is imported to our main + ports tree. + + + Writing the description files + +

There are three required description files that are + required for any port, whether they actually package or not. + They are COMMENT, DESCR, and + PLIST, and reside in the pkg subdirectory. + + + COMMENT + +

This is the one-line description of the port. It is + recommended to have the name of the package at the + beginning, as in: + +oneko-1.1b, a cat chasing a mouse all over the screen + + + + DESCR + +

This is a longer description of the port. One to a few + 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's a concise description + of the port. + +

It is recommended that you sign the name at the end of + this file, and also state the version number, as in: + + +This is a port of oneko, in which a cat chases a poor mouse all over +the screen. + : +(etc.) + : +This is version 1.1b. + +- Satoshi +asami@cs.berkeley.edu + + + + PLIST + +

This file lists all the files installed by the port. It + 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). + +

Here is a small example: + + +bin/oneko +man/man1/oneko.1.gz +lib/X11/app-defaults/Oneko +lib/X11/oneko/cat1.xpm +lib/X11/oneko/cat2.xpm +lib/X11/oneko/mouse.xpm + + + + Creating the checksum file + +

Just type `make makesum'. The ports make rules + will automatically generate the file files/md5. + + + Testing the port + +

You should make sure that the port rules do exactly what + you want it to do, including packaging up the port. Try + doing `make install', `make package' and + then `pkg_delete -d <pkgname>' and see if all + the files are correctly deleted. Then do a `pkg_add + <pkgname>.tgz' and see if everything re-appears + and works correctly. + + + Submitting the port + +

Now that you're happy with your port, the only thing + remaining is to put it in the main FreeBSD ports tree and + make everybody else happy about it too. To accomplish this, + pack the necessary files (everything described in this + section -- in particular do not include the + original source tarball or the `work' subdirectory) + into a .tar.gz file, stick it in the directory + +ftp://ftp.freebsd.org/pub/FreeBSD/incoming/ + + and send mail to ports@freebsd.org. We will take a + look, get back to you if necessary, and put it in the tree. + Your name will also appear in the list of `Additional + FreeBSD contributors' on the FreeBSD Handbook and other + files. Isn't that great?!? :) + + + Slow Porting + +

Ok, so it wasn't that simple, and the port required some + modifications to get it to work. In this section, we'll + explain, step by step, how to modify it to get it to work with + the ports paradigm. + + + How things work + +

First, this is the sequence of events which occurs when the + user first types `make' in your port's directory, + and you may find that having bsd.port.mk in another + window while you read this really helps to understand it. + +

But don't worry if you don't really understand what + bsd.port.mk is doing, not many people + do... :> - Get the original sources (normally) as a - compressed tarball (<foo>.tar.gz or - <foo>.tar.Z) and copy it into - ${DISTDIR}. Always use - mainstream sources when and where you can, - and don't be tempted to patch a tarball 2 or 3 - revisions ahead just to save yourself trouble. The - idea is that the ports collection should be usable - even with all of ${DISTDIR} blown - away, which is to say that it should be possible for - a user to repopulate all of - ${DISTDIR} with publically available - files. + The fetch target is run. The fetch target is + responsible for making sure that the tarball exists + locally in ${DISTDIR}. If fetch cannot + find the required files in ${DISTDIR} it + will look up the ftp-URL ${MASTER_SITES}, + which is set in the Makefile. It will then attempt to + fetch the named distribution file with + ${NCFTP}, assuming that the requesting + site has direct access to the Internet. If that succeeds, + it will save the file in ${DISTDIR} for + future use and proceed. - Unpack a copy of the tarball in a private - directory and make whatever changes are necessary to - get the port to compile properly under FreeBSD 2.0. - Keep careful track of everything you do, as - you will be automating the process shortly. - Everything, including the deletion, addition or - modification of files should be doable using an - automated script or patch file when your port is - finished. If your port requires significant user - interaction/customization to compile or install, you - should take a look at one of Larry Wall's classic - Configure scripts and perhaps do something similar - yourself. The goal of the new ports collection is to - make each port as `plug-and-play' as possible for the - end-user while using a minimum of disk space. + The extract target is run. It looks for your ports' + distribution file in ${DISTDIR} (typically + a gzip'd tarball) and unpacks it into a temporary + subdirectory specified by ${WRKDIR} + (defaults to work). - Carefully consider the list of patches, shell - commands or user queries necessary for customizing - the port, then, making sure you understand the - following thoroughly, go for it. The sequence of - events you need to understand is that which occurs - when the user first types `make' in your - port's directory, and you may find that having - bsd.port.mk in another window while you read - this really helps to understand it: + The patch target is run. First, any patches defined + in ${PATCHFILES} are applied. Second, if + any patches are found in ${PATCHDIR} + (defaults to the patches subdirectory), they are + applied at this time in alphabetical order. - Sequence of events: + The configure target is run. This can do any one of + many different things. - The pre-fetch and fetch targets are run. The - fetch target is responsible for making sure that - the tarball exists locally in ${DISTDIR}. - The pre-fetch target hook is optional. If fetch - cannot find the required files in - ${DISTDIR} it will look up the URL - ${MASTER_SITES}, which can be set in the - Makefile or allowed to default to the Walnut - Creek CDROM archive site. It will then attempt - to fetch the named distribution file with - ${NCFTP}, assuming that the requesting - site has direct access to the Internet. If that - succeeds, it will save the file in - ${DISTDIR} for future use and proceed. - The pre-extract target hook, if it exists, is - run. + If it exists, scripts/configure is run. - The extract target, if not disabled, is run. - It looks for your ports' distribution file in - ${DISTDIR} (typically a gzip'd - tarball) and unpacks it into a temporary - directory. + If ${HAS_CONFIGURE} or + ${GNU_CONFIGURE} is set, + ${WRKSRC}/configure is run. - The pre-configure target hook is run. + If ${USE_IMAKE} is set, + ${XMKMF} (default: `xmkmf + -a') is run. - The configure target is run. This can do any - one of many different things. First, if any - patches are found in the - ${PATCHDIR} subdirectory, they - are applied at this time in alphabetical order. - Next, a series of scripts, if detected, are run - in the following order: - - - - ${SCRIPTDIR}/pre-configure - - ${SCRIPTDIR/configure or - ${WRKSRC}/configure if - ${HAS_CONFIGURE} is set. - - If ${USE_IMAKE} is set, an - xmkmf command is done. - - ${SCRIPTDIR}/post-configure - - - As you can see, it's possible to do just about anything to your - port, in a variety of stages! - - The pre-build target hook is run. - - The build target is run. This is responsible - for decending into the ports' private working - directory (${WRKSRC}) and - building it. If ${USE_GMAKE} is - set, GNU make will be used, otherwise - the system ${MAKE}. - In the preparation of the port, files that have - been added or changed can be picked up with a - recursive diff for later feeding to patch. This is - the easiest kind of change to make as it doesn't - involve any mucking around with configuration files. - Each set of patches you wish to apply should be - collected into a file named - "patch-<xx>" where <xx> - denotes the sequence in which the patches will be - applied - these are done in alphabetical - order, thus "aa" first, "ab" - second and so on. These files should be stored in - ${PATCHDIR}, from where they will be - automatically applied. All patches should be - relative to ${WRKSRC} (generally the - directory your port's tarball unpacks itself into, - that being where the make is done). + The build target is run. This is responsible for + descending into the ports' private working directory + (${WRKSRC}) and building it. If + ${USE_GMAKE} is set, GNU make + will be used, otherwise the system make will be + used. - Include any additional customization commands to - your `configure' script and save it to - ${SCRIPTDIR}/configure. Add your - port to the Makefile one level above it so that it - will be made automatically. - - Always try to install relative to - ${PREFIX} in your Makefiles. This will - normally be set to /usr/local, though it can be can - be reassigned in your Makefile or in the users - environment. Not hardcoding /usr/local anywhere in - your installation will make the port much more - flexible and cater to the needs of other sites. Note - that this doesn't count for package `packing list' - files since they have their own scheme for relocating - themselves and can be left independant of - ${PREFIX} unless the package is one that - hardcodes itself to a compiled-in location. - - If your port requires user input to build, - configure or install, then set - IS_INTERACTIVE in your Makefile. This will - allow "overnight builds" to progress past your port - if the user sets the variable BATCH in his - environment (and if the user sets the variable - INTERACTIVE, then only those ports - requiring interaction are built). - - For more details on any of this (since it may not be - clear at first reading), examine an existing port and - read the contents of /usr/share/mk/bsd.port.mk; - you'll see that it's not as difficult as it sounds! - - +

The above are the default actions. In addition, you can + define targets `pre-<something>' or + `post-<something>', or put scripts with those + names, in the scripts subdirectory, and they will + be run before or after the default actions are done. + +

For example, if you have a post-extract target + defined in your Makefile, and a file pre-build in + the scripts subdirectory, the + post-extract target will be called after the + regular extraction actions, and the pre-build + script will be executed before the default build rules are + done. It is recommended that you use Makefile targets if + possible, because it will be easier for someone to figure + out what kind of non-default action the port requires. + +

The default actions are done by the bsd.port.mk + targets `do-<something>'. For example, the + commands to extract a port are in the target + `do-extract'. If you are not happy with the + default target, and you can't fix it by redefining the + `do-<something>' target in your Makefile. + +

Note that the `main' targets (e.g., extract, + configure, etc.) do nothing more than make sure all + the stages up to that one is completed and call the real + targets or scripts, and they are not intended to be + changed. If you want to fix the extraction, fix + do-extract, but never ever touch extract! + +

Now that you understand what goes on when the user types + `make', let's go through the recommended steps to + create the perfect port. + + + Getting the original sources + +

Get the original sources (normally) as a compressed tarball + (<foo>.tar.gz or <foo>.tar.Z) + and copy it into ${DISTDIR}. Always use + mainstream sources when and where you can. + +

If you can't find a ftp site that is well-connected to the + net, or can only find sites that have irritatingly + non-standard formats, we can `house' it ourselves by putting + it on + +ftp://freefall.freebsd.org/pub/FreeBSD/LOCAL_PORTS/ + + as the last resort. Send mail to ports@freebsd.org + if you are not sure what to do. + +

If your port requires some additional `patches' that are + available on the Internet, fetch them too and put them in + ${DISTDIR}. Don't worry if they come from + site other than where you got the the main source tarball, + we have a way to handle these situations (see the + description of ${PATCHFILES} below). + + + Modifying the port + +

Unpack a copy of the tarball in a private directory and + make whatever changes are necessary to get the port to + compile properly under the current version of FreeBSD. Keep + careful track of everything you do, as you will be + automating the process shortly. Everything, including the + deletion, addition or modification of files should be doable + using an automated script or patch file when your port is + finished. + +

If your port requires significant user + interaction/customization to compile or install, you should + take a look at one of Larry Wall's classic Configure scripts + and perhaps do something similar yourself. The goal of the + new ports collection is to make each port as `plug-and-play' + as possible for the end-user while using a minimum of disk + space. + + + Patching + +

In the preparation of the port, files that have been added + or changed can be picked up with a recursive diff for later + feeding to patch. This is the easiest kind of change to + make as it doesn't involve any mucking around with + configuration files. Each set of patches you wish to apply + should be collected into a file named + `patch-<xx>' where <xx> + denotes the sequence in which the patches will be applied -- + these are done in alphabetical order, thus + `aa' first, `ab' second and so on. These + files should be stored in ${PATCHDIR}, from + where they will be automatically applied. All patches + should be relative to ${WRKSRC} (generally + the directory your port's tarball unpacks itself into, that + being where the make is done). To make fixes and upgrades + easier you should avoid having more than one patch fix the + same file (e.g., patch-ab and patch-ab both changing + ${WRKSRC}/foobar.c). + + + Configuring + +

Include any additional customization commands to your + configure script and save it in the + `scripts' subdirectory. As mentioned above, you + can also do this as Makefile targets and/or scripts with the + name pre-configure or post-configure. + + + Handling user input + +

If your port requires user input to build, configure or + install, then set IS_INTERACTIVE in your Makefile. + This will allow `overnight builds' to skip your port if the + user sets the variable BATCH in his environment + (and if the user sets the variable INTERACTIVE, + then only those ports requiring interaction are + built). + + Configuring the Makefile -

Configuring the Makefile is pretty simple, and again I +

Configuring the Makefile is pretty simple, and again we suggest that you look at existing examples before starting. Consider the following problems in sequence as you design your new Makefile: - - Does it live in ${DISTDIR} as a - standard gzip'd tarball? If so, you can go on to the - next step. If not, you should look at overriding any - of the ${EXTRACT_CMD}, - ${EXTRACT_ARGS}, - ${EXTRACT_SUFX}, or - ${DISTFILE} variables, depending on - how alien a format your port's distribution file is. - In the worst case, you can simply create your own - `extract' target to override the default, - though this should be rarely, if ever, necessary. If - you do find it necessary to do your own, your extract - target should take care to "leave tracks" for itself - so that files are not unnecessarily extracted - twice---see the default extract rule in - bsd.port.mk for an example of this. + + The original source - If your port is integrated into the ports - directory directly (original sources are already part - of FreeBSD), you may also consider simply setting - NO_EXTRACT and dispensing with the idea of a - distribution file altogether. +

Does it live in ${DISTDIR} as a standard + gzip'd tarball? If so, you can go on to the next step. If + not, you should look at overriding any of the + ${EXTRACT_CMD}, + ${EXTRACT_BEFORE_ARGS}, + ${EXTRACT_AFTER_ARGS}, + ${EXTRACT_SUFX}, or + ${DISTFILE} variables, depending on how + alien a format your port's distribution file is. (The most + common case is `EXTRACT_SUFX=.tar.Z', when the + tarball is condensed by regular compress, not gzip.) - You should set ${DISTNAME} to be the base - name of your port. The default rules expect the - distribution file list (${DISTFILES}) to be - named - ${DISTDIR}/${DISTFILE}${EXTRACT_SUFX} - by default which, if it's a normal tarball, is going - to be something like: +

In the worst case, you can simply create your own + `do-extract' target to override the default, though + this should be rarely, if ever, necessary. + + + DISTNAME +

You should set ${DISTNAME} to be the base + name of your port. The default rules expect the + distribution file list (${DISTFILES}) to be + named + ${DISTFILE}${EXTRACT_SUFX} + by default which, if it's a normal tarball, is going to be + something like: foozolix-1.0.tar.gz - For a setting of "DISTNAME=foozolix-1.0" + for a setting of `DISTNAME=foozolix-1.0'. - The default rules also expect the tarball(s) to - extract into a subdirectory called - ${WRKDIR}/${DISTNAME}, e.g. + The default rules also expect the tarball(s) to extract into + a subdirectory called work/${DISTNAME}, e.g. -"/foozolix-1.0/" +work/foozolix-1.0/ - All this behavior can be overridden, of course, it - simply represents the most common time-saving - defaults. For a port requiring multiple distribution - files, simply set ${DISTFILES} explicitly. If - only a subset of ${DISTFILES} are actual - extractable archives, then set them up in - ${EXTRACT_ONLY}, which will override the - ${DISTFILES} list when it comes to extraction. + All this behavior can be overridden, of course, it simply + represents the most common time-saving defaults. For a port + requiring multiple distribution files, simply set + ${DISTFILES} explicitly. If only a subset + of ${DISTFILES} are actual extractable + archives, then set them up in + ${EXTRACT_ONLY}, which will override the + ${DISTFILES} list when it comes to + extraction, and the rest will be just left in + ${DISTDIR} for later use. - If your package uses GNU make, set - "USE_GMAKE=yes". If your package uses GNU - configure, set "GNU_CONFIGURE=yes". - If you want to override the default GNU configure - arguments from `i386--freebsd' to something else, - set those arguments in ${GNU_CONFIGURE_ARGS}. + + CATEGORIES and KEYWORDS +

When a package is created, it is put under + /usr/ports/packages/All and links are made from one + or more subdirectories of /usr/ports/packages. The + names of these subdirectories are specified by the variable + ${CATEGORIES}. 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 CD-ROM. Please take a look + at the existing categories (some of them have different + names from subdirectories of /usr/ports) and pick + the ones that are suitable for your port. If your port + truly belongs to something that is different from all the + existing ones, you can even create a new category name. - If your package uses imake (e.g. is an X - application that has an Imakefile), then set - "USE_IMAKE=yes". This will cause the - configure stage to automatically do an xmkmf and then - a `make Makefiles'. +

If you want to add more information than just the category + names, add them to ${KEYWORDS}. The value + of this variable defaults to that of + ${CATEGORIES}. This is currently used only + as a field of the /usr/ports/INDEX file. - If you have a URL pointing at the the original - tarball, record the directory containing the tarball - in ${MASTER_SITES}. This will provide a - backup site, as well as a direct pointer to the - original source location. + + MASTER_SITES +

If you have a ftp-URL pointing at the the original tarball, + record the directory containing the tarball in + ${MASTER_SITES}. This will provide a backup + site, as well as a direct pointer to the original source + location. Don't forget the trailing slash (/)! - The make macros will currently try to use this - specification for grabbing the distribution file with - ${NCFTP} if they can't find it - already on the system. See some of the other ports - for examples. +

The make macros will try to use this specification for + grabbing the distribution file with ${NCFTP} + if they can't find it already on the system. - Due to a problem in some of the ports, 2.0 was - distributed with a setting which meant ports that - have ${USE_IMAKE} set do not install their - manpages by default. Although -current has the logic - reversed, for compatability with 2.0 systems (at - least until 2.1 comes out) you should set - "INSTALL_MANPAGES=yes". For complete forward - compatability, if the port doesn't understand the - "install.man" target, "NO_INSTALL_MANPAGES=yes" - should be set (which conforms with the current logic - in bsd.port.mk) +

It is recommended that you put multiple sites on this list, + preferably from different continents. This will safeguard + against wide-area network problems, and we are even planning + to add support for automatically determining the closest + master site and fetching from there! - Don't forget to include - <bsd.port.mk> at the bottom. That - should do it! + + PATCHFILES +

If your port requires some additional patches that are + available by ftp, set ${PATCHFILES} to the + names of the files and ${PATCH_SITES} to the + URL of the directory that contains them (the format is the + same as ${MASTER_SITES}). - +

If the patch is not relative to the top of the source tree + (i.e., ${WKRSRC}) because it contains some + extra pathnames, set ${PATCH_DIST_STRIP} + accordingly. For instance, if all the pathnames in the + patch has an extra `foozolix-1.0/' in front of the + filenames, then set `PATCH_DIST_STRIP=-p1'. - +

Don't worry if the patches are compressed, they will be + decompressed automatically if the filenames end with + `.gz' or `.Z'. + + + MAINTAINER +

Set your mail-address here. Please. :) + + + Dependencies +

Many ports depend on other ports. There are three + variables that you can use to ensure that all the required + bits will be on the user's machine. + + LIB_DEPENDS +

This variable specifies the shared libraries this port + depends on. It is a list of `lib:dir' pairs + where lib is the name of the shared library, and + dir is the directory in which to find it in case + it's not available. For example, + +LIB_DEPENDS= tcl\\.7\\.:${PORTSDIR}/lang/tcl + + will check for a shared tcl library with major version 7, + and descend into the lang/tcl subdirectory of + your ports tree to build and install it if it's not found. + + Note that the lib part is just an argument given + to `ldconfig -r | grep', so periods should be + escaped by two backslashes like in the example above. + + EXEC_DEPENDS +

This variable specifies executables this port depends + on. It is a list of `exec:dir' pairs + where exec is the name of the executable, and + dir is the directory in which to find it in case + it's not available. For example, + +EXEC_DEPENDS= wish:${PORTSDIR}/x11/tk + + will check for an executable called `wish', and + descend into the x11/tk subdirectory of your + ports tree to build and install it if it's not found. + + DEPENDS +

If there is a dependency that doesn't fall into either of + the above two categories, or your port requires to have + the source of the other port extracted (i.e., having them + installed is not enough), then use this variable. This is + just a list of directories, as there is nothing to check, + unlike the previous two. + + + Building mechanisms +

If your package uses GNU make, set + `USE_GMAKE=yes'. If your package uses GNU + configure, set `GNU_CONFIGURE=yes'. If + you want to override the default GNU configure + arguments from `--prefix=${PREFIX}' to + something else, set those arguments in + ${CONFIGURE_ARGS}. + +

If your package uses imake (e.g. is an X + application that has an Imakefile), then set + `USE_IMAKE=yes'. This will cause the configure + stage to automatically do an xmkmf -a. If the + `-a' flag is a problem for your port, set + `XMKMF=xmkmf'. + +

If your port's source Makefile has something else than + `all' as the main build target, set + ${ALL_TARGET} accordingly. Same goes for + `install' and ${INSTALL_TARGET}. + + + NO_INSTALL_MANPAGES +

If the port uses imake but doesn't understand the + `install.man' target, + `NO_INSTALL_MANPAGES=yes' should be set. In + addition, the author of the original port should be shot. + + + Licensing Problems +

Some software packages have restrictive licenses or are in + violation to the law (PKP's patent on public key crypto, + ITAR (export of crypto software) to name just two of them). + What we can do with them vary a lot, depending on the exact + wordings of the respective licenses. + +

Note that it is your responsibility as a porter to read the + licensing terms of the software and make sure that the FreeBSD + project won't held accountable of violating them by + redistributing the source or compiled binaries either via ftp + or CD-ROM. If in doubt, please contact + ports@freebsd.org. + +

We usually get around this problem by setting + ${NO_PACKAGE} in the Makefile, and not putting + the distfile up for ftp. However, for most cases, you should + at least be able to make a port, so don't let the license + scare you away! + +

Note: The GNU General Public License (GPL), both version 1 + and 2, shouldn't be a problem for ports. + +

Note: If you are a commiter, make sure you update the + ports/LEGAL file too. + + + * Upgrading +

This section is still under construction, sorry. + + Do's and Dont's -

+

Here's a list of common do's and dont's that you encounter + during the porting process. - Don't leave anything valuable lying around in - ${WRKDIR}, `make clean' will - nuke it completely! If you need auxilliary - files that aren't scripts or patches, put them in - ${FILESDIR}. + + WRKDIR +

Don't leave anything valuable lying around in the + `work' subdirectory, `make clean' will + nuke it completely! If you need auxiliary files + that aren't scripts or patches, put them in the subdirectory + `files' and use the post-extract target to + copy them to the `work' subdirectory. - Do install package information, if possible. It - would sure be nice if `make package' worked - for the whole ports tree this time. + + Package information +

Do install package information, i.e., the three files in + pkg. Note that these files are not used only for + packaging anymore, and are mandatory now, even if + ${NO_PACKAGE} is set. - Do look at existing examples and the - bsd.port.mk file before asking me questions! - ;-) + + Compress manpages, strip binaries +

Do compress manpages and strip binaries. If the original + source already does that, fine; otherwise, you can add a + post-install rule to do it yourself. Make sure + that you check the variable NOMANCOMPRESS that the + user can set in /etc/make.conf to disable man page + compression. Here's an example: + +post-install: + strip ${PREFIX}/bin/xdl +.if !defined(NOMANCOMPRESS) + gzip -9nf ${PREFIX}/man/man1/xdl.1 +.endif + - Do ask me questions if you have any trouble! - Don't just beat your head against a wall! :-) +

Use the file command on the installed executable + to check whether the binary is stripped or not. If it + doesn't say `not stripped', it is stripped. - Don't rely on custom utilities in your local - configure script---they may not be there on the - user's system! If you really need something else to - be installed before you can work, detect this from - your configure script, print a helpful message and - exit with a non-zero status! At least you'll have - given the user some idea of what's needed. If the - custom utility or package is actually part of the - ports tree, then set a pointer to it in your - DEPENDS variable---the port structure will - ensure that all DEPENDS targets are built - first. + + Custom utilities +

Don't rely on custom utilities in your local configure + script or anything -- they may not be there on the user's + system! If you really need something else to be installed + before you can work, detect this from your configure script, + print a helpful message and exit with a non-zero status! At + least you'll have given the user some idea of what's needed. + If the custom utility or package is actually part of the + ports tree, this should be dealt by the dependency mechanism + of ports. - Do send applicable changes/patches to the - original author/maintainer for inclusion in next - release of the code. This will only make your job - that much easier for the next release. - - +

Actually, if this utility is not part of the ports tree you + should probably make a port of this utility (this is how + many of the ports made it into the tree!). Depending on + something that is not part of the main FreeBSD distribution + or the ports tree is a bad idea, and the user should be able + to go to any subdirectory of /usr/ports and type + `make' and have that port, as well as everything it + requires, built automatically. + + Feedback +

Do send applicable changes/patches to the original + author/maintainer for inclusion in next release of the code. + This will only make your job that much easier for the next + release. + + + RCS strings +

Don't put RCS strings in patches. CVS will mangle them + when we put the files into the ports tree, and when we check + them out again, they will come out different and the patch + will fail. RCS strings are surrounded by dollar + (`$') signs, and typically start with + `$Id' or `$RCS'. + + + Recursive diff +

Using the recurse (`-r') option to diff + 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 + 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. + + + PREFIX +

Do try to make your port install relative to + ${PREFIX} in your Makefiles. This will + normally be set to /usr/local, or + /usr/X11R6 if ${USE_IMAKE} or + ${USE_X11} is set, though it can be + reassigned in your Makefile or in the users environment, if + need be. + +

Not hard-coding /usr/local anywhere in your + installation will make the port much more flexible and cater + to the needs of other sites. Note that this doesn't count + for package `packing list' files since they have their own + scheme for relocating themselves and can be left independent + of ${PREFIX} unless the package is one that + hard-codes itself to a compiled-in location. + + + Subdirectories +

Try to let the port put things in the right subdirectories + of ${PREFIX}. Some ports lump everything + and put it in the subdirectory with the port's name, which is + 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 + following: `etc' (setup/configuration files), + `libexec' (executables started internally), + `sbin' (executables for superusers/managers) or + `share' (architecture independent files). See + hier(7) for details, the rule governing + /usr pretty much applies to /usr/local + too. + + + ldconfig +

If your port installs a shared library, add a + post-install target to your Makefile that runs + `ldconfig -m' on the directory where the new + library is installed (usually ${PREFIX}/lib) + to register it into the shared library cache. + +

Also, add an @exec line to your pkg/PLIST + file so that a user who installed the package can start + using the shared library immediately. This line should + immediately follow the line for the shared library itself, + as in: + +lib/libtcl.so.7.3 +@exec ldconfig -m %D/%F + + +

Note: the `-m' option is new since 2.0.5 and + 2.1.0-950726-SNAP, so don't be alarmed if it doesn't work on + your machine. + +

Never, ever, ever add a line that says + `ldconfig' without any arguments to your Makefile + or pkg/PLIST. This will reset the shared library cache to + the contents of /usr/lib only, and will royally + screw up the user's machine ("Help, xinit doesn't run + anymore after I install this port!"). Anybody who does this + will be shot and cut into 65,536 pieces by a rusty knife and + have his liver chopped out by a bunch of crows and will + eternally rot to death in the deepest bowels of hell (not + necessarily in that order).... + + + If you are stuck.... +

Do look at existing examples and the bsd.port.mk + file before asking us questions! ;) + +

Do ask us questions if you have any trouble! Don't just + beat your head against a wall! :) + + + A Sample Makefile +

Here is a sample Makefile that you can use to create a new + port. Make sure you remove all the extra comments (ones + between brackets)! + +

It is recommended that you follow this format (ordering of + variables, etc.). Not all of the existing Makefiles are in + this format (mostly old ones), but we are trying to uniformize + how they look. This format is designed so that the most + important information is easy to locate. + + +[the header...just to make it easier for us to identify the ports] +# New ports collection makefile for: xdvi +# Version required: 2.2 [things like "1.5alpha" are fine here too] +# Date created: 26 May 1995 +[this is the person who did the original port to FreeBSD, in particular, the + person who wrote this Makefile] +# Whom: Satoshi Asami +# +# $Id$ +[ ^^^^ don't worry about this...it will be automatically filled in by CVS when + it is committed to our repository] +# + +[section to describe the package itself and main ftp site - DISTNAME + is always first, followed by PKGNAME (if necessary), CATEGORIES, + KEYWORDs (if necessary) and then MASTER_SITES, and optionally + EXTRACT_SUFX or DISTFILES] +DISTNAME= xdvi +PKGNAME= xdvi-pl18 +CATEGORIES+= printing +[don't forget the trailing slash ("/")!] +MASTER_SITES= ftp://crl.dec.com/pub/X11/contrib/applications/ +[set this if the source is not in the standard ".tar.gz" form] +EXTRACT_SUFX= .tar.Z + +[section for distributed patches -- can be empty] +PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ +PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz + +[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 don't want to have your + address here, set it to "ports@FreeBSD.ORG".] +MAINTAINER= asami@FreeBSD.ORG + +[dependencies -- can be empty] +EXEC_DEPENDS= gs:${PORTSDIR}/print/ghostscript +LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm + +[this section is for other standard bsd.port.mk variables that don't belong to + any of the above] +[If it extracts to a directory other than ${DISTNAME}...] +WRKSRC= ${WRKDIR}/xdvi-new +[If it asks questions during configure, build, install...] +IS_INTERACTIVE= yes +[If it requires "configure" in the distributed source directory to be run...] +HAS_CONFIGURE= yes +[If it requires GNU make, not /usr/bin/make, to build...] +USE_GMAKE= yes +[If it is an X application and requires "xmkmf -a" to be run...] +USE_IMAKE= yes +[et cetera.] + +[non-standard variables to be used in the rules below] +MY_FAVORITE_RESPONSE= "yeah, right" + +[then the special rules, in the order they are called] +pre-fetch: + i go fetch something, yeah + +post-patch: + i need to do something after patch, great + +pre-install: + and then some more stuff before installing, wow + +[and then the epilogue] +.include + + + + Package Names + +

The following are the conventions you should follow in + naming your packages. This is to have our package directory + easy to scan, as there are already lots and lots of packages + and users are going to turn away if they hurt their eyes! + +

If your ${DISTNAME} does not look like + `<name>-<version.string.numbers>', set + ${PKGNAME} to something in that format. + + + The `<name>' part should be all + lowercases, except for a really large package (with lots of + programs in it). Things like XFree86 (yes there really is a + package of it, check it out) and ImageMagick fall into this + category. Otherwise, convert the name (or at least the + first letter) to lowercase. If the software in question + really is called that way, you can have numbers, hyphens and + underscores in the name too. + + The version string should be a period-separated list of + integers and single lowercase alphabets. The only exception + is the string `pl' (meaning `patchlevel'), which can be used + only when there are no major and minor version + numbers in the software. + + +

Here are some (real) examples on how to convert a + ${DISTNAME} into a suitable + ${PKGNAME}: + + +DISTNAME PKGNAME Reason +mule-2.2.2 mule-2.2.2 no prob at all +XFree86-3.1.2 XFree86-3.1.2 ditto +EmiClock-1.0.2 emiclock-1.0.2 no uppercase names for single programs +gmod1.4 gmod-1.4 need hyphen after `' +xmris.4.02 xmris-4.02 ditto +rdist-1.3alpha rdist-1.3a no strings like `alpha' allowed +es-0.9-beta1 es-0.9b1 ditto +v3.3beta021.src jpeg-5a what the heck was that anyway? ;) +tvtwm tvtwm-pl11 version string always required +piewm piewm-1.0 ditto +xvgr-2.10pl1 xvgr-2.10.1 `pl' allowed only when no maj/minor numbers + + +

If there is absolutely no trace of version information in the + original source and it is unlikely that the original author + will ever release another version, just set the version string + to `1.0' (like the piewm example above). Otherwise, ask the + original author or use the date string (`yy.mm.dd') as the + version. + + + That's It, Folks! + +

Boy, this sure was a long tutorial, wasn't it? Thanks for + following us to here, really. + +

Well, now that you know how to do a port, let's go at it and + convert everything in the world into ports! That is the + easiest way to start contributing to the FreeBSD Project! + :)