From 9af6bd9962971d0e6f4cbec51852ecc734b21167 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Fri, 22 May 1998 04:20:53 +0000 Subject: Move FAQ_DEV to docs directory, where it belongs. --- doc/FAQ_DEV | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/DEVELOPERS | 4 +- src/tools/FAQ_DEV | 141 ----------------------------------------------------- 3 files changed, 145 insertions(+), 142 deletions(-) create mode 100644 doc/FAQ_DEV delete mode 100644 src/tools/FAQ_DEV diff --git a/doc/FAQ_DEV b/doc/FAQ_DEV new file mode 100644 index 00000000000..e9f663f5113 --- /dev/null +++ b/doc/FAQ_DEV @@ -0,0 +1,142 @@ +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 +pgsql/src/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 +pgsql/src/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 pgsql/src/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 three good books, An Introduction to Database Systems, by C.J. Date, +Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et. al, +Addison, Wesley, and Transaction Processing: Concepts and Techniques, +by Jim Gray and Andreas Reuter, Morgan, Kaufmann. + +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. diff --git a/src/DEVELOPERS b/src/DEVELOPERS index 99f0c8c8908..ae44a31334f 100644 --- a/src/DEVELOPERS +++ b/src/DEVELOPERS @@ -1 +1,3 @@ -All the developer tools are located in the /tools directory. +Read the Developer's FAQ in pgsql/doc/FAQ_DEV. All the developer tools +are located in the pgsql/src/tools directory. + diff --git a/src/tools/FAQ_DEV b/src/tools/FAQ_DEV deleted file mode 100644 index 72de67a988d..00000000000 --- a/src/tools/FAQ_DEV +++ /dev/null @@ -1,141 +0,0 @@ -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 three good books, An Introduction to Database Systems, by C.J. Date, -Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et. al, -Addison, Wesley, and Transaction Processing: Concepts and Techniques, -by Jim Gray and Andreas Reuter, Morgan, Kaufmann. - -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. -- cgit v1.2.3