Diff to the HTML version attached.

I'm assuming that you have a script to dump the text version, so I haven't
sent a diff against the text version. Note that I have made a few more
changes since the last diff.


--- doc/src/FAQ/FAQ_DEV.html
+++ doc/src/FAQ/FAQ_DEV.html
@@ -1,9 +1,9 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
     <META name="generator" content="HTML Tidy, see www.w3.org">
+       <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
     <TITLE>PostgreSQL Developers FAQ</TITLE>
@@ -12,57 +12,63 @@
     <H1>Developer's Frequently Asked Questions (FAQ) for
-    <P>Last updated: Fri Oct 15 12:26:50 EDT 2004</P>
+    <P>Last updated: Wed Dec  1 16:11:11 EST 2004</P>
     <P>Current maintainer: Bruce Momjian (<A href=
+    "mailto:[EMAIL PROTECTED]";>[EMAIL PROTECTED]</A>)<br />
     <P>The most recent version of this document can be viewed at <A href=
-    <BR>
+    <br />
       <H2>General Questions</H2>
-     <A href="#1.1">1.1</A>) How do I get involved in PostgreSQL
-    development?<BR>
-     <A href="#1.2">1.2</A>) How do I add a feature or fix a bug?<BR>
-     <A href="#1.3">1.3</A>) How do I download/update the current source
-    tree?<BR>
-     <A href="#1.4">1.4</A>) How do I test my changes?<BR>
-    <A href="#1.5">1.5</A>) What tools are available for developers?<BR>
-     <A href="#1.6">1.6</A>) What books are good for developers?<BR>
-     <A href="#1.7">1.7</A>) What is configure all about?<BR>
-     <A href="#1.8">1.8</A>) How do I add a new port?<BR>
-     <A href="#1.9">1.9</A>) Why don't you use threads/raw
+     <A href="#1.1">1.1</A>) How do I get involved in PostgreSQL 
+      development?<br />
+     <a href="#1.2">1.2</a>) What development environment is required to 
+      develop code?<br />
+        <a href="#1.3">1.3</a>) What areas need work?<br />
+        <a href="#1.4">1.4</a>) What do I do after choosing an item to 
+      work on?<br />
+     <a href="#1.5">1.5</a>) Where can I learn more about the code?<br />
+     <a href="#1.6">1.6</a>) I've developed a patch, what next?<br />
+     <A href="#1.7">1.7</A>) How do I download/update the current source 
+      tree?<br />
+     <A href="#1.8">1.8</A>) How do I test my changes?<br />
+     <A href="#1.9">1.9</A>) What tools are available for developers?<br />
+     <A href="#1.10">1.10</A>) What books are good for developers?<br />
+     <A href="#1.11">1.11</A>) What is configure all about?<br />
+     <A href="#1.12">1.12</A>) How do I add a new port?<br />
+     <A href="#1.13">1.13</A>) Why don't you use threads/raw
      devices/async-I/O, &lt;insert your favorite wizz-bang feature 
-     here&gt;?<BR>
-     <A href="#1.10">1.10</A>) How are RPM's packaged?<BR>
-     <A href="#1.11">1.11</A>) How are CVS branches handled?<BR>
-     <A href="#1.12">1.12</A>) Where can I get a copy of the SQL
-     standards?<BR>
+     here&gt;?<br />
+     <A href="#1.14">1.14</A>) How are RPM's packaged?<br />
+     <A href="#1.15">1.15</A>) How are CVS branches handled?<br />
+     <A href="#1.16">1.16</A>) Where can I get a copy of the SQL
+     standards?<br />
+     <a href="#1.17">1.17</a>) Where can I get technical assistance?<br />
       <H2>Technical Questions</H2>
      <A href="#2.1">2.1</A>) How do I efficiently access information in
-    tables from the backend code?<BR>
+    tables from the backend code?<br />
      <A href="#2.2">2.2</A>) Why are table, column, type, function, view
     names sometimes referenced as <I>Name</I> or <I>NameData,</I> and
-    sometimes as <I>char *?</I><BR>
+    sometimes as <I>char *?</I><br />
      <A href="#2.3">2.3</A>) Why do we use <I>Node</I> and <I>List</I> to
