=================================================================== RCS file: /cvsrepo/anoncvs/cvs/www/Attic/checklist.html,v retrieving revision 1.19 retrieving revision 1.20 diff -c -r1.19 -r1.20 *** www/Attic/checklist.html 2000/02/14 01:35:31 1.19 --- www/Attic/checklist.html 2000/03/10 17:13:13 1.20 *************** *** 1,111 **** !
! ! ! ! ! ! !!
!
/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 patch
make 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_BUILD
GNU_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 configure
make 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: !
user executables: /usr/local/bin system admin executables: /usr/local/sbin program executables: /usr/local/libexec --- 1,243 ---- ! ! ! ! ! ! ! ! !! !OpenBSD Porting Checklist ! ! ! !OpenBSD Porting Checklist
! 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 . !
!! !
! Thank you for supporting the OpenBSD "ports" process! !- ! 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_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. !- ! 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,171 **** man pages: /usr/local/man/... read-only architecture-independent: /usr/local/share/<name> misc documentation: /usr/local/share/doc/<name> !!!
make
! Begin a cycle of makes until the port is ready. Patch (see above) ! clean, and make until the port is generated. Get rid of all warnings ! if possible, especially security related warnings. !!
- Control
SEPARATE_BUILD
semantics
! You have to do this only if the port builds with !SEPARATE_BUILD
defined. ! Ideally, the port should no longer modify any file in !${WRKSRC}
aftermake 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, setSEPARATE_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}
! Create dummy versions of the package files. Edit DESCR and COMMENT. !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
! install the application. !!
- 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. !!
- Check port for security holes again. This is ! especially important for network and setuid programs. See ! our security recommendations ! for that. Log interesting stuff and fixes in the !
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$ --- 251,307 ---- man pages: /usr/local/man/... read-only architecture-independent: /usr/local/share/<name> misc documentation: /usr/local/share/doc/<name> !!- ! Begin a cycle of makes until the port is ready. Patch (see above) ! clean, and make until the port is generated. Get rid of all warnings ! if possible, especially security related warnings. !
- ! Control SEPARATE_BUILD semantics. ! You have to do this only if the port builds with ! SEPARATE_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. +- + Edit pkg/DESCR, pkg/COMMENT, pkg/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. +
- + Install the application with make install +
+ 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. + +- + Check port for security holes again. This is + especially important for network and setuid programs. See + our security recommendations + for that. Log interesting stuff and fixes in the +
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,270 **** call to mktemp (wrapper function do_mktemp) does seem to be correct. The server makes extensive use of strlcpy/strlcat/snprintf. -!- Create pkg/PLIST
! After the install is complete use the developer's command: !
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: !
!
!- list any files installed with `tar' as their timestamp ! will not change and thus won't be found by `find' !
- update the
info/dir
file if .info files are ! added. You'll have to add that by hand. Also, be sure that ! theinfo/dir
is not part of the PLIST. !- try to do anything special with links or symbolic links. A ! cursory test of tar shows it does the right thing with links ! and symbolic links so I don't see why we need to special case ! anything in the packing list. But still... !
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 ofPLIST
! less references to any shared libraries. !!
- uninstall and reinstall; repeat until perfect.
! Perfect is when everything installs and uninstalls ! in its proper location. `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. !
!
- Create package:
! After the port installs correctly issue the command !make package
to create a package. To test the ! package first do apkg_delete
and then do a !pkg_add
The results after an add should EXACTLY ! match the results after a `make install'. !!
- Distribute it!
! Since the whole point of this process ! is to make your ported version of the software available to ! other OpenBSD users, you now need to disseminate it. !!
!- First, get others to test it on a variety of ! platforms (the DEC Alpha is good because it has only static libraries ! and because sizeof int != sizeof long; Sun SPARC is good because it is ! very common and because its byte order is the reverse of i386; if you ! developed on SPARC, of course, you'd want it tested on i386). !
The ports@openbsd mailing list is a good place to find porting-savy ! people with different platforms! !
- Incorporate any feedback you get. Test it again on your platform. ! Get those who gave you feedback to test it again from your new port. !
- Finally, include it in the "ports" tree. ! If you are a developer with CVS access, check it in. ! We normally use "import" for a new port, ! rather than adding a zillion (or a dozen) files individually. ! Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry ! about that! :-) If you make changes to a specific file (edit, then ! cvs commit), it will be 1.2, and that will be used. !
! 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 --- 309,438 ---- call to mktemp (wrapper function do_mktemp) does seem to be correct. The server makes extensive use of strlcpy/strlcat/snprintf.!- ! Create pkg/PLIST. After the install is complete use the developer's command, ! 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: !
!
!- ! list any files installed with `tar' as their timestamp ! will not change and thus won't be found by `find' !
- ! Update the
info/dir
file if .info files are added. ! Also, be sure that theinfo/dir
is not part of the PLIST. !- ! Try to do anything special with links or symbolic links. A ! cursory test of tar shows it does the right thing with links ! and symbolic links so I don't see why we need to special case ! anything in the packing list. But still... !
! 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. !
!
! !- ! PLIST describes the files installed on those architectures that support ! shared libraries. !
- ! 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. !
- ! Keep repeating uninstall and reinstall until perfect.
! Perfect is when everything installs and uninstalls ! in its proper location. `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. ! !
- ! Test the packaging:
! After the port installs correctly issue the command !make package
to create a package. To test the ! package first do apkg_delete
and then do a !pkg_add
The results after an add should EXACTLY ! match the results after a `make install'. ! !- ! Mail ports@openbsd.org with a short ! note asking for comments and testing. Attach the port to this email and ! sent it out. If you don't get any comments, send email to ! turan@openbsd.org and I will pick it for you. !
! Try to get others to test it on a variety of platforms for you. !
! !
- ! The DEC Alpha is good because it has only static libraries and because ! sizeof(int) != sizeof(long) !
- ! Sun SPARC is good because it is very common and because its byte order is ! the reverse of i386; if you developed on SPARC, of course, you'd want it ! tested on i386). !
!
- ! Incorporate any feedback you get. Test it again on your platform. ! Get those who gave you feedback to test it again from your new port. ! !
- ! Finally, include it in the "ports" tree. !
! 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. ! !
- ! If you are a developer with CVS access, check it in. ! We normally use "import" for a new port, ! rather than adding a zillion (or a dozen) files individually. ! Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry ! about that! :-) If you make changes to a specific file (edit, then ! cvs commit), it will be 1.2, and that will be used. !
! 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 !!! As a real example, here is the output of checking in the Kaffe1 port, ! which one of us did on September 8, 1998: !
- ! -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. !
$ cd kaffe1 $ make clean >/dev/null $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08 *************** *** 282,308 **** 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. !
!
- Maintain the port!
! As time goes by, problems may arise, or new versions of the software ! may be released. You should strive to keep your port up to date. ! In other words - iterate, test, test, iterate, ... !
! ! www@openbsd.org !
$OpenBSD: checklist.html,v 1.19 2000/02/14 01:35:31 espie Exp $ ! --- 450,473 ---- No conflicts created by this import $ !