Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix syntax highlighting in SE-0238 #2367

Merged
merged 1 commit into from Mar 18, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
24 changes: 18 additions & 6 deletions proposals/0238-package-manager-build-settings.md
Expand Up @@ -28,41 +28,53 @@ We propose to add the following build settings in this proposal:

### Header search path (C/CXX)

`static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>`
```
static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>
```

Many C-family projects are structured in a way that requires adding header search paths to different directories of the project. Currently, SwiftPM only adds a search path to the `include` directory which makes it difficult for many C projects to add support for building with SwiftPM. This specified path should be relative to the target and should not escape the package boundary. Absolute paths are disallowed.

*Note: It is not recommended to use this setting for adding search paths of public headers as the target-specific settings are not imparted onto other targets.*

### Define (C/CXX)

`static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>`
```swift
static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>
```

This setting will add the `-D<name>=<value>` flag during a target's compilation. This is useful for projects that want to specify a compile-time condition.

*Note: It is not recommended to use this setting for public headers as the target-specific settings are not imparted.*

### Define (Swift)

`static func define(_ name: String, _ condition: BuildSettingCondition? = nil) -> SwiftSetting`
```swift
static func define(_ name: String, _ condition: BuildSettingCondition? = nil) -> SwiftSetting
```

This setting enables the specified compilation condition for Swift targets. Unlike C/CXX's define, it doesn't have an associated value.

### Link library (Linker)

`static func linkLibrary(_ libraryName: String, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>`
```swift
static func linkedLibrary(_ libraryName: String, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>
```

This is useful for packages that want to link against a library present in the system. The current approach requires them to create a module map using system library targets or a fake C target in order to achieve this effect. There is also no provision for conditionalization based on the platform in the existing approach, which is valuable when writing cross-platform packages.

### Link framework (Linker)

`static func linkFramework(_ frameworkName: String, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>`
```swift
static func linkedFramework(_ frameworkName: String, _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>
```

Frameworks are autolinked for Swift and C/ObjC targets so most packages shouldn't require this build setting. However, packages that contain C++ files can't autolink the frameworks. Since frameworks are widely used on Apple platforms, it is recommended to use this setting with a platform conditional.

### Unsafe flags (All)

`static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>`
```swift
static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> <BuildSettingType>
```

This is an escape hatch that will allow targets to pass arbitrary command-line flags to the corresponding build tool. The "unsafe" here implies that SwiftPM can't safely determine if the build flags will have any negative side-effect to the build since certain flags can change the behavior of how a build is performed. It is similar to how the `-Xcc`, `-Xswiftc`, `-Xlinker` option work in the command-line SwiftPM tools.

Expand Down