search

conan-io / docs

conan.io reStructuredText documentation
http://docs.conan.io
MIT License
104 stars 352 forks source link

`tools.build:*flags` documentation is confusing #3175

Open maksim-petukhov opened 1 year ago

maksim-petukhov commented 1 year ago

For example tools.build:sharedlinkflags documentation says

List of extra flags used by CMakeToolchain for CMAKE_SHARED_LINKER_FLAGS_INIT variable

I think this is not entirely true, because I see that these extra flags are propagated to other generators too

https://github.com/conan-io/conan/blob/6aa9bf6823383610ccf9abe50172eb841832c79d/conan/tools/microsoft/toolchain.py#L219

https://github.com/conan-io/conan/blob/6aa9bf6823383610ccf9abe50172eb841832c79d/conan/tools/gnu/autotoolstoolchain.py#L133

https://github.com/conan-io/conan/blob/6aa9bf6823383610ccf9abe50172eb841832c79d/conan/tools/microsoft/nmaketoolchain.py#L81

https://github.com/conan-io/conan/blob/6aa9bf6823383610ccf9abe50172eb841832c79d/conan/tools/meson/toolchain.py#L341

https://github.com/conan-io/conan/blob/6aa9bf6823383610ccf9abe50172eb841832c79d/conan/tools/apple/xcodetoolchain.py#L45

Or tools.build:cxxflags documentation says

List of extra CXX flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain

and at the same time I see that this configuration is used in MSBuildToolchain which is not mentioned

https://github.com/conan-io/conan/blob/6aa9bf6823383610ccf9abe50172eb841832c79d/conan/tools/microsoft/toolchain.py#L217

Probably not a documentation issue, but... I'm trying to build a large dependency tree, and I don't even know what Toolchain or Deps they use, and I want some confidence. I would like documentation to say that all my flags are just propagated without mentioning generators. If this isn't the case for some generators, a big fat red error when my linker flags aren't propagated will be a huge plus.

memsharded commented 1 year ago

Hi @maksim-petukhov

Thanks for your report. It seems that this could be the effect of historical evolution, initially tools.build:xxxflags probably only supported CMake integration, but it is true that the idea is that these flags are independent of the build system, and all build systems will implement and listen to them (this might be partially true, it is very possible that some integrations like Bazel still don't support them).

In any case, yes, the docs should be updated to reflect this fact and correct to say they should apply to all generators (to all XXXToolchain generators, as the Deps ones are responsible for dependencies information, not for toolchain information.