mirror of https://github.com/postgres/postgres
Bruce Momjian
28 years ago
parent
2ed7b03c46
commit
fe521fbe76
@ -0,0 +1,140 @@ |
||||
Developer's Frequently Asked Questions (FAQ) for PostgreSQL |
||||
|
||||
Last updated: Wed Feb 11 20:23:01 EST 1998 |
||||
|
||||
Current maintainer: Bruce Momjian (maillist@candle.pha.pa.us) |
||||
|
||||
The most recent version of this document can be viewed at the postgreSQL Web |
||||
site, http://postgreSQL.org. |
||||
|
||||
------------------------------------------------------------------------ |
||||
|
||||
Questions answered: |
||||
|
||||
1) What tools are available for developers? |
||||
2) What books are good for developers? |
||||
3) Why do we use palloc() and pfree() to allocate memory? |
||||
4) Why do we use Node and List to make data structures? |
||||
5) How do I add a feature or fix a bug? |
||||
6) How do I download/update the current source tree? |
||||
7) How do I test my changes? |
||||
|
||||
------------------------------------------------------------------------ |
||||
|
||||
1) What tools are available for developers? |
||||
|
||||
Aside from the User documentation mentioned in the regular FAQ, there are |
||||
several development tools available. First, all the files in the /tools |
||||
directory are designed for developers. |
||||
|
||||
RELEASE_CHANGES changes we have to make for each release |
||||
SQL_keywords standard SQL'92 keywords |
||||
backend web flowchart of the backend directories |
||||
ccsym find standard defines made by your compiler |
||||
entab converts tabs to spaces, used by pgindent |
||||
find_static finds functions that could be made static |
||||
find_typedef get a list of typedefs in the source code |
||||
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.README make comparison of our keywords and SQL'92 |
||||
make_mkid make mkid ID files |
||||
mkldexport create AIX exports file |
||||
pgindent indents C source files |
||||
|
||||
Let me note some of these. If you point your browser at the tools/backend |
||||
directory, you will see all the backend components in a flow chart. You can |
||||
click on any one 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 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 tools/backend directory is also contained |
||||
on our web page under the title Backend Flowchart. |
||||
|
||||
Second, you really should have an editor that can handle tags, so you can |
||||
tag a function call to see the function definition, and then tag inside that |
||||
function to see an even lower-level function, and then back out twice to |
||||
return to the original function. Most editors support this via tags or etags |
||||
files. |
||||
|
||||
Third, you need to get mkid from ftp.postgresql.org. By running |
||||
tools/make_mkid, an archive of source symbols can be created that can be |
||||
rapidly queried like grep or edited. |
||||
|
||||
make_diff has tools to create patch diff files that can be applied to the |
||||
distribution. |
||||
|
||||
pgindent will format source files to match our standard format, which has |
||||
four-space tabs, and an indenting format specified by flags to the your |
||||
operating system's utility indent. |
||||
|
||||
2) What books are good for developers? |
||||
|
||||
I have two good books, An Introduction to Database Systems, by C.J. Date, |
||||
Addison, Wesley and A Guide to the SQL Standard, by C.J. Date, et. al, |
||||
Addison, Wesley. |
||||
|
||||
3) Why do we use palloc() and pfree() to allocate memory? |
||||
|
||||
palloc() and pfree() are used in place of malloc() and free() because we |
||||
automatically free all memory allocated when a transaction completes. This |
||||
makes it easier to make sure we free memory that gets allocated in one |
||||
place, but only freed much later. There are several contexts that memory can |
||||
be allocated in, and this controls when the allocated memory is |
||||
automatically freed by the backend. |
||||
|
||||
4) Why do we use Node and List to make data structures? |
||||
|
||||
We do this because this allows a consistent way to pass data inside the |
||||
backend in a flexible way. Every node has a NodeTag which specifies what |
||||
type of data is inside the Node. Lists are lists of Nodes. lfirst(), |
||||
lnext(), and foreach() are used to get, skip, and traverse through Lists. |
||||
|
||||
5) How do I add a feature or fix a bug? |
||||
|
||||
The source code is over 250,000 lines. Many problems/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. |
||||
|
||||
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. |
||||
|
||||
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. |
||||
|
||||
6) How do I download/update the current source tree? |
||||
|
||||
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 get CVSup, which is available from |
||||
ftp.postgresql.org too. CVSup allows you to download the source tree, then |
||||
occasionally update your copy of the source tree with any new changes. Using |
||||
CVSup, you don't have to download the entire source each time, only the |
||||
changed files. CVSup does not allow developers to update the source tree. |
||||
|
||||
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. |
||||
|
||||
For hard-core developers, Marc(scrappy@postgresql.org) will give you a Unix |
||||
shell account on postgresql.org, and you can ftp your files into your |
||||
account, patch, and cvs install the changes directly into the source tree. |
||||
|
||||
6) How do I test my changes? |
||||
|
||||
First, use psql to make sure it is working as you expect. Then run |
||||
src/test/regress and get the output of src/test/regress/checkresults 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. |
||||
Loading…
Reference in new issue