consensus on debug (-g) policy

[Ben Collins <bcollins@debian.org>]

retitle 43787 [AMENDED] changing policy on compiling with -g .. a better way

thanks

Since this obviously has a consensus, I am making it amended. Here are the
final changes.

Thanks to all who helped mold this into it's final state, and to Manoj who
drafted the original change that this one is based on. I think it was fairly
agreed that the second choice was the better, so that is the only one I am
including in this final draft.

NOTE: I added a blurb about debhelper's dh_strip abiding by this policy,
since Joey said he would make the change if it was passed. This is a good
thing since packages that depend on dh_strip will automatically follow
this policy (almost, they still compile with -g by default).

Ben

======================================================================
        We deprecate the old method, but let it be still legal.
======================================================================
          CC = gcc
-         CFLAGS = -O2 -g -Wall # sane warning options vary between programs
+         # sane warning options vary between programs
+         CFLAGS = -O2 -Wall
+         ifneq (,$(findstring $(DEB_BUILD_OPTIONS),DEBUG Debug debug))
+         CFLAGS += -g 
+         INSTALL_FLAGS= -s
+         endif
          LDFLAGS = # none
-         install -s # (or use strip on the files in debian/tmp)
+         install $(INSTALL_FLAGS) # 
.........
          The `-g' flag is useful on compilation so that you have available a
          full set of debugging symbols in your built source tree, in case
          anyone should file a bug report involving (for example) a core dump.
+         It is acceptable, but deprecated, to always have -g in
+         ``CFLAGS'', and use ``install -s'' to install binaries or use
+         ``strip'' on the binaries in debian/tmp, but that make it
+         hard to create a debuggable debian package, and increase
+         build time for all builds, since debugging information is
+         created and then stripped away. The preferred method is to
+         use an environment variable DEB_BUILD_OPTIONS, which, if it 
+         contains `debug', would cause compilation to be done with -g. The
+         resulting binaries in your package will then contain the full
+         set of debugging symbols (remember not to call ``install -s''
+         or ``strip'' on the binaries afterwards).
+
+         NOTE: Debhelper's ``dh_strip'' command will honor this policy, so that
+         old packages that use it will automatically compile and keep the debug
+         symbols when DEB_BUILD_OPTIONS contains ``debug'' (although they will
+         still build with -g by default, and should be changed).
+
+         The DEB_BUILD_OPTIONS var will also let us later add other options in
+         a fairly clean way.
+
+         Additionally, (and optionally) you may also provide a target
+         `build-debug' in debian/rules which has the same effect as
+         setting DEB_BUILD_OPTIONS to contain `debug'. This can be done 
+         quite simply, with the following lines:
+ build-debug: DEB_BUILD_OPTIONS+=debug
+ build-debug: build
======================================================================