[BACK]Return to checklist.html CVS log [TXT][DIR] Up to [local] / www

Diff for /www/Attic/checklist.html between version 1.44 and 1.45

version 1.44, 2002/07/06 09:32:07 version 1.45, 2002/11/19 22:02:19
Line 9 
Line 9 
 <meta name="copyright" content="This document copyright 1998-2002 by OpenBSD.">  <meta name="copyright" content="This document copyright 1998-2002 by OpenBSD.">
   
 <title>OpenBSD Porting Checklist</title>  <title>OpenBSD Porting Checklist</title>
  </head>  </head>
   
 <body text=Black bgcolor=White link="#23238E">  <body text=Black bgcolor=White link="#23238E">
 <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>  <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
Line 18 
Line 18 
   
 This document describes how to make or upgrade a port.  It is a useful  This document describes how to make or upgrade a port.  It is a useful
 reminder of things to do.  This is neither totally accurate nor perfect.  reminder of things to do.  This is neither totally accurate nor perfect.
 Direct comments and questions to <a href="mailto:ports@openbsd.org">  Direct comments and questions to <a href="mailto:ports@openbsd.org">
 ports@openbsd.org </a>.  ports@openbsd.org</a>.
   
 <hr>  <hr>
 <ol>  <ol>
Line 41 
Line 41 
 It also means trying to keep them up-to-date, and to answer questions about  It also means trying to keep them up-to-date, and to answer questions about
 them.  them.
   
 <br><li>  <br><br><li>
 Check out a copy of the ports tree from cvs.  Check out a copy of the ports tree from cvs.
 You can find instructions on how to do this at  You can find instructions on how to do this at
 <a href="http://www.openbsd.org/anoncvs.html">  <a href="http://www.openbsd.org/anoncvs.html">
Line 51 
Line 51 
 Pick a place to put your port and create the basic  Pick a place to put your port and create the basic
 infrastructure there.  Use the template Makefile at  infrastructure there.  Use the template Makefile at
 <code>/usr/ports/infrastructure/templates/Makefile.template</code>.  <code>/usr/ports/infrastructure/templates/Makefile.template</code>.
   
 <br>  
 NEED_VERSION is obsolete and should not be used in new ports.  NEED_VERSION is obsolete and should not be used in new ports.
 As you are a port developer, you are supposed to update  As you are a port developer, you are supposed to update
 your ports tree, including bsd.port.mk.  your ports tree, including bsd.port.mk.
 <br>  
   
 <ul><li>  <ul><li>
 Create the directories <code>patches, pkg</code>.  Create the directories <code>patches, pkg</code>.
 <li>  <li>
 Create these empty files <code>pkg/DESCR, pkg/PLIST</code>  Create the empty files <code>pkg/DESCR, pkg/PLIST</code>.
 </ul>  </ul>
   
 <br><li>  <br><li>
Line 70 
Line 66 
 Fill in EXTRACT_SUFX if it's anything besides .tar.gz.  Other examples are  Fill in EXTRACT_SUFX if it's anything besides .tar.gz.  Other examples are
 .tar.Z, or .tgz.  .tar.Z, or .tgz.
 <li>  <li>
 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 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.
 <li>  <li>
 Fill in MASTER_SITES which is a URL to the directory where the distfile  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/ . <strong>Don't forget  is kept.  E.g., ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/.
 the trailing slash.</strong> Try to have at least three distinct sites as well.  <strong>Don't forget the trailing slash.</strong>
   Try to have at least three distinct sites as well.
 Place the most easily accessible first as they are traversed in order.  Place the most easily accessible first as they are traversed in order.
 <li>  <li>
 Keep in mind that fetch references the file as  Keep in mind that fetch references the file as
Line 82 
Line 80 
 set DISTNAME to point to the file directly.  set DISTNAME to point to the file directly.
 <li>  <li>
 You can check to see if you have filled these values in correctly by typing  You can check to see if you have filled these values in correctly by typing
 <b>make fetch-all</b>  <b>make fetch-all</b>.
 </ul>  </ul>
 <p>  <p>
 For more complex ports, you have more options and tools available to you:  For more complex ports, you have more options and tools available to you:
Line 121 
Line 119 
   
 <br><li>  <br><li>
 Create a checksum in <i>distinfo</i> by typing <b>make makesum</b>.  Create a checksum in <i>distinfo</i> by typing <b>make makesum</b>.
 Then verify the checksum is correct by typing <b>make checksum</b>  Then verify the checksum is correct by typing <b>make checksum</b>.
 <ul><li>  <ul><li>
 In some rare cases, files checksums can't be verified reliably. By all means, porters should try to find sites that are reliable. Communicating  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  with the software author and the archive site maintainer at this stage is highly desirable. In the worst case, non-checksummable files can be
Line 159 
Line 157 
 PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom.  PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom.
 <li>  <li>
 PERMIT_DISTFILES_FTP tells us if we can mirror the distfiles on the ftp sites.  PERMIT_DISTFILES_FTP tells us if we can mirror the distfiles on the ftp sites.
 </ul><p>  </ul>
   <p>
 Set these values to Yes if it is permitted or to a comment string stating why  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  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  later on.  E.g., some ports require to install a copy of the license.  We
 recommend you place the license in <code>/usr/local/share/DISTNAME/</code>.  recommend you place the license in <code>/usr/local/share/DISTNAME/</code>.
   
 <br><br><li>  <br><br><li>
Line 227 
Line 226 
 </ul>  </ul>
   
 <br><li>  <br><li>
 Try setting <code>SEPARATE_BUILD</code><br>  Try setting <code>SEPARATE_BUILD</code>.
 <ul><li>  <ul><li>
 If the port can build with object files outside its source tree,  If the port can build with object files outside its source tree,
 this is cleaner (many programs using <code>CONFIGURE_STYLE=gnu</code> can),  this is cleaner (many programs using <code>CONFIGURE_STYLE=gnu</code> can),
Line 241 
Line 240 
 Peruse the output (if any) and tweak any options in the Makefile.  Peruse the output (if any) and tweak any options in the Makefile.
 To repeat issue the command `<b>make clean configure</b>'.  To repeat issue the command `<b>make clean configure</b>'.
 <p>  <p>
 Note: make sure host dependent files go in <i>/etc</i> or  Note: make sure host-dependent files go in <i>/etc</i> or
 <i>/etc/&lt;name&gt;</i>, but <strong>NEVER REPLACE OR MODIFY</strong> existing files  <i>/etc/&lt;name&gt;</i>, but <strong>NEVER REPLACE OR MODIFY</strong>
 in <i>/etc</i>.  Best to have install place  existing files in <i>/etc</i>.  Best to have install place them
 in <i>/usr/local/share/&lt;name&gt;</i> and then copy to  in <i>/usr/local/share/&lt;name&gt;</i> and then copy to
 <i>/etc</i> or <i>/etc/&lt;name&gt;</i> only if the files do not exist.  <i>/etc</i> or <i>/etc/&lt;name&gt;</i> only if the files do not exist.
 If the files exist, display a message that says such-and-such files need  If the files exist, display a message that says such-and-such files need
Line 280 
Line 279 
 Control SEPARATE_BUILD semantics.  Control SEPARATE_BUILD semantics.
 You have to do this only if the port builds with  You have to do this only if the port builds with
 SEPARATE_BUILD defined.  SEPARATE_BUILD defined.
 Ideally, the port should no longer modify any file in  Ideally, the port should not modify any file in
 ${WRKSRC} after <b>make patch</b>.  ${WRKSRC} after <b>make patch</b>.
 You can check this by making sure you don't have any write access  You can check this by making sure you don't have any write access
 to ${WRKSRC}. Then you can set  to ${WRKSRC}. Then you can set
 SEPARATE_BUILD=concurrent: someone can use the same  <code>SEPARATE_BUILD=concurrent</code> -- someone can use the same
 source tree to build on distinct arches simultaneously.  source tree to build on distinct arches simultaneously.
 Otherwise, set <code>SEPARATE_BUILD=simple</code>: building on  Otherwise, set <code>SEPARATE_BUILD=simple</code> -- building on
 distinct arches simultaneously may meet with problems, as some  distinct arches simultaneously may be met with problems, as some
 source files may be regenerated at awkward moments.  source files may be regenerated at awkward moments.
   
 <br><br><li>  <br><br><li>