-    make data structures?<BR>
+    make data structures?<br />
      <A href="#2.4">2.4</A>) I just added a field to a structure. What else
-    should I do?<BR>
+    should I do?<br />
      <A href="#2.5">2.5</A>) Why do we use <I>palloc</I>() and
-    <I>pfree</I>() to allocate memory?<BR>
-     <A href="#2.6">2.6</A>) What is ereport()?<BR>
-     <A href="#2.7">2.7</A>) What is CommandCounterIncrement()?<BR>
-     <BR>
+    <I>pfree</I>() to allocate memory?<br />
+     <A href="#2.6">2.6</A>) What is ereport()?<br />
+     <A href="#2.7">2.7</A>) What is CommandCounterIncrement()?<br />
+     <br />
@@ -73,171 +79,174 @@
     <H3><A name="1.1">1.1</A>) How go I get involved in PostgreSQL
-    <P>This was written by Lamar Owen:</P>
+       <p>Download the code and have a look around. See <a href="#1.7">1.7</a>.
-    <P>2001-06-22</P>
+       <p>Subscribe to and read the 
+       <a href="http://archives.posrgresql.org/pgsql-hackers";>pgsql-hackers</a>
+       mailing list (often termed 'hackers'). This is where the major 
+    contributors and core members of the project discuss development.</p>
-    <B>What open source development process is used by the PostgreSQL
-    team?</B>
+    <h3><a name="1.2">1.2</a>) What development environment is required 
+       to develop code?</h3>
-    <P>Read HACKERS for six months (or a full release cycle, whichever
-    is longer). Really. HACKERS _is_the process. The process is not
-    well documented (AFAIK -- it may be somewhere that I am not aware
-    of) -- and it changes continually.</P>
+       <p>PostgreSQL is developed mostly in the C programming language. It also
+    makes use of Yacc and Lex.</p>
+    <p>The source code is targeted at most of the popular Unix platforms and
+    the Windows environment (XP, Windows 2000, and up).</p>
+    <p>Most developers make use of the open source development tool chain.
+    If you have contributed to open source software before, you will probably
+    be familiar with these tools. They include: GCC
+    (<a href="http://gcc.gnu.org";>http://gcc.gnu.org</a>, GDB
+    (<a 
+    autoconf (<a 
+    GNU make (<a 
-    <B>What development environment (OS, system, compilers, etc) is
-    required to develop code?</B>
+       <p>Developers using this tool chain on Windows make use of MingW (see 
+    <a href="http://www.mingw.org/";>http://www.mingw.org/</a>).</p>
-    <P><A href="http://developer.postgresql.org";>Developers Corner</A> on the
-    website has links to this information. The distribution tarball
-    itself includes all the extra tools and documents that go beyond a
-    good Unix-like development environment. In general, a modern unix
-    with a modern gcc, GNU make or equivalent, autoconf (of a
-    particular version), and good working knowledge of those tools are
-    required.</P>
+    <p>Some developers use compilers from other software vendors with
+    mixed results.</p>
-    <B>What areas need support?</B>
+    <p>Developers who are regularly rebuilding the source often pass the
+    --enable-depend flag to <i>configure</i>. The result is that when you
+    make a modification to a C header file, all files depend upon that file
+    are also rebuilt.</p>
-    <P>The TODO list.</P>
+       <h3><a name="1.3">1.3</a>) What areas need work?</h3>
-    <P>You've made the first step, by finding and subscribing to
-    HACKERS. Once you find an area to look at in the TODO, and have
-    read the documentation on the internals, etc, then you check out a
-    current CVS,write what you are going to write (keeping your CVS
-    checkout up to date in the process), and make up a patch (as a
-    context diff only) and send to the PATCHES list, prefereably.</P>
+    Outstanding features are detailed in the TODO list. This is located in
+    <i>doc/TODO</i> in the source distribution or at
+    <a 
+    <p>You can learn more about these features by consulting the archives, the
+    SQL standards and the recommend texts (see <a href="#1.10">1.10</a>).</p>
+    <h3><a name="1.4">1.4</a>) What do I do after choosing an item to 
+    work on?</h3>
+    <p>Send an email to pgsql-hackers with a proposal for what you want to do
+    (assuming your contribution is not trivial). Working in isolation is not
+    advisable: others may be working on the same TODO item; you may have
+    misunderstood the TODO item; your approach may benefit from the review of
+    others.</p>
+    <h3><a name="1.5">1.5</a>) Where can I learn more about the code?</h3>
+    <p>Other than documentation in the source tree itself, you can find some
+    papers/presentations discussing the code at 
+    <a 
-    <P>Discussion on the patch typically happens here. If the patch
-    adds a major feature, it would be a good idea to talk about it
-    first on the HACKERS list, in order to increase the chances of it
-    being accepted, as well as toavoid duplication of effort. Note that
-    experienced developers with a proven track record usually get the
-    big jobs -- for more than one reason. Also note that PostgreSQL is
-    highly portable -- nonportable code will likely be dismissed out of
-    hand.</P>
+    <h3><a name="1.6">1.6</a>) I've developed a patch, what next?</h3>
+    <p>Generate the patch in contextual diff format. If you are unfamiliar with
+    this, you may find the script <i>src/tools/makediff/difforig</i> 
+    <p>Ensure that your patch is generated against the most recent version 
+    of the code. If it is a patch adding new functionality, the most recent 
+    version is cvs HEAD; if it is a bug fix, this will be the most recently 
+    version of the branch which suffers from the bug (for more on branches in 
+    PostgreSQL, see <a href="#1.15">1.15</a>).</p>
-    <P>Once your contributions get accepted, things move from there.
-    Typically, you would be added as a developer on the list on the
-    website when one of the other developers recommends it. Membership
-    on the steering committee is by invitation only, by the other
-    steering committee members, from what I have gathered watching
-    froma distance.</P>
+    <p>Finally, submit the patch to [EMAIL PROTECTED] It will be
+    reviewed by other contributors to the project and may be either accepted
+    or sent back for further work.</p>
-    <P>I make these statements from having watched the process for over
-    two years.</P>
-    <P>To see a good example of how one goes about this, search the
-    archives for the name 'Tom Lane' and see what his first post
-    consisted of, and where he took things. In particular, note that
-    this hasn't been _that_ long ago -- and his bugfixing and general
-    deep knowledge with this codebase is legendary. Take a few days to
-    read after him. And pay special attention to both the sheer
-    quantity as well as the painstaking quality of his work. Both are
-    in high demand.</P>
-    <H3><A name="1.2">1.2</A>) How do I add a feature or fix a bug?</H3>
-    <P>The source code is over 350,000 lines. Many fixes/features
-    are isolated to one specific area of the code. Others require
-    knowledge of much of the source. If you are confused about where to
-    start, ask the hackers list, and they will be glad to assess the
-    complexity and give pointers on where to start.</P>
-    <P>Another thing to keep in mind is that many fixes and features
-    can be added with surprisingly little code. I often start by adding
-    code, then looking at other areas in the code where similar things
-    are done, and by the time I am finished, the patch is quite small
-    and compact.</P>
-    <P>When adding code, keep in mind that it should use the existing
-    facilities in the source, for performance reasons and for
-    simplicity. Often a review of existing code doing similar things is
-    helpful.</P>
-    <P>The usual process for source additions is:
-    <UL>
-    <LI>Review the TODO list.</LI>
-    <LI>Discuss hackers the desirability of the fix/feature.</LI>
-    <LI>How should it behave in complex circumstances?</LI>
-    <LI>How should it be implemented?</LI>
-    <LI>Submit the patch to the patches list.</LI>
-    <LI>Answer email questions.</LI>
-    <LI>Wait for the patch to be applied.</LI>
-    </UL></P>
-    <H3><A name="1.3">1.3</A>) How do I download/update the current source
+       <H3><A name="1.7">1.7</A>) How do I download/update the current source
     <P>There are several ways to obtain the source tree. Occasional
     developers can just get the most recent source tree snapshot from
