Bikeshedding on cc/cgo option/flag naming

[sureshjoshi]

As per @tdyas 's suggestion, splitting out the bikeshed-on-naming to a discussion, and out of the PR.

See: #16424 (comment)
and
#16413 (comment)

However, with @tdyas's cgo PR in the mix, it seems like a good time to bikeshed on target and subsystem naming, determining how consistent we want to keep names with other tools, and within Pants itself.

References:

Bazel's CC rules: https://bazel.build/reference/be/c-cpp#cc_library
Please's CC rules: https://github.com/please-build/cc-rules
Makefile naming: https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html and https://www.gnu.org/software/make/manual/html_node/Catalogue-of-Rules.html#Catalogue-of-Rules
CMake: https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html#variable:CMAKE_%3CLANG%3E_FLAGS

Note: Both target aliases and subsystem options are in a state of flux, so they may not match each other at time of opening this discussion. That's fine, as this snapshot is merely a start to the conversation about how they should be named, not about how they are currently named.

Current Target Aliases

class CCCompileFlagsField(StringSequenceField):
    alias = "compile_flags"
    help = softwrap(
        """
        Flags passed to the compiler.
        These flags are merged with the toolchain-level defines, with the target-level flags taking precedence.
        """
    )

class CCDefinesField(StringSequenceField):
    alias = "defines"
    help = softwrap(
        """
        A list of strings to define in the preprocessor. Will be prefixed by -D at the command line.
        These defines are merged with the toolchain-level defines, with the target-level definitions taking precedence.
        """
    )

class CCLanguage(Enum):
    C = "c"
    CPP = "c++"

class CCLanguageField(StringField, AsyncFieldMixin):
    alias = "language"
    default = None
    valid_choices = CCLanguage
    help = softwrap(
        """
        A field to indicate what programming language the source is written in.

        The default selection is `None`, in which case we attempt to determine the correct compiler based on file extension.
        Alternatively, `c` or `c++` may be specified to force compilation with the specified toolchains/flags.
        """
    )

class CCLinkTypeField(StringField):
    alias = "link_type"
    default = "shared"
    valid_choices = ("shared", "static")
    help = softwrap(
        """
        This field determines the link basis for `cc_library` targets.
        """
    )

class CCLinkFlagsField(StringSequenceField):
    alias = "link_flags"

class CCHeadersField(Dependencies):
    alias = "headers"
    help = softwrap(
        """
        This field specifies public headers which are made available to dependent targets.
        The headers should be specified as `cc_source` or `cc_sources` targets.
        """
    )

Current Subsystem Options

    c_compile_options = StrListOption(
        default=["-std=c11"],
        help=softwrap(
            """
            Flags passed to the C compiler.
            These flags are merged with the target-level defines, with the target-level flags taking precedence.
            """
        ),
    )

    c_defines = StrListOption(
        default=None,
        help=softwrap(
            """
            A list of strings to define in the C preprocessor. Will be prefixed by -D at the command line.
            These defines are merged with the target-level defines, with the target-level definitions taking precedence.
            """
        ),
    )

    cpp_compile_options = StrListOption(
        default=["-std=c++11"],
        help=softwrap(
            """
            Flags passed to the C++ compiler.
            These flags are merged with the target-level defines, with the target-level flags taking precedence.
            """
        ),
    )

    cpp_defines = StrListOption(
        default=None,
        help=softwrap(
            """
            A list of strings to define in the C++ preprocessor. Will be prefixed by -D at the command line.
            These defines are merged with the target-level defines, with the target-level definitions taking precedence.
            """
        ),
    )

Aside: Just discovered this subsystem from a slack convo

https://www.pantsbuild.org/docs/reference-python-native-code

Annnnnnnd, cannot forget about Ninja: https://ninja-build.org/build.ninja.html

It's probably worth investigating (as an optimization step, not a preliminary step) using Pants to generate Ninja build files, which actually performs the compilation step. But, this is an aside until we have benchmarking numbers.

[tdyas]

First bike shed: Regarding the naming of C++ options, we should use "cxx" instead of "cpp" since "cpp" can also refer to the C preprocessor. That naming will match up with Go (e.g., CGO_CXXFLAGS), cmake (as per all the references in the cmake properties docs to CXX; h/t @sureshjoshi's comment), and gcc using cpp in its docs (h/t @sureshjoshi's comment).

[tdyas]

Switching over to "cxx" can happen in a follow-on PR.

[sureshjoshi]

Not that we need it, but another point of reference is Swift's implementations:

Pretty cut and dry at this point.

I may do it in cc before I PR, since I'm already doing cleanup.

[sureshjoshi]

I hate how muddled this question is:
https://developer.android.com/ndk/guides/application_mk#app_cxxflags

So dumb.

[tdyas]

Next bike shed: naming the compiler/linker flag options and fields. For cgo, I was thinking --cgo-c-flags, --cgo-cxx-flags, and --cgo-linker-flags. Then the corresponding fields on go_binary would be cgo_c_flags, cgo_cxx_flags, and cgo_linker_flags. Putting "compiler" in the name seems too verbose but "ldflags" for the linker flags seemed too terse. Thoughts?

[sureshjoshi]

This was more CMake habit on my side. 12 years of CMake is hard to drop:
https://cmake.org/cmake/help/latest/manual/cmake-commands.7.html

target_compile_definitions
target_compile_features
target_compile_options
target_include_directories
target_link_directories
target_link_libraries
target_link_options

Not proposing that's the best, but that's where I was coming from.

Flags vs Options

I prefer using flags I think, only because options is so commonly used in Pants, and they both appear to be used interchangeably on the webs. I don't think any cc devs would be surprised at the use of either word.

LD flags

Pretty opposed to ld anything. ld is the GNU tool, but there is gold and also lld and I believe they all are capable of using the same gcc flags (and I think lld has some extra options).

Even if they're all equally compatible, I think specifying link or linker is preferable.

Transitive ...stuff...

In thinking about these names, I think we might also have to consider whether/what of these flags/options will be considered locally vs transitively and whether that plays a role.

This is separate to some flags being specified at the "compiler" level (which apply to all targets) vs on a single target.

In between those two, we need to determine if setting some flags on a target would require some of those flags/defines being sent downstream.

I haven't given this any thought yet, but it was something I wanted to mention before concluding my response.

[tdyas]

In thinking about these names, I think we might also have to consider whether/what of these flags/options will be considered locally vs transitively and whether that plays a role.

At least for cgo, it shouldn't play a role. So probably a cc backend only item. Is there a prior art in other build tools?

[sureshjoshi]

Is there a prior art in other build tools?

Basically this:

https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_COMPILE_OPTIONS.html#prop_tgt:INTERFACE_COMPILE_OPTIONS

via

https://cmake.org/cmake/help/latest/command/target_compile_options.html#arguments

I would have to dig through some of my projects to see how this plays out. But, some of it is covered here starting at slide 30: https://purplekarrot.net/blog/cmake-introduction-and-best-practices.html

What I'm trying to recall is whether this is more of a CMake thing, or a C/C++ build tool thing.

My gut feel is that between compiler-level (ie. global) and target-level, I think we cover a large number of use cases. Except maybe transitive linking.