Line 296 
Line 295 
 (max. 60 characters). Do <strong>NOT</strong> include the package  (max. 60 characters). Do <strong>NOT</strong> include the package
 name (or version number of the software) in the comment.  name (or version number of the software) in the comment.
 Do <strong>NOT</strong> start with an uppercase letter  Do <strong>NOT</strong> start with an uppercase letter
 unless semantically significant,  unless semantically significant, and
 do <strong>NOT</strong> end with a period.  do <strong>NOT</strong> end with a period.
 <strong>DON'T EVER START WITH AN UNDETERMINATE ARTICLE SUCH AS `a' or `as',  <strong>DON'T EVER START WITH AN INDETERMINATE ARTICLE SUCH AS `a' or `as';
 remove the article altogether.</strong>  remove the article altogether.</strong>
   
 <br><br><li>  <br><br><li>
 Edit <i>pkg/DESCR</i>, <i>pkg/PLIST</i>.  Edit <i>pkg/DESCR</i>, <i>pkg/PLIST</i>.
 <ul>  <ul><li>
 <li>  
 DESCR is a longer description of the port. One to a few paragraphs  DESCR is a longer description of the port. One to a few paragraphs
 concisely explaining what the port does is sufficient. It is also advised to  concisely explaining what the port does is sufficient. It is also advised to
 wrap your lines at 80 characters. This can be done by first editing the DESCR  wrap your lines at 80 characters. This can be done by first editing the DESCR
Line 314 
Line 312 
 </ul>  </ul>
   
 <br><li>  <br><li>
 Install the application with <b>make install</b>  Install the application with <b>make install</b>.
 <p>  
 If the port installs dynamic libraries, check their symbol tables  If the port installs dynamic libraries, check their symbol tables
 with <code>nm</code>, as some mistaken software strips dynamic libraries,  with <code>nm</code>, as some mistaken software strips dynamic libraries,
 which may lead to weird failures later. On the other hand, executable binaries  which may lead to weird failures later. On the other hand, executable binaries
Line 347 
Line 344 
 This file is a candidate packing list.  This file is a candidate packing list.
 <p>  <p>
 Beware! The files are found by timestamp.  This means it does NOT:  Beware! The files are found by timestamp.  This means it does NOT:
 <ul>  <ul><li>
 <li>  
 list any files installed with `tar' as their timestamp  list any files installed with `tar' as their timestamp
 will not change and thus won't be found by `find'  will not change and thus won't be found by `find'.
 <li>  <li>
 Update the <code>info/dir</code> file if .info files are added.  Update the <code>info/dir</code> file if .info files are added.
 Also, be sure that the <code>info/dir</code> is not part of the PLIST.  Also, be sure that the <code>info/dir</code> is not part of the PLIST.
Line 366 
Line 362 
 can be added to a port Makefile `post-install' rule.  can be added to a port Makefile `post-install' rule.
   
 <p>  <p>
 Ports that install shared libraries will have another file called PFRAG.shared.  Ports that install shared libraries will have another file called PFRAG.shared.
 <ul>  <ul><li>
 <li>  
 PLIST describes the files being independent of whether the architecture supports shared libraries or not.  PLIST describes the files being independent of whether the architecture supports shared libraries or not.
 <li>  <li>
 PFRAG.shared describes only the files being additionally installed on those architectures that support  PFRAG.shared describes only the files being additionally installed on those architectures that support
Line 379 
Line 374 
 </ul>  </ul>
   
 <br><li>  <br><li>
 Keep repeating uninstall and reinstall until perfect.<br>  Keep repeating uninstall and reinstall until perfect.
 <em>Perfect</em> is when everything installs and uninstalls  <em>Perfect</em> is when everything installs and uninstalls
 in its proper location.  `pkg_delete &lt;pkg_name&gt;' is  in its proper location.  `pkg_delete &lt;pkg_name&gt;' is
 used to uninstall.  `sudo make reinstall' is used to reinstall.  See the  used to uninstall.  `sudo make reinstall' is used to reinstall.  See the
 `pkg_create' man page for other commands that may be added  `pkg_create' man page for other commands that may be added
 to PLIST to ensure all is cleaned up.  After an uninstall the command  to PLIST to ensure all is cleaned up.  After an uninstall the command:
 <p><code>find /usr/local -newer w-${PKGNAME}${FLAVOR_EXT}/fake-${MACHINE_ARCH}[-${FLAVOR}]/.install_started -print</code>  <pre>
 <p>should only list standard directory names.  $ find /usr/local -newer w-${PKGNAME}${FLAVOR_EXT}/fake-${MACHINE_ARCH}[-${FLAVOR}]/.install_started -print
   </pre>
   should only list standard directory names.
   
 <br><br><li>  <br><br><li>
 Test the packaging:<br>  Test the packaging.
 After the port installs correctly issue the command  After the port installs correctly issue the command
 <code>make package</code> to create a package.  To test the  <code>make package</code> to create a package.  To test the
 package first do a <code>pkg_delete</code> and then do a  package first do a <code>pkg_delete</code> and then do a