-    ftp.postgresql.org. For regular developers, you can use CVS. CVS
-    allows you to download the source tree, then occasionally update
-    your copy of the source tree with any new changes. Using CVS, you
-    don't have to download the entire source each time, only the
-    changed files. Anonymous CVS does not allows developers to update
-    the remote source tree, though privileged developers can do this.
-    There is a CVS section 
-    in our documentation that describes how to use remote CVS. You can
-    also use CVSup, which has similarly functionality, and is available
-    from ftp.postgresql.org.</P>
+    <a href="ftp://ftp.postgresql.org";>ftp://ftp.postgresql.org</a>.</p>
+    <p>Regular developers may want to take advantage of anonymous access to
+    our source code management system. The source tree is currently hosted in
+    CVS. For details of how to obtain the source from CVS see
+    <a 
+    <h3><A name="1.8">1.8</A>) How do I test my changes?</h3>
+    <p><b>Basic system testing</b></p>
+    <p>The easiest way to test your code is to ensure that it builds against
+    the latest verion of the code and that it does not generate compiler
+    warnings.</p>
-    <P>To update the source tree, there are two ways. You can generate
-    a patch against your current source tree, perhaps using the
-    make_diff tools mentioned above, and send them to the patches list.
-    They will be reviewed, and applied in a timely manner. If the patch
-    is major, and we are in beta testing, the developers may wait for
-    the final release before applying your patches.</P>
+    <p>It is worth advised that you pass --enable-cassert to <i>configure</i>.
+    This will turn on assertions with in the source which will often show
+    us bugs because they cause data corruption of segmentation violations. This
+    generally makes debugging much easier.</p>
+    <p>Then, perform run time testing via psql.</p>
+    <p><b>Regression test suite</b></p>
+    <p>The next step is to test your changes against the existing regression 
+    test suite. To do this, issue "make check" in the root directory of the 
+    source tree. If any tests failure, investigate.</p>
+    <p>If you've deliberately changed existing behaviour, this change may 
+    cause a regression test failure but not any actual regression. If so, 
+    you should also patch the regression test suite.</p>
+    <p><b>Other run time testing</b></p>
+    <p>Some developers make use of tools such as valgrind
+    (<a href="http://valgrind.kde.org";>http://valgrind.kde.org</a>) for 
+    memory testing, gprof (which comes with the GNU binutils suite) and 
+    oprofile (<a 
+     for profiling and other related tools.</p>
+    <p><b>What about unit testing, static analysis, model checking...?</b></p>
+    <p>There have been a number of discussions about other testing frameworks
+    and some developers are exploring these ideas.</p>
+   <h3><A name="1.9">1.9</A>) What tools are available for developers?</h3>
-    <P>For hard-core developers, Marc([EMAIL PROTECTED]) will give
-    you a Unix shell account on postgresql.org, so you can use CVS to
-    update the main source tree, or you can ftp your files into your
-    account, patch, and cvs install the changes directly into the
-    source tree.</P>
+    <p>First, all the files in the <i>src/tools</i> directory are designed for 
+    developers.</p>
-    <H3><A name="1.4">1.4</A>) How do I test my changes?</H3>
-    <P>First, use <I>psql</I> to make sure it is working as you expect.
-    Then run <I>src/test/regress</I> and get the output of
-    <I>src/test/regress/checkresults</I> with and without your changes,
-    to see that your patch does not change the regression test in
-    unexpected ways. This practice has saved me many times. The
-    regression tests test the code in ways I would never do, and has
-    caught many bugs in my patches. By finding the problems now, you
-    save yourself a lot of debugging later when things are broken, and
-    you can't figure out when it happened.</P>
-    <H3><A name="1.5">1.5</A>) What tools are available for
-    developers?</H3>
-    <P>Aside from the User documentation mentioned in the regular FAQ,
-    there are several development tools available. First, all the files
-    in the <I>/tools</I> directory are designed for developers.</P>
     RELEASE_CHANGES changes we have to make for each release
