conan-io / conan-io/docs

`tools.build:*flags` documentation is confusing

Open
#3,175 1 comment 0 reactions 0 assignees View on GitHub
type: bug
Dominant language
C++
Stars
125
Forks
382
Avg merge
22h 39m
Merged PRs (30d)
21

Description

For example `tools.build:sharedlinkflags` [documentation ](https://docs.conan.io/2.0/reference/config_files/global_conf.html) 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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the global_conf documentation linked in the issue and compare its descriptions with the cited toolchain.py locations for Microsoft, GNU, Meson, and Apple generators. Confirm which tools receive each tools.build:*flags setting, then update the documentation to describe the actual propagation and identify any exceptions or missing error behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
cmake, cpp
Domain
build-system, documentation, tooling
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.