Skip to content

Commit 7d1d4e2

Browse files
authored
drop Swift 4.x info from the readme (apple#182)
1 parent 12d3a86 commit 7d1d4e2

File tree

1 file changed

+0
-77
lines changed

1 file changed

+0
-77
lines changed

README.md

Lines changed: 0 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# SwiftLog
22

3-
A Logging API package for Swift. Version `1.0.0` requires Swift 5.0 but there is a version `0.x.y` series available for Swift 4 to ease your transition towards Swift 5. If you intend to use or support SwiftLog for Swift 4, please check the [paragraph](#help-i-need-swift-4) at the end of the document.
4-
53
First things first: This is the beginning of a community-driven open-source project actively seeking contributions, be it code, documentation, or ideas. Apart from contributing to `SwiftLog` itself, there's another huge gap at the moment: `SwiftLog` is an _API package_ which tries to establish a common API the ecosystem can use. To make logging really work for real-world workloads, we need `SwiftLog`-compatible _logging backends_ which then either persist the log messages in files, render them in nicer colors on the terminal, or send them over to Splunk or ELK.
64

75
What `SwiftLog` provides today can be found in the [API docs][api-docs].
@@ -28,7 +26,6 @@ and to your application/library target, add `"Logging"` to your `dependencies`,
2826
.target(name: "BestExampleApp", dependencies: [
2927
.product(name: "Logging", package: "swift-log")
3028
],
31-
3229
```
3330

3431

@@ -205,80 +202,6 @@ around between libraries to preserve metadata and the like.
205202
If you want to filter all log messages originating from a certain subsystem, filter by `source` which defaults to the module that is emitting the
206203
log message.
207204

208-
## SwiftLog for Swift 4
209-
<a name="help-i-need-swift-4"></a>
210-
211-
First of, SwiftLog 1.0.x and SwiftLog 0.0.x are mostly compatible so don't be afraid. In fact, SwiftLog 0.0.0 is the same source code as SwiftLog 1.0.0 with a few changes made to make it Swift 4 compatible.
212-
213-
### How can I use SwiftLog 0 library or application?
214-
215-
If you have a application or a library that needs to be compatible with both Swift 4 and 5, then we recommend using the following in your `Package.swift`:
216-
217-
```swift
218-
.package(url: "https://github.com/apple/swift-log.git", Version("0.0.0") ..< Version("2.0.0")),
219-
```
220-
221-
This will instruct SwiftPM to allow any SwiftLog 0 and any SwiftLog 1 version. This is an unusual form because usually packages don't support multiple major versions of a package. Because SwiftLog 0 and 1 are mostly compatible however, this should not be a real issue and will enable everybody to get the best. If compiled with a Swift 4 compiler, this will be a SwiftLog 0 version but if compiled with a Swift 5 compiler everybody will get the best experience and performance delivered by SwiftLog 1.
222-
223-
In most cases, there is only one thing you need to remember: Always use _string literals_ and _string interpolations_ in the log methods and don't rely on the fact that SwiftLog 0 also allows `String`.
224-
225-
Good:
226-
227-
```swift
228-
logger.info("hello world")
229-
```
230-
231-
Bad:
232-
233-
```swift
234-
let message = "hello world"
235-
logger.info(message)
236-
```
237-
238-
If you have a `String` that you received from elsewhere, please use
239-
240-
```swift
241-
logger.info("\(stringIAlreadyHave)")
242-
```
243-
244-
For more details, have a look in the next section.
245-
246-
247-
### What are the differences between SwiftLog 1 and 0?
248-
249-
- SwiftLog 0 does not use `@inlinable`.
250-
- Apart from accepting `Logger.Message` for the message, SwiftLog 0 has a `String` overload.
251-
- In SwiftLog 0, `Logger.Message` is not `ExpressibleByStringLiteral` or `ExpressibleByStringInterpolation`.
252-
- In SwiftLog 0, `Logger.MetadataValue` is not `ExpressibleByStringLiteral` or `ExpressibleByStringInterpolation`.
253-
254-
#### Why these differences?
255-
256-
##### @inlinable
257-
258-
Swift 4.0 & 4.1 don't support `@inlinable`, so SwiftLog 0 can't use them.
259-
260-
##### Logger.Message
261-
Because all Swift 4 versions don't have a (non-deprecated) mechanism for a type to be `ExpressibleByStringInterpolation` we couldn't make `Logger.Message` expressible by string literals. Unfortunately, the most basic form of our logging API is `logger.info("Hello \(world)")`. For this to work however, `"Hello \(world)"` needs to be accepted and because we can't make `Logger.Message` `ExpressibleByStringInterpolation` we added an overload for all the logging methods to also accept `String`. In most cases, you won't even notice that with SwiftLog 0 you're creating a `String` (which is then transformed to a `Logger.Message`) and with SwiftLog 1 you're creating a `Logger.Message` directly. That is because both `String` and `Logger.Message` will accept all forms of string literals and string interpolations.
262-
Unfortunately, there is code that will make this seemingly small difference visible. If you write
263-
264-
```swift
265-
let message = "Hello world"
266-
logger.info(message)
267-
```
268-
269-
then this will only work in SwiftLog 0 and not in SwiftLog 1. Why? Because SwiftLog 1 will want a `Logger.Message` but `let message = "Hello world"` will make `message` to be of type `String` and in SwiftLog 1, the logging methods don't accept `String`s.
270-
271-
So if you intend to be compatible with SwiftLog 0 and 1 at the same time, please make sure to always use a _string literal_ or a _string interpolation_ inside of the logging methods.
272-
273-
In the case that you already have a `String` handy that you want to log, don't worry at all, just use
274-
275-
```swift
276-
let message = "Hello world"
277-
logger.info("\(message)")
278-
```
279-
280-
and again, you will be okay with SwiftLog 0 and 1.
281-
282205
## Design
283206

284207
This logging API was designed with the contributors to the Swift on Server community and approved by the [SSWG (Swift Server Work Group)](https://swift.org/server/) to the 'sandbox level' of the SSWG's [incubation process](https://github.com/swift-server/sswg/blob/master/process/incubation.md).

0 commit comments

Comments
 (0)