You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
-77Lines changed: 0 additions & 77 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,5 @@
1
1
# SwiftLog
2
2
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
-
5
3
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.
6
4
7
5
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`,
28
26
.target(name: "BestExampleApp", dependencies: [
29
27
.product(name: "Logging", package: "swift-log")
30
28
],
31
-
32
29
```
33
30
34
31
@@ -205,80 +202,6 @@ around between libraries to preserve metadata and the like.
205
202
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
206
203
log message.
207
204
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.0is 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`:
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
-
282
205
## Design
283
206
284
207
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