Contents

DaveWoodCom/XCGLogger

A debug log framework for use in Swift projects. Allows you to log details to the console (and optionally a file), just like you would have with NSLog() or print(), but with additional information, such as the date, function name, filename and line number.

tl;dr

XCGLogger is the original debug log module for use in Swift projects.

Swift does not include a C preprocessor so developers are unable to use the debug log #define macros they would use in Objective-C. This means our traditional way of generating nice debug logs no longer works. Resorting to just plain old print calls means you lose a lot of helpful information, or requires you to type a lot more code.

XCGLogger allows you to log details to the console (and optionally a file, or other custom destinations), just like you would have with NSLog() or print(), but with additional information, such as the date, function name, filename and line number.

Go from this:


to this:
Example

<img src="https://raw.githubusercontent.com/DaveWoodCom/XCGLogger/main/ReadMeImages/SampleLog.png" alt="Example" style="width: 690px;" />

Communication (Hat Tip AlamoFire)

  • If you need help, use [Stack Overflow][stackoverflow] (Tag '[xcglogger][stackoverflow]').
  • If you'd like to ask a general question, use [Stack Overflow][stackoverflow].
  • If you've found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, submit a pull request.
  • If you use XCGLogger, please Star the project on [GitHub][github-xcglogger]

Installation

Git Submodule

Execute:

	
in your repository folder.

### [Carthage][carthage]

Add the following line to your `Cartfile`.

Then run carthage update --no-use-binaries or just carthage update. For details of the installation and usage of Carthage, visit [its project page][carthage].

Developers running 5.0 and above in Swift will need to add $(SRCROOT)/Carthage/Build/iOS/ObjcExceptionBridging.framework to their Input Files in the Copy Carthage Frameworks Build Phase.

[CocoaPods][cocoapods]

Add something similar to the following lines to your Podfile. You may need to adjust based on your platform, version/branch etc.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

pod 'XCGLogger', '~> 7.1.5'

Specifying the pod XCGLogger on its own will include the core framework. We're starting to add subspecs to allow you to include optional components as well:

pod 'XCGLogger/UserInfoHelpers', '~> 7.1.5': Include some experimental code to help deal with using UserInfo dictionaries to tag log messages.

Then run pod install. For details of the installation and usage of CocoaPods, visit [its official web site][cocoapods].

Note: Before CocoaPods 1.4.0 it was not possible to use multiple pods with a mixture of Swift versions. You may need to ensure each pod is configured for the correct Swift version (check the targets in the pod project of your workspace). If you manually adjust the Swift version for a project, it'll reset the next time you run pod install. You can add a post_install hook into your podfile to automate setting the correct Swift versions. This is largely untested, and I'm not sure it's a good solution, but it seems to work:

post_install do |installer|
    installer.pods_project.targets.each do |target|
        if ['SomeTarget-iOS', 'SomeTarget-watchOS'].include? "#{target}"
            print "Setting #{target}'s SWIFT_VERSION to 4.2\n"
            target.build_configurations.each do |config|
                config.build_settings['SWIFT_VERSION'] = '4.2'
            end
        else
            print "Setting #{target}'s SWIFT_VERSION to Undefined (Xcode will automatically resolve)\n"
            target.build_configurations.each do |config|
                config.build_settings.delete('SWIFT_VERSION')
            end
        end
    end

    print "Setting the default SWIFT_VERSION to 3.2\n"
    installer.pods_project.build_configurations.each do |config|
        config.build_settings['SWIFT_VERSION'] = '3.2'
    end
end

You can adjust that to suit your needs of course.

[Swift Package Manager][swiftpm]

Add the following entry to your package's dependencies:

.Package(url: "https://github.com/DaveWoodCom/XCGLogger.git", majorVersion: 7)

Backwards Compatibility

