Annotation of htdocs/developers/notes.xml, revision 1.2

1.1       hubertf     1: <?xml version="1.0"?>
                      2: <!DOCTYPE webpage
                      3:  PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
                      4:         "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
                      5: 
                      6: <webpage id="developers-notes">
                      7: <config param="desc" value="Misc developer notes"/>
1.2     ! hubertf     8: <config param="cvstag" value="$NetBSD: notes.xml,v 1.1 2007/04/05 14:42:00 hubertf Exp $"/>
        !             9: <config param="rcsdate" value="$Date: 2007/04/05 14:42:00 $"/>
1.1       hubertf    10: 
                     11: <head>
                     12: 
                     13: <!-- Copyright (c) 1994-2007
                     14:        The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->
                     15: 
                     16: <title>Misc developer notes</title>
                     17: </head>
                     18: 
                     19: 
                     20: <sect1 role="toc">
                     21: 
                     22: <sect2 id="misc-notes">
                     23: 
1.2     ! hubertf    24: <sect3 id="about">
        !            25:   <title>About this file</title>
        !            26:   <para>
1.1       hubertf    27: If some nugget of information is useful enough for NetBSD developers 
                     28: to know - list it here.
1.2     ! hubertf    29:   </para>
        !            30: </sect3>
1.1       hubertf    31: 
                     32: <sect3 id="elf-aout-align">
                     33: <title>ELF vs. a.out .align</title>
                     34: 
                     35: <para>
                     36: <emphasis>Klaus Klein writes:</emphasis>
                     37: Just as a short reminder for those who are about to switch over their
                     38: m68k port to ELF: the interpretation of the .align directive has
                     39: changed in the m68k/ELF toolchain.  While its argument is log2(alignment)
                     40: on m68k/a.out, it is now linear; I've updated the ports which have already
                     41: been switched to reflect this.
                     42: </para>
                     43: 
                     44: <para>
                     45: (This is also true for i386, but neither for ARM ("different" vs. log2)
                     46: nor SPARC (both linear).)
                     47: </para>
                     48: </sect3>
                     49: 
                     50: <sect3 id="bumping-version-numbers">
                     51: <title>Logs when bumping a kernel version number or an shlib_version file</title>
                     52: <para>
                     53: When one bumps either the kernel version number or an shlib_version file, please
                     54: include both the interface changed <emphasis>and the new version number</emphasis> in the
                     55: log message.  Otherwise it's hard to figure out what a particular version
                     56: bump means by reading the cvs log.
                     57: </para>
                     58: </sect3>
                     59: 
                     60: <sect3 id="sharing-userland">
                     61: <title>Sharing userland and MACHINE_ARCH</title>
                     62: <para>
                     63: Userland should be shareable between machines of the same MACHINE_ARCH.
                     64: Some obvious issues:
                     65: </para>
                     66: 
                     67: <itemizedlist>
                     68:   <listitem>MAXPARTITIONS:
                     69:       Should be determined at runtime using &man.sysctl.3;.
                     70:   </listitem>
                     71:   <listitem>Machine specific binaries, keymaps, etc.:
                     72:       Should fail gracefully on different MACHINE types, and be included on
                     73:       all MACHINE_ARCH systems.
                     74:   </listitem>
                     75:   <listitem>Differing memory architectures:
                     76:       In the case where the memory architectures differs sufficiently to
                     77:       need different libkvm routines, they should all be included in &man.kvm.3;
                     78:       and the version to use determined at runtime.
                     79:   </listitem>
                     80:   <listitem>disklabels and boot blocks:
                     81:       This is the largest outstanding area to be addressed. Volunteers welcome.
                     82:   </listitem>
                     83: </itemizedlist>
                     84: </sect3>
                     85: 
                     86: <sect3 id="adding-library">
                     87: <title>Adding a new library</title>
                     88: <para>
                     89: The following is intended to be a brief list of items that need to
                     90: be addressed when adding a new library to the NetBSD tree.  In the
                     91: following example pathnames, <code>foo</code> is the name of the library,
                     92: <code>0</code> is the library's major number and <code>0</code> is the library's
                     93: minor number.  A new library would normally have <code>0</code> for both the
                     94: major and minor number.
                     95: </para>
                     96: 
                     97: <itemizedlist>
                     98:   <listitem>Place the source files (including header files to
                     99:       be installed, Makefile and shlib_version) into a <code>libfoo</code>
                    100:       directory in the CVS repository, using <emphasis>cvs add</emphasis> or <emphasis>cvs
                    101:       import</emphasis>, depending on which is more appropriate e.g. due to
                    102:       external maintenance of the product.
                    103:   </listitem>
                    104:   <listitem>Add the <code>libfoo</code> subdirectory to the Makefile's SUBDIRS
                    105:       list one level up in the hierarchy.
                    106:   </listitem>
                    107:   <listitem>Add the full shared object name (<code>./usr/lib/libfoo.so.0.0</code>) to
                    108:       <code>src/distrib/sets/lists/base/shl.mi</code>.
                    109:   </listitem>
                    110:   <listitem>Add the PIC library (<code>./usr/lib/libfoo_pic.a</code>) to
                    111:       <code>src/distrib/sets/lists/comp/shl.mi</code>.
                    112:   </listitem>
                    113:   <listitem>Add the ELF shared object names with no suffix
                    114:       (<code>./usr/lib/libfoo.so</code>) and a single numeric suffix
                    115:       (<code>./usr/lib/libfoo.so.0</code>) to
                    116:       <code>src/distrib/sets/lists/base/shl.elf</code>.
                    117:   </listitem>
                    118:   <listitem>Add the lint library (<code>./usr/libdata/lint/llib-lfoo.ln</code>) to
                    119:       <code>src/distrib/sets/lists/comp/lint.mi</code>.
                    120:   </listitem>
                    121:   <listitem>Add the normal library (<code>./usr/lib/libfoo.a</code>),
                    122:       profiled library (<code>./usr/lib/libfoo_p.a</code>)
                    123:       and any headers and manual pages to
                    124:       <code>src/distrib/sets/lists/comp/mi</code>.
                    125:   </listitem>
                    126:   <listitem>Add
                    127:       <screen>&nbsp;&nbsp;&nbsp;LIBFOO?= ${DESTDIR}/usr/lib/libfoo.a</screen>
                    128:       to <code>src/share/mk/bsd.prog.mk</code> and to the DPADD
                    129:       section of <code>src/share/mk/bsd.README</code>.
                    130:   </listitem>
                    131:   <listitem>Add <code>FOO</code> to the
                    132:       <code>__bsd_prog_mk_system_libs</code> variable in
                    133:       <code>src/share/mk/bsd.hostprog.mk</code>.
                    134:   </listitem>
                    135:   <listitem>Update the DPADD list in src/share/mk/bsd.README
                    136:   </listitem>
                    137:   <listitem>Add
                    138:       <screen>&nbsp;&nbsp;&nbsp;.if "\\$1"libfoo" \&amp;Foo Library (libfoo, -lfoo)</screen>
                    139:       to <code>src/share/tmac/doc2html</code>.
                    140:   </listitem>
                    141:   <listitem>Add an entry to the <code>.Lb libfoo</code> macro in
                    142:       <code>src/share/tmac/doc-syms</code>.
                    143:   </listitem>
                    144:   <listitem>Make sure that all files have <code>$<!-- -->NetBSD<!-- -->$</code> RCS
                    145:       Ids.
                    146:   </listitem>
                    147:   <listitem>Update <ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/doc/CHANGES.?rev=HEAD&amp;content-type=text/x-cvsweb-markup">doc/CHANGES.</ulink>
                    148:   </listitem>
                    149: </itemizedlist>
                    150: </sect3>
                    151: 
                    152: 
                    153: <sect3 id="changing-library-versions">
                    154: <title>Changing the version number of a library</title>
                    155: <para>
                    156: The minor number of a library should be incremented when it is
                    157: possible for external programs to call any new functions or variables
                    158: added. 
                    159: </para>
                    160: 
                    161: <para>
                    162: The major number should be incremented and the minor set to zero
                    163: when an externally visible structure changed size, or function
                    164: changed arguments. This can cause significant disruption and version
                    165: renaming is frequently used to avoid this.
                    166: </para>
                    167: 
                    168: <para>
                    169: With the current C ABIs changing functions (previously void) to return
                    170: a value of either integer, pointer, or floating-point type
                    171: does not necessitate incrementing the major number
                    172: since return values are always passed in (unconditionally)
                    173: caller-saved registers.  In such a case the minor number should be
                    174: incremented to note the "additions".
                    175: </para>
                    176: 
                    177: <para>
                    178: If you bump the major of a library, you should:
                    179: </para>
                    180: 
                    181: <orderedlist>
                    182:   <listitem>Bump the major of any library that depends on it.
                    183:   </listitem>
                    184:   <listitem>Send mail to <email>current-users@NetBSD.org</email> warning about it, so
                    185:       that if anybody's built a shared library that depends on it
                    186:       they can know to do the right thing.
                    187:   </listitem>
                    188:   <listitem>Note it in the install notes, for people upgrading to the next
                    189:       release (or, presumably, to -current via binary snapshots).
                    190:   </listitem>
                    191: </orderedlist>
                    192: </sect3>
                    193: 
                    194: <sect3 id="syscall-passing">
                    195: <title>Notes on syscall passing</title>
                    196: <para>
                    197: <emphasis>Christos Zoulas writes:</emphasis>
                    198: I'd like to mention for future reference, that our syscall
                    199: argument passing mechanism does not handle passing structs or unions
                    200: properly on all architectures, so syscall implementors need to
                    201: convert those to pointers and provide stubs in userland that &amp;struct
                    202: or &amp;union before calling the kernel stub.
                    203: </para>
                    204: </sect3>
                    205: 
                    206: 
                    207: <sect3 id="manpage-writing">
                    208: <title>Writing a manpage</title>
                    209: <orderedlist>
                    210:   <listitem>The &man.mdoc.samples.7; and &man.mdoc.7; manpages are excellent for reference
                    211:       (if a little lengthy).
                    212:   </listitem>
                    213:   <listitem>Work from the template in /usr/share/misc/mdoc.template, and
                    214:       refer to an existing manpage (for example &man.who.1; for a command,
                    215:       and &man.err.3; for a function).
                    216:   </listitem>
                    217:   <listitem>When done, remember to add the formatted
                    218:       (/usr/share/man/man<emphasis>section</emphasis>/<emphasis>name</emphasis>.<emphasis>section</emphasis>)
                    219:       and formatted (/usr/share/man/cat<emphasis>section</emphasis>/<emphasis>name</emphasis>.0)
                    220:       to <code>src/distrib/sets/lists/man/mi</code>.
                    221:   </listitem>
                    222: </orderedlist>
                    223: </sect3>
                    224: 
                    225: 
                    226: <sect3 id="file-rename">
                    227: <title>Renaming or removing installed binaries</title>
                    228: <para>
                    229: If your change filename, or remove any of files installed to DESTDIR,
                    230: you will need to do something like the following.
                    231: You need to decide which list file to update,
                    232: based on the file you will be removing.
                    233: </para>
                    234: 
                    235: <orderedlist>
                    236:   <listitem>Remove the old filename (or removed filename) from
                    237:       <ulink
                    238:       url="http://cvsweb.NetBSD.org/bsdweb.cgi/distrib/sets/lists/base/mi?rev=HEAD&amp;content-type=text/x-cvsweb-markup">distrib/sets/lists/base/mi</ulink>
                    239:       (or relevant file).
                    240:   </listitem>
                    241:   <listitem>Add the old filename (or removed filename) to 
                    242:       <ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/distrib/sets/lists/base/obsolete.mi.?rev=HEAD&amp;content-type=text/x-cvsweb-markup">distrib/sets/lists/base/obsolete.mi.</ulink>
                    243:       This is for upgrade installations.
                    244:   </listitem>
                    245:   <listitem>And of course, don't forget to add new filename to
                    246:       <ulink url="http://cvsweb.NetBSD.org/bsdweb.cgi/distrib/sets/lists/base/mi.?rev=HEAD&amp;content-type=text/x-cvsweb-markup">distrib/sets/lists/base/mi.</ulink>
                    247:   </listitem>
                    248: </orderedlist>
                    249: </sect3>
                    250: 
                    251: 
                    252: <sect3 id="cleaning-tree">
                    253: <title>Cleaning your tree</title>
                    254: <para>
                    255: <emphasis>Perry E. Metzger writes:</emphasis>
                    256: At periodic intervals, I find that my checked out tree gets filled
                    257: with garbage that cvs update normally doesn't "?" because it is in the
                    258: ignored list -- stuff like .orig files from patching runs or .o files
                    259: for things that don't exist any more. Since CVS ignores them, one
                    260: never finds out one's tree has the junk in it.
                    261: </para>
                    262: 
                    263: <para>
                    264: I'm sure I'm the last person to discover this trick, but in case I'm
                    265: not, I have found that doing
                    266: </para>
                    267: 
                    268: <screen> cvs update -I \! -I CVS </screen>
                    269: 
                    270: <para>
                    271: nicely yields lots of good complaints about left-over garbage like
                    272: this.
                    273: </para>
                    274: </sect3>
                    275: 
                    276: 
                    277: <sect3 id="weak-symbol">
                    278: <title> When to add weak-symbol to library functions?</title>
                    279: <para>
                    280: In short, to quote Klaus Klein:
                    281: </para>
                    282: 
                    283: <itemizedlist>
                    284:   <listitem>the identifier is to be used internally by libc, and
                    285:   </listitem>
                    286:   <listitem>the identifier is not a feature of ANSI C resp. C90.
                    287:   </listitem>
                    288: </itemizedlist>
                    289: 
                    290: <para>
                    291: The weak symbol reference has two goals:
                    292: </para>
                    293: 
                    294: <itemizedlist>
                    295:   <listitem>Users should be allowed to define a function "foo", if "foo" is not
                    296:       defined in ANSI C, and the name is used in any of OS-supplied
                    297:       library.
                    298:   </listitem>      
                    299:   <listitem>A library function may call other library functions.  In this case,
                    300:       the call must be made safe against name collision with user-supplied
                    301:       functions.  Therefore, we need to use "_foo", not "foo",
                    302:       to refer other library functions from within the library function.
                    303:       If we call "foo", "foo" can be overridden by user-supplied function
                    304:       and may result in strange behavior.
                    305:   </listitem>      
                    306: </itemizedlist>
                    307: </sect3>
                    308: 
                    309: 
                    310: <sect3 id="newyear">
                    311: <title>What files need updating on each Jan 1st?</title>
                    312: 
                    313: <para>
                    314: On the first of each year, the following files need to be updated
                    315: to list the new year in the Copyright strings
                    316: </para>
                    317: 
                    318: <itemizedlist>
                    319: <listitem> src/sys/conf/copyright
                    320: </listitem>
                    321: <listitem> localsrc/admin/copyright/templates/*
                    322: </listitem>
                    323: </itemizedlist>
                    324: </sect3>
                    325: 
                    326: 
                    327: <sect3 id="mailinglist">
                    328: <title>What is the job of a mailing list moderator?</title>
                    329: 
                    330: <para>
                    331: A short summary by Herb Peyerl:
                    332: You have to accept and read all bounce messages from the lists
                    333: you own to make sure they're not legitimate postings. You then
                    334: forward all legitimate postings that have bounced to the list
                    335: in question using the majordomo 'approve' script. You also
                    336: have to do any subscribes or unsubscribes from people whose
                    337: email addresses didn't match exactly the email address they
                    338: subscribed with.
                    339: </para>
                    340: 
                    341: <para>
                    342: In the case of moderated lists (-announce, -news) you need 
                    343: to make sure the postings match the charter of the list(s) 
                    344: and approve them if they are appropriate, or reply to the
                    345: author and explain why you can't approve their postings.
                    346: </para>
                    347: 
                    348: <para>
                    349: You'll also get keyword bounces which are usually spam (that
                    350: you have to read) and if they're legitimate postings,
                    351: determine where the keyword match was and decide whether it
                    352: was legitimate and forward it. If not, communicate back to
                    353: the author to ask him/her to rephrase their posting.
                    354: </para>
                    355: 
                    356: <para>
                    357: The above task becomes fairly onerous during virus season.
                    358: </para>
                    359: </sect3>
                    360: 
                    361: </sect2>
                    362: 
                    363: </sect1>
                    364: </webpage>

CVSweb <webmaster@jp.NetBSD.org>