-    SQL_keywords    standard SQL'92 keywords
     backend         description/flowchart of the backend directories
     ccsym           find standard defines made by your compiler
+     copyright       fixes copyright notices
     entab           converts tabs to spaces, used by pgindent
     find_static     finds functions that could be made static
     find_typedef    finds typedefs in the source code
     find_badmacros  finds macros that use braces incorrectly
+    fsync           a script to provide information about the cost of cache
+                     syncing system calls
     make_ctags      make vi 'tags' file in each directory
     make_diff       make *.orig and diffs of source
     make_etags      make emacs 'etags' files
     make_keywords   make comparison of our keywords and SQL'92
     make_mkid       make mkid ID files
-    mkldexport      create AIX exports file
-    pgindent        indents C source files
-    pgjindent       indents Java source files
+    pgcvslog        used to generate a list of changes for each release
     pginclude       scripts for adding/removing include files
-    unused_oids     in pgsql/src/include/catalog
-    Let me note some of these. If you point your browser at the
-    <I>file:/usr/local/src/pgsql/src/tools/backend/index.html</I>
-    directory, you will see few paragraphs describing the data flow,
-    the backend components in a flow chart, and a description of the
-    shared memory area. You can click on any flowchart box to see a
-    description. If you then click on the directory name, you will be
-    taken to the source directory, to browse the actual source code
+    pgindent        indents source files
+    pgtest          a semi-automated build system
+    thread          a thread testing script
+    <p>In <i>src/include/catalog</i>:</p>
+    unused_oids     a script which generates unused OIDs for use in system
+                     catalogs
+    duplicate_oids  finds duplicate OIDs in system catalog definitions
+ </PRE>
+    If you point your browser at the <i>tools/backend/index.html</i> file,
+    you will see few paragraphs describing the
+    data flow, the backend components in a flow chart, and a description of the
+    shared memory area. You can click on any flowchart box to see a 
+    If you then click on the directory name, you will be taken to the source
+    directory, to browse the actual source code
     behind it. We also have several README files in some source
     directories to describe the function of the module. The browser
     will display these when you enter the directory also. The
