PERFORCE change 102664 for review

[Gabor Kovesdan]

http://perforce.freebsd.org/chv.cgi?CH=102664

Change 102664 by gabor at gabor_spitfire on 2006/07/28 17:08:30

	Document WITH_DEBUG.

Affected files ...

.. //depot/projects/soc2006/gabor_docs/porters-handbook/book.sgml#11 edit

Differences ...

==== //depot/projects/soc2006/gabor_docs/porters-handbook/book.sgml#11 (text+ko) ====

@@ -4117,6 +4117,25 @@
     <sect1 id="building">
       <title>Building mechanisms</title>
 
+      <sect2 id="with-debug">
+        <title>Building binaries for debugging purposes with
+	  <makevar>WITH_DEBUG</makevar></title>
+
+	<para>If you need to build binaries with debug symbols, you can set
+	  <makevar>WITH_DEBUG</makevar>.  This adds <makevar>DEBUG_FLAGS</makevar>
+	  to <makevar>CFLAGS</makevar> and prevents <makevar>INSTALL_PROGRAM</makevar>
+	  from stripping binaries when installing.  <makevar>DEBUG_FLAGS</makevar> is
+	  set to "-g" at default, but you can override this if necessary.  Furthermore,
+	  ports could (and should) add their own specific things to build for
+	  debugging.</para>
+
+	<para>Note, that there are ports that do not respect our
+	  <makevar>INSTALL_PROGRAM</makevar> variable, so they will be still
+	  stripped even if <makevar>WITH_DEBUG</makevar> is set.  In these
+	  cases, you have to manually patch the port to work as intended.</para>
+
+      </sect2>
+
       <sect2 id="using-make">
 	<title><command>make</command>, <command>gmake</command>, and
 	  <command>imake</command></title>