[CMake] CPack 101

[KC Jones]

Feeling really uneasy about putting this out there, but here goes...

I have an app that I am building with cmake (2.8) on both Mac (10.6.40 and Linux (Ubuntu 10.04).
The app depends on some libraries (Qt4.6 (no plugins) and a customized build of Poco).
I want to generate a DragAndDrop DMG installer on Mac. (a la macdeployqt + Poco lib packaging)
On Linux, I want a Debian package to install the Poco libs at a minimum along with my executable.
Equivalent Windows installers will be needed someday.

I've reviewed the docs at http://www.cmake.org/cmake/help/cmake-2-8-docs.html
I've reviewed bits and pieces on the wiki:
http://www.cmake.org/Wiki/BundleUtilitiesExample
http://www.cmake.org/Wiki/CMake#CPack

And I just don't seem to get it. I know this is very possible.  I know this is my own problem, first and foremost.  So I'm exposing myself to potential criticism here since RTFM and "get a clue" are probably the biggest part of fixing my problem.  Im not really asking for specific help on my code - I might ask for that later.  For now I just want to vent, hopefully in a constructive way.

I just don't think that CPack documentation and examples as they currently are published are sufficient or effective.

A few suggestions:
More CPack example and tutorials would be very helpful.  I see from archive searches that I'm not the first to suggest this.  The Qt example is great, but the plugin support is overkill for most, and obfuscates much of the rest of the example.
A step-wise tutorial format that starts with a working build, adds install target support, then adds CPack code would help my addled brain.  Presenting newbies like me with a fully baked end result is helpful, but somewhat hard to digest.
Separating the docs into different namespaces (Cmake, CPack, CTest...) might be more effective.  I struggled a long while before finding the install command docs (which I continue to struggle with). The atomic layout of the docs obscures the module-level relationships.
A glossary, please.  For instance "bundle" comes out of OS X, but now has some CMake-specific meaning for Linux and Win that I know is very important to me, but fully incomprehensible in my reading so far.  Oh, and what are bundle keys?
More meta docs please.  Somewhere in my stumbling I found a decent diagram about how the ExternalProject module works.  I think it was on the wiki, but I can't find it now.  I would die for something similar that shows what install does and how it integrates with CPack.  Same goes for BudleUtilities and other modules I've yet to discover.

One final comment, cmake is elegant in the extreme.  I can see from some of the wiki pages about how install is a merge that canonically folds multiple precursors into one uber-powerful, uber-flexible silver bullet.  Impressive I'm sure.  But harder to grok.  I'm not suggesting that this is a wrong choice.  But it is a barrier to learning.  Where there is this kind of folding of advanced features into basic operations, some care is needed to ensure the docs convey the basics clearly.

WRT Cpack, what I find is that by merging it into CMake, the CPack code is declared one step away from where it is applied.  The need for careful quoting in install(CODE ) blocks is a case in point.  I'm sure this folding into a canonical, unified single CMakeLists.txt source is a good thing.  But right now I feel like I'm learning Lisp again.  Kind of mind blowing.  Wishing I had some better training wheels to break this down for me...

Thanks for your indulgence.  I hope this does not offend those who've put so much into this great tool.

KC Jones
kc.jones at skype.net
SkypeId: bernalkc

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.cmake.org/pipermail/cmake/attachments/20101222/1d9d4ddb/attachment.htm>