[CMake] Announcing CMake BASIS, a set of CMake based project interoperability and automation tools

[Andrew Hundt]

On Wed, Jan 22, 2014 at 5:44 PM, Stephen Kelly <steveire at gmail.com> wrote:

> Andrew Hundt wrote:
>
> > CMake BASIS is a set of utilities and standards created with the goal of
> > making CMake projects and libraries very easy to create, share, and
> reuse.
>
> Hello,
>
> There seems to be several years of development behind this already. Is it
> newly public, or newly publicized? I've never heard of it before.
>

The about page <http://opensource.andreasschuh.com/cmake-basis/about.html> and
the 3.0 release on
github<https://github.com/schuhschuh/cmake-basis/releases/tag/v3.0.0>
explains
the history reasonably well. Previously it was public but not publicized.
For the v3.0 release we moved it to github, redesigned and rewrote much of
the documentation, added custom project templates, and made everything else
configurable. For example we needed take out previously hard coded items
such as University of Pennsylvania logo (I'm at Carnegie Mellon).


>
> > Website: http://opensource.andreasschuh.com/cmake-basis/index.html
> > GitHub: https://github.com/schuhschuh/cmake-basis/
>
> The repo is surprisingly large (67 mb) for something like this. I consider
> such large files in a git repo to be bad practice. This is just the first
> thing I noticed...
>
> Commit: [...]


Hmm, I hadn't noticed the size before. There are a few powerpoint
presentations and a PDF manual that probably contribute to the size, there
are also a couple of small external libraries that are directly committed
into the tree. The zip version of the release is 2.7 MB which is not quite
as bad. I'm not well versed with the guts of git but are there any good
ways to do some cleanup?


>
> > Also, if any CMake developers are interested in bringing any of this
> > functionality upstream into CMake itself we would also love to hear from
> > you.
>
> I read some of the docs and some of the code (TargetTools.cmake). My
> understanding my not be complete or correct.
>
> 1) BASIS seems to be doing lots of things. Can you identify what parts of
> BASIS or what concepts are most valuable/most useful/most missing from
> CMake
> etc? I think you could know better than we can.
>

I would suggest many of the items from the BASIS CMake
modules<http://opensource.andreasschuh.com/cmake-basis/apidoc/modules.html>,
specifically the section labeled "BASIS Modules".

Some of the specific useful items include:

   - basis_add_doc<http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/group__CMakeAPI.html#ga06f94c5d122393ad4e371f73a0803cfa>()
   - built in support of documentation tools
   - Additional support for other languages, such as MATLAB and Python
   - Automated packaging and installation of libraries
   - Support for doxygen documentation of CMake Code

I'm sure there is more but those are some of the most obvious items that I
can think of off the top of my head.


> For example, do you consider
>
>  add_executable(myexe.cpp)
>
> to be good user interface for creating a target called 'myexe', and
> something that CMake should do?


It seems like it would be pretty straightforward and easy to use. I've seen
that functionality implemented independently on more than one occasion.


> Should CMake automatically create
> installation rules for it?
>

I think this would be excellent if there was a reasonable default, plus
more advanced configuration for when it is needed. This could also happen
for libraries. Right now it seems CMake has a lot of boilerplate that could
be skipped by making functions automate steps using reasonable defaults
that can be modified or disabled as needed.


>
> Another example: You have some target-source-file-globbing code. Should
> that
> be extracted, generalized and upstreamed?
>
>  https://www.mail-archive.com/cmake-developers@cmake.org/msg06725.html


I've seen a number of requests for such funcitonality so it may be
desirable, although I don't personally use it.


> Another example: You have code for adding scripts as executables. What are
> the generic (non-BASIS related) use cases for that?


Many projects aren't libraries or installable software for distribution in
one language, but instead a set of custom utilities that call each other
via the general Unix philosophy. Also, groups that build embedded software
or backend software will have scripts that automatically start, monitor,
deploy, implement, and/or run their software. Programs based on scripting
languages also need packaging and installation just like any other compiled
language if they are to be opened via an icon on a user's system.


> Should CMake be extended with similar capabilities somehow?


I personally believe this could be very useful to quite a few users.


> Would it help if an IMPORTED executable could be a script?
>

What would this entail? Is there perhaps another question behind this
question?


> Another example: Can the documentation utilities be separated from the rest
> of BASIS, made generic and still be useful?
>

Yes, I believe that is possible. I may be mistaken but I believe
DocTools.cmake is fairly independent aside from a few auxillary files in
the local folder that it configures.


>
> 2) Do you generally recommend that CMake users use BASIS from now on, or is
> it something you expect will be niche/mostly used by yourselves?
>

Everyone will have different use cases and needs, and BASIS doesn't handle
100% of CMake functionality. However, I personally expect that I will use
BASIS on my own projects because it simply cuts out a lot of the manual
steps and boilerplate needed for documentation and setting up a typical
project/library directory.


>
> 3) BASIS requires me to use basis_add_executable, KDE4 requires me to use
> kde4_add_executable, VTK requires me to use vtk_add_executable.
>
> BASIS seems to wrap many or most CMake commands which define the
> buildsystem. That was realized to be bad practice in KDE. The new KDE
> Frameworks (KF5) do not have that requirement or practice, and instead the
> regular add_executable CMake commands (and similar) are recommended. CMake
> has been extended (by myself and others) to make that possible without
> losing features.


> This way, not only is interoperability increased, but users of a KF5
> package
> can rely on the CMake documentation to understand and reason about code
> they
> read and write. Further, the buildsystem for KF5 is CMake not 'something on
> top of CMake', which then must be understood. Using CMake directly, and not
> 'something on top of CMake' is also a goal of the boost effort to migrate
> to
> CMake.
>
> Further, wrappers like that can not cleanly offer all of the features of
> wrapped commands, as those commands get updated in CMake. I'm not sure your
> wrappers can handle ALIAS, INTERFACE or OBJECT libraries for example, and
> it
> seems that
>
>  add_library(tgt SHARED IMPORTED)
>
> might work, whereas
>
>  add_library(tgt IMPORTED SHARED)
>
> would not. Ok, it's not documented to work either, but my point is that
> wrappers are not good API proxies.
>
> Any comments on that?
>

Cool, is there a good reference explaining how wrapped functions can be
eliminated? Some of the functionality like the automated packaging steps
are made possible by the wrapped functions, but if there was another way to
do it I'm sure that would be ideal.


>
> 4) BASIS seems to expect settings, flags etc to be written as directory
> scoped. Modern CMake is increasingly scoped to targets, with directory
> scoped commands considered only convenience for populating properties on
> targets.
>
>
> http://www.cmake.org/cmake/help/git-master/manual/cmake-buildsystem.7.html#directory-scoped-commands
>
> This is mostly helpful for transitive usage requirements and related CMake
> concepts.
>
> Do you think BASIS would move in a similar direction?
>

Yes, I would expect it to follow the direction of CMake. As a side note,
one thing I've wished for with CMake is an up-to-date style guide, how-to,
and tutorials capturing the best recommended way to write Modern CMake code
for a cross platform distributable library. For example, even the basic
cmake tutorial <http://cmake.org/cmake/help/cmake_tutorial.html> doesn't
use the more recent "Modern CMake" capabilities.


>
>
> Thanks,
>
> Steve.


Thanks for all your feedback and interest! It is appreciated.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.cmake.org/pipermail/cmake/attachments/20140122/33a54c9a/attachment-0001.html>