[swift-evolution] [DRAFT] Enhancing the Platform Configuration Test Suite for Conditional Compilation Blocks

[Jacob Bandes-Storch]

+1 on getting this proposal reviewed soon; I ran into the lack of
TARGET_OS_SIMULATOR today (and was about to send an email, before I
searched a little harder and found this).

On Thu, Jun 16, 2016 at 9:49 AM, Erica Sadun via swift-evolution <
swift-evolution at swift.org> wrote:

> This is an omnibus conditional compilation block proposal. It is built out
> of Swift Evolution community requests and discussions dating back on
> various threads to the genesis of the list.
>
>
>    - This draft does not include tests for debug conditions. That was
>    pitched under separate cover using runtime functions instead of conditional
>    compilation blocks.
>    - This draft does not include tests for OS versions, as that seems to
>    be better addressed using the existing availability tests.
>    - This draft is rewritten with respect to Jordan Rose's "Rename "build
>    configurations" to "conditional compilation blocks"" swift commit
>    <https://github.com/apple/swift/commit/6272941c5cba9581a5ee93d92a6ee66e28c1bf13> from
>    12 February (rdar://problem/19812930).
>    - It is offered as an omnibus because all the tests fall under the
>    same "conditional compilation block" umbrella. Using an omnibus reduces
>    list traffic and demands on core team resources. It's understood that the
>    proposal is likely to be accepted with modifications (or rejected as a
>    whole) due to the multiple tests.
>
>
> -- Erica
>
> gist: https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298
>
> Enhancing the Platform Configuration Test Suite for Conditional
> Compilation Blocks
>
>    - Proposal: TBD
>    - Author: Erica Sadun <http://github.com/erica>
>    - Status: TBD
>    - Review manager: TBD
>
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#introduction>
> Introduction
>
> This proposal introduces additional configuration tests to differentiate
> platform conditions in conditional compilation blocks.
>
> This proposal was first discussed on-list in the [Draft] Introducing
> Build Configuration Tests for Platform Conditions
> <http://thread.gmane.org/gmane.comp.lang.swift.evolution/12140/focus=12267> thread
> and then re-pitched in TBD <https://gist.github.com/erica/TBD>.
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#note>Note
>
> The term "build configuration" is subsumed by "conditional compilation
> block". See this accepted patch
> <https://github.com/apple/swift/commit/6272941c5cba9581a5ee93d92a6ee66e28c1bf13>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#motivation>
> Motivation
>
> Testing for platform conditions is a typical developer task. Although some
> built-in features like CFByteOrderGetCurrentexist, it seems a natural
> match for Swift to introduce conditional compilation blocks specific to
> common platform conditions.
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#current-art>Current
> Art
>
> Swift currently supports the following platform configuration tests,
> defined in lib/Basic/LangOptions.cpp.
>
>    - The literals true and false
>    - The os() function that tests for OSX, iOS, watchOS, tvOS, Linux,
>    Windows, Android, and FreeBSD
>    - The arch() function that tests for x86_64, arm, arm64, i386,
>    powerpc64, s390x, and powerpc64le
>    - The swift() function that tests for specific Swift language
>    releases, e.g. swift(>=2.2)
>
> The following platform configuration test has been accepted in SE-0075
> <https://github.com/apple/swift-evolution/blob/master/proposals/0075-import-test.md> but
> not yet implemented:
>
>    - The canImport() function that tests whether specific modules can be
>    imported.
>
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#detailed-design>Detailed
> Design
>
> This proposal introduces several platform condition tests for use in
> conditional compilation blocks: endianness, bitwidth, vendor, objc interop,
> and simulator.
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#endianness>
> Endianness
>
> Endianness refers to the byte order used in memory. This proposal exposes
> endian test conditions, promoting them from private underscored names to
> public developer-referencable ones.
>
> // Set the "_endian" platform condition.
>   switch (Target.getArch()) {
>   case llvm::Triple::ArchType::arm:
>   case llvm::Triple::ArchType::thumb:
>     addPlatformConditionValue("_endian", "little");
>     break;
>   case llvm::Triple::ArchType::aarch64:
>     addPlatformConditionValue("_endian", "little");
>     break;
>   case llvm::Triple::ArchType::ppc64:
>     addPlatformConditionValue("_endian", "big");
>     break;
>   case llvm::Triple::ArchType::ppc64le:
>     addPlatformConditionValue("_endian", "little");
>     break;
>   case llvm::Triple::ArchType::x86:
>     addPlatformConditionValue("_endian", "little");
>     break;
>   case llvm::Triple::ArchType::x86_64:
>     addPlatformConditionValue("_endian", "little");
>     break;
>   case llvm::Triple::ArchType::systemz:
>     addPlatformConditionValue("_endian", "big");
>     break;
>   default:
>     llvm_unreachable("undefined architecture endianness");
>
> Under this proposal _endian is renamed to endian and made a public API.
>
> Use:
>
> #if endian(big)
>     // Big endian code
> #endif
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#bitwidth>
> Bitwidth
>
> Bitwidth describes the number of bits used to represent a number. This
> proposal introduces a bitwidth test with two options: 32 and 64.
>
> Use:
>
> #if bitwidth(64)
>     // 64-bit code
> #endif
>
> List members briefly discussed whether it was better to measure pointer
> width or the size of Int. William Dillon suggested renaming bitwidth to
> either intwidth or intsize. Brent Royal-Gordon suggests intbits.
> Alternatives include bitsand bitsize. This proposal avoids wordbits because
> of the way, for example, Intel ends up doing “dword”, “qword”, and so forth
> for backwards compatibility.
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#vendor>
> Vendor
>
> A vendor describes the corporate or other originator of a platform. This
> proposal introduces a test that returns platform vendor, with one option at
> this time: Apple. Apple deployment provides an umbrella case for wide
> range of coding norms that may not be available on non-Apple platforms.
> This "family of targets" provides a simpler test than looking for specific
> modules or listing individual operating systems, both of which provide
> fragile approaches to this requirement.
>
> This call would be supported in Swift's source-code by the existing
> private getVendor() used in lib/Basic/LangOptions.cpp.
>
> Use:
>
> #if vendor(Apple)
>     // Code specific to Apple platform deployment
> #endif
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#interop>
> Interop
>
> Swift's Objective-C compatibility enables developers to build
> mix-and-match projects with a mixed-language codebase. This proposal
> introduces a test to determine whether the Objective-C runtime is available
> for use. This test uses only one option, objc, although it could
> potentially expand to other scenarios, such as jvm, clr, and C++.
>
> if (EnableObjCInterop)
>     addPlatformConditionValue("_runtime", "_ObjC");else
>     addPlatformConditionValue("_runtime", "_Native")
>
> Use:
>
> #if interop(objc)
>     // Code that depends on Objective-C
> #endif
>
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#simulator-conditions>Simulator
> Conditions
>
> Xcode simulators enable developers to test code on a wide range of
> platforms without directly using physical devices. A simulator may not
> offer the full suite of modules available with device deployment or provide
> device-only hardware hooks like GPS. This proposal introduces a test for
> simulator platform conditions, enabling developers to omit references to
> unsupported features. It offers two options: simulator and device.
>
> bool swift::tripleIsAnySimulator(const llvm::Triple &triple) {
>     return tripleIsiOSSimulator(triple) ||
>     tripleIsWatchSimulator(triple) ||
>     tripleIsAppleTVSimulator(triple);
> }
>
> This proposal uses a targetEnvironment test as target or platform are too
> valuable burn on this test.
>
> Use:
>
> #if targetEnvironment(simulator)
>     // Code specific to simulator use
> #endif
>
> This condition test would reduce the fragility and special casing
> currently in use:
>
> #if (arch(i386) || arch(x86_64)) && os(iOS)
>     print("Probably simulator")
> #endif
>
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#impact-on-existing-code>Impact
> on Existing Code
>
> This proposal is additive and should not affect existing code. Some
> developers may refactor code as in the case of the simulator/device test.
>
> <https://gist.github.com/erica/c9c11b540a2439696b2f514c2ffc6298#alternatives-considered>Alternatives
> Considered
> Not accepting this proposal
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160628/7233fe5f/attachment.html>