target_link_libraries - private public interface rules

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

target_link_libraries - private public interface rules

Miller Henry
 
I’ve been playing with the private/public/interface keyword to target_link_libraries. It seems to me that WHAT they do is well documented, but nobody has ever actually documented what they correct rules of WHEN/WHY you should use any of them. After a lot of misstarts I think I’ve started to understand what the rules should be. I think they need to be written down someplace so that others don’t have to make the mistakes I have. Also it would be nice if others would look this list over to see what else might be overlooking.
 
Can somebody point me to a good place to do this? Sending to the mailing list seems like a poor solution as corrections will not be easily findable.  A wiki seems ideal, but which? KDE in particular should probably have these rules in their official requirements, but I’m not sure if they are the correct ones to own them.
 

--

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
Reply | Threaded
Open this post in threaded view
|

Re: target_link_libraries - private public interface rules

Robert Maynard
You could look at extending the official CMake documentation,
specifically the build system documentation (
https://cmake.org/cmake/help/v3.9/manual/cmake-buildsystem.7.html ).

The documentation is all in restructure text and we accept
documentation changes through our gitlab instance.

cmake gitlab: https://gitlab.kitware.com/cmake/cmake

build-system restructure page:
https://gitlab.kitware.com/cmake/cmake/blob/master/Help/manual/cmake-buildsystem.7.rst

contribution guideline:
https://gitlab.kitware.com/cmake/cmake/blob/master/CONTRIBUTING.rst

On Tue, Aug 22, 2017 at 9:44 AM, Miller Henry <[hidden email]> wrote:

>
> I’ve been playing with the private/public/interface keyword to
> target_link_libraries. It seems to me that WHAT they do is well documented,
> but nobody has ever actually documented what they correct rules of WHEN/WHY
> you should use any of them. After a lot of misstarts I think I’ve started to
> understand what the rules should be. I think they need to be written down
> someplace so that others don’t have to make the mistakes I have. Also it
> would be nice if others would look this list over to see what else might be
> overlooking.
>
> Can somebody point me to a good place to do this? Sending to the mailing
> list seems like a poor solution as corrections will not be easily findable.
> A wiki seems ideal, but which? KDE in particular should probably have these
> rules in their official requirements, but I’m not sure if they are the
> correct ones to own them.
>
>
> --
>
> 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
--

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
Reply | Threaded
Open this post in threaded view
|

Re: target_link_libraries - private public interface rules

Haocheng Liu


On Tue, Aug 22, 2017 at 10:45 AM, Robert Maynard <[hidden email]> wrote:
You could look at extending the official CMake documentation,
specifically the build system documentation (
https://cmake.org/cmake/help/v3.9/manual/cmake-buildsystem.7.html ).

The documentation is all in restructure text and we accept
documentation changes through our gitlab instance.

cmake gitlab: https://gitlab.kitware.com/cmake/cmake

build-system restructure page:
https://gitlab.kitware.com/cmake/cmake/blob/master/Help/manual/cmake-buildsystem.7.rst

contribution guideline:
https://gitlab.kitware.com/cmake/cmake/blob/master/CONTRIBUTING.rst

As Rob has pointed out, you can start from this file as target_link_libraries.rst in CMake source code.
On Tue, Aug 22, 2017 at 9:44 AM, Miller Henry <[hidden email]> wrote:
>
> I’ve been playing with the private/public/interface keyword to
> target_link_libraries. It seems to me that WHAT they do is well documented,
> but nobody has ever actually documented what they correct rules of WHEN/WHY
> you should use any of them. After a lot of misstarts I think I’ve started to
> understand what the rules should be. I think they need to be written down
> someplace so that others don’t have to make the mistakes I have. Also it
> would be nice if others would look this list over to see what else might be
> overlooking.
>
> Can somebody point me to a good place to do this? Sending to the mailing
> list seems like a poor solution as corrections will not be easily findable.
> A wiki seems ideal, but which? KDE in particular should probably have these
> rules in their official requirements, but I’m not sure if they are the
> correct ones to own them.
>
>
> --
>
> 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
--

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



--
Best regards
Haocheng

Haocheng LIU
Kitware, Inc.
R&D Engineer
21 Corporate Drive
Clifton Park, NY 12065-8662
Phone: <a href="tel:(518)%20881-4421" value="+15188814443" style="color:rgb(17,85,204);font-size:12.8px" target="_blank">518-881-4421

--

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
Reply | Threaded
Open this post in threaded view
|

Re: target_link_libraries - private public interface rules

Miller Henry
In reply to this post by Robert Maynard
Is that the right place to say things like

If a header file contains
        #include <OtherLibraryClassHeader.h>
Then OtherLibrary is probably candidate for PUBLIC, if the header contains the predeclaration
        class OtherLibraryClass;
then OtherLibrary should be PRIVATE?  

I'm not against putting that content in official cmake documentation, but it seems like something that has never been done before.

-----Original Message-----
From: Robert Maynard [mailto:[hidden email]]
Sent: Tuesday, August 22, 2017 9:46 AM
To: Miller Henry <[hidden email]>
Cc: [hidden email]
Subject: Re: [CMake] target_link_libraries - private public interface rules

You could look at extending the official CMake documentation, specifically the build system documentation ( https://cmake.org/cmake/help/v3.9/manual/cmake-buildsystem.7.html ).

The documentation is all in restructure text and we accept documentation changes through our gitlab instance.

cmake gitlab: https://gitlab.kitware.com/cmake/cmake

build-system restructure page:
https://gitlab.kitware.com/cmake/cmake/blob/master/Help/manual/cmake-buildsystem.7.rst

contribution guideline:
https://gitlab.kitware.com/cmake/cmake/blob/master/CONTRIBUTING.rst

On Tue, Aug 22, 2017 at 9:44 AM, Miller Henry <[hidden email]> wrote:

>
> I’ve been playing with the private/public/interface keyword to
> target_link_libraries. It seems to me that WHAT they do is well
> documented, but nobody has ever actually documented what they correct
> rules of WHEN/WHY you should use any of them. After a lot of misstarts
> I think I’ve started to understand what the rules should be. I think
> they need to be written down someplace so that others don’t have to
> make the mistakes I have. Also it would be nice if others would look
> this list over to see what else might be overlooking.
>
> Can somebody point me to a good place to do this? Sending to the
> mailing list seems like a poor solution as corrections will not be easily findable.
> A wiki seems ideal, but which? KDE in particular should probably have
> these rules in their official requirements, but I’m not sure if they
> are the correct ones to own them.
>
>
> --
>
> 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
--

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
Reply | Threaded
Open this post in threaded view
|

Re: target_link_libraries - private public interface rules

Robert Maynard
The `Transitive Usage Requirements` section of the cmake-buildsystem
documentation quickly covers this idea but it could be elaborated on.
This might be a good place for a concrete example.

Any thoughts Brad?

On Tue, Aug 22, 2017 at 11:31 AM, Miller Henry
<[hidden email]> wrote:

> Is that the right place to say things like
>
> If a header file contains
>         #include <OtherLibraryClassHeader.h>
> Then OtherLibrary is probably candidate for PUBLIC, if the header contains the predeclaration
>         class OtherLibraryClass;
> then OtherLibrary should be PRIVATE?
>
> I'm not against putting that content in official cmake documentation, but it seems like something that has never been done before.
>
> -----Original Message-----
> From: Robert Maynard [mailto:[hidden email]]
> Sent: Tuesday, August 22, 2017 9:46 AM
> To: Miller Henry <[hidden email]>
> Cc: [hidden email]
> Subject: Re: [CMake] target_link_libraries - private public interface rules
>
> You could look at extending the official CMake documentation, specifically the build system documentation ( https://cmake.org/cmake/help/v3.9/manual/cmake-buildsystem.7.html ).
>
> The documentation is all in restructure text and we accept documentation changes through our gitlab instance.
>
> cmake gitlab: https://gitlab.kitware.com/cmake/cmake
>
> build-system restructure page:
> https://gitlab.kitware.com/cmake/cmake/blob/master/Help/manual/cmake-buildsystem.7.rst
>
> contribution guideline:
> https://gitlab.kitware.com/cmake/cmake/blob/master/CONTRIBUTING.rst
>
> On Tue, Aug 22, 2017 at 9:44 AM, Miller Henry <[hidden email]> wrote:
>>
>> I’ve been playing with the private/public/interface keyword to
>> target_link_libraries. It seems to me that WHAT they do is well
>> documented, but nobody has ever actually documented what they correct
>> rules of WHEN/WHY you should use any of them. After a lot of misstarts
>> I think I’ve started to understand what the rules should be. I think
>> they need to be written down someplace so that others don’t have to
>> make the mistakes I have. Also it would be nice if others would look
>> this list over to see what else might be overlooking.
>>
>> Can somebody point me to a good place to do this? Sending to the
>> mailing list seems like a poor solution as corrections will not be easily findable.
>> A wiki seems ideal, but which? KDE in particular should probably have
>> these rules in their official requirements, but I’m not sure if they
>> are the correct ones to own them.
>>
>>
>> --
>>
>> 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
--

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
Reply | Threaded
Open this post in threaded view
|

Re: target_link_libraries - private public interface rules

Brad King
On 08/22/2017 11:36 AM, Robert Maynard wrote:
> The `Transitive Usage Requirements` section of the cmake-buildsystem
> documentation quickly covers this idea but it could be elaborated on.
> This might be a good place for a concrete example.

Yes.  Showing the transitive header case as an example would be good
to show when a dependency should be PUBLIC instead of PRIVATE.

-Brad
--

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
Reply | Threaded
Open this post in threaded view
|

Re: target_link_libraries - private public interface rules

Luis Caro Campos
I think the documentation also fails to mention that link dependencies propagate even when "PRIVATE" is used, if the target is a static library. 





On 22 Aug 2017 4:40 pm, "Brad King" <[hidden email]> wrote:
On 08/22/2017 11:36 AM, Robert Maynard wrote:
> The `Transitive Usage Requirements` section of the cmake-buildsystem
> documentation quickly covers this idea but it could be elaborated on.
> This might be a good place for a concrete example.

Yes.  Showing the transitive header case as an example would be good
to show when a dependency should be PUBLIC instead of PRIVATE.

-Brad
--

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

--

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