Re: Patch - Debug builds without optimization

Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > I have applied the attached patch to mention the debugger.  OK?
>
> >         Server developers should consider using the configure options
> >         <option>--enable-cassert</> and <option>--enable-debug</> to enhance the
> >         ability to detect and debug server errors.  They should also consider
> > !       running configure with <literal>CFLAGS="-O0 -g"</> if using a debugger.
>
> I still think this is basically useless.  If we're going to mention the
> topic at all, we should provide enough information to be helpful, which
> this does not.  Furthermore, it's concretely wrong in that it suggests
> you need to say -g when --enable-debug already does that, and that it
> fails to note that all this advice is gcc-specific.
>
> I suggest wording along these lines:
>
>     When developing code inside the server, it's recommended to
>     use the configure options --enable-cassert, which turns on many
>     run-time error checks, and --enable-debug, which improves the
>     usefulness of debugging tools.
>
>     If you use gcc, it's best to build with an optimization level
>     of at least -O1, because using level -O0 disables some important
>     compiler warnings (such as use of an uninitialized variable).
>     However, nonzero optimization levels can complicate debugging
>     because stepping through the compiled code will usually not
>     match up one-to-one with source code lines.  If you get confused
>     while trying to debug optimized code, recompile the specific
>     file(s) of interest with -O0.  An easy way to do this with the
>     Unix makefiles is "make PROFILE=-O0 file.o".

OK, I make some slight modifications and applied the attached patch.

Ideally we could tell everyone to read the developer's FAQ, but that is
too large for people who are debugging problems in our shipped code ---
that is why I was excited to get something into our main docs.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
new file mode 100644
index 1135961..75fb783
*** a/doc/src/sgml/installation.sgml
--- b/doc/src/sgml/installation.sgml
*************** su - postgres
*** 1415,1424 ****

      <note>
       <para>
!       Server developers should consider using the configure options
!       <option>--enable-cassert</> and <option>--enable-debug</> to enhance the
!       ability to detect and debug server errors.  Your debugger might
!       also require specific compiler flags to produce useful output.
       </para>
      </note>
     </step>
--- 1415,1437 ----

      <note>
       <para>
!       When developing code inside the server, it is recommended to
!       use the configure options <option>--enable-cassert</> (which
!       turns on many run-time error checks) and <option>--enable-debug</>
!       (which improves the usefulness of debugging tools).
!      </para>
!
!      <para>
!       If using GCC, it is best to build with an optimization level of
!       at least <option>-O1</>, because using no optimization
!       (<option>-O0</>) disables some important compiler warnings (such
!       as the use of uninitialized variables).  However, non-zero
!       optimization levels can complicate debugging because stepping
!       through compiled code will usually not match up one-to-one with
!       source code lines.  If you get confused while trying to debug
!       optimized code, recompile the specific files of interest with
!       <option>-O0</>.  An easy way to do this is by passing an option
!       to <application>make</>: <command>gmake PROFILE=-O0 file.o</>.
       </para>
      </note>
     </step>