Use:

  • XCGLogger version [7.1.5][xcglogger-7.1.5] for Swift 5.0
  • XCGLogger version [6.1.0][xcglogger-6.1.0] for Swift 4.2
  • XCGLogger version [6.0.4][xcglogger-6.0.4] for Swift 4.1
  • XCGLogger version [6.0.2][xcglogger-6.0.2] for Swift 4.0
  • XCGLogger version [5.0.5][xcglogger-5.0.5] for Swift 3.0-3.2
  • XCGLogger version [3.6.0][xcglogger-3.6.0] for Swift 2.3
  • XCGLogger version [3.5.3][xcglogger-3.5.3] for Swift 2.2
  • XCGLogger version [3.2][xcglogger-3.2] for Swift 2.0-2.1
  • XCGLogger version [2.x][xcglogger-2.x] for Swift 1.2
  • XCGLogger version [1.x][xcglogger-1.x] for Swift 1.1 and below.

Basic Usage (Quick Start)

This quick start method is intended just to get you up and running with the logger. You should however use the advanced usage below to get the most out of this library.

Add the XCGLogger project as a subproject to your project, and add the appropriate library as a dependency of your target(s). Under the General tab of your target, add XCGLogger.framework and ObjcExceptionBridging.framework to the Embedded Binaries section.

Then, in each source file:

import XCGLogger

In your AppDelegate (or other global file), declare a global constant to the default XCGLogger instance.

let log = XCGLogger.default

In the

application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]? = nil) // iOS, tvOS

or

applicationDidFinishLaunching(_ notification: Notification) // macOS

function, configure the options you need:

log.setup(level: .debug, showThreadName: true, showLevel: true, showFileNames: true, showLineNumbers: true, writeToFile: "path/to/file", fileLevel: .debug)

The value for writeToFile: can be a String or URL. If the file already exists, it will be cleared before we use it. Omit the parameter or set it to nil to log to the console only. You can optionally set a different log level for the file output using the fileLevel: parameter. Set it to nil or omit it to use the same log level as the console.

Then, whenever you'd like to log something, use one of the convenience methods:

log.verbose("A verbose message, usually useful when working on a specific problem")
log.debug("A debug message")
log.info("An info message, probably useful to power users looking in console.app")
log.notice("A notice message")
log.warning("A warning message, may indicate a possible error")
log.error("An error occurred, but it's recoverable, just info about what happened")
log.severe("A severe error occurred, we are likely about to crash now")
log.alert("An alert error occurred, a log destination could be made to email someone")
log.emergency("An emergency error occurred, a log destination could be made to text someone")

The different methods set the log level of the message. XCGLogger will only print messages with a log level that is greater to or equal to its current log level setting. So a logger with a level of .error will only output log messages with a level of .error, .severe, .alert, or .emergency.

Contributing

