document implementation-defined behavior

[zygoloid]

Bugzilla Link	11272
Version	unspecified
OS	Linux
CC	@gribozavr,@Blaisorblade,@zygoloid

Extended Description

The clang documentation should specify how clang behaves in cases specified to be implementation-defined in the relevant standards. Perhaps simply saying that our behavior is the same as GCC's would suffice?

[llvmbot]

Hi,

Just adding a note about an implementation-defined behavior I ran into.

I noticed that when casting an integer value to a smaller integer type, clang
generates a trunc in IR. e.g., for "(signed char)x", clang generates:
%conv = trunc i32 %x to i8

When this bug is fixed, the clang manual should document this behavior.

As an example, the GCC manual says:
(see http://gcc.gnu.org/onlinedocs/gcc/Integers-implementation.html#Integers-implementation)

The result of, or the signal raised by, converting an integer to a signed integer type when the value cannot be represented in an object of that type (C90 6.2.1.2, C99 6.3.1.3).

For conversion to a type of width N, the value is reduced modulo 2^N to be within range of the type; no signal is raised.

• Gao.

[llvmbot]

Note that this documentation is required for ISO C conformance.
See N1570 section 4 paragraph 8).

[zygoloid]

Note that this documentation is required for ISO C conformance.

We're an open-source project. Our implementation-defined behavior is defined by our implementation :) Nonetheless, we should document it in a more accessible way...

[llvmbot]

mentioned in issue llvm/llvm-bugzilla-archive#50694

[apinski-cavium]

I noticed this as GCC and clang disagree when converting from a pointer type to an integer type which is bigger.
See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107238 for the difference on aarch64.

[hexagonrecursion]

Note that this documentation is required for ISO C conformance.

We're an open-source project. Our implementation-defined behavior is defined by our implementation :) Nonetheless, we should document it in a more accessible way...

That is not enough. Correct me if I'm wrong, but implementation-defined behavior is supposed to be documented. Documentation defines a public API - a "contract". Without documentation clang is free to change implementation-defined behavior from one release to another and it would technically not be a breaking change.

I could start slowly chipping away at this mammoth, but I do not have a copy of the officially blessed C++ standard. I only have the draft that can be found online.

[Endilll]

That is not enough. Correct me if I'm wrong, but implementation-defined behavior is supposed to be documented. Documentation defines a public API - a "contract". Without documentation clang is free to change implementation-defined behavior from one release to another and it would technically not be a breaking change.

I do not agree. Keep in mind that this requirement was put in the era of proprietary compilers. Back then, if implementation-defined behavior wasn't explicitly documented, users were forced to feed the compiler with various tests, observe results, and make conclusions. Since it's a form of reverse engineering, there was always a room for unknowns.

This is different for open-source compilers, though. Users have access to a source of truth on the matter. As mentioned above, it's not too accessible, but it's there.

Documentation defines a public API - a "contract". Without documentation clang is free to change implementation-defined behavior from one release to another and it would technically not be a breaking change.

While you bring good points here, I'd like to make it clear that the Standard doesn't require implementations to pick a certain implementation-defined behavior, and maintain backwards compatibility as the implementation evolves. The reason is that as far as the Standard is concerned, different versions of the same compiler are different implementations, with nothing preventing them having different sets of implementation-defined behavior. We have other reasons to maintain compatibility between versions, but Standards conformance is not one of them.

I could start slowly chipping away at this mammoth, but I do not have a copy of the officially blessed C++ standard. I only have the draft that can be found online.

We'd love to see work in this direction. I guess you refer to http://eel.is/c++draft/. Originating from https://github.com/cplusplus/draft, it's as accurate as an official publication, but is updated much more frequently than once per 3 years. While it doesn't have same legal power as an official publication, it's better suited to answer technical questions, including ones you're going to have while documenting implementation-defined behaviors.

[pmor13]

@hexagonrecursion

Correct me if I'm wrong, but implementation-defined behavior is supposed to be documented.

Just a quick note. Both C and C++ standards require that an implementation "is accompanied by" (C) or "includes" (C++) a document that "defines all implementation-defined and locale-specific characteristics and all extensions." (C) or "identifies all conditionally-supported constructs that it does not support and defines all locale-specific characteristics" (C++). Both standards, however, place no requirements on the form (e.g. structure, format, etc.) of this document. Hence, LLVM authors may say "our source code is this document". However, this may be confusing for the end user (who may not be a [LLVM/Clang] compiler writer).