[CMake] Recap of some steps for making Debian files

[Christian Convey]

Some good ideas and some misconceptions have been thrown around as
I've tried to use CMake to produce Debian packages.  Here's a
consolidation of what I think are the major lessons, in case anyone
else has to do this too.

The notes below do *not* completely describe how to build Debian
packages with CMake.  They're just a braindump of stuff that I
couldn't figure out except by talking with people.

A) If you want to do "make install", you must first make the
"preinstall" target.  Otherwise "make install" will fail.  (Well, I
think the actual situation is that 'make install' will only fail if
you're using CMake to build both executables, and libraries against
which those executables are linked.)

But beware: Although "make preinstall" seems to work, it appears that
"preinstall" isn't exactly a proper target name.  When I tried to list
it in the DEPENDS section of an ADD_CUSTOM_TARGET call, CMake
complained that it didn't know about any target named 'preinstall'.
Also, Alex warned that 'make preinstall' isn't a formally supported
aspect of CMake, so it could disappear at any time in the future.

B) It *is* possible to adjust, as you're running "make install", the
base directory into which files get installed.  You do it with the
"DESTDIR" variable.  I.e.:
   make install DESTDIR=/tmp/test-installation/
(Note that the CMAKE_INSTALL_PREFIX directory also comes into play, as
well as the issue of whether you specified an absolute or relative
pathname within your INSTALL(...) commands.)

C) The version of CPack currently in CVS, and scheduled to become part
of the 2.6 release, can create Debian files.  2.6 will hopefully be
released later this year.  The Debian functionality for CPack is still
somewhat unproven though and could use more testing.

D) There's a package called DpkgDeb, from a guy named Medhi:
   http://www.cmake.org/Wiki/CMakeUserUseDebian#Derived_work
I had a few issues with it, so I decided to write my own code for
making Debian packages.  But at least until CPack 2.6 comes out,
DpkgDeb seems to be the recommended starting point.

E) Medhi's package actually uses a pretty helpful technique, which I'm
using too.  You write your CMake files so that the "install" target
populates a directory tree with your project's install-worthy files
(libraries, executables, etc.).  Then you run "dpkg-deb" on that
directory (in addition to doing a few other things) to produce the
.deb files.

F) Now that INSTALL(...) supports the COMPONENT parameter, you can
more easily use Medhi's general approach to produce multiple Debian
packages from a single CMake project.  The idea is that you define one
INSTALL COMPONENT to describe the files that belong in each of the
different Debian packages you want to create.  Then you do a different
'make install' for each of those components, into a different
directory for each component.

G) It's possible to perform an installation using details that differ
from what you specified when you ran CCMake on your project.  You can
run a command something like this:
   cmake -P cmake_install.cmake -D<cmake-variable-assignment> -D...

(Also note that this is actually what "make install" does: it invokes
the "cmake" program and has it process a file called
"cmake_install.cmake" which was written when you ran "cmake" in this
project directory.)

I *used* to think this "cmake -P ..." approach was the only way to
install to a directory whose path was computed at CMake runtime.  But
it turns out that the following code fragment works just fine:

ADD_CUSTOM_TARGET(debs
   COMMAND ${CMAKE_MAKE_PROGRAM} preinstall
   COMMAND ${CMAKE_MAKE_PROGRAM} install DESTDIR=${MY_CALCULATED_DIR}
)

(Note that you can't just use "DEPENDS preinstall install"; neither
'preinstall' nor 'install' seems to be the kind of target that can be
part of a dependency tree.)

Hope this is helpful.

- Christian