XCGLogger is the best logger available for Swift because of the contributions from the community like you. There are many ways you can help continue to make it great.

  1. Star the project on [GitHub][github-xcglogger].
  2. Report issues/bugs you find.
  3. Suggest features.
  4. Submit pull requests.
  5. Download and install one of my apps: [https://www.cerebralgardens.com/apps/][cerebral-gardens-apps] Try my newest app: [All the Rings][all-the-rings].
  6. You can visit my [Patreon][patreon-davewoodx] and contribute financially.

Note: when submitting a pull request, please use lots of small commits verses one huge commit. It makes it much easier to merge in when there are several pull requests that need to be combined for a new version.

Third Party Tools That Work With XCGLogger

Note: These plug-ins no longer 'officially' work in Xcode. File a bug report if you'd like to see plug-ins return to Xcode.

[XcodeColors:][XcodeColors] Enable colour in the Xcode console <br /> [KZLinkedConsole:][KZLinkedConsole] Link from a log line directly to the code that produced it

Note: These may not yet work with the Swift 4 version of XCGLogger.

[XCGLoggerNSLoggerConnector:][XCGLoggerNSLoggerConnector] Send your logs to [NSLogger][NSLogger] -->

To Do

  • Add more examples of some advanced use cases
  • Add additional log destination types
  • Add Objective-C support
  • Add Linux support

More

If you find this library helpful, you'll definitely find this other tool helpful:

Watchdog: https://watchdogforxcode.com/

Also, please check out some of my other projects:

  • All the Rings: App Store
  • Rudoku: App Store
  • TV Tune Up: https://www.cerebralgardens.com/tvtuneup

Change Log

The change log is now in its own file: CHANGELOG.md

[xcglogger-logo]: https://github.com/DaveWoodCom/XCGLogger/raw/main/ReadMeImages/XCGLoggerLogo_326x150.png [swift.org]: https://swift.org/ [license]: https://github.com/DaveWoodCom/XCGLogger/blob/main/LICENSE.txt [swiftpm]: https://swift.org/package-manager/ [cocoapods]: https://cocoapods.org/ [cocoapods-xcglogger]: https://cocoapods.org/pods/XCGLogger [carthage]: https://github.com/Carthage/Carthage [cerebral-gardens]: https://www.cerebralgardens.com/ [cerebral-gardens-apps]: https://www.cerebralgardens.com/apps/ [all-the-rings]: https://alltherings.fit/?s=GH3 [mastodon-davewoodx]: https://mastodon.social/@davewoodx [twitter-davewoodx]: https://twitter.com/davewoodx [github-xcglogger]: https://github.com/DaveWoodCom/XCGLogger [stackoverflow]: https://stackoverflow.com/questions/tagged/xcglogger [patreon-davewoodx]: https://www.patreon.com/DaveWoodX

[badge-language]: https://img.shields.io/badge/Swift-1.x%20%7C%202.x%20%7C%203.x%20%7C%204.x%20%7C%205.x-orange.svg?style=flat [badge-platforms]: https://img.shields.io/badge/Platforms-macOS%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS-lightgray.svg?style=flat [badge-license]: https://img.shields.io/badge/License-MIT-lightgrey.svg?style=flat [badge-swiftpm]: https://img.shields.io/badge/Swift_Package_Manager-v7.1.5-64a6dd.svg?style=flat [badge-cocoapods]: https://img.shields.io/cocoapods/v/XCGLogger.svg?style=flat [badge-carthage]: https://img.shields.io/badge/Carthage-v7.1.5-64a6dd.svg?style=flat

[badge-sponsors]: https://img.shields.io/badge/Sponsors-Cerebral%20Gardens-orange.svg?style=flat [badge-mastodon]: https://img.shields.io/badge/Mastodon-DaveWoodX-606A84.svg?style=flat [badge-twitter]: https://img.shields.io/twitter/follow/DaveWoodX.svg?style=social [badge-patreon]: https://img.shields.io/badge/Patreon-DaveWoodX-F96854.svg?style=flat

[XcodeColors]: https://github.com/robbiehanson/XcodeColors [KZLinkedConsole]: https://github.com/krzysztofzablocki/KZLinkedConsole [NSLogger]: https://github.com/fpillet/NSLogger [XCGLoggerNSLoggerConnector]: https://github.com/markuswinkler/XCGLoggerNSLoggerConnector [Firebase]: https://www.firebase.com/

[xcglogger-7.1.5]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/7.1.5 [xcglogger-6.1.0]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/6.1.0 [xcglogger-6.0.4]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/6.0.4 [xcglogger-6.0.2]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/6.0.2 [xcglogger-5.0.5]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/5.0.5 [xcglogger-3.6.0]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/3.6.0 [xcglogger-3.5.3]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/3.5.3 [xcglogger-3.2]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/3.2.0 [xcglogger-2.x]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/2.4.0 [xcglogger-1.x]: https://github.com/DaveWoodCom/XCGLogger/releases/tag/1.8.1

Package Metadata

Repository: DaveWoodCom/XCGLogger

Stars: 3985

Forks: 477

Open issues: 49

Default branch: main

Primary language: swift

License: MIT

Topics: carthage, cocoapods, debug, debugging, debugging-tool, ios, logging, logging-library, macos, swift, swift-framework, swift-library, swiftpm, tvos, watchos, xcglogger

README: README.md