{"id":13693584,"url":"https://github.com/migueldeicaza/SwiftTerm","last_synced_at":"2025-05-02T21:32:29.051Z","repository":{"id":38040638,"uuid":"177906917","full_name":"migueldeicaza/SwiftTerm","owner":"migueldeicaza","description":"Xterm/VT100 Terminal emulator in Swift","archived":false,"fork":false,"pushed_at":"2025-04-20T22:20:13.000Z","size":3659,"stargazers_count":1049,"open_issues_count":60,"forks_count":150,"subscribers_count":27,"default_branch":"main","last_synced_at":"2025-04-20T23:24:18.037Z","etag":null,"topics":["appkit","imgcat","ios","macos","sixel","ssh-connection","swift","terminal-engine","uikit","vt100","xterm","xterm-256color"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/migueldeicaza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-27T02:52:33.000Z","updated_at":"2025-04-20T22:20:17.000Z","dependencies_parsed_at":"2023-02-14T00:45:58.172Z","dependency_job_id":"f4ac31f8-7b4d-4050-a813-2de5d696039f","html_url":"https://github.com/migueldeicaza/SwiftTerm","commit_stats":{"total_commits":639,"total_committers":28,"mean_commits":"22.821428571428573","dds":0.2018779342723005,"last_synced_commit":"d59364294704280e435c42c6343e2d2b76b930e3"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migueldeicaza%2FSwiftTerm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migueldeicaza%2FSwiftTerm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migueldeicaza%2FSwiftTerm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migueldeicaza%2FSwiftTerm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/migueldeicaza","download_url":"https://codeload.github.com/migueldeicaza/SwiftTerm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252109084,"owners_count":21696189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appkit","imgcat","ios","macos","sixel","ssh-connection","swift","terminal-engine","uikit","vt100","xterm","xterm-256color"],"created_at":"2024-08-02T17:01:13.181Z","updated_at":"2025-05-02T21:32:24.157Z","avatar_url":"https://github.com/migueldeicaza.png","language":"Swift","readme":"[![Swift](https://github.com/migueldeicaza/SwiftTerm/actions/workflows/swift.yml/badge.svg)](https://github.com/migueldeicaza/SwiftTerm/actions/workflows/swift.yml)\n\n\nSwiftTerm\n=========\n\nSwiftTerm is a VT100/Xterm terminal emulator library for Swift applications that can be \nembedded into macOS, iOS applications, text-based, headless applications or other \ncustom scenarios. It has been used in several commercially available SSH clients, including \n[Secure Shellfish](https://apps.apple.com/us/app/secure-shellfish-ssh-files/id1336634154), \n [La Terminal](https://apps.apple.com/us/app/la-terminal-ssh-client/id1629902861) and [CodeEdit](https://github.com/CodeEditApp/CodeEdit)\n\nCheck the [API Documentation](https://migueldeicaza.github.io/SwiftTermDocs/documentation/swiftterm/)\n\nThis repository contains both a terminal emulator engine that is UI agnostic, as well as\nfront-ends for this engine for iOS using UIKit, and macOS using AppKit.   A curses-based\nterminal emulator (to emulate an xterm inside a console application) is available as\npart of the [TermKit](https://github.com/migueldeicaza/TermKit) library. \n\n**Sample Code** There are a couple of minimal sample apps for Mac and iOS showing how to \nuse the library inside the `TerminalApp` directory.   \n\n* The sample Mac app has much of the functionality of MacOS' Terminal.app, but without the configuration UI.   \n* The sample iOS application uses an SSH library to connect to a remote system (as there is no native shell \non iOS to run), and the sample happens to be hardcoded to my home machine, you can change that in the source\ncode. \n\n**Companion App** [SwiftTermApp](https://github.com/migueldeicaza/SwiftTermApp)\nbuilds an actual iOS app that uses this library and is more complete than the\ntesting apps in this module and provides a proper configuration UI.\n\n\nThis is a port of my original\n[XtermSharp](https://github.com/migueldeicaza/XtermSharp), which was itself\nbased on [xterm.js](https://xtermjs.org).  At this point, I consider SwiftTerm\nto be a more advanced terminal emulator than both of those (modulo\nSelection/Accessibility) as it handles UTF, Unicode and grapheme clusters better\nthan those and has a more complete coverage of terminal emulation.   XtermSharp\nis generally attempting to keep up.\n\nFeatures\n========\n\n* Pretty decent terminal emulation, on or better than XtermSharp and xterm.js (and more comprehensive in many ways)\n* Unicode rendering (including Emoji, and combining characters and emoji)\n* Reusable and pluggable engine allows multiple user interfaces to be built on top of it.\n* Selection engine (with macOS support in the view)\n* Supports colors (ANSI, 256, TrueColor)\n* Supports mouse events\n* Supports terminal resizing operations (controlled by remote host, or locally)\n* [Hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) in terminal output\n* AppKit, UIKit front-ends; ncurses front-end [provided separately](https://github.com/migueldeicaza/TermKit)\n* Local process and SSH connection support (some assembly required for the last one)\n* Proper CoreText rendering can munch through the hardened Unicode test suites.\n* Sixel graphics (Use img2sixel to test)\n* iTerm2-style graphic rendering (Use imgcat to test)\n* Fuzzed and abused\n* Seems pretty fast to me\n\n# SwiftTerm library\n\nThe SwiftTerm library itself contains the source code for both\nthe engine and the front-ends.  The front-ends are conditionally\ncompiled based on the target platform.\n\nThe engine is in this directory, while code for macOS lives under `Mac`, and\ncode for iOS, lives under `iOS`.    Given that those two share a lot of common \ntraits, the shared code is under `Apple`.\n\n## Using SwiftTerm\n\nSwiftTerm uses the Swift Package Manager for its build, and you can\nadd the library to your project by using the url for this project or a\nfork of it.\n\n## MacOS NSView \nThe macOS AppKit NSView implementation [`TerminalView`](https://migueldeicaza.github.io/SwiftTermDocs/documentation/swiftterm/terminalview) is a reusable\nNSView control that can be connected to any source by implementing the\n[`TerminalViewDelegate`](https://migueldeicaza.github.io/SwiftTermDocs/documentation/swiftterm/terminalviewdelegate).  \nI anticipate that a common scenario will be\nto host a local Unix command, so I have included\n[`LocalProcessTerminalView`](https://migueldeicaza.github.io/SwiftTermDocs/documentation/swiftterm/localprocessterminalview)\n which is an implementation that connects\nthe `TerminalView` to a Unix pseudo-terminal and runs a command there.\n\n## iOS UIView\nThere is an equivalent UIKit UIView implementation for\n[`TerminalView`](https://migueldeicaza.github.io/SwiftTermDocs/documentation/swiftterm/terminalview)\nwhich like its NSView companion is an embeddable and reusable view\nthat can be connected to your application by implementing the same\nTerminalViewDelegate.  Unlike the NSView case running on a Mac, where\na common scenario will be to run local commands, given that iOS does\nnot offer access to processes, the most common scenario will be to\nwire up this terminal to a remote host.  And the safest way of\nconnecting to a remote system is with SSH.\n\n## Shared Code between MacOS and iOS\n\nThe iOS and UIKit code share a lot of the code, that code lives under the Apple directory.\n\n## Using SSH\nThe core library currently does not provide a convenient way to connect to SSH, purely\nto avoid the additional dependency.   But this git module references a module that pulls\na precompiled SSH client ([Frugghi's SwiftSH](https://github.com/migueldeicaza/SwiftSH)), along with \na [`UIKitSsshTerminalView`](https://github.com/migueldeicaza/SwiftTerm/blob/main/TerminalApp/iOSTerminal/UIKitSshTerminalView.swift)\nin the iOS sample that that connects the `TerminalView` for iOS to an SSH connection.  \n\nWorking on SwiftTerm\n====================\n\nIf you are using Xcode, there are two toplevel projects, one for Mac\nand one for iOS in the TerminalApp directory, one called \"iOSTerminal.xcodeproj\"\nand one called \"MacTerminal.xcodeproj\".  \n\nThis is needed because Xcode does not provide code completion for iOS if you \nhave a Mac project in the project.   So I had to split them up.   Both \nprojects reference the same SwiftTerm package.\n\nWhen working with these projects, if you choose the terminal application\nit will run this one.   To run the test suite, select the 'SwiftTerm' target\ninstead, and you can use 'SwiftTermFuzz' to run the fuzzer.\n\nYou can use `swift build` to build the package, and `swift test` to\nrun the test suite - but be warned that the test suite expects the\ndirectory `esctest` to be checked out to run.  You can see how I run\nthese on GitHub actions in the file `.github/workflows/swift.yml` if you\nwant to do this locally.\n\nIf using Xcode, you can select the \"SwiftTerm\" project, and then use Command-U \nto run the test suite.\n\nPending Work\n============\n\nGitHub issues has a list of desired features and enhancements\n\nLong Term Plans\n===============\n\nIn the longer term, I want to also add a tvOS UIView, a\n[SwiftGtk](https://github.com/rhx/SwiftGtk) front-end for Linux.\n\nScreenshots\n===========\n\n24 Bit Color \n\n\u003cimg width=\"1246\" alt=\"24 bit color\" src=\"https://user-images.githubusercontent.com/36863/79060395-82181400-7c52-11ea-8f48-cd02323a8284.png\"\u003e\n\nMidnight Commander\n\n\u003cimg width=\"969\" alt=\"Screen Shot 2020-04-12 at 12 17 49 AM\" src=\"https://user-images.githubusercontent.com/36863/79060466-49c50580-7c53-11ea-8514-bb4a31359662.png\"\u003e\n\nSolid UTF-8 support, excellent rendering:\n\u003cimg width=\"799\" alt=\"Screen Shot 2020-04-22 at 11 25 30 PM\" src=\"https://user-images.githubusercontent.com/36863/80055786-95e43580-84f0-11ea-86dd-8dfb7f062b39.png\"\u003e\n\n\u003cimg width=\"799\" alt=\"Screen Shot 2020-04-22 at 11 25 24 PM\" src=\"https://user-images.githubusercontent.com/36863/80055792-9977bc80-84f0-11ea-8cac-735d4a516a80.png\"\u003e\n\nSupports hyperlinks emitted by modern apps:\n\n\u003cimg width=\"674\" alt=\"image\" src=\"https://user-images.githubusercontent.com/36863/80055972-0b500600-84f1-11ea-9c57-41cadce67162.png\"\u003e\n\niOS support:\n\n\u003cimg width=\"981\" alt=\"image\" src=\"https://user-images.githubusercontent.com/36863/80056069-54a05580-84f1-11ea-8597-5a227c9c64a7.png\"\u003e\n\nSixel support:\n\n\u003cimg width=\"770\" alt=\"image\" src=\"https://user-images.githubusercontent.com/36863/115647346-97a62c00-a2f1-11eb-929a-f9d942cc0c09.png\"\u003e\n\n\u003cimg width=\"568\" alt=\"image\" src=\"https://user-images.githubusercontent.com/36863/115647706-4e0a1100-a2f2-11eb-9bba-2a82503bca33.png\"\u003e\n\n\nResources \n========= \n\n* [Digital's VT100 User Guide](https://geoffg.net/Downloads/Terminal/VT100_User_Guide.pdf)\n* [Terminal Guide](https://terminalguide.namepad.de) - very nice and visual, but not normative\n* [Xterm Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking)\n* [VT510 Video Terminal Programmer Information](https://vt100.net/docs/vt510-rm/contents.html])\n\nAdditional and useful documents:\n* [VT330/VT340 Programmer Reference Manual Volume 2: Graphics Programming](https://vt100.net/docs/vt3xx-gp/contents.html)\n* [A parser for DEC’s ANSI-compatible video terminals](https://vt100.net/emu/dec_ansi_parser)\n* [Codes and Standards](https://vt100.net/emu/)\n* [Linux Console Docs](http://man7.org/linux/man-pages/man4/console_codes.4.html) they are a subset of vt100, but often simple to follow.\n* [Sixel Graphics](https://github.com/saitoha/libsixel)\n\nTest suites:\n* [VTTest](https://invisible-island.net/vttest/) - old, but still good\n* [EscTest](https://gitlab.freedesktop.org/terminal-wg/esctest) - fantastic: George Nachman, the author of iTerm, created this test suite, and it became a FreeDesktop standard.  Since then, Thomas E. Dickey, the xterm maintainer and maintainer of many text apps has contributed to this effort.\n\n# Authors\n\n* Thanks go to the [xterm.js](https://xtermjs.org/) developers that originally wrote a terminal emulator\nthat was licensed under a license that allowed for maximum reuse.   \n* [Marcin Krzyzanowski](https://krzyzanowskim.com) who masterfully improved and curated the rendering engine on AppKit/CoreText to be the glorious renderer that it is today - and for his contributions to the rendering engine\n* Greg Munn that did a lot of work in XtermSharp to support the needs of Visual Studio for\nMac\n* [Anders Borum](https://github.com/palmin) has contributed reliability fixes, the sixel parser and changes required to put SwiftTerm to use in production.\n* [Miguel de Icaza](https://tirania.org/) -me- who have been looking for an excuse to write some Swift code.\n","funding_links":[],"categories":["Swift","Misc","Developer"],"sub_categories":["SwiftUI","Terminal"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigueldeicaza%2FSwiftTerm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmigueldeicaza%2FSwiftTerm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigueldeicaza%2FSwiftTerm/lists"}