Renaming "Build Configuration"

Evolution Discussion
1

Hi, everyone. This isn't exactly a language feature, but it's something that would benefit from the idea pool and bikeshedding that happens on the list. Simply put, what's the name of this feature?

#if os(OSX)
#if swift(>=3.0)
#if DEBUG

And what's this command-line option? (not that most people are invoking Swift on the command line)

swift -DDEBUG main.swift

···

---

The Swift Programming Language book <Statements — The Swift Programming Language (Swift 5.7); and the compiler diagnostics aren't quite consistent here:

#if: "configuration block" (compiler), "build configuration statement" (book)
(the condition): "build configuration expression" (compiler), "build configuration" (book)
os(…) and arch(…): "target configuration expression" (compiler), "platform testing function" (book)
swift(>=…): "version requirement" (compiler), (not yet in book)

-D flag: "specifies one or more build configuration options"

On top of this, there's another problem: the term "build configuration" has long been used by Xcode to refer to "Debug", "Release", etc—a different mode of compilation that manifests itself as different build settings. Having two different concepts with the same name is never a great idea, and Xcode's feature definitely has seniority here.

---

Some things to keep in mind for this feature:

- All conditions are (currently) compile-time conditions.
- Code in the non-compiled block still has to parse…except if the predicate is "swift(>=…)", for obvious reasons.
- All conditions are boolean-valued predicates; the ones set on the command line are options (present or absent), not macros.

Here's my proposed names to get the discussion started:

