Project:Quality Assurance/User vs upstream FLAGS

This guide aims to provide a quick reference of which *FLAGS can be forced by upstream, which can be forced by the ebuild, and which should be removed and left for user control.

Generic policy
The generic policy is that user-provided *FLAGS should be respected, unless there is a very good reason not to use them. If some combinations of flags are known to cause breakages on the package, ebuilds can strip them as necessary.

User-provided *FLAGS can be only ignored if there is a very good reason to do so. Those include special targets (e.g. building bootloader code). Usually, USE=custom-cflags should be provided to allow user to force his flags anyway.

Upstream packages should not force any optimization or debugging flags, and respect all optimization and debugging flags passed by the user. However, they can append additional quasi-optimization flags if they can not be used safely as a global flags (i.e. rely on specific deviations from the standards) and only indicate that the code is safe for those optimizations. See the tables below for specific flags.

If upstream forces a disallowed flag, the ebuild should prevent that from happening (e.g. for autotools, you can commonly override the cache variable detecting whether it is supported).

The ebuild can also provide additional allowed flags on the ebuild author leisure. However, it is recommended to pass the flags on to upstream instead.

USE flags should not be used to control *FLAGS (except for USE=custom-cflags). Especially, USE=debug should be only used to control debug behavior other than -g flags (and it should not force them anyway), e.g. -DNDEBUG. CPU_FLAGS_* should be used to control assembly and not passing -m flags -- and the latter should be passed by user (mostly implicitly via -march).

CFLAGS and CXXFLAGS
Rule of thumb: look at gcc(1) manpage. Flags from C Language Options, C++ Language Options... and Code Generation Options are safe to use upstream. The flags from Debugging Options, Optimization Options and Machine Dependent Options usually should be only set by user, except for those allowed in the table following.