Hi guys.
You've probably seen me whining a bit here and there about why CMake is hard to
get for begginers,
and thanks to Ruslo pushing me to it, I finally got the motivation to be
involved and contribute to CMake.
I hope this mail can be the beginning of a thought on the CMake ecosystem, and
not seen as a rant.
I'd like to discuss a few issues and learning barriers I've heard in the
previous years concerning CMake.
Those problems were even more pointed out recently when Boost decided to switch
to cmake.
Most of the time, people will tell you stuff like this (note that I'm not
inventing those, as most were told to me by co-workers) :
- "it is too hard to know what I should do, or how to do it right"
- "Many articles are out there, none agree on what to do and the documentation
is just an API reference, not a real documentation"
- "Based my CmakeLists.txt on the wiki, and now people tell me it's bad
practice"
- "I don't get why it's not finding my stuff, it's frustrating"
- "I managed to get a simple program running, but as soon as tried to add more
stuff, nothing was working or I didn't understand the docs"
... And the list goes on.
>From my point of view, it mostly comes from a misconception of what CMake now
>is and the fact it is hard to learn.
In a sense, it's basicly the same problem as C++.
CMake can be easy, but is seen as hard by some people because it has many
features and ways to express the same thing, and that many people write
CMakeLists.txt that do not "embrace modern CMake".
So I'd like to make it easier for these people to learn CMake, and for that I
need some pointers and the opinion of the current developpers.
I'll make this a list of questions / proposals on which I need feedback, and
try to explain my reasons behind it.
Question : Would it possible to delete the wiki, or reset/reopen it ?
Reason: The wiki is full of old stuff, but we can't register to edit stuff.
Still, people willing to learn will end up visiting it, thinking it gives good
advice. "How could it not ? It's the official wiki". At the very least I wish
we could add a big red message stating it is outdated and not updated anymore.
Question: Would it be ok to add tutorials to the documentation ?
Reason: That's where most people will start with. Diving in the CMake
documentation is hard for beginners. For example, understanding transitive
properties requires that you read most of cmake-buildsystem, which is a lot to
digest at once. A tutorial would help people understanding how to use it and
more importantly why they should use it.
Question: Add examples (in link with the tutorials) ?
Reason : Mostly the same as the previous one, having examples can help people
with a quickstart and agree on what is the "latest" command/feature to use for
X/Y/Z.
Question: Can we add "Added in / API last updated" fields ? I'm not familiar
enough with Sphynx yet to know how we could change the template for this. Or
perhaps just add it as text in the rst?
Reason: It is hard to know in what version some functionalities are added, and
not everybody can afford to require the latest CMake version (though it would
be nice). It would be nice to have this at least for new features in the next
version
I hope that little by little we will make CMake easier to use for the
community, and to this end I'm ready to spend time updating the documentation,
errors and write some tutorials / examples.
I truely believe that it is as important as releasing new features.
My idea is mainly to slowly move/enhance stuff from CGold
(https://cgold.readthedocs.io/en/latest/) in the official documentation, so
that people can rely on it. (By that I mean that people will more easily trust
the documentation than CGold if they are new to CMake)
Lectem
--
Powered by www.kitware.com
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Kitware offers various services to support the CMake community. For more
information on each offering, please visit:
CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/mailman/listinfo/cmake-developers
