![[OpenBSD]](images/smalltitle.gif){kind=small}
+
+
+
- -
-
/usr/ports/infrastructure/templates/Makefile.template.
- This file can be retrieved from any of the anoncvs servers or via the
- OpenBSD cvs/web source browser system
- http://www.openbsd.org/cgi-bin/cvsweb/.
- -
make fetch-all-
make makesum-
make extract-
Note: Patches go in the directory `patches' and are named patch-xx - where xx should be aa, ab, ..., az, ba, bb ... zz. -
$OpenBSD$.
- -
make patchmake PATCH_DEBUG=YES patch
-
The easiest way to re-run patches is to `make clean && make patch'. - This will delete the work directory and re-extract and patch. -
-
If GNU_CONFIGURE is used you may want to run ./configure --help - to see what options are available. Anything that you may want to - override can be changed by adding the --option flags to the - CONFIGURE_ARGS parameter in the Makefile -
-
SEPARATE_BUILDGNU_CONFIGURE can),
- and may help people who mount their ports tree on several arches.
- This can also spare you some effort, as you will possibly be able to
- restart the cycle at configure most of the time.
- -
make configuremake clean && make configure'.
- Note: make sure host dependent files go in /etc or
- /etc/<name>, but NEVER replace existing files
- in /etc. Best to have install place
- in /usr/local/lib/<name> and then copy to
- /etc or
- /etc/<name> only if the files do not exist.
-
The OpenBSD file locations are: +This document describes how to make or upgrade a port. It is a useful +reminder of things to do. This is not totally accurate nor perfect. +Direct comments and questions to +turan@openbsd.org . -
+-
++ +
- +If you want to be a maintainer, subscribe to + ports@openbsd.org. +
+ +
- +This is where all ports discussions take place. +
- +Reading this list is important since many announcements go over this list. +
- +You will find a lot of porting-savvy people here. They can often give you +good advice or test ports for you. +
- +Check out a copy of the ports tree from cvs. +You can find instructions to do this at + +http://www.openbsd.org/anoncvs.html. + +
- +Pick a place to put your port and create the basic +infrastructure there. Use the template Makefile at +
/usr/ports/infrastructure/templates/Makefile.template. ++ +
- +Create the directories
files, patches, pkg. +- +Create these empty files
pkg/COMMENT, pkg/DESCR, pkg/PLIST+- +Add the fetch portions of the Makefile. +
+
- +Fill in EXTRACT_SUFFIX if its anything besides .tar.gz. Other examples are +.tar.Z, or .tgz. +
- +Fill in DISTNAME which is the name of the file minus the extract suffix. E.g. if you have foo-1.0.tar.gz, DISTNAME is foo-1.0. +
- +Fill in MASTER_SITES which is a URL to the directory where the distfile +is kept. E.g. ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/ Don't forget +the trailing slash. Try to have at least three distinct sites as well. +Place the most easily accessible first as they are traversed in order. +
- +Keep in mind that fetch references the file as +${MASTER_SITE}${DISTNAME}$EXTRACT_SUFFIX}. All three are used. Don't +set DISTNAME to point to the file directly. +
- +You can check to see if you have filled this values in correctly by typing +make fetch-all +
+For more complex ports, you have more options and tools available to you: +
+ +
- +You also have the variable PATCHFILES available. This is a list of vendor +(not openbsd) patches to the port. Common uses are things like security +or reliability fixes. +
- +If your ports are available over large public mirrors such as GNU, SunSite, or +CPAN, we have already provided a list of sites for your use in +/usr/ports/infrastructure/template/network.conf.template. +Set MASTER_SITES to ${MASTER_SITE_GNU}, or ${MASTER_SITE_SUNSITE}, etc. +To simplify this process, the construct %SUBDIR% is replaced by the variable +MASTER_SITE_SUBDIR in your Makefile. +
- +Ports normally correspond to given versions of software. Once they are retrieved, files are checksummed and compared to the recorded +checksum in files/md5. So, to avoid confusion, DISTFILES and PATCHFILES should have clearly visible version numbers: +don't retrieve foo-latest.tar.gz if it is a link to foo-1.0.5.tar.gz. If necessary, gently ask the original program author +to make such distinctions clear. +
- +If a given port needs more than about 5 DISTFILES + PATCHFILES to work, use DIST_SUBDIR to avoid cluttering +/usr/ports/distfiles too much. +
- +DIST_SUBDIR must not include version numbers. When the port is updated to a later version, some distfiles may not change, but will be +refetched if DIST_SUBDIR is changed. Even if all distfiles change, it is easier for the user to track cruft. +
- +All DISTFILES and PATCHFILES don't necessarily come from the same set of MASTER_SITES. Supplementary sites can be +defined using the variables MASTER_SITES0 to MASTER_SITES9. Just write DISTFILES=foo-1.0.5.tar.gz:5 to +retrieve foo-1.0.5.tar.gz from MASTER_SITES5. +
- +Some ports don't always need to retrieve all files in all circumstances. For instance, some ports may have some compilation options, and +associated files which are only required in such a case. Or they may need some files for some architectures only. In such a case, those +supplementary optional files must be mentioned in the SUPDISTFILES variable. Targets such as makesum or +mirror-distfiles will fetch those supplementary files that the casual user doesn't need. +
- +Create a checksum in files/md5 by typing make makesum. +Then verify the checksum is correct by typing make checksum +
+ +
- +In some rare cases, files checksums can't be verified reliably. By all means, porters should try to find sites that are reliable. Communicating +with the software author and the archive site maintainer at this stage is highly desirable. In the worst case, non-checksummable files can be +mentioned in the IGNOREFILES variable. +
- +All files in DISTFILES are usually processed during make extract. EXTRACT_ONLY may be used to limit extraction to a +subset of files (possibly empty). The customary use of this variable is to customize extraction: for instance, if some DISTFILES need +some special treatment, they will be removed from EXTRACT_ONLY and handled manually at post-extract stage. +For historic reasons, make extract does set up the working directory first along with extracting files. Thus, providing a +pre-extract or a do-extract target is highly unusual (and fairly suspicious behavior, indicative of a high degree of obfuscation +in the port). +
- +Patches that need specific treatment should be mentioned in DISTFILES, and removed from EXTRACT_ONLY, for historic reasons. +
- +Extract the port with make extract. Pay attention to where the base +of the sources are. Usually, its work/DISTNAME You may need to modify +the Makefile's WRKDIST variable if it is different. + +
- +Read the installation documentation and note what you have to do to build +the port and any special options that might be needed. +
- +Now is also a good time to figure out what kind of licensing restrictions +apply to your port. Many are freely redistribution but then again, quite +a few are not. We need four questions answered to distribute ports +properly. These are the PERMIT_* values in the Makefile. +
- +PERMIT_PACKAGE_CDROM tells us if we can put the package on the cdrom. +
- +PERMIT_PACKAGE_FTP tells us if we can put the package on the ftp sites. +
- +PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom. +
- +PERMIT_DISTFILES_FTP tells us if we can mirror the distfiles on the ftp sites. +
+Set these values to Yes if it is permitted or to a comment string stating why +it is not. Pay attention to any special conditions you may need to fulfill +later on. E.g. some ports require to install a copy of the license. We +recommend you place the license in
/usr/local/share/DISTNAME/. + +- +Add configuration options to Makefile and/or create the configuration script. +
+ +
- +You can add a port configuration script named `configure' to a directory +named
scripts/. This will be run before any configuration +specified by GNU_CONFIGURE or HAS_CONFIGURE is run. +- +If GNU_CONFIGURE is used you may want to run ./configure --help +to see what options are available. +
- +Anything that you may want to override can be changed by adding the +--option flags to the CONFIGURE_ARGS parameter in the Makefile. +
- +Use CONFIGURE_ARGS+= to append to the variable. CONFIGURE_ARGS= will +overwrite it. +
- +Try building the port with make build. +
+ +
- +If you're lucky, the port will go all the way through without errors. +
- +If it exits with an error, you will need to generate patches for your port. +Figure out what needs to be changed and make patch for it. +
- +Patches must be relative to ${WRKDIST}. +
- The easiest way to reset the port and test your patches is +make clean patch. This will delete the work directory, re-extract, +and patch your port. +
- +Begin and cycle of make build, generate a patch, and +make clean patch. +
+ +
- +Patches go in the directory patches/ and should be named patch-* with +* being something meaningful. We recommend you name your patches +patch-FILENAME where FILENAME is the name of the file it is patching. +
- +Applying PATCHFILES is the first half of the make patch stage. It can be +invoked separately as make distpatch, which is a convenient target for +porters. Ignore this if you haven't set it. +
- +Only patch one source file per patchfile, please, +
- +Use diff -p -u to generate patches, +
- +All patches MUST be relative to ${WRKDIST}, +
- +Check that patches DON'T contain tags that cvs +will replace. If they do, your patches won't apply after you check +them in. You can check in your changes with -kk to avoid this. +
- +Add a small explanation of the patch role in the patchfile before +the patch itself, and an OpenBSD CVS tag
$OpenBSD$. +- +Please feed your patches back to the author of that piece of software. +
- +Try setting
SEPARATE_BUILD
++ +
- +If the port can build with object files outside its source tree, +this is cleaner (many programs using
GNU_CONFIGUREcan), +and may help people who mount their ports tree on several arches. +- +This can also spare you some effort, as you will possibly be able to +restart the cycle at
configuremost of the time. +- +Peruse the output (if any) and tweak any options in the Makefile. +To repeat issue the command `make clean configure'. +
+Note: make sure host dependent files go in /etc or +/etc/<name>, but NEVER REPLACE OR MODIFY existing files +in /etc. Best to have install place +in /usr/local/share/<name> and then copy to +/etc or /etc/<name> only if the files do not exist. +If the files exist, display a message that says such-and-such files need +to be modified. This also guarantees that the files will be included in +the package since everything under /usr/local is included in the PLIST + +
+The OpenBSD file locations are: +
user executables: /usr/local/bin system admin executables: /usr/local/sbin program executables: /usr/local/libexec @@ -119,53 +251,57 @@ man pages: /usr/local/man/... read-only architecture-independent: /usr/local/share/<name> misc documentation: /usr/local/share/doc/<name> -+
-
make-
SEPARATE_BUILD semanticsSEPARATE_BUILD defined.
- Ideally, the port should no longer modify any file in
- ${WRKSRC} after make patch.
- You can check this by making sure you don't have any write access
- to ${WRKSRC}. Then you can set
- SEPARATE_BUILD=concurrent: someone can use the same
- source tree to build on distinct arches simultaneously.
- Otherwise, set SEPARATE_BUILD=simple: building on
- distinct arches simultaneously may meet with problems, as some
- source files may be regenerated at awkward moments.
- -
mkdir pkg; touch pkg/{DESCR,COMMENT,PLIST}COMMENT is a SHORT one-line description of the port - (max. 60 characters). Do NOT include the package name (or version number - of the software) in the comment. Do NOT start with an uppercase letter - unless semantically significant, do NOT end with a period. -
DESCR is a longer description of the port. One to a few paragraphs - concisely explaining what the port does is sufficient. -
PLIST is kept empty at this point. -
-
sudo make install-
nm, as some mistaken software strips dynamic libraries,
- which may lead to weird failures later.
- -
pkg/SECURITY file. This file
- should list audited potential problems, along with relevant patches,
- so that another person can see at first glance what has been done.
- Example:
+SEPARATE_BUILD=simple: building on
+distinct arches simultaneously may meet with problems, as some
+source files may be regenerated at awkward moments.
+
+If the port installs dynamic libraries, check their symbol tables
+with nm, as some mistaken software strips dynamic libraries,
+which may lead to weird failures later.
+
+
pkg/SECURITY file. This file
+should list audited potential problems, along with relevant patches,
+so that another person can see at first glance what has been done.
+Example:
$OpenBSD$
@@ -173,98 +309,130 @@
call to mktemp (wrapper function do_mktemp) does seem to be correct.
The server makes extensive use of strlcpy/strlcat/snprintf.
-
- make plist
-
which makes the file PLIST-auto in the pkg directory. This file - is a candidate packing list. Beware: the files are found by - timestamp. This means it does NOT: -
info/dir file if .info files are
- added. You'll have to add that by hand. Also, be sure that
- the info/dir is not part of the PLIST.
- Peruse `PLIST-auto' and verify that everything was installed and - that it was installed in the proper locations. Anything not installed - can be added to a port Makefile `post-install' rule. -
Copy `PLIST-auto' to `PLIST' -
Ports that install shared libraries will need two versions of
- the PLIST file. PLIST describes the files installed on
- those architectures that support shared libraries, and
- PLIST.noshared describes the files installed on
- architectures that do not support shared libs. Typically,
- PLIST.noshared is a copy of PLIST
- less references to any shared libraries.
-
-
pkg_delete <pkg_name>' is
- used to uninstall. `sudo make reinstall' is used to reinstall. See the
- `pkg_create' man page for other commands that may be added
- to PLIST to ensure all is cleaned up. After an uninstall the command
- find /usr/local -newer work/.install_started -print
-
should only list standard directory names. -
-
make package to create a package. To test the
- package first do a pkg_delete and then do a
- pkg_add The results after an add should EXACTLY
- match the results after a `make install'.
- -
The ports@openbsd mailing list is a good place to find porting-savy - people with different platforms! -
- In short, import is typically used when a port is created. - From that point on cvs add and cvs rm are typically used to add or remove - files, and the normal edit->commit cycle for changes. -
- You might use something like this: -
+
+Beware! The files are found by timestamp. This means it does NOT: +
info/dir file if .info files are added.
+Also, be sure that the info/dir is not part of the PLIST.
++Peruse `PLIST-auto' and verify that everything was installed and +that it was installed in the proper locations. Anything not installed +can be added to a port Makefile `post-install' rule. +
+Move `PLIST-auto' to `PLIST' + +
+Ports that install shared libraries will need two versions of the PLIST file. +
find /usr/local -newer work/.install_started -print
+
should only list standard directory names. + +
make package to create a package. To test the
+package first do a pkg_delete and then do a
+pkg_add The results after an add should EXACTLY
+match the results after a `make install'.
+
++Try to get others to test it on a variety of platforms for you. +
+
+If you do not have CVS access, ask someone on +ports@openbsd.org to commit it. Don't forget +about me, turan@openbsd.org if no one +picks it up. + +
+In short, import is typically used when a port is created. +From that point on cvs add and cvs rm are typically used to add or remove +files, and the normal edit->commit cycle for changes. +You might use something like this: +
cd kaffe1 make clean # you really really don't want to check in all of work! cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \ YourName YourName_YYYY-MMM-DD --
-d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you - have a CVS_ROOT environment variable defined. -
-m 'kaffe port' is your login message. Change it to whatever you like -
ports/lang/kaffe1 is the path relative to /cvs where the port lives -
YourName (replaced with your login name) is the "vendor tag". - You imported it so you are the vendor. -
YourName_YYYY-MMM-DD (e.g., ian_2000-Jan-01) - is the 'vendor release tag'. This is as good as any. -
As a real example, here is the output of checking in the Kaffe1 port, - which one of us did on September 8, 1998: -
++
$ cd kaffe1 $ make clean >/dev/null $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08 @@ -282,27 +450,24 @@ No conflicts created by this import $ --
Last but not least, add a one-line entry for the new port - in its parent directory's makefile, i.e., for ports/lang/kaffe1, - add it to ports/lang/Makefile. -
If you do not have CVS commit access, send mail to the ports - maintainers at ports@openbsd.org, - stating that you have a port ready to go into the tree. List the - name and version of the program, the platforms it's been tested on, - and any limitations. -
-
- www@openbsd.org
-
+www@openbsd.org
+