Re: [cmake-developers] Make it easier for beginners

[Clément Gregoire]

Sorry, while I am motivated I had quite a busy month and let this thread
quietly slumber, which was not my intent.
I was hoping for a concrete answer to my questions but I suppose it
requires some sort of merge request (for the documentation/tutorials part),
as it would be more effective to get answers and feedback. I just didn't
want to have work being rejected just because "we don't put tutorials in
the documentation".
However I still think what I said for the wiki, if we can't put an
automated banner on CMake pages, then I guess I will have to edit those
myself.
@Bill sending you an email for the account.
If anybody has any resources or would like to help me for the tutorials,
please tell me. While I think I already have most of the resources and
knowledge for most of it, it never hurts.

Cheers,
- Lectem



2017-10-26 10:46 GMT+02:00 Nicholas Devenish :

> On Thu, Oct 26, 2017 at 12:49 AM, Wesley Smith 
> wrote:
>
>> I still don't understand the scoped syntax in Daniel Pfeifer's talk (e.g.
>> boost::boost)
>>
>
> Easy: It doesn't mean anything special, it's almost entirely just a name
> (think of :: as any other character).
>
> The advantage is,
> a) bookkeeping e.g. cleanly namespacing stuff (which admittedly could be
> done with _/prefixes)
> and more importantly
> b) If you give an undefined name e.g. "boost_notalib" (or something
> mis-spelled) to target_link_libraries it'll just add "-lboost_notalib" to
> the link command - because it doesn't know if it's a custom library that it
> doesn't know about,  or an undefined target. A name like "Boost::NotALib"
> can never be a library name, so if it's not a defined target you'll get an
> error at configuration time rather than build time.
>
> (Caveat: I am not an expert so could be completely wrong in incomplete or
> subtle ways, but this is definitely one way it makes a difference)
>
> Nick
>
> --
>
> 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
>
-- 

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

Re: [cmake-developers] Make it easier for beginners

[Nicholas Devenish]

On Thu, Oct 26, 2017 at 12:49 AM, Wesley Smith 
wrote:

> I still don't understand the scoped syntax in Daniel Pfeifer's talk (e.g.
> boost::boost)
>

Easy: It doesn't mean anything special, it's almost entirely just a name
(think of :: as any other character).

The advantage is,
a) bookkeeping e.g. cleanly namespacing stuff (which admittedly could be
done with _/prefixes)
and more importantly
b) If you give an undefined name e.g. "boost_notalib" (or something
mis-spelled) to target_link_libraries it'll just add "-lboost_notalib" to
the link command - because it doesn't know if it's a custom library that it
doesn't know about,  or an undefined target. A name like "Boost::NotALib"
can never be a library name, so if it's not a defined target you'll get an
error at configuration time rather than build time.

(Caveat: I am not an expert so could be completely wrong in incomplete or
subtle ways, but this is definitely one way it makes a difference)

Nick
-- 

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

Re: [cmake-developers] Make it easier for beginners

[Wesley Smith]

I agree that if you do a search for how to setup a project with cmake, it's
hard to know what's best practice.  As cmake has evolved, the best practice
has changed and many old style techniques still return toward the top of
search results.  For me, the best resources have been:

http://preshing.com/20170522/learn-cmakes-scripting-language-in-15-minutes/
https://www.youtube.com/watch?v=bsXLMQ6WgIk

I still don't understand the scoped syntax in Daniel Pfeifer's talk (e.g.
boost::boost).  And CPack was really opaque to me until I bought the cmake
book.  I wish there were better tutorials on CPack and on how to write
cmake scripts that play well as dependencies on other projects using cmake.

wes


On Sun, Oct 22, 2017 at 12:08 PM, Bill Hoffman 
wrote:

> On 10/21/2017 10:56 AM, Lectem wrote:
>
>> _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.
>>
>> The wiki is still open.  If people want to edit they have to send an
> email and let us know what they want to do.  It was too hard to keep the
> spam off of it otherwise.  So, send me an email off list and I can get you
> setup with a wiki account.
>
> -Bill
> --
>
> 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/opensou
> rce/opensource.html
>
> Follow this link to subscribe/unsubscribe:
> http://public.kitware.com/mailman/listinfo/cmake-developers
>
-- 

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

Re: [cmake-developers] Make it easier for beginners

[Bill Hoffman]

On 10/21/2017 10:56 AM, Lectem wrote:

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


The wiki is still open.  If people want to edit they have to send an 
email and let us know what they want to do.  It was too hard to keep the 
spam off of it otherwise.  So, send me an email off list and I can get 
you setup with a wiki account.


-Bill
--

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

[cmake-developers] Make it easier for beginners

[Lectem]

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