@@ -250,26 +253,22 @@
     and then back out twice to return to the original function. Most
     editors support this via <I>tags</I> or <I>etags</I> files.</P>
-    <P>Third, you need to get <I>id-utils</I> from:</P>
-    <A href=
-    <A href=
-    <A href=
-    By running <I>tools/make_mkid</I>, an archive of source symbols can
-    be created that can be rapidly queried like <I>grep</I> or edited.
-    Others prefer <I>glimpse.</I> 
+    <p>Third, you need to get <I>id-utils</I> from <A 
+    <p>By running <I>tools/make_mkid</I>, an archive of source symbols can
+    be created that can be rapidly queried.</p>
-    <P><I>make_diff</I> has tools to create patch diff files that can
+    <p>Some developers make use of cscope, which can be found at 
+    <a href="http://cscope.sf.net";>http://cscope.sf.net/</a>. Others use
+    glimpse, which can be found at
+    <a href="http://webglimpse.net/";>http://webglimpse.net/</a>.
+    <P><I>tools/make_diff</I> has tools to create patch diff files that can
     be applied to the distribution. This produces context diffs, which
     is our preferred format.</P>
     <P>Our standard format is to indent each code level with one tab,
     where each tab is four spaces. You will need to set your editor to
-    display tabs as four spaces:<BR>
+    display tabs as four spaces:<br />
     vi in ~/.exrc:
@@ -313,11 +309,11 @@
              * End:
-    <BR>
+    <br />
      <I>pgindent</I> will the format code by specifying flags to your
     operating system's utility <I>indent.</I>  This 
-    <A HREF="http://ezine.daemonnews.org/200112/single_coding_style.html";>
-    article</A> describes the value of a constent coding style.
+    <A 
+       describes the value of a consistent coding style.
     <P><I>pgindent</I> is run on all source files just before each beta
     test period. It auto-formats all source files to make them
@@ -334,7 +334,7 @@
     There is also a script called <I>unused_oids</I> in
     <I>pgsql/src/include/catalog</I> that shows the unused oids.</P>
-    <H3><A name="1.6">1.6</A>) What books are good for developers?</H3>
+    <H3><A name="1.10">1.10</A>) What books are good for developers?</H3>
     <P>I have four good books, <I>An Introduction to Database
     Systems,</I> by C.J. Date, Addison, Wesley, <I>A Guide to the SQL
@@ -344,10 +344,9 @@
     <P>There is also a database performance site, with a handbook
