diff options
Diffstat (limited to 'share/doc/handbook/porting.sgml')
| -rw-r--r-- | share/doc/handbook/porting.sgml | 1422 |
1 files changed, 0 insertions, 1422 deletions
diff --git a/share/doc/handbook/porting.sgml b/share/doc/handbook/porting.sgml deleted file mode 100644 index de29944..0000000 --- a/share/doc/handbook/porting.sgml +++ /dev/null @@ -1,1422 +0,0 @@ -<!-- $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 -of FreeBSD's growth and of great usefulness to those who would not -otherwise know where to turn for it. All ported software is organized -into a carefully organized hierarchy know as ``the ports collection''. -The collection enables a new user to get a quick and complete overview -of what is available for FreeBSD in an easy-to-compile form. It also -saves considerable space by not actually containing the majority -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 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. 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> - - <p>Note: Only a fraction of the overridable variables - (<tt>${..}</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> 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. - - <p>You may come across code that needs modifications or - conditional compilation based upon what version of UNIX it is - 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, NetBSD, and OpenBSD. - - <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><sys/param.h></tt>. Hopefully that file - is already included; if not, add the code: - -<tscreen><verb> -#ifdef (defined(__unix__) || defined(unix)) && !defined(USG) -#include <sys/param.h> -#endif -</verb></tscreen> - - <p>to the proper place in the <tt>.c</tt> file. We believe that every - 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>Another way is to use the GNU Autoconf style of doing this: - -<tscreen><verb> -#ifdef HAVE_SYS_PARAM_H -#include <sys/param.h> -#endif -</verb></tscreen> - - Don't forget to add <tt>-DHAVE_SYS_PARAM_H</tt> to the <tt>CFLAGS</tt> - in the Makefile for this method. - - Once you have <tt><sys/param.h></tt> included, you may use: - -<tscreen><verb> -#if (defined(BSD) && (BSD >= 199103)) -</verb></tscreen> - - 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: - -<tscreen><verb> -#if (defined(BSD) && (BSD >= 199306)) -</verb></tscreen> - - 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). - - The value of the BSD macro is 199506 for the 4.4BSD-Lite2 code - base. This is stated for informational purposes only. It should - not be used to distinguish between version of FreeBSD based only - on 4.4-Lite vs. versions that have merged in changes from 4.4-Lite2. - The __FreeBSD__ macro should be used instead. - - <p>Use sparingly: - - <itemize> - <item><tt>__FreeBSD__</tt> is defined in all versions of - FreeBSD. Use it if the change you are making ONLY affects - FreeBSD. Porting gotchas like the use of - <tt>sys_errlist[]</tt> vs <tt>strerror()</tt> are - 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>. 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 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__ > - 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: - -<tscreen><verb> -#if __FreeBSD__ >= 2 -#include <osreldate.h> -# if __FreeBSD_version >= 199504 - /* 2.0.5+ release specific code here */ -# endif -#endif -</verb></tscreen> -<tt>__FreeBSD_version</tt> values: -<tscreen><verb> -2.0-RELEASE: 199411 -2.1-current's: 199501, 199503 -2.0.5-RELEASE: 199504 -2.2-current before 2.1: 199508 -2.1.0-RELEASE: 199511 -2.2-current before 2.1.5: 199512 -2.1.5-RELEASE: 199607 -2.2-current before 2.1.6: 199608 -2.1.6-RELEASE: 199612 -2.1.7-RELEASE: 199612 -2.2-RELEASE: 220000 -2.2.1-RELEASE: 220000 (yes, no change) -2.2-STABLE after 2.2.1-RELEASE: 220000 (yes, still no change) -2.2-STABLE after texinfo-3.9: 221001 -2.2-STABLE after top: 221002 -2.2.2-RELEASE: 222000 -3.0-current as of May 1997: 300000 -</verb></tscreen> - The pattern used to be year followed by the month, but we - decided to change it to a more straightforward major/minor - system starting from 2.2. This is because the parallel - development on several branches made it infeasible to - classify the releases simply by their real release dates. - (Note that if you are making a port now, you don't have to - worry about old -current's; they are listed here just for - your reference.) - - </itemize> - - <p>In the hundreds of ports that have been done, there have - only been one or two cases where <tt>__FreeBSD__</tt> - should have been used. Just because an earlier port - screwed up and used it in the wrong place does not mean - you should do so too. - - <sect2> - <heading>Quick Porting</heading> - - <p>This section tells you how to do a quick port. In many - cases, it is not enough, but we will see. - - <p>First, get the original tarball and put it into - <tt>${DISTDIR}</tt>, which defaults to - <tt>/usr/ports/distfiles</tt>. - - <p>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 will have to refer to the next section - too. - - <sect3> - <heading>Writing the Makefile</heading> - - <p>The minimal <tt>Makefile</tt> would look something like this: - -<tscreen><verb> - # New ports collection makefile for: oneko - # Version required: 1.1b - # Date created: 5 December 1994 - # Whom: asami - # - # $Id$ - # - - DISTNAME= oneko-1.1b - CATEGORIES= games - MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - - MAINTAINER= asami@FreeBSD.ORG - - USE_IMAKE= yes - - .include <bsd.port.mk> -</verb></tscreen> - - <p>See if you can figure it out. Do not worry about the contents - of the <tt>$Id$</tt> line, it will be filled in - automatically by CVS when the port is imported to our main - ports tree. You can find a more detailed example in the <ref - id="porting:samplem" name="sample Makefile"> section. - - <sect3> - <heading>Writing the description files</heading> - - <p>There are three required description files that are - required for any port, whether they actually package or not. - They are <tt>COMMENT</tt>, <tt>DESCR</tt>, and - <tt>PLIST</tt>, and reside in the <tt>pkg</tt> subdirectory. - - <sect4> - <heading>COMMENT</heading> - - <p>This is the one-line description of the port. <em>PLEASE - do not include the package name (or version number of the - software) in the comment.</em> - Here is an example: -<tscreen><verb> -A cat chasing a mouse all over the screen. -</verb></tscreen> - - <sect4> - <heading>DESCR</heading> - - <p>This is a longer description of the port. One to a few - 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, <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 - this file, as in: - -<tscreen><verb> -This is a port of oneko, in which a cat chases a poor mouse all over -the screen. - : -(etc.) - -- Satoshi -asami@cs.berkeley.edu -</verb></tscreen> - - <sect4> - <heading>PLIST</heading> - - <p>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 - <tt>/usr/local</tt> or <tt>/usr/X11R6</tt>) Also it is assumed - the manpages will be compressed. - - <p>Here is a small example: - -<tscreen><verb> -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 -</verb></tscreen> - - <p>Refer to the <tt>pkg_create(1)</tt> man page for details - on the packing list. - - <sect3> - <heading>Creating the checksum file</heading> - - <p>Just type `<tt>make makesum</tt>'. The ports make rules - will automatically generate the file <tt>files/md5</tt>. - - <sect3> - <heading>Testing the port</heading> - - <p>You should make sure that the port rules do exactly what - you want it to do, including packaging up the port. Try - doing `<tt>make install</tt>', `<tt>make package</tt>' and - then `<tt>pkg_delete -d <pkgname></tt>' and see if all - the files are correctly deleted. Then do a `<tt>pkg_add - <pkgname>.tgz</tt>' and see if everything re-appears - and works correctly. - - <sect3> - <heading>Submitting the port<label id="porting:submitting"></heading> - - <p>Now that you are 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 <em>not</em> include the - original source tarball, the `<tt>work</tt>' subdirectory or - the package) into a <tt>.tar.gz</tt> file, stick it in the - directory -<tscreen><verb> -ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ -</verb></tscreen> - and send mail to us using <tt>send-pr(1)</tt> (please - classify it as category `ports' and class `change-request'). - 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?!? <tt>:)</tt> - - <sect2> - <heading>Slow Porting</heading> - - <p>Ok, so it was not that simple, and the port required some - modifications to get it to work. In this section, we will - explain, step by step, how to modify it to get it to work with - the ports paradigm. - - <sect3> - <heading>How things work</heading> - - <p>First, this is the sequence of events which occurs when the - user first types `<tt>make</tt>' in your port's directory, - and you may find that having <tt>bsd.port.mk</tt> in another - window while you read this really helps to understand it. - - <p>But do not worry if you do not really understand what - <tt>bsd.port.mk</tt> is doing, not many people - do... <tt>:></tt> - - <enum> - <item>The fetch target is run. The fetch target is - responsible for making sure that the tarball exists - locally in <tt>${DISTDIR}</tt>. If fetch cannot - find the required files in <tt>${DISTDIR}</tt> it - will look up the URL <tt>${MASTER_SITES}</tt>, - which is set in the Makefile, as well as our main ftp - site at <htmlurl - url="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/" - name="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,"> - where we put sanctioned distfiles as backup. It will then - attempt to - fetch the named distribution file with - <tt>${FETCH}</tt>, assuming that the requesting - site has direct access to the Internet. If that succeeds, - it will save the file in <tt>${DISTDIR}</tt> for - future use and proceed. - - <item>The extract target is run. It looks for your ports' - distribution file in <tt>${DISTDIR}</tt> (typically - a gzip'd tarball) and unpacks it into a temporary - subdirectory specified by <tt>${WRKDIR}</tt> - (defaults to <tt>work</tt>). - - <item>The patch target is run. First, any patches defined - in <tt>${PATCHFILES}</tt> are applied. Second, if - any patches are found in <tt>${PATCHDIR}</tt> - (defaults to the <tt>patches</tt> subdirectory), they are - applied at this time in alphabetical order. - - <item>The configure target is run. This can do any one of - many different things. - - <enum> - - <item>If it exists, <tt>scripts/configure</tt> is run. - - <item>If <tt>${HAS_CONFIGURE}</tt> or - <tt>${GNU_CONFIGURE}</tt> is set, - <tt>${WRKSRC}/configure</tt> is run. - - <item>If <tt>${USE_IMAKE}</tt> is set, - <tt>${XMKMF}</tt> (default: `<tt>xmkmf - -a</tt>') is run. - - </enum> - - <item>The build target is run. This is responsible for - descending into the ports' private working directory - (<tt>${WRKSRC}</tt>) and building it. If - <tt>${USE_GMAKE}</tt> is set, GNU <tt>make</tt> - will be used, otherwise the system <tt>make</tt> will be - used. - - </enum> - - <p>The above are the default actions. In addition, you can - define targets `<tt>pre-<something></tt>' or - `<tt>post-<something></tt>', or put scripts with those - names, in the <tt>scripts</tt> subdirectory, and they will - be run before or after the default actions are done. - - <p>For example, if you have a <tt>post-extract</tt> target - defined in your Makefile, and a file <tt>pre-build</tt> in - the <tt>scripts</tt> subdirectory, the - <tt>post-extract</tt> target will be called after the - regular extraction actions, and the <tt>pre-build</tt> - script will be executed before the default build rules are - done. It is recommended that you use Makefile targets if - the actions are simple enough, because it will be easier for - someone to figure out what kind of non-default action the - port requires. - - <p>The default actions are done by the <tt>bsd.port.mk</tt> - targets `<tt>do-<something></tt>'. For example, the - commands to extract a port are in the target - `<tt>do-extract</tt>'. If you are not happy with the - default target, you can fix it by redefining the - `<tt>do-<something></tt>' target in your Makefile. - - <p>Note that the `main' targets (e.g., <tt>extract</tt>, - <tt>configure</tt>, 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 - <tt>do-extract</tt>, but never ever touch <tt>extract</tt>! - - <p>Now that you understand what goes on when the user types - `<tt>make</tt>', let us go through the recommended steps to - create the perfect port. - - <sect3> - <heading>Getting the original sources</heading> - - <p>Get the original sources (normally) as a compressed tarball - (<tt><foo>.tar.gz</tt> or <tt><foo>.tar.Z</tt>) - and copy it into <tt>${DISTDIR}</tt>. Always use - <em>mainstream</em> sources when and where you can. - - <p>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, we can `house' it ourselves by putting - it on -<tscreen><verb> -ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/ -</verb></tscreen> - as the last resort. Please refer to this localation as - <tt>${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 - available on the Internet, fetch them too and put them in - <tt>${DISTDIR}</tt>. Do not worry if they come from - site other than where you got the main source tarball, - we have a way to handle these situations (see the - description of <ref id="porting:patchfiles" - name="${PATCHFILES}"> below). - - <sect3> - <heading>Modifying the port</heading> - - <p>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 - <em>careful track</em> 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. - - <p>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. - - <p>Note: Unless explicitly stated, patch files, scripts, and - other files you have created and contributed to the FreeBSD - ports collection are assumed to be covered by the standard - BSD copyright conditions. - - <sect3> - <heading>Patching</heading> - - <p>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. Each set of patches you wish to apply - should be collected into a file named - `<tt>patch-<xx></tt>' where <tt><xx></tt> - denotes the sequence in which the patches will be applied -- - these are done in <em>alphabetical order</em>, thus - `<tt>aa</tt>' first, `<tt>ab</tt>' second and so on. These - files should be stored in <tt>${PATCHDIR}</tt>, from - where they will be automatically applied. All patches - should be relative to <tt>${WRKSRC}</tt> (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-aa and patch-ab both changing - <tt>${WRKSRC}</tt>/foobar.c). - - <sect3> - <heading>Configuring</heading> - - <p>Include any additional customization commands to your - <tt>configure</tt> script and save it in the - `<tt>scripts</tt>' subdirectory. As mentioned above, you - can also do this as Makefile targets and/or scripts with the - name <tt>pre-configure</tt> or <tt>post-configure</tt>. - - <sect3> - <heading>Handling user input</heading> - - <p>If your port requires user input to build, configure or - install, then set <tt>IS_INTERACTIVE</tt> in your Makefile. - This will allow `overnight builds' to skip your port if the - user sets the variable <tt>BATCH</tt> in his environment - (and if the user sets the variable <tt>INTERACTIVE</tt>, - then <em>only</em> those ports requiring interaction are - built). - - <sect2> - <heading>Configuring the Makefile</heading> - - <p>Configuring the Makefile is pretty simple, and again we - suggest that you look at existing examples before starting. - Also, there is a <ref id="porting:samplem" name="sample - Makefile"> in this handbook, so take a look and please follow - the ordering of variables and sections in that template to - make your port easier for others to read. - - <p>Now, consider the following problems in sequence as you - design your new Makefile: - - <sect3> - <heading>The original source</heading> - - <p>Does it live in <tt>${DISTDIR}</tt> 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 - <tt>${EXTRACT_CMD}</tt>, - <tt>${EXTRACT_BEFORE_ARGS}</tt>, - <tt>${EXTRACT_AFTER_ARGS}</tt>, - <tt>${EXTRACT_SUFX}</tt>, or - <tt>${DISTFILES}</tt> variables, depending on how - alien a format your port's distribution file is. (The most - common case is `<tt>EXTRACT_SUFX=.tar.Z</tt>', when the - tarball is condensed by regular compress, not gzip.) - - <p>In the worst case, you can simply create your own - `<tt>do-extract</tt>' target to override the default, though - this should be rarely, if ever, necessary. - - <sect3> - <heading>DISTNAME</heading> - - <p>You should set <tt>${DISTNAME}</tt> to be the base - name of your port. The default rules expect the - distribution file list (<tt>${DISTFILES}</tt>) to be - named - <tt>${DISTNAME}${EXTRACT_SUFX}</tt> - by default which, if it is a normal tarball, is going to be - something like: -<tscreen><verb> -foozolix-1.0.tar.gz -</verb></tscreen> - for a setting of `<tt>DISTNAME=foozolix-1.0</tt>'. - - The default rules also expect the tarball(s) to extract into - a subdirectory called <tt>work/${DISTNAME}</tt>, e.g. -<tscreen><verb> -work/foozolix-1.0/ -</verb></tscreen> - - 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 - <tt>${DISTFILES}</tt> explicitly. If only a subset - of <tt>${DISTFILES}</tt> are actual extractable - archives, then set them up in - <tt>${EXTRACT_ONLY}</tt>, which will override the - <tt>${DISTFILES}</tt> list when it comes to - extraction, and the rest will be just left in - <tt>${DISTDIR}</tt> for later use. - - <sect3> - <heading>CATEGORIES</heading> - - <p>When a package is created, it is put under - <tt>/usr/ports/packages/All</tt> and links are made from one - or more subdirectories of <tt>/usr/ports/packages</tt>. The - names of these subdirectories are specified by the variable - <tt>${CATEGORIES}</tt>. 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 (you can find them in <htmlurl - url="http://www.freebsd.org/ports/" name="the ports - page">) 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. - - <sect3> - <heading>MASTER_SITES</heading> - - <p>Record the directory part of the ftp/http-URL pointing at - the original tarball in <tt>${MASTER_SITES}</tt>. - Do not forget the trailing slash (<tt>/</tt>)! - - <p>The make macros will try to use this specification for - grabbing the distribution file with <tt>${FETCH}</tt> - if they cannot find it already on the system. - - <p>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! - - <p>If the original tarball is part of one of the following - popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or - Linux Sunsite, you refer to those sites in an easy compact - form using MASTER_SITE_XCONTRIB, MASTER_SITE_GNU, - MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and - MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the path - with in the archive. Here is an example: -<tscreen><verb> -MASTER_SITES= ${MASTER_SITE_XCONTRIB} -MASTER_SITE_SUBDIR= applications -</verb></tscreen> - <p>The user can also set the MASTER_SITE_* variables in - <tt>/etc/make.conf</tt> to override our choices, and use their - favorite mirrors of these popular archives instead. - - <sect3> - <heading>PATCHFILES<label id="porting:patchfiles"></heading> - - <p>If your port requires some additional patches that are - available by ftp or http, set <tt>${PATCHFILES}</tt> - to the names of the files and <tt>${PATCH_SITES}</tt> - to the URL of the directory that contains them (the format - is the same as <tt>${MASTER_SITES}</tt>). - - <p>If the patch is not relative to the top of the source tree - (i.e., <tt>${WKRSRC}</tt>) because it contains some - extra pathnames, set <tt>${PATCH_DIST_STRIP}</tt> - accordingly. For instance, if all the pathnames in the - patch has an extra `<tt>foozolix-1.0/</tt>' in front of the - filenames, then set `<tt>PATCH_DIST_STRIP=-p1</tt>'. - - <p>Do not worry if the patches are compressed, they will be - decompressed automatically if the filenames end with - `<tt>.gz</tt>' or `<tt>.Z</tt>'. - - <p>If the patch is distributed with some other files, such as - documentation, in a gzip'd tarball, you can't just use - <tt>${PATCHFILES}</tt>. If that is the case, add the - name and the location of the patch tarball to - <tt>${DISTFILES}</tt> and - <tt>${MASTER_SITES}</tt>. Then, from the - <tt>pre-patch</tt> target, apply the patch either by running - the patch command from there, or copying the patch file into - the <tt>${PATCHDIR}</tt> directory and calling it - <tt>patch-<xx></tt>. (Note 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 exists in that - directory. Also do not forget to add a command to remove - the copied patch in the <tt>pre-clean</tt> target. - - <sect3> - <heading>MAINTAINER</heading> - - <p>Set your mail-address here. Please. <tt>:)</tt> - - <p>For detailed description of the responsibility of maintainers, - refer to <ref id="policies:maintainer" - name="MAINTAINER on Makefiles"> section. - - <sect3> - <heading>Dependencies</heading> - - <p>Many ports depend on other ports. There are five - variables that you can use to ensure that all the required - bits will be on the user's machine. - - <sect4> - <heading>LIB_DEPENDS</heading> - - <p>This variable specifies the shared libraries this port - depends on. It is a list of `<tt>lib:dir</tt>' pairs - where <tt>lib</tt> is the name of the shared library, and - <tt>dir</tt> is the directory in which to find it in case - it is not available. For example, -<tscreen><verb> -LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg -</verb></tscreen> - will check for a shared jpeg library with major version 6, - and descend into the <tt>graphics/jpeg</tt> subdirectory - of your ports tree to build and install it if it is not - found. - - Note that the <tt>lib</tt> part is just an argument given - to `<tt>ldconfig -r | grep</tt>', so periods should be - escaped by two backslashes like in the example above. - - The dependency is checked from within the <tt>extract</tt> - target. Also, the name of the dependency is put in to the - package so that <tt>pkg_add</tt> will automatically - install it if it is not on the user's system. - - <sect4> - <heading>RUN_DEPENDS</heading> - - <p>This variable specifies executables or files this port - depends on during run-time. It is a list of - `<tt>path:dir</tt>' pairs where <tt>path</tt> is the name - of the executable or file, and <tt>dir</tt> is the - directory in which to find it in case it is not - available. If <tt>path</tt> starts with a slash - (<tt>/</tt>), it is treated as a file and its existence is - tested with `<tt>test -e</tt>'; otherwise, it is assumed - to be an executable, and `<tt>which -s</tt>' is used to - determine if the program exists in the user's search path. - - <p>For example, -<tscreen><verb> -RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ - wish:${PORTSDIR}/x11/tk -</verb></tscreen> - will check if the file `<tt>/usr/local/etc/innd</tt>' - exists, and build and install it from the - <tt>news/inn</tt> subdirectory of the ports tree if it is - not found. It will also see if an executable called - `<tt>wish</tt>' is in your search path, and descend into - the <tt>x11/tk</tt> subdirectory of your ports tree to - build and install it if it is not found. (Note that in - this case, `<tt>innd</tt>' is actually an executable; if - an executable is in a place that is not expected to be in - a normal user's search path, you should use the full - pathname.) - - The dependency is checked from within the <tt>install</tt> - target. Also, the name of the dependency is put in to the - package so that <tt>pkg_add</tt> will automatically - install it if it is not on the user's system. - - <sect4> - <heading>BUILD_DEPENDS</heading> - - <p>This variable specifies executables or files this port - requires to build. Like <tt>RUN_DEPENDS</tt>, it is a - list of `<tt>path:dir</tt>' pairs. For example, -<tscreen><verb> -BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip -</verb></tscreen> - will check for an executable called `<tt>unzip</tt>', and - descend into the <tt>archivers/unzip</tt> subdirectory of - your ports tree to build and install it if it is not found. - - Note that `build' here means everything from extracting to - compilation. The dependency is checked from within the - <tt>extract</tt> target. - - <sect4> - <heading>FETCH_DEPENDS</heading> - - <p>This variable specifies executables or files this port - requires to fetch. Like the previous two, it is a list of - `<tt>path:dir</tt>' pairs. For example, -<tscreen><verb> -FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 -</verb></tscreen> - will check for an executable called `<tt>ncftp2</tt>', and - descend into the <tt>net/ncftp2</tt> subdirectory of - your ports tree to build and install it if it is not found. - - The dependency is checked from within the <tt>fetch</tt> - target. - - <sect4> - <heading>DEPENDS</heading> - - <p>If there is a dependency that does not fall into either of - the above four 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 four. - - <sect3> - <heading>Building mechanisms</heading> - - <p>If your package uses GNU <tt>make</tt>, set - `<tt>USE_GMAKE=yes</tt>'. If your package uses GNU - <tt>configure</tt>, set `<tt>GNU_CONFIGURE=yes</tt>'. If - you want to give some extra arguments to GNU - <tt>configure</tt> (other than the default - `<tt>--prefix=${PREFIX}</tt>'), - set those extra arguments in - <tt>${CONFIGURE_ARGS}</tt>. - - <p>If your package is an X application that creates Makefiles - from Imakefiles using <tt>imake</tt>, then set - `<tt>USE_IMAKE=yes</tt>'. This will cause the configure - stage to automatically do an <tt>xmkmf -a</tt>. If the - `<tt>-a</tt>' flag is a problem for your port, set - `<tt>XMKMF=xmkmf</tt>'. - - <p>If your port's source Makefile has something else than - `<tt>all</tt>' as the main build target, set - <tt>${ALL_TARGET}</tt> accordingly. Same goes for - `<tt>install</tt>' and <tt>${INSTALL_TARGET}</tt>. - - <sect3> - <heading>NO_INSTALL_MANPAGES</heading> - - <p>If the port uses imake but does not understand the - `<tt>install.man</tt>' target, - `<tt>NO_INSTALL_MANPAGES=yes</tt>' should be set. In - addition, the author of the original port should be - shot. <tt>:></tt> - - <sect2> - <heading>Ports that require Motif</heading> - - <p>There are many programs that require a Motif library - (available from several commercial vendors, while there is (at - least) one effort to create a free clone) to compile. Since - it is a popular toolkit and their licenses usually permit - redistribution of statically linked binaries, we have made - special provisions for handling ports that require Motif in a - way that we can easily compile binaries linked either - dynamically or statically. - - <sect3> - <heading>REQUIRES_MOTIF</heading> - - <p>If your port requires Motif, define this variable in the - Makefile. This will prevent people who don't own a copy of - Motif from even attempting to build it. - - <sect3> - <heading>${MOTIFLIB}</heading> - - <p>This variable will be set by <tt>bsd.port.mk</tt> to be the - appropriate reference to the Motif library. Please patch - the source to use this wherever the Motif library is - referenced in the Makefile or Imakefile. - - <p>There are two common cases: - <enum> - <item>If the port refers to the Motif library as - `<tt>-lXm</tt>' in its Makefile or Imakefile, simply - substitute `<tt>${MOTIFLIB}</tt>' for it. - - <item>If the port uses `<tt>XmClientLibs</tt>' in its - Imakefile, change it to `<tt>${MOTIFLIB} - ${XTOOLLIB} ${XLIB}</tt>'. - </enum> - - <p>Note that <tt>${MOTIFLIB}</tt> (usually) expands to - `<tt>-L/usr/X11R6/lib -lXm</tt>' or - `<tt>/usr/X11R6/lib/libXm.a</tt>', so there is no need to - add `<tt>-L</tt>' or `<tt>-l</tt>' in front. - - <sect2> - <heading>Licensing Problems</heading> - - <p>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. - - <p>Note that it is your responsibility as a porter to read the - licensing terms of the software and make sure that the FreeBSD - project will not be held accountable of violating them by - redistributing the source or compiled binaries either via ftp - or CD-ROM. If in doubt, please contact the &a.ports;. - - <p>There are two variables you can set in the Makefile to handle - the situations that arise frequently: - - <enum> - <item>If the port has a `do not sell for profit' type of - license, set the variable <tt>NO_CDROM</tt>. We will make - sure such ports won't go into the CD-ROM come release time. - The distfile and package will still be available via ftp. - - <item>If the resulting package needs to be built uniquely for - each site, or the resulting binary package can't be distributed - due to licensing; set the variable <tt>NO_PACKAGE</tt>. - We will make sure such packages won't go on the ftp site, nor - into the CD-ROM come release time. The distfile will still be - included on both however. - - <item>If the port has legal restrictions on who can use it - (e.g., crypto stuff) or has a `no commercial use' license, - set the variable <tt>RESTRICTED</tt> to be the string - describing the reason why. For such ports, the - distfiles/packages will not be available even from our ftp - sites. - </enum> - - <p>Note: The GNU General Public License (GPL), both version 1 - and 2, should not be a problem for ports. - - <p>Note: If you are a committer, make sure you update the - <tt>ports/LEGAL</tt> file too. - - <sect2> - <heading>Upgrading</heading> - - <p>When you notice that a port is out of date compared to the - latest version from the original authors, first make sure you - have the latest port. You can find them in the - <tt>ports-current</tt> directory of the ftp mirror sites. - - <p>The next step is to send a mail to the maintainer, if one is - listed in the port's Makefile. That person may already be - working on an upgrade, or have a reason to not upgrade the - port right now (because of, for example, stability problems - of the new version). - - <p>If the maintainer asks you to do the upgrade or there isn't - any such person to begin with, please make the upgrade and - send the recursive diff of the new and old ports directories - 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 - -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> (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. - - <sect2> - <heading>Do's and Dont's</heading> - - <p>Here is a list of common do's and dont's that you encounter - during the porting process. - - <sect3> - <heading>WRKDIR</heading> - - <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 - <tt>${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 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>${NO_PACKAGE}</tt> is set. - - <sect3> - <heading>Compress manpages, strip binaries</heading> - - <p>Do compress manpages and strip binaries. If the original - source already strips the binary, fine; otherwise, you can add a - <tt>post-install</tt> rule to do it yourself. Here is an example: -<tscreen><verb> - post-install: - strip ${PREFIX}/bin/xdl -</verb></tscreen> - <p>Use the <tt>file</tt> command on the installed executable - to check whether the binary is stripped or not. If it - does not say `not stripped', it is stripped. - - <p>To automagically compress the manpages, use the MAN[1-9LN] - variables. They will check the variable - <tt>NOMANCOMPRESS</tt> that the user can set in - <tt>/etc/make.conf</tt> to disable man page compression. - Place them last in the section below the - <tt>MAINTAINER</tt> variable. Here is an example: -<tscreen><verb> -MAN1= foo.1 bar.1 -MAN5= foo.conf.5 -MAN8= baz.8 -</verb></tscreen> - <p>Note that this is not usually necessary with ports that are X - applications and use Imake to build. - - <p>If your port anchors its man tree somewhere other than - <tt>PREFIX</tt>, you can use the <tt>MANPREFIX</tt> to set it. - Also, if only manpages in certain section go in a - non-standard place, such as many Perl modules ports, you - can set individual man paths using - <tt>MAN<em>sect</em>PREFIX</tt> (where <em>sect</em> is one - of 1-9, L or N). - - <sect3> - <heading>INSTALL_* macros</heading> - <p>Do use the macros provided in <tt>bsd.port.mk</tt> to - ensure correct modes and ownership of files in your own - *-install targets. They are: - - <itemize> - <item><tt>${INSTALL_PROGRAM}</tt> is a command to install - binary executables. - <item><tt>${INSTALL_SCRIPT}</tt> is a command to install - executable scripts. - <item><tt>${INSTALL_DATA}</tt> is a command to install - sharable data. - <item><tt>${INSTALL_MAN}</tt> is a command to install - manpages and other documentation (it doesn't compress anything). - </itemize> - - <p>These are basically the <tt>install</tt> command with all - the appropriate flags. See below for an example on how to - use them. - - <sect3> - <heading>INSTALL package script</heading> - <p>If your port needs execute commands when the binary package - is installed with pkg_add you can do with via the pkg/INSTALL - script. This script will automatically be added to the - package, and will be run twice by pkg_add. The first time - will as `<tt>INSTALL ${PKGNAME} PRE-INSTALL</tt>' - and the second time as `<tt>INSTALL ${PKGNAME} POST-INSTALL</tt>'. - `<tt>$2</tt>' can be tested to determine which mode - the script is being run in. - The `<tt>PKG_PREFIX</tt>' environmental variable will be set to - the package installation directory. See man <tt>pkg_add(1)</tt> - for additional information. - Note, that this script is not run automatically if you install - the port with `<tt>make install</tt>'. If you are depending - on it being run, you will have to explicitly call it on your - port's Makefile. - - <sect3> - <heading>REQ package script</heading> - <p>If your needs to determine if it should install or not, you - can create a pkg/REQ ``requirements'' script. It will be invoked - automatically at installation/deinstallation time to determine - whether or not installation/deinstallation should proceed. - See man <tt>pkg_create(1)</tt> and man <tt>pkg_add(1)</tt> for - more information. - - <sect3> - <heading>Install additional documentation</heading> - - <p>If your software has some documentation other than the - standard man and info pages that you think is useful for the - user, install it under <tt>${PREFIX}/share/doc</tt>. - This can be done, like the previous item, in the - <tt>post-install</tt> target. - - <p>Create a new directory for your port. The directory name - should reflect what the port is. This usually means - <tt>${PKGNAME}</tt> minus the version part. However, - if you think the user might want different versions of the - port to be installed at the same time, you - can use the whole <tt>${PKGNAME}</tt>. - - <p>Make the installation dependent to the variable - <tt>NOPORTDOCS</tt> so that users can disable it in - <tt>/etc/make.conf</tt>, like this: -<tscreen><verb> - post-install: - .if !defined(NOPORTDOCS) - ${MKDIR} ${PREFIX}/share/doc/xv - ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv - .endif -</verb></tscreen> - - <p>Do not forget to add them to <tt>pkg/PLIST</tt> too! (Do not - worry about <tt>NOPORTDOCS</tt> here; there is currently no - way for the packages to read variables from - <tt>/etc/make.conf</tt>.) - - <p>If you need to display a message to the installer, you may - place the message in <tt>pkg/MESSAGE</tt>. This capibility - is often useful to display additional installation steps to - be taken after a pkg_add, or to display licensing information. - (note: the MESSAGE file does not need to be added to pkg/PLIST). - - - <sect3> - <heading>DIST_SUBDIR</heading> - - <p>Do not let your port clutter <tt>/usr/ports/distfiles</tt>. If - your port requires a lot of files to be - fetched, or contains a file that has a name that might conflict - with other ports (e.g., `Makefile'), set - <tt>${DIST_SUBDIR}</tt> to the name of the port - (<tt>${PKGNAME}</tt> without the version part should work - fine). This will change <tt>${DISTDIR}</tt> from the - default <tt>/usr/ports/distfiles</tt> to - <tt>/usr/ports/distfiles/${DIST_SUBDIR}</tt>, and in - effect puts everything that is required for your port into that - subdirectory. - - <p>It will also look at the subdirectory with the same name on the - backup master site at <tt>ftp.freebsd.org</tt>. (Setting - <tt>${DISTDIR}</tt> explicitly in your Makefile will not - accomplish this, so please use <tt>${DIST_SUBDIR}</tt>.) - - <p>Note this does not affect the <tt>${MASTER_SITES}</tt> - you define in your Makefile. - - <sect3> - <heading>Feedback</heading> - - <p>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. - - <sect3> - <heading>RCS strings</heading> - - <p>Do not 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 - (`<tt>$</tt>') signs, and typically start with - `<tt>$Id</tt>' or `<tt>$RCS</tt>'. - - <sect3> - <heading>Recursive diff</heading> - - <p>Using the recurse (`<tt>-r</tt>') option to <tt>diff</tt> - 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 - <tt>post-extract</tt> target rather than as part of the - patch. Once you are happy with the resuling diff, please - split it up into one source file per patch file. - - <sect3> - <heading>PREFIX</heading> - - <p>Do try to make your port install relative to - <tt>${PREFIX}</tt>. (The value of this variable will be - set to <tt>${LOCALBASE}</tt> (default - <tt>/usr/local</tt>), unless <tt>${USE_IMAKE}</tt> or - <tt>${USE_X11}</tt> is set, in which case it will be - <tt>${X11BASE}</tt> (default <tt>/usr/X11R6</tt>).) - - <p>Not hard-coding `<tt>/usr/local</tt>' or `<tt>/usr/X11R6</tt>' - anywhere in the source will make the port much more flexible and - able to cater to the needs of other sites. For X ports that use - imake, this is automatic; otherwise, this can often be done by - simply replacing the occurrences of `<tt>/usr/local</tt>' (or - `<tt>/usr/X11R6</tt>' for X ports that do not use imake) in the - various scripts/Makefiles in the port to read - `<tt>${PREFIX}</tt>', as this variable is automatically - passed down to every stage of the build and install processes. - - <p>The variable <tt>${PREFIX}</tt> can be reassigned in your - Makefile or in the user's environment. However, it is strongly - discouraged for individual ports to set this variable explicitly - in the Makefiles. (If your port is an X port but does not use - imake, set <tt>USE_X11=yes</tt>; this is quite different from - setting <tt>PREFIX=/usr/X11R6</tt>.) - - <p>Also, refer to programs/files from other ports with the - variables mentioned above, not explicit pathnames. For instance, - if your port requires a macro <tt>PAGER</tt> to be the full - pathname of <tt>less</tt>, use the compiler flag: - <verb>-DPAGER=\"${PREFIX}/bin/less\"</verb> or - <verb>-DPAGER=\"${LOCALBASE}/bin/less\"</verb> if this is an - X port, instead of <verb>-DPAGER=\"/usr/local/bin/less\"</verb>. - This way it will have a better chance of working if the system - administrator has moved the whole `/usr/local' tree somewhere - else. - - <sect3> - <heading>Subdirectories</heading> - - <p>Try to let the port put things in the right subdirectories - of <tt>${PREFIX}</tt>. 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 - `<tt>lib</tt>', which does not bode well with the BSD - 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), - `<tt>info</tt>' (documentation for info browser) or - `<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. The exception are ports dealing with USENET `news'. - They may use <tt>${PREFIX}/news</tt> as a destination - for their files. - - <sect3> - <heading>ldconfig</heading> - - <p>If your port installs a shared library, add a - <tt>post-install</tt> target to your Makefile that runs - `<tt>/sbin/ldconfig -m</tt>' on the directory where the new - library is installed (usually <tt>${PREFIX}/lib</tt>) - to register it into the shared library cache. - - <p>Also, add an <tt>@exec</tt> line to your <tt>pkg/PLIST</tt> - 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: -<tscreen><verb> -lib/libtcl.so.7.3 -@exec /sbin/ldconfig -m %D/lib -</verb></tscreen> - - <p>Never, ever, <em>ever</em> add a line that says - `<tt>ldconfig</tt>' without any arguments to your Makefile - or pkg/PLIST. This will reset the shared library cache to - the contents of <tt>/usr/lib</tt> only, and will royally - screw up the user's machine ("Help, xinit does not 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).... - - <sect3> - <heading>If you are stuck....</heading> - - <p>Do look at existing examples and the <tt>bsd.port.mk</tt> - file before asking us questions! <tt>;)</tt> - - <p>Do ask us questions if you have any trouble! Do not just - beat your head against a wall! <tt>:)</tt> - - <sect2> - <heading>A Sample Makefile<label id="porting:samplem"></heading> - - <p>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)! - - <p>It is recommended that you follow this format (ordering of - variables, empty lines between sections, 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. - -<tscreen><verb> - [the header...just to make it easier for us to identify the ports] - # New ports collection makefile for: xdvi - # Version required: pl18 [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 <asami@FreeBSD.ORG> - # - # $Id$ - [ ^^^^ This will be automatically replaced with RCS ID string by CVS - when it is committed to our repository.] - # - - [section to describe the port itself and the master site - DISTNAME - is always first, followed by PKGNAME (if necessary), CATEGORIES, - and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. - After those, one of EXTRACT_SUFX or DISTFILES can be specified too.] - DISTNAME= xdvi - PKGNAME= xdvi-pl18 - CATEGORIES= print - [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] - 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 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] - [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] - PATCH_DIST_STRIP= -p1 - [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 - [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 <bsd.port.mk> -</verb></tscreen> - - <sect2> - <heading>Package Names</heading> - - <p>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! - - <p>The package name should look like - -<tscreen><verb> -[<language>-]<name>[[-]<compiled.specifics>]-<version.string.numbers>; -</verb></tscreen> - - If your <tt>${DISTNAME}</tt> doesn't look like that, - set <tt>${PKGNAME}</tt> to something in that format. - - <enum> - <item>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, - `ru' for Russian, `vn' for Vietnamese, `cn' for Chinese, - and `kr' for Korean. - - <item>The `<tt><name></tt>' 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 (like `kinput2'). - - <item>If the port can be built with different hardcoded - defaults (usually specified as environment variables or on - the <tt>make</tt> command line), the - `<compiled.specifics>' part should state the - compiled-in defaults (the hyphen is optional). Examples are - papersize and font units. - - <item>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 - <em>only</em> when there are no major and minor version - numbers in the software. - </enum> - - <p>Here are some (real) examples on how to convert a - <tt>${DISTNAME}</tt> into a suitable - <tt>${PKGNAME}</tt>: - -<tscreen><verb> -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 `<name>' -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 tiff-3.3 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 -gawk-2.15.6 jp-gawk-2.15.6 Japanese language version -psutils-1.13 psutils-letter-1.13 papersize hardcoded at package build time -pkfonts pkfonts300-1.0 package for 300dpi fonts -</verb></tscreen> - - <p>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. - - <sect2> - <heading>That is It, Folks!</heading> - - <p>Boy, this sure was a long tutorial, wasn't it? Thanks for - following us to here, really. - - <p>Well, now that you know how to do a port, let us go at it and - convert everything in the world into ports! That is the - easiest way to start contributing to the FreeBSD Project! - <tt>:)</tt> |