- "Conditional Compilation Block" for the whole construct (from the #if to the #endif and everything in between).
- "Conditional Compilation Directive" for the #if line (and #elseif line). Not sure if the #endif line applies.
- "Conditional Compilation Expression" for the condition of a #if.
- "Platform Compilation Features" for all the function-like predicates (including "swift(>=…)", even though that's special.
- "Custom Compilation Features" for all the user-defined options.
- "marks a custom compilation feature as present" as the --help text for -D.

…but I'd be happy if someone comes up with something better. (And I'd like feedback on if any of these names are problematic in some other way.)

Thanks, all,
Jordan

P.S. Since this is only changing diagnostics and the book, I don't think it needs to go through the full evolution process, but someone else from the core team can correct me.

2

Hi, everyone. This isn't exactly a language feature, but it's something that would benefit from the idea pool and bikeshedding that happens on the list. Simply put, what's the name of this feature?

if os(OSX)
if swift(>=3.0)
if DEBUG

And what's this command-line option? (not that most people are invoking Swift on the command line)

swift -DDEBUG main.swift

---

The Swift Programming Language book <The Swift Programming Language: Redirect; and the compiler diagnostics aren't quite consistent here:

#if: "configuration block" (compiler), "build configuration statement" (book)
(the condition): "build configuration expression" (compiler), "build configuration" (book)
os(…) and arch(…): "target configuration expression" (compiler), "platform testing function" (book)
swift(>=…): "version requirement" (compiler), (not yet in book)

-D flag: "specifies one or more build configuration options"

On top of this, there's another problem: the term "build configuration" has long been used by Xcode to refer to "Debug", "Release", etc—a different mode of compilation that manifests itself as different build settings. Having two different concepts with the same name is never a great idea, and Xcode's feature definitely has seniority here.

---

Some things to keep in mind for this feature:

- All conditions are (currently) compile-time conditions.
- Code in the non-compiled block still has to parse…except if the predicate is "swift(>=…)", for obvious reasons.
- All conditions are boolean-valued predicates; the ones set on the command line are options (present or absent), not macros.

Here's my proposed names to get the discussion started:

- "Conditional Compilation Block" for the whole construct (from the if to the #endif and everything in between).
- "Conditional Compilation Directive" for the if line (and #elseif line). Not sure if the #endif line applies.
- "Conditional Compilation Expression" for the condition of a if.
- "Platform Compilation Features" for all the function-like predicates (including "swift(>=…)", even though that's special.

I don’t love the name “Features” , but I don’t have an obviously better suggestion off hand.

Why do you want to combine the version requirement with the other predicates? I would think the special behaviour was worth calling out.

- "Custom Compilation Features" for all the user-defined options.
- "marks a custom compilation feature as present" as the --help text for -D.

…but I'd be happy if someone comes up with something better. (And I'd like feedback on if any of these names are problematic in some other way.)

+1 overall, this seems like a nice cleanup.

···

On Jan 27, 2016, at 5:18 PM, Jordan Rose via swift-evolution <swift-evolution@swift.org> wrote:

Thanks, all,
Jordan

P.S. Since this is only changing diagnostics and the book, I don't think it needs to go through the full evolution process, but someone else from the core team can correct me.
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

3

I'm used to the name "directive" from C preprocessor nomenclature, but I
think it would best be used for all of #available, selector, and #line, in
addition to if/#else/#endif.

Maybe "if" is a "conditional directive", and "os(...) && swift(...)" is
simply its condition.

-D "Defines" something (a flag). Perhaps it "defines a flag such that the
'if flag' condition is true".

···

On Wed, Jan 27, 2016 at 5:18 PM, Jordan Rose via swift-evolution < swift-evolution@swift.org> wrote:

Hi, everyone. This isn't *exactly* a language feature, but it's something
that would benefit from the idea pool and bikeshedding that happens on the
list. Simply put, what's the name of this feature?

if os(OSX)
if swift(>=3.0)
if DEBUG

And what's this command-line option? (not that most people are invoking
Swift on the command line)

swift -DDEBUG main.swift

---

The Swift Programming Language book
<The Swift Programming Language: Redirect; and
the compiler diagnostics aren't quite consistent here:

#if: "configuration block" (compiler), "build configuration statement"
(book)
(the condition): "build configuration expression" (compiler), "build
configuration" (book)
os(…) and arch(…): "target configuration expression" (compiler), "platform
testing function" (book)
swift(>=…): "version requirement" (compiler), (not yet in book)

-D flag: "specifies one or more build configuration options"

On top of this, there's another problem: the term "build configuration"
has long been used by Xcode to refer to "Debug", "Release", etc—a different
mode of compilation that manifests itself as different build settings.
Having two different concepts with the same name is never a great idea, and
Xcode's feature definitely has seniority here.

---

Some things to keep in mind for this feature:

- All conditions are (currently) compile-time conditions.
- Code in the non-compiled block still has to parse…except if the
predicate is "swift(>=…)", for obvious reasons.
- All conditions are boolean-valued predicates; the ones set on the
command line are options (present or absent), not macros.

Here's my proposed names to get the discussion started:

- "Conditional Compilation Block" for the whole construct (from the if to
the #endif and everything in between).
- "Conditional Compilation Directive" for the if line (and #elseif line).
Not sure if the #endif line applies.
- "Conditional Compilation Expression" for the condition of a if.
- "Platform Compilation Features" for all the function-like predicates
(including "swift(>=…)", even though that's special.
- "Custom Compilation Features" for all the user-defined options.
- "marks a custom compilation feature as present" as the --help text for
-D.

…but I'd be happy if someone comes up with something better. (And I'd like
feedback on if any of these names are problematic in some other way.)

Thanks, all,
Jordan

P.S. Since this is only changing diagnostics and the book, I don't think
it needs to go through the full evolution process, but someone else from
the core team can correct me.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

4

Renaming this seems like a good idea.

- "Custom Compilation Features" for all the user-defined options.
- "marks a custom compilation feature as present" as the --help text
  for -D.

…but I'd be happy if someone comes up with something better. (And
I'd like feedback on if any of these names are problematic in some
other way.)

How about "Conditional Compilation Flags" for the user-defined options?
The term "flag" implies boolean, and also connotes the presence of the
flag as being the true value. The help text can then say "marks a
conditional compilation flag as true". The boolean nature of the flag
also makes the syntax `#if SomeFlag` make more sense, because we're used
to if conditions being boolean values.

-Kevin Ballard

···

On Wed, Jan 27, 2016, at 05:18 PM, Jordan Rose via swift-evolution wrote:

5

Hm. I wasn't considering #available and selector to be "directives" because they don't "direct" the compiler to do anything; they're "just" expressions with special effects. The existing "#line" would be a directive, though.

Jordan

···

On Jan 28, 2016, at 10:45, Jacob Bandes-Storch <jtbandes@gmail.com> wrote:

I'm used to the name "directive" from C preprocessor nomenclature, but I think it would best be used for all of #available, selector, and #line, in addition to if/#else/#endif.

Maybe "if" is a "conditional directive", and "os(...) && swift(...)" is simply its condition.

-D "Defines" something (a flag). Perhaps it "defines a flag such that the 'if flag' condition is true".

On Wed, Jan 27, 2016 at 5:18 PM, Jordan Rose via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
Hi, everyone. This isn't exactly a language feature, but it's something that would benefit from the idea pool and bikeshedding that happens on the list. Simply put, what's the name of this feature?

if os(OSX)
if swift(>=3.0)
if DEBUG

And what's this command-line option? (not that most people are invoking Swift on the command line)

swift -DDEBUG main.swift

---

The Swift Programming Language book <The Swift Programming Language: Redirect; and the compiler diagnostics aren't quite consistent here:

#if: "configuration block" (compiler), "build configuration statement" (book)
(the condition): "build configuration expression" (compiler), "build configuration" (book)
os(…) and arch(…): "target configuration expression" (compiler), "platform testing function" (book)
swift(>=…): "version requirement" (compiler), (not yet in book)

-D flag: "specifies one or more build configuration options"

On top of this, there's another problem: the term "build configuration" has long been used by Xcode to refer to "Debug", "Release", etc—a different mode of compilation that manifests itself as different build settings. Having two different concepts with the same name is never a great idea, and Xcode's feature definitely has seniority here.

---

Some things to keep in mind for this feature:

- All conditions are (currently) compile-time conditions.
- Code in the non-compiled block still has to parse…except if the predicate is "swift(>=…)", for obvious reasons.
- All conditions are boolean-valued predicates; the ones set on the command line are options (present or absent), not macros.

Here's my proposed names to get the discussion started:

- "Conditional Compilation Block" for the whole construct (from the if to the #endif and everything in between).
- "Conditional Compilation Directive" for the if line (and #elseif line). Not sure if the #endif line applies.
- "Conditional Compilation Expression" for the condition of a if.
- "Platform Compilation Features" for all the function-like predicates (including "swift(>=…)", even though that's special.
- "Custom Compilation Features" for all the user-defined options.
- "marks a custom compilation feature as present" as the --help text for -D.

…but I'd be happy if someone comes up with something better. (And I'd like feedback on if any of these names are problematic in some other way.)

Thanks, all,
Jordan

P.S. Since this is only changing diagnostics and the book, I don't think it needs to go through the full evolution process, but someone else from the core team can correct me.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

6

Renaming this seems like a good idea.

- "Custom Compilation Features" for all the user-defined options.
- "marks a custom compilation feature as present" as the --help text for -D.

…but I'd be happy if someone comes up with something better. (And I'd like feedback on if any of these names are problematic in some other way.)

How about "Conditional Compilation Flags" for the user-defined options? The term "flag" implies boolean, and also connotes the presence of the flag as being the true value. The help text can then say "marks a conditional compilation flag as true". The boolean nature of the flag also makes the syntax `#if SomeFlag` make more sense, because we're used to if conditions being boolean values.

Closing the loop: I implemented this in Merge pull request #1289 from jrose-apple/conditional-compilation-blocks · apple/swift@c90511a · GitHub, taking Kevin's suggestion of "flags" for the user-set options. Jack L from Apple convinced me to avoid the word "feature" as well, since the platform conditions refer to mutually exclusive environments ("os(OSX)" vs. "os(iOS)"), while "features" can usually be mixed.

Jordan

···

On Jan 28, 2016, at 11:08, Kevin Ballard via swift-evolution <swift-evolution@swift.org> wrote:
On Wed, Jan 27, 2016, at 05:18 PM, Jordan Rose via swift-evolution wrote:

7

How about "hashtags"? ;-)

···

On Thu, Jan 28, 2016 at 10:49 AM, Jordan Rose <jordan_rose@apple.com> wrote:

Hm. I wasn't considering #available and selector to be "directives"
because they don't "direct" the compiler to do anything; they're "just"
expressions with special effects. The existing "#line" would be a
directive, though.

Jordan

On Jan 28, 2016, at 10:45, Jacob Bandes-Storch <jtbandes@gmail.com> wrote:

I'm used to the name "directive" from C preprocessor nomenclature, but I
think it would best be used for all of #available, selector, and #line, in
addition to if/#else/#endif.

Maybe "if" is a "conditional directive", and "os(...) && swift(...)" is
simply its condition.

-D "Defines" something (a flag). Perhaps it "defines a flag such that the
'if flag' condition is true".

On Wed, Jan 27, 2016 at 5:18 PM, Jordan Rose via swift-evolution < > swift-evolution@swift.org> wrote:

Hi, everyone. This isn't *exactly* a language feature, but it's
something that would benefit from the idea pool and bikeshedding that
happens on the list. Simply put, what's the name of this feature?

if os(OSX)
if swift(>=3.0)
if DEBUG

And what's this command-line option? (not that most people are invoking
Swift on the command line)

swift -DDEBUG main.swift

---

The Swift Programming Language book
<The Swift Programming Language: Redirect; and
the compiler diagnostics aren't quite consistent here:

#if: "configuration block" (compiler), "build configuration statement"
(book)
(the condition): "build configuration expression" (compiler), "build
configuration" (book)
os(…) and arch(…): "target configuration expression" (compiler),
"platform testing function" (book)
swift(>=…): "version requirement" (compiler), (not yet in book)

-D flag: "specifies one or more build configuration options"

On top of this, there's another problem: the term "build configuration"
has long been used by Xcode to refer to "Debug", "Release", etc—a different
mode of compilation that manifests itself as different build settings.
Having two different concepts with the same name is never a great idea, and
Xcode's feature definitely has seniority here.

---

Some things to keep in mind for this feature:

- All conditions are (currently) compile-time conditions.
- Code in the non-compiled block still has to parse…except if the
predicate is "swift(>=…)", for obvious reasons.
- All conditions are boolean-valued predicates; the ones set on the
command line are options (present or absent), not macros.

Here's my proposed names to get the discussion started:

- "Conditional Compilation Block" for the whole construct (from the if
to the #endif and everything in between).
- "Conditional Compilation Directive" for the if line (and #elseif
line). Not sure if the #endif line applies.
- "Conditional Compilation Expression" for the condition of a if.
- "Platform Compilation Features" for all the function-like predicates
(including "swift(>=…)", even though that's special.
- "Custom Compilation Features" for all the user-defined options.
- "marks a custom compilation feature as present" as the --help text for
-D.

…but I'd be happy if someone comes up with something better. (And I'd
like feedback on if any of these names are problematic in some other way.)

Thanks, all,
Jordan

P.S. Since this is only changing diagnostics and the book, I don't think
it needs to go through the full evolution process, but someone else from
the core team can correct me.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution