SwiftPlantUML

Generate UML class diagrams from swift code with this Command Line Interface (CLI) and Swift Package.

Use one or more Swift files as input for a diagram to visualize class, struct, protocol, enum and extension types with their instance and static members as well as their inheritance and implementation relationships

<details> <summary><strong>Table of Contents</strong> (click to expand)</summary> <!-- toc -->

• SwiftPlantUML
  • Usage
    • Command Line
    • Swift package
    • Xcode source editor extension
  • Installation
    • Using Homebrew
    • Using Mint
    • Installing from source
    • Note: Working with Multiple Swift Versions
  • Configuration
    • Options
      • Theming
    • Examples
    • Code Completion during Editing
  • Large Diagrams
  • Generate UML documentation from a binary framework
  • Planned improvements
  • Known limitations
  • Logging
  • Manual page
  • Acknowledgements

<!-- tocstop --> </details>

Usage

Command Line

Example to generate and render diagram, based on a single Swift file, in your browser:

swiftplantuml ./Tests/SwiftPlantUMLFrameworkTests/TestData/basics.txt

Run swiftplantuml in the directory containing the Swift files to be considered for diagram generation. Directories will be searched recursively.

$ swiftplantuml classdiagram --help
OVERVIEW: Generate PlantUML script and view it and diagram in browser

USAGE: swift-plant-uml classdiagram [--config <config>] [--exclude <exclude> ...] [--output <format>] [--sdk <sdk>] [--verbose] [<paths> ...]

ARGUMENTS:
  <paths>                 List of paths to the files or directories containing
                          swift sources

OPTIONS:
  --config <config>       Path to custom configuration filed (otherwise will
                          search for `.swiftplantuml.yml` in current directory)
  --exclude <exclude>     paths to ignore source files. Takes precedence over
                          arguments
  --output <format>       Defines output format. Options: browser,
                          browserImageOnly, consoleOnly
  --sdk <sdk>             MacOSX SDK path used to handle type inference
                          resolution, usually `$(xcrun --show-sdk-path -sdk
                          macosx)`
  --hide-extensions/--merge-extensions/--show-extensions
                          Decide if/how Swift extensions shall be considered for class diagram generation (default:
                          hideExtensions)
  --verbose               Verbose
  --version               Show the version.
  -h, --help              Show help information.

As classdiagram is the default subcommand you can omit it.

Note: unknown type in diagrams for variables declared with type inference (e.g. var hasBasket = false) unless you specify sdk argument

<details> <summary><strong>Type inference details</strong> (click to expand)</summary>

In the following example the property hasBasket is of type Bool but the type is inferred and not explicitly declared.

class Bicycle: Vehicle {
    var hasBasket = false
}

SwiftPlantUML requires the macosx SDK in order to properly recognize the inferred type. If you have Xcode installed (which includes the macosx SDK) then use --sdk $(xcrun --show-sdk-path -sdk macosx).

| | No inferred type (default) | inferred type | |--------------------|-------------------|-----------------------| | Generated PlantUML | ~hasBasket | ~hasBasket : Bool | Command | swiftplantuml classdiagram Tests/SwiftPlantUMLFrameworkTests/TestData/demo.txt | swiftplantuml classdiagram Tests/SwiftPlantUMLFrameworkTests/TestData/demo.txt --sdk $(xcrun --show-sdk-path -sdk macosx) | |

</details>

Swift package

dependencies: [
    .package(url: "https://github.com/MarcoEidinger/SwiftPlantUML.git", .upToNextMajor(from: "0.5.0"))
]

This project has yet to reach a major version. Anything may change at anytime, and the public API should not be considered stable. However, I'll try to reserve breaking changes for new minor versions. You might feel more comfortable pinning the version to .upToNextMinor or even to an .exact version.

API documentation

Xcode source editor extension

See MarcoEidinger/SwiftPlantUML-Xcode-Extension for more details

Installation

Using Homebrew

brew install swiftplantuml

previously you were able to use brew install MarcoEidinger/formulae/swiftplantuml (and you still can)

Using Mint

$ mint install MarcoEidinger/SwiftPlantUML

Installing from source

You can also build and install from source by cloning this project and running make install (Xcode 12 or later).

Manually Run the following commands to build and install manually:

$ git clone https://github.com/MarcoEidinger/SwiftPlantUML.git
$ cd SwiftPlantUML
$ make install

Note: Working with Multiple Swift Versions

SwiftPlantUML hooks into SourceKit and therefore needs a Swift toolschain.

You should always run SwiftPlantUML with the same toolchain you use to compile your code.

You may want to override SwiftPlantUML's default Swift toolchain if you have multiple toolchains or Xcodes installed.

Here's the order in which SwiftPlantUML determines which Swift toolchain to use:

• $XCODE_DEFAULT_TOOLCHAIN_OVERRIDE
• $TOOLCHAIN_DIR or $TOOLCHAINS
• xcrun -find swift
• /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
• /Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
• ~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
• ~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain

sourcekitd.framework is expected to be found in the usr/lib/ subdirectory of the value passed in the paths above.

So if you encounter Fatal error: Loading sourcekitd.framework/Versions/A/sourcekitd failed then please check result of xcode-select -p to see if that directory subsequently contains a Swift toolschain. You can use sudo xcode-select -s <pathToYourXcodeInstallation> to rectify the situation, e.g.

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Configuration

Configure SwiftPlantUML by adding a .swiftplantuml.yml file from the directory you'll run SwiftPlantUML from. Note: the same configuration options can be set programmatically with Configuration.

Options

You can

• include/exclude files (wildcards supported)
• include/exclude elements by name (wildcards supported)
• limit elements and members based on their access level, e.g. show only public types
• hide extensions or merge extensions (with their known type)

| Show Extensions (Default) | Merge Extensions | Hide Extensions | | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | | | | | Clutter but represents codebase accurately | Reduced clutter. No loss of information | No clutter but loss of information |

• hide nested types
• hide member access level attribute
• configure styles, use skin parameters and even include external files or themes
• exclude inheritance relationships based on parent (wildcards supported), e.g. do not show inheritance to Codable

Theming

| Default | Amiga | Reddress-darkblue | Sketchy Outline | Many More Available | | :---------------------------------------------: | --