[CMake] CPack 101

Thu Dec 23 07:43:15 EST 2010

On Wed, Dec 22, 2010 at 12:57 PM, KC Jones <kc.jones at skype.net> wrote:

> 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.
>
>
Neither do we:
http://public.kitware.com/Bug/view.php?id=10067

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.
>
>
As always, as developers we find ourselves constantly working to improve
what we have: fixing bugs, implementing new features, answering questions on
the mailing list, blogging/communicating about it, adding examples and
suggestions to the Wiki.

The struggle is reserving enough time to contribute to documentation when
there are always "real" (functional) bugs to be fixed. Perpetual questions:
what's "enough" documentation?, how do we make sure people can find it
easily?, how do we name this better (but still preserve the existing names
for people already using it / backwards compatibility)?

I make no excuses here: yes, the CPack and CTest documentation are lacking /
lagging behind the CMake documentation. However, it will take a very real
and concerted and time-consuming effort to improve the situation. With the
open source nature of the project, we have to be willing to accept the
organic growth that occurs in the code base: the documentation will be the
same: it will improve gradually, over time, as contributors are able to
improve it.

Until then, at least the mailing list has a reasonable response rate and, it
seems, sufficient participation from knowledgeable folks willing to pitch in
and answer. So... if you're confused about something, please ask here.

> 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.
>

Thanks for your comments and questions. May we quote you on that? ("cmake is
elegant in the extreme ... great tool")

We (I hope I speak for all CMake devs, here) take no offense. We welcome
discussion, always.

David Cole
Kitware, Inc.

> KC Jones
> kc.jones at skype.net
> SkypeId: bernalkc
>
>
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
>
> Please keep messages on-topic and check the CMake FAQ at:
> http://www.cmake.org/Wiki/CMake_FAQ
>
> Follow this link to subscribe/unsubscribe:
> http://www.cmake.org/mailman/listinfo/cmake
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.cmake.org/pipermail/cmake/attachments/20101223/fe3679de/attachment.htm>