Hosting Provided By

presentation consistency in checklist.html

From: jsyn <jsyn(at)nthought.com>
Date: Tue Nov 19 2002 - 15:43:44 EST

This is a quick first pass at making checklist.html a little more internally consistent and correct. There is still plenty left for someone to nit over; in particular, representation of variable names, commands, targets, etc. needs to be better standardized (again, at least within this document). There are no changes in policy here, just grammar/presentation/justification cleanup.

jsyn

Index: checklist.html

RCS file: /cvs/www/checklist.html,v
retrieving revision 1.44
diff -u -r1.44 checklist.html

--- checklist.html	6 Jul 2002 09:32:07 -0000	1.44
+++ checklist.html	19 Nov 2002 20:34:44 -0000

@@ -9,7 +9,7 @@
<DEFANGED_meta name="copyright" content="This document copyright 1998-2002 by OpenBSD.">

<title>OpenBSD Porting Checklist</title>
- </head>
+</head>

<body text=Black bgcolor=White link="#23238E">

@@ -41,7 +41,7 @@
It also means trying to keep them up-to-date, and to answer questions about them.

- <li>
+ <li>
Check out a copy of the ports tree from cvs. You can find instructions on how to do this at
<a href="http://www.openbsd.org/anoncvs.html">
@@ -51,17 +51,13 @@
Pick a place to put your port and create the basic infrastructure there. Use the template Makefile at
<code>/usr/ports/infrastructure/templates/Makefile.template</code>.
-
- 
NEED_VERSION is obsolete and should not be used in new ports. As you are a port developer, you are supposed to update your ports tree, including bsd.port.mk. - 
-
<ul><li>

Create the directories <code>patches, pkg</code>.
<li>

-Create these empty files <code>pkg/DESCR, pkg/PLIST</code> +Create the empty files <code>pkg/DESCR, pkg/PLIST</code>.
</ul>

<li>

@@ -70,11 +66,13 @@
Fill in EXTRACT_SUFX if it's anything besides .tar.gz. Other examples are .tar.Z, or .tgz.
<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>

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. 
+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.
<li>

Keep in mind that fetch references the file as @@ -82,7 +80,7 @@
set DISTNAME to point to the file directly.
<li>

You can check to see if you have filled these values in correctly by typing

-make fetch-all 
+make fetch-all.

</ul>


For more complex ports, you have more options and tools available to you: @@ -121,7 +119,7 @@

<li>

 Create a checksum in distinfo by typing make makesum.
-Then verify the checksum is correct by typing make checksum
+Then verify the checksum is correct by typing make checksum.

<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 with the software author and the archive site maintainer at this stage is highly desirable. In the worst case, non-checksummable files can be @@ -159,10 +157,11 @@
PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom.
<li>

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 +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>.

Do you need help?

<li>

@@ -227,7 +226,7 @@
</ul>

<li>

-Try setting <code>SEPARATE_BUILD</code> +Try setting <code>SEPARATE_BUILD</code>.
<ul><li>

If the port can build with object files outside its source tree, this is cleaner (many programs using <code>CONFIGURE_STYLE=gnu</code> can), @@ -241,9 +240,9 @@
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
+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 them 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 @@ -280,14 +279,14 @@
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 +Ideally, the port should not 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 +<code>SEPARATE_BUILD=concurrent</code> -- someone can use the same source tree to build on distinct arches simultaneously. -Otherwise, set <code>SEPARATE_BUILD=simple</code>: building on -distinct arches simultaneously may meet with problems, as some +Otherwise, set <code>SEPARATE_BUILD=simple</code> -- building on +distinct arches simultaneously may be met with problems, as some source files may be regenerated at awkward moments.

<li>