Line 404 
Line 401 
 Try to get others to test it on a variety of platforms for you.  Try to get others to test it on a variety of platforms for you.
 <ul><li>  <ul><li>
 The DEC Alpha is good  because it has only static libraries and because  The DEC Alpha is good  because it has only static libraries and because
 <code>sizeof(int) != sizeof(long)</code>  <code>sizeof(int) != sizeof(long)</code>.
 <li>  <li>
 Sun SPARC is good because it is very common and because its byte order is  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  the reverse of i386; if you developed on SPARC, of course, you'd want it
 tested on i386).  tested on i386.
 </ul>  </ul>
   
 <br><li>  <br><li>
Line 417 
Line 414 
   
 <br><br><li>  <br><br><li>
 Finally, include it in the "ports" tree.  Finally, include it in the "ports" tree.
 <p>  
 If you do not have CVS access, ask someone on  If you do not have CVS access, ask someone on
 <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> to commit it.  <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> to commit it.
   
Line 434 
Line 430 
 files, and the normal edit->commit cycle for changes.  files, and the normal edit->commit cycle for changes.
 You might use something like this:  You might use something like this:
 <pre>  <pre>
 cd kaffe1  $ cd kaffe1
 make clean      # you really really don't want to check in all of work!  $ 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 \  $ cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
         <I>YourName</I> <I>YourName_YYYY-MMM-DD</I>          <I>YourName</I> <I>YourName_YYYY-MMM-DD</I>
 </pre>  </pre>
 <ul><li>  <ul><li>
Line 447 
Line 443 
 <li>  <li>
 ports/lang/kaffe1 is the path relative to /cvs where the port lives  ports/lang/kaffe1 is the path relative to /cvs where the port lives
 <li>  <li>
 <i>YourName</i> (replaced with your login name) is the "vendor tag".  <i>YourName</i> (replaced with your login name) is the 'vendor tag'.
 You imported it so you are the vendor.  You imported it so you are the vendor.
 <li>  <li>
 <i>YourName_YYYY-MMM-DD</i> (e.g., ian_2000-Jan-01)  <i>YourName_YYYY-MMM-DD</i> (e.g., ian_2000-Jan-01)
 is the 'vendor release tag'.  This is as good as any.  is the 'vendor release tag'.  This is as good as any.
 </ul>  </ul>
   <br>
 As a real example, here is the output of checking in the Kaffe1 port,  As a real example, here is the output of checking in the Kaffe1 port,
 which one of us did on September 8, 1998:  which one of us did on September 8, 1998:
 <pre>  <pre>
Line 477 
Line 474 
   
 <li>  <li>
 Last but not least, add a one-line entry for the new port  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,  in its parent directory's Makefile, e.g., for ports/lang/kaffe1,
 add it to ports/lang/Makefile.  add it to ports/lang/Makefile.
   
 <br><br><li>  <br><br><li>
Line 485 
Line 482 
 of the software may be released. You should strive to keep your port up  of the software may be released. You should strive to keep your port up
 to date.  In other words - iterate, test, test, iterate...  to date.  In other words - iterate, test, test, iterate...
   
 <br><li>  <br><br><li>
 When updating a port, remember to handle dependencies! You shouldn't break any  When updating a port, remember to handle dependencies! You shouldn't break any
 port that depends on yours. In case of problems, communicate with the  port that depends on yours. In case of problems, communicate with the
 maintainers of such ports. Likewise, be alert for dependency updates, and  maintainers of such ports. Likewise, be alert for dependency updates, and
Legend:
Removed from v.1.44  
changed lines
  Added in v.1.45