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> 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> .if "\\$1"libfoo" \&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&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 &struct
202: or &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&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&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&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>