@@ -296,15 +295,14 @@
(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,
+unless semantically significant, and
do NOT end with a period. -DON'T EVER START WITH AN UNDETERMINATE ARTICLE SUCH AS `a' or `as', +DON'T EVER START WITH AN INDETERMINATE ARTICLE SUCH AS `a' or `as'; remove the article altogether.

<li>

Edit pkg/DESCR, pkg/PLIST.

-
-
+

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 wrap your lines at 80 characters. This can be done by first editing the DESCR @@ -314,8 +312,7 @@
</ul>

<li>

-Install the application with make install -
+Install the application with make install. If the port installs dynamic libraries, check their symbol tables with <code>nm</code>, as some mistaken software strips dynamic libraries, which may lead to weird failures later. On the other hand, executable binaries @@ -347,10 +344,9 @@
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' +will not change and thus won't be found by `find'.
<li>

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. @@ -366,9 +362,8 @@
can be added to a port Makefile `post-install' rule.

-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><li>
PLIST describes the files being independent of whether the architecture supports shared libraries or not.
<li>

PFRAG.shared describes only the files being additionally installed on those architectures that support @@ -379,17 +374,19 @@
</ul>

<li>

-Keep repeating uninstall and reinstall until perfect. +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 w-${PKGNAME}${FLAVOR_EXT}/fake-${MACHINE_ARCH}[-${FLAVOR}]/.install_started -print
-
should only list standard directory names.
+to PLIST to ensure all is cleaned up.  After an uninstall the command:
+
+$ 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>



-Test the packaging:<br>


+Test the packaging.


 After the port installs correctly issue the command


 <code>make package</code> to create a package.  To test the


 package first do a <code>pkg_delete</code> and then do a
@@ -404,11 +401,11 @@


 Try to get others to test it on a variety of platforms for you.


 <ul><li>



 The DEC Alpha is good  because it has only static libraries and because 
-sizeof(int) != sizeof(long)
+sizeof(int) != sizeof(long).

 <li>



 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).


+tested on i386.

 </ul>

 
Do you need more help? 
In addition to our free technical library, Pantek provides professional IT services to companies who utilize Open Source software:Learn more about Pantek's Technical Support offerings
Place an order for 24/7/365 Technical Support here
Learn more about Pantek, who we are, and what we do
Chat with a Live Operator
Related openbsd.org Links
advocacy
announce
bugs
ipv6
misc
ports
ports-changes
security-announce
smp
source-changes
tech
Request more information about Pantek

 <br><li>



@@ -417,7 +414,6 @@
 

 <br><br><li>



 Finally, include it in the "ports" tree.
-<p>


 If you do not have CVS access, ask someone on 


 <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> to commit it.  


 

@@ -434,9 +430,9 @@


 files, and the normal edit->commit cycle for changes.
 You might use something like this:

 <pre>

-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 \
+$ 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


 </pre>


 <ul><li>



@@ -447,12 +443,13 @@

 <li>



 ports/lang/kaffe1 is the path relative to /cvs where the port lives

 <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.

 <li>

 <i>YourName_YYYY-MMM-DD</i> (e.g., ian_2000-Jan-01)


 is the 'vendor release tag'.  This is as good as any.

 </ul>



+<br>


 As a real example, here is the output of checking in the Kaffe1 port,
 which one of us did on September 8, 1998:

 <pre>



@@ -477,7 +474,7 @@
 
 <li>



 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.
 

 <br><br><li>



@@ -485,7 +482,7 @@


 of the software may be released. You should strive to keep your port up 
 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
 port that depends on yours. In case of problems, communicate with the 
 maintainers of such ports. Likewise, be alert for dependency updates, and
Received on Tue Nov 19 15:46:41 2002

This message: [ Message body ]
Next message: Jose Nazario: "Re: presentation consistency in checklist.html"
Previous message: Peter Valchev: "Re: Where to put my own ports?"
Next in thread: Jose Nazario: "Re: presentation consistency in checklist.html"
Reply: Jose Nazario: "Re: presentation consistency in checklist.html"
Reply: Brian Poole: "Update: devel/ccache"

Contemporary messages sorted: [ By Date ] [ By Thread ] [ By Subject ] [ By Author ] [ By messages with attachments ]

This archive was generated by hypermail 2.1.8 : Wed Aug 23 2006 - 13:37:46 EDT