-    on-line written by Jim Gray at <A href=
+    on-line written by Jim Gray at <A href= 
-    <H3><A name="1.7">1.7</A>) What is configure all about?</H3>
+    <H3><A name="1.11">1.11</A>) What is configure all about?</H3>
     <P>The files <I>configure</I> and <I>configure.in</I> are part of
     the GNU <I>autoconf</I> package. Configure allows us to test for
@@ -371,7 +370,7 @@
     all files derived by configure are removed, so you see only the
     file contained in the source distribution.</P>
-    <H3><A name="1.8">1.8</A>) How do I add a new port?</H3>
+    <H3><A name="1.12">1.12</A>) How do I add a new port?</H3>
     <P>There are a variety of places that need to be modified to add a
     new port. First, start in the <I>src/template</I> directory. Add an
@@ -390,7 +390,7 @@
     handling. There is a <I>backend/port</I> directory if you need
     special files for your OS.</P>
-    <H3><A name="1.9">1.9</A>) Why don't you use threads/raw
+    <H3><A name="1.13">1.13</A>) Why don't you use threads/raw
      devices/async-I/O, &lt;insert your favorite wizz-bang feature 
@@ -425,7 +425,7 @@
     contains links to discussions showing our reasoning in
     these areas.</P>
-    <H3><A name="1.10">1.10</A>) How are RPM's packaged?</H3>
+    <H3><A name="1.14">1.14</A>) How are RPMs packaged?</H3>
     <P>This was written by Lamar Owen:</P>
@@ -530,7 +530,7 @@
     <P>Of course, there are many projects that DO include all the files
     necessary to build RPMs from their Official Tarball (TM).</P>
-    <H3><A name="1.11">1.11</A>) How are CVS branches managed?</H3>
+    <H3><A name="1.15">1.15</A>) How are CVS branches managed?</H3>
     <P>This was written by Tom Lane:</P>
@@ -600,7 +600,7 @@
     dot-release or two, so that we won't have to double-patch the first
     wave of fixes.</P>
-    <H3><A name="1.12">1.12</A>) Where can I get a copy of the SQL
+    <H3><A name="1.16">1.16</A>) Where can I get a copy of the SQL
     <P>There are three versions of the SQL standard:  SQL-92, SQL:1999,
@@ -633,7 +633,21 @@
     http://dbs.uni-leipzig.de/en/lokal/standards.pdf</a> (paper)</li>
+       <h3><a name="1.17">1.17</a>) Where can I get technical assistance?</h3>
+    <p>Many technical questions held by those new to the code have been 
+    answered on the pgsql-hackers mailing list - the archives of which can be 
+    found at <a 
+    <p>If you cannot find discussion or your particular question, feel free to
+    put it to the list.</p>
+    <p>Major contributors also answer technical questions, including questions
+    about development of new features, on IRC at irc.freenode.net in the
+    #postgresql channel.</p>
       <H2>Technical Questions</H2>
@@ -746,9 +760,10 @@
-        <DT>lfirst(i)</DT>
+        <DT>lfirst(i), lfirst_int(i), lfirst_oid(i)</DT>
-        <DD>return the data at list element <I>i.</I></DD>
+        <DD>return the data (a point, inteter and OID respectively) at list 
+        element <I>i.</I></DD>
@@ -764,7 +765,9 @@
           snippet that loops through a List containing <I>Var *'s</I>
           and processes each one: 
-<CODE>List *i, *list;
+    List               *list;
+    ListCell   *i;
     foreach(i, list)
@@ -829,10 +831,11 @@
     <P>The structures passing around from the parser, rewrite,
     optimizer, and executor require quite a bit of support. Most
     structures have support routines in <I>src/backend/nodes</I> used
-    to create, copy, read, and output those structures. Make sure you
+    to create, copy, read, and output those structures (in particular,
+    the files <i>copyfuncs.c</i> and <i>equalfuncs.c</i>. Make sure you
     add support for your new field to these files. Find any other
     places the structure may need code for your new field. <I>mkid</I>
-    is helpful with this (see above).</P>
+       is helpful with this (see <a href="#1.9">1.9</a>).</P>
     <H3><A name="2.5">2.5</A>) Why do we use <I>palloc</I>() and
     <I>pfree</I>() to allocate memory?</H3>
---------------------------(end of broadcast)---------------------------
TIP 5: Have you checked our extensive FAQ?


Reply via email to