diff --git a/.gitmodules b/.gitmodules index 0942606..17e6b5b 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,6 +1,3 @@ -[submodule "docs/wiki"] - path = docs/wiki - url = https://github.com/lihop/godot-xterm.wiki [submodule "addons/godot_xterm/native/thirdparty/godot-cpp"] path = addons/godot_xterm/native/thirdparty/godot-cpp url = https://github.com/godotengine/godot-cpp diff --git a/LICENSE.md b/LICENSE.md index b73011a..5d18ffe 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020-2021, Leroy Hopson <> and [contributors](https://github.com/lihop/godot-xterm/contributors). +Copyright (c) 2020-2022, Leroy Hopson <> and [contributors](https://github.com/lihop/godot-xterm/contributors). Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md deleted file mode 100644 index 65c5c63..0000000 --- a/README.md +++ /dev/null @@ -1,95 +0,0 @@ - - -# GodotXterm - -![Godot Version](https://img.shields.io/badge/Godot-3.3+-blue.svg) -![License](https://img.shields.io/badge/License-MIT-green.svg) -[![Build and Test](https://github.com/lihop/godot-xterm/actions/workflows/main.yml/badge.svg?event=schedule)](https://github.com/lihop/godot-xterm/actions/workflows/main.yml) - -GDNative terminal for Godot. -Built using [libtsm](https://www.freedesktop.org/wiki/Software/libtsm/), [libuv](https://github.com/libuv/libuv), and [node-pty](https://github.com/microsoft/node-pty). -Primarily developed and tested on Linux, it also supports macOS with partial support for Windows and HTML5. See the [Features](#features) section for more detail. - -https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4 - -## [Documentation](https://github.com/lihop/godot-xterm/wiki) - -Documentation is available in [the wiki](https://github.com/lihop/godot-xterm/wiki). -If you have a question not answered by the docs, or would like more support, feel free to open a new discussion in the [discussions](https://github.com/lihop/godot-xterm/discussions) section of this project. - -## Features - -- ### [Terminal](https://github.com/lihop/godot-xterm/wiki/Terminal) - A Terminal emulator Control node. - - Supports ANSI and (some) XTerm Control Sequences which can be used to do things such as clear the screen, move the cursor, change printed text color, ring a bell, and so on. - For an exhaustive list of terminal control sequences (not all of which are supported by GodotXterm) see . - -- ### [PTY](https://github.com/lihop/godot-xterm/wiki/PTY) - *Linux and macOS only.* - - Node for forking processes (e.g. bash, nodejs, python) with pseudoterminal file descriptors. - Can be used with the Terminal node to get an actual shell. - - Not currently supported on Windows, but it could be in the future using [ConPTY](https://docs.microsoft.com/en-us/windows/console) or [WinPTY](https://github.com/rprichard/winpty). - See issue [\#25](https://github.com/lihop/godot-xterm/issues/25). - -- ### Terminal Editor Plugin - *Linux and macOS only.* - - Adds a panel to the Editor's bottom panel that can be used to spawn terminals in the editor. - Similar to VSCode's integrated terminal and IntelliJ's embedded terminal. - -- ### Asciicast Import Plugin - Adds support for importing asciinema v2 `.cast` files as animations that can be played by an AnimationPlayer that is a child of a Terminal node. - Example `.cast` files can be downloaded from the [asciinema website](https://asciinema.org). - -- ### Xresources Import Plugin - Adds support for importing color schemes from `.xrdb` or `.Xresources` files. - Example xresources files can be exported from [terminal.sexy](https://terminal.sexy). - The [iTerm2-Color-Schemes repo](https://github.com/mbadolato/iTerm2-Color-Schemes) also has many example color scheme files in [xrdb](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/xrdb) and [Xresources](https://github.com/mbadolato/iTerm2-Color-Schemes) format. - -## Installation - -GodotXterm is available on the Godot Asset Library: . -For more ways to install see the [Installation](https://github.com/lihop/godot-xterm/wiki/Installation) page on the wiki. - -## Demos - -- [Online demo](https://lihop.github.io/godot-xterm-dist/) of an HTML5 export of this repo (using the GDNative export type, available since Godot 3.3). - Make sure you click the screen at least once after loading. - -- [Xterminate](https://lihop.itch.io/xterminate). A Linux, macOS, and Windows demo, which uses an older version GodotXterm in conjunction with [Godot Python](https://github.com/touilleMan/godot-python). - -- This repository also contains a number of demo scenes in the [`examples`](/examples) directory. The easiest way to run these scenes is to clone this repo and then download the `libgodot-xterm-release.zip` archive from the [Releases](https://github.com/lihop/godot-xterm/releases) section and extract its contents (`.so`, `.wasm`, `.dll`, and `.dylib` files) into the `addons/godot_xterm/native/bin` directory. - - -## [License](/LICENSE.md) - -Copyright (c) 2020-2021, Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/graphs/contributors) (MIT License). - -### Third-party components - -The GDNative source code incorporates code snippets and source code from many third-party libraries. The licenses of these components can be found in the various sub-directories of this project (provided git submodules have been cloned). Many of these licenses must be distributed with source and binary distributions of this software. For convenience, the texts of these licenses have been bundled together (but clearly demarcated) in the [THIRDPARTY_NOTICES.txt](/addons/godot_xterm/THIRDPARTY_NOTICES.txt) file. - -**Note:** On platforms where the PTY node is not supported or if the library has been compiled with the option `disable_pty=yes` then only the licenses bundled in [THIRDPARTY_NOTICES_nopty.txt](/addons/godot_xterm/THIRDPARTY_NOTICES_nopty.txt) are applicable. - -### Fonts - -- The Hack regular font is bundled with GodotXterm as the default Terminal font. This is also the default monospace font of the Godot editor. See the [full license](/addons/godot_xterm/themes/fonts/hack/LICENSE.md). - - -### Nonbundled Resources -The following resources are not bundled with GodotXterm (i.e. are not included in the `addons/godot_xterm` directory) but are included in this repository for demo and testing purposes. They are: - - -#### Sounds - -- [bell.wav](/themes/audio/bell.wav) by InspectorJ (), downloaded from [freesound.org](https://freesound.org/people/InspectorJ/sounds/484344/), released under [CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/). - -#### Fonts - -- The **bold**, *italic*, and ***bold italic*** styles of the Hack font which are covered by the same license as above. -- Nerd Fonts. Combines symbols from a multitude of other fonts. See [license information](/themes/fonts/nerd_fonts/README.md). -- Noto Color Emoji. Released under the [SIL Open Font License](/themes/fonts/noto_color_emoji/LICENSE_OFL.txt). -- Unifont. Dual-licensed (since version 13.0.04) under the GNU GPL 2+ with the GNU font embedding exception and the SIL Open Font License (OFL) version 1.1. This project uses it under the terms of the [SIL Open Font License](/themes/fonts/unifont/LICENSE_OFL-1.1.txt). diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..f40fbd8 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +_site +.sass-cache +.jekyll-cache +.jekyll-metadata +vendor diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 0000000..086a5c9 --- /dev/null +++ b/docs/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/CHANGELOG.md b/docs/CHANGELOG.md similarity index 100% rename from CHANGELOG.md rename to docs/CHANGELOG.md diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..858d935 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,2 @@ +source "https://rubygems.org" +gem "github-pages", "~> 227", group: :jekyll_plugins diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..d733d2f --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,261 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (6.0.5.1) + concurrent-ruby (~> 1.0, >= 1.0.2) + i18n (>= 0.7, < 2) + minitest (~> 5.1) + tzinfo (~> 1.1) + zeitwerk (~> 2.2, >= 2.2.2) + addressable (2.8.0) + public_suffix (>= 2.0.2, < 5.0) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.23.5) + concurrent-ruby (1.1.10) + dnsruby (1.61.9) + simpleidn (~> 0.1) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.15.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + execjs (2.8.1) + faraday (2.4.0) + faraday-net_http (~> 2.0) + ruby2_keywords (>= 0.0.4) + faraday-net_http (2.1.0) + ffi (1.15.5) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (227) + github-pages-health-check (= 1.17.9) + jekyll (= 3.9.2) + jekyll-avatar (= 0.7.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.2.0) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.15.1) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.13.0) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.12.0) + kramdown (= 2.3.2) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.3) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.13.6, < 2.0) + rouge (= 3.26.0) + terminal-table (~> 1.4) + github-pages-health-check (1.17.9) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (>= 3.0, < 5.0) + typhoeus (~> 1.3) + html-pipeline (2.14.2) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.8.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.9.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.7.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.2.0) + commonmarker (~> 0.23.4) + jekyll (~> 3.9.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 4.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.15.1) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.13.0) + jekyll (>= 3.4, < 5.0) + octokit (~> 4.0, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.12.0) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + kramdown (2.3.2) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.3) + listen (3.7.1) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.3.6) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.16.2) + nokogiri (1.13.8-x86_64-linux) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (4.0.7) + racc (1.6.0) + rb-fsevent (0.11.1) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.5) + rouge (3.26.0) + ruby2_keywords (0.0.5) + rubyzip (2.3.2) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + simpleidn (0.2.1) + unf (~> 0.1.4) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.4.0) + ethon (>= 0.9.0) + tzinfo (1.2.10) + thread_safe (~> 0.1) + unf (0.1.4) + unf_ext + unf_ext (0.0.8.2) + unicode-display_width (1.8.0) + zeitwerk (2.6.0) + +PLATFORMS + x86_64-linux + +DEPENDENCIES + github-pages (~> 227) + +BUNDLED WITH + 2.3.19 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f2163e1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,130 @@ + + +# GodotXterm - Terminal Emulator +
+ +[![Godot Version](https://img.shields.io/badge/Godot-3.3+-blue.svg)](https://godotengine.org) +[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/lihop/godot-xterm/blob/stable/LICENSE.md) +[![Build and Test](https://github.com/lihop/godot-xterm/actions/workflows/main.yml/badge.svg?event=schedule)](https://github.com/lihop/godot-xterm/actions/workflows/main.yml) + +GDNative terminal for Godot. +Built using [libtsm](https://www.freedesktop.org/wiki/Software/libtsm/), [libuv](https://github.com/libuv/libuv), and [node-pty](https://github.com/microsoft/node-pty). +Primarily developed and tested on Linux, it also supports macOS with partial support for Windows and HTML5. See the [Features section](#features) for more detail. + + + +
+ +https://user-images.githubusercontent.com/3696783/126894061-a69eb6ad-9979-4723-ade7-829494a9fc87.mp4 + +
+ +[![Live Demo](./media/live_demo_button.png)](https://lihop.github.io/godot-xterm-dist/) +[![View it on GitHub](./media/view_it_on_github_button.png)](https://github.com/lihop/godot-xterm) + +#### Table of Contents +1. [Features](#features) +2. [Screenshots](#screenshots) +3. [Demos and Examples](#demos-and-examples) +4. [Installation](#installation) +5. [Documentation](#documentation) +6. [License](#license) + +## Features + +- ### [Terminal](https://lihop.github.io/godot-xterm/api/terminal) + A Terminal emulator Control node. + + Supports ANSI and (some) XTerm Control Sequences which can be used to do things such as clear the screen, move the cursor, change printed text color, ring a bell, and so on. + For an exhaustive list of terminal control sequences (not all of which are supported by GodotXterm) see ["XTerm Control Sequences"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html). + +- ### [PTY](https://lihop.github.io/godot-xterm/api/pty) + *Linux and macOS only.* + + Node for forking processes (e.g. bash, nodejs, python) with pseudoterminal file descriptors. + Can be used with the Terminal node to get an actual shell. + + Not currently supported on Windows, but it could be in the future using [ConPTY](https://docs.microsoft.com/en-us/windows/console) or [WinPTY](https://github.com/rprichard/winpty). + See issue [\#25](https://github.com/lihop/godot-xterm/issues/25). + +- ### Terminal Editor Plugin + *Linux and macOS only.* + + Adds a panel to the Editor's bottom panel that can be used to spawn terminals in the editor. + Similar to VSCode's integrated terminal and IntelliJ's embedded terminal. + +- ### Asciicast Import Plugin + Adds support for importing asciinema v2 `.cast` files as animations that can be played by an AnimationPlayer that is a child of a Terminal node. + Example `.cast` files can be downloaded from the [asciinema website](https://asciinema.org). + +- ### Xresources Import Plugin + Adds support for importing color schemes from `.xrdb` or `.Xresources` files. + Example xresources files can be exported from [terminal.sexy](https://terminal.sexy). + The [iTerm2-Color-Schemes repo](https://github.com/mbadolato/iTerm2-Color-Schemes) also has many example color scheme files in [xrdb](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/xrdb) and [Xresources](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/Xresources) format. + +## Screenshots + +| | | +|--------------------------------------|--------------------------------------| +|![](./media/screenshot_editor.png) |![](./media/screenshot_the_guest.png) | +|![](./media/screenshot_retro_term.jpg)|![](./media/screenshot_xterminate.png)| + +## Demos and Examples + +The GodotXterm repository contains several example scenes in the [`/examples`](https://github.com/lihop/godot-xterm/tree/stable/examples) directory. +After cloning this repo you will need to either build the GDNative binaries from source or copy pre-compiled binaries into your project. +See the [Setup section](https://lihop.github.io/godot-xterm/setup) for more details. + +Other examples of GodotXterm usage are available online: + +- [**Live Demo**](https://lihop.github.io/godot-xterm-dist/): An HTML5 export of the GodotXterm repo's example scenes. + +- [**The Guest**](https://lihop.itch.io/the-guest): A Linux only submission to the [Linux Game Jam 2022](https://itch.io/jam/linux-game-jam-2022). Uses GodotXterm in conjunction with the [gdtemu addon](https://github.com/lihop/gdtemu) and Linux's Kernel-based Virtual Machine, to provide the player with interactive VM that can be used in the game world. + +- [**Xterminate**](https://lihop.itch.io/xterminate): A Linux, macOS, and Windows demo which uses an older version GodotXterm in conjunction with [Godot Python](https://github.com/touilleMan/godot-python). + +Are you using GodotXterm in your project and want it listed here? Please [open a pull request](https://github.com/lihop/godot-xterm/pulls) to have it added. + +## Installation + +GodotXterm is available on the [Godot Asset Library](https://godotengine.org/asset-library/asset/1007). +For more ways to install see the [Setup section](https://lihop.github.io/godot-xterm/setup). + +## Documentation + +Documentation is available on [GitHub Pages](https://lihop.github.io/godot-xterm). +If you have a question not answered by the docs, or would like more support, feel free to open a new discussion in the [discussions](https://github.com/lihop/godot-xterm/discussions) section of this project. + +## License + +Copyright (c) 2020-2022, Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/graphs/contributors) (MIT License). + +See the [full license](https://github.com/lihop/godot-xterm/blob/stable/LICENSE.md). + +### Third-party components + +The GDNative source code incorporates code snippets and source code from many third-party libraries. The licenses of these components can be found in the various sub-directories of this project (provided git submodules have been cloned). Many of these licenses must be distributed with source and binary distributions of this software. For convenience, the texts of these licenses have been bundled together (but clearly demarcated) in the [THIRDPARTY_NOTICES.txt](https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/THIRDPARTY_NOTICES.txt) file. + +**Note:** On platforms where the PTY node is not supported or if the library has been compiled with the option `disable_pty=yes` then only the licenses bundled in [THIRDPARTY_NOTICES_nopty.txt](https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/THIRDPARTY_NOTICES_nopty.txt) are applicable. + +### Fonts + +- The Hack regular font is bundled with GodotXterm as the default Terminal font. This is also the default monospace font of the Godot editor. See the [full license](https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/themes/fonts/hack/LICENSE.md). + + +### Nonbundled Resources +The following resources are not bundled with GodotXterm (i.e. are not included in the `addons/godot_xterm` directory) but are included in this repository for demo and testing purposes. They are: + + +#### Sounds + +- [bell.wav](https://github.com/lihop/godot-xterm/blob/stable/themes/audio/bell.wav) by [InspectorJ](https://www.jshaw.co.uk), downloaded from [freesound.org](https://freesound.org/people/InspectorJ/sounds/484344/), released under [CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/). + +#### Fonts + +- The **bold**, *italic*, and ***bold italic*** styles of the Hack font which are covered by the same license as above. +- Nerd Fonts. Combines symbols from a multitude of other fonts. See [license information](https://github.com/lihop/godot-xterm/blob/stable/themes/fonts/nerd_fonts/README.md). +- Noto Color Emoji. Released under the [SIL Open Font License](https://github.com/lihop/godot-xterm/blob/stable/themes/fonts/noto_color_emoji/LICENSE_OFL.txt). +- Unifont. Dual-licensed (since version 13.0.04) under the GNU GPL 2+ with the GNU font embedding exception and the SIL Open Font License (OFL) version 1.1. This project uses it under the terms of the [SIL Open Font License](https://github.com/lihop/godot-xterm/blob/stable/themes/fonts/unifont/LICENSE_OFL-1.1.txt). diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..2974185 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,12 @@ +# Site settings. +title: GodotXterm +email: godotxterm@leroy.geek.nz +description: Terminal emulator for the Godot game engine. +github_username: lihop + +# Build settings. +remote_theme: just-the-docs/just-the-docs + +# Just-the-docs settings. +color_scheme: dark +logo: /media/logo.png diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss new file mode 100644 index 0000000..5f600a9 --- /dev/null +++ b/docs/_sass/custom/custom.scss @@ -0,0 +1 @@ +#video-preview { display: none; } diff --git a/docs/api/api.md b/docs/api/api.md new file mode 100644 index 0000000..fc50184 --- /dev/null +++ b/docs/api/api.md @@ -0,0 +1,9 @@ +--- +layout: default +title: API +nav_order: 3 +has_children: true +permalink: /api +--- + +# API diff --git a/docs/api/pty.md b/docs/api/pty.md new file mode 100644 index 0000000..47d40d7 --- /dev/null +++ b/docs/api/pty.md @@ -0,0 +1,201 @@ +--- +layout: default +title: PTY +parent: API +nav_order: 1 +permalink: /api/pty +--- + +# PTY + +**Inherits:** [Node] < [Object] + +*Linux and macOS only.* + +Node for forking processes (e.g. bash, nodejs, python) with pseudoterminal file descriptors. +Can be used with the [Terminal] node to get an actual shell. + +Not currently supported on Windows, but it could be in the future using [ConPTY](https://docs.microsoft.com/en-us/windows/console) or [WinPTY](https://github.com/rprichard/winpty). +See issue [\#25](https://github.com/lihop/godot-xterm/issues/25). + + +## Overview + +![PTY Diagram](/media/pty_diagram.png) +"PTY Diagram" is a derivative of [Termios-script-diagram.svg](https://commons.wikimedia.org/wiki/File:Termios-script-diagram.svg) by [Krishnavedala](https://en.wikipedia.org/wiki/User:Krishnavedala?rdfrom=commons:User:Krishnavedala), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). + + +## Properties + +| Type | Name | Default | +|--------------|--------------------------------------|--------------------------------------------------------| +| [NodePath] | [terminal_path](#prop-terminal_path) | None | +| [int] | [cols](#prop-cols) | `80` | +| [int] | [rows](#prop-rows) | `24` | +| [Dictionary] | [env](#prop-env) | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` | +| [bool] | [use_os_env](#prop-use_os_env) | `true` | + + +## Methods + +| Returns | Signature | +|---------|-------------------------------------------------------------------------------------------------------------------------------------| +| [Error] | [fork](#mthd-fork) **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)** | +| void | [kill](#mthd-kill) **(** [int] signum **)** | +| [Error] | [open](#mthd-open) **(** [int] cols=80, [int] rows=24 **)** | +| void | [resize](#mthd-resize) **(** [int] cols, [int] rows **)** | +| void | [resizev](#mthd-resizev) **(** [Vector2] size **)** | +| void | [write](#mthd-write) **(** [String]\|[PoolByteArray] data **)** | + + +## Signals + +- **data_received** **(** [PoolByteArray] data **)** + + Emitted when data is read from the pseudoterminal master device. + +--- + +- **exited** **(** [int] exit_code, [int] signum **)** + + Emitted when the child program exits. `exit_code` is the exit status of the child program and `signum` is the number of the signal that terminated the child program. + +## Enumerations + +### enum **Signal**: + +- **SIGHUP** = 1 --- Hangup. +- **SIGINT** = 2 --- Terminal interrupt signal. +- **SIGQUIT** = 3 --- Terminal quit signal. +- **SIGILL** = 4 --- Illegal instruction. +- **SIGTRAP** = 5 --- Trace/breakpoint trap. +- **SIGABRT** = 6 --- Process abort signal. +- **SIGFPE** = 8 --- Erroneous arithmetic operation. +- **SIGKILL** = 9 --- Kill (cannot be caught or ignored). +- **SIGSEGV** = 11 --- Invalid memory reference. +- **SIGPIPE** = 13 --- Write on a pipe with no one to read it. +- **SIGALRM** = 14 --- Alarm clock. +- **SIGTERM** = 15 --- Termination signal. + + +## Property Descriptions + +### [NodePath] **terminal_path** + + | | | + |-----------|--------------------------| + | *Default* | None | + | *Setter* | set_terminal_path(value) | + | *Getter* | None | + + [NodePath] to a [Terminal]. Setting this path will automatically connect the appropriate signals of both nodes for standard operation. It will also disconnected the signals of the previously set terminal, if any. + +--- + +- [int] **cols** + + | | | + |-----------|--------------------------| + | *Default* | `80` | + | *Setter* | set_cols(value) | + | *Getter* | None | + + The column size in characters. + +--- + +- [int] **rows** + + | | | + |-----------|--------------------------| + | *Default* | `24` | + | *Setter* | set_rows(value) | + | *Getter* | None | + + The row size in characters. + +--- + +- [Dictionary] **env** + + | | | + |-----------|--------------------------------------------------------| + | *Default* | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` | + | *Setter* | None | + | *Getter* | None | + + Environment variables to be set for the child program. + +--- + +- [bool] **use_os_env** + + | | | + |-----------|--------| + | *Default* | `true` | + | *Setter* | None | + | *Getter* | None | + + If `true` the environment variables from `env` will be merged with the environment variables of the current program (i.e. Godot), with the variables from `env` taking precedence over the environment variables of the current program. + + +## Method Descriptions + +- [Error] **fork** **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)** +{ .red } + + Opens a pseudoterminal and starts a new process using the program specified by `file`. + `file` defaults to the value of the `SHELL` environment variable, falling back to `sh`. + The arguments specified in `args` are passed to the program. + `cwd` is the directory in which the program will be executed. Defaults to the working directory of the current program (typically the project directory, when running from editor). + `cols` is the initial number of columns and `rows` is the initial number of rows. + Returns [OK] if successful. + + See also Godot's [OS.execute()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-execute) method. + +--- + +- void **kill** **(** [int] signum=1 **)** + + Sends the specified signal (`signum`) to the PTY's child process, if any. Defaults to 1 (SIGHUP). + + See also Godot's [OS.kill()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-kill) method. + +--- + +- [Error] **open** **(** [int] cols=80, [int] rows=24 **)** + + Opens a pseudoterminal but does not start any process. Returns [OK] if successful. + +--- + +- void **resize** **(** [int] cols, [int] rows **)** + + Resizes the dimensions of the pseudoterminal. + +--- + +- void **resizev** **(** [Vector2] size **)** + + Same as resize, but accepts a [Vector2] where `x` is cols and `y` is rows. + +--- + +- void **write** **(** [String] \| [PoolByteArray] data **)** + + Writes data to the pseudoterminal master device. + + +[Dictionary]: https://docs.godotengine.org/en/stable/classes/class_dictionary.html +[Error]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#enum-globalscope-error +[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html +[NodePath]: https://docs.godotengine.org/en/stable/classes/class_nodepath.html +[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html +[OK]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#class-globalscope-constant-ok +[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html +[PoolStringArray]: https://docs.godotengine.org/en/stable/classes/class_poolstringarray.html +[String]: https://docs.godotengine.org/en/stable/classes/class_string.html +[Terminal]: /api/terminal +[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html +[bool]: https://docs.godotengine.org/en/stable/classes/class_bool.html +[int]: https://docs.godotengine.org/en/stable/classes/class_int.html diff --git a/docs/api/terminal.md b/docs/api/terminal.md new file mode 100644 index 0000000..8c7857c --- /dev/null +++ b/docs/api/terminal.md @@ -0,0 +1,225 @@ +--- +layout: default +title: Terminal +parent: API +nav_order: 2 +permalink: /api/terminal +--- + +# Terminal + +**Inherits:** [Control] < [CanvasItem] < [Node] < [Object] + +A Terminal emulator Control node. + +Supports ANSI and (some) XTerm Control Sequences which can be used to do things such as clear the screen, move the cursor, change printed text color, ring a bell, and so on. +For an exhaustive list of terminal control sequences (not all of which are supported by GodotXterm) see ["XTerm Control Sequences"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html). + + +## Overview +![Terminal Flow Diagram](/media/flow_diagram.svg) +"Terminal Flow Diagram" is a derivative of ["computer keyboard 2"](https://openclipart.org/detail/2396/computer-keyboard-2) and ["monitor"](https://openclipart.org/detail/1637/monitor), from U.S. patent drawings, uploaded by [johnny_automatic](https://openclipart.org/artist/johnny_automatic), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). + +### (1) User Input + +The user enters some data into the terminal, typically by typing something on the keyboard. +This corresponds to the `_gui_input()` method. + +### (2) Terminal Output + +The user input from (1) is processed by the terminal state machine and converted to the appropriate output. +For example, if the user were to press the downwards arrow key (↓), the terminal would then emit `data_sent()` +with the value `"\u001b[A"`. + +### (3) Terminal Input + +In the other direction, data can be sent to the terminal. This corresponds to the `write()` method. + +### (4) Draw + +The input from (3) is then interpreted by the terminal state machine and drawn to the screen. +For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal, then it would draw a green colored capital letter 'A' on the screen. + + +## Properties + +| Type | Name | Default | +|--------------|--------------------------------------|---------| +| [bool] | [bell_muted](#prop-bell_muted) | `false` | +| [float] | [bell_cooldown](#prop-bell_cooldown) | `0.1` | +| [int] | [cols](#prop-cols) | `2` | +| [int] | [rows](#prop-rows) | `2` | +| [UpdateMode] | [update_mode](#prop-update_mode) | `AUTO` | + + +## Methods + +| Returns | Signature | +|----------|-----------------------------------------------------------------| +| void | [clear](#mthd-clear) **()** | +| [String] | [copy_all](#mthd-copy_all) **()** | +| [String] | [copy_selection](#mthd-copy_selection) **()** | +| void | [write](#mthd-write) **(** [String]\|[PoolByteArray] data **)** | + + +## Signals + +- **bell** **()** + + Emitted when the [bell character](https://en.wikipedia.org/wiki/Bell_character) (`"\u0007"`) is written to the terminal. + +--- + +- **data_sent** **(** [PoolByteArray] data **)** + + Emitted when some data comes out of the terminal. + This typically occurs when the user interacts with the terminal by typing on the keyboard. + Input can be interpreted differently depending on modifier keys and the terminal's settings/state. + + When connected to a [PTY], this data will be forwarded to it. + +--- + +- **key_pressed** **(** [String] data, [InputEventKey] event **)** + + Emitted when a key is pressed. `data` is the data that would be emitted by the terminal via the [`data_sent()`](#sgnl-data_sent) signal and may vary based on the terminal's state. `event` is the event captured by Godot in the `_gui_input(event)` method. + +--- + +- **size_changed** **(** [Vector2] new_size **)** + + Emitted when the terminal's size changes, typically in response to its `rect_size` changing. + `new_size.x` will be the number of columns and `new_size.y` will be the number of rows. + This information should be forwarded to a pseudoterminal, if it is connected, so that it can update its size accordingly. + + +## Enumerations + + enum **UpdateMode**: + +- **DISABLED** = **0** --- The terminal's `update()` method will never be called. No new cells will be drawn. +- **AUTO** = **1** --- Only changed cells will be drawn after `update()` is called, but will switch to **ALL_NEXT_FRAME** when mass redraws are required. +- **ALL** = **2** --- Every cell will be drawn on every `update()` call. +- **ALL_NEXT_FRAME** = **3** --- Draws every cell afetr the next `update()` call, then returns to **AUTO**. + + +## Property Descriptions + +- [int] **rows** + + | | | + |-----------|------------| + | *Default* | `2` | + | *Setter* | None | + | *Getter* | None | + + The number of rows in the terminal's rect. + When using a monospace font, this is typically the number of characters that can fit from the top to the bottom. + It will automatically update as the Control's rect_size changes, and therefore shouldn't be used to set the size of the terminal directly. + +--- + +- [int] **cols** + + | | | + |-----------|------------| + | *Default* | `2` | + | *Setter* | None | + | *Getter* | None | + + The number of columns in the terminal's rect. + When using a monospace font, this is typically the number of characters that can fit from one side to another. + It will automatically update as the Control's rect_size changes, and therefore shouldn't be used to set the size of the terminal directly. + +--- + +- [bool] **bell_muted** + + | | | + |-----------|---------| + | *Default* | `false` | + | *Setter* | None | + | *Getter* | None | + + If muted, no [`bell`](#sgnl-bell) signal will be emitted when the bell character (`"\u0007"`) is written to the terminal. + +--- + +- [float] **bell_cooldown** + + | | | + |-----------|-------| + | *Default* | `0.1` | + | *Setter* | None | + | *Getter* | None | + + The minimum amount of time to wait before emitting another [`bell`](#sgnl-bell) signal on subsequent writes of the bell character. + Writing the bell character too frequently, for example by running the command `while true; do echo -e "\a"; done`, + can have a negative impact on performance depending on how the signal is connected. + This property allows throttling of that signal. + +--- + +- [UpdateMode] **update_mode** + + | | | + |-----------|------------------------| + | *Default* | `AUTO` | + | *Setter* | set_update_mode(value) | + | *Getter* | None | + + Determines which cells of the terminal will be updated when its state changes. + By default `AUTO` will only update cells that changed, but will update all cells (i.e. the entire screen) on major changes, + such as terminal resize. + If you are having trouble with the terminal not updating correctly or exhibiting artifacts, you can try remedying this by setting `update_mode` to `ALL`, however, this will have a negative impact on performance. + + +## Method Descriptions + +- void **clear** **()** + + Removes all but the bottommost row of the terminal including scrollback buffer. + +--- + +- String **copy_all** **()** + + Copies all of the text in the terminal including scrollback buffer. + +--- + +- String **copy_selection** **()** + + Copies only selected (i.e. highlighted) text in the terminal. + Will return an empty string if nothing is highligted. + +--- + +- void **write** **(** [String] \| [PoolByteArray] data **)** + + Writes data to the terminal emulator. Accepts either a [String] or [PoolByteArray]. + Typically it would be connected to the output of a [PTY]'s [`data_received()`](/api/pty#sgnl-data_received) signal. + + Example: + ```gdscript + $Terminal.write("Hello World") + $Terminal.write("Hello World".to_utf8()) + $Terminal.write(PoolByteArray([0x1b, 0x9e]) + ``` + +[AudioStream]: https://docs.godotengine.org/en/stable/classes/class_audiostream.html +[CanvasItem]: https://docs.godotengine.org/en/stable/classes/class_canvasitem.html +[Color]: https://docs.godotengine.org/en/stable/classes/class_color.html +[Control]: https://docs.godotengine.org/en/stable/classes/class_control.html +[Font]: https://docs.godotengine.org/en/stable/classes/class_font.html +[InputEventKey]: https://docs.godotengine.org/en/stable/classes/class_inputeventkey.html +[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html +[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html +[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html +[PTY]: /api/pty +[String]: https://docs.godotengine.org/en/stable/classes/class_string.html +[UpdateMode]: #enum-update_mode +[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html +[bool]: https://docs.godotengine.org/en/stable/classes/class_bool.html +[float]: https://docs.godotengine.org/en/stable/classes/class_float.html +[int]: https://docs.godotengine.org/en/stable/classes/class_int.html diff --git a/docs/build.sh b/docs/build.sh deleted file mode 100755 index 8f63eb7..0000000 --- a/docs/build.sh +++ /dev/null @@ -1,7 +0,0 @@ -# Build export templates and export HTML5 release build. -pushd ../misc/export_templates -./build.sh -popd -pushd ../ -godot --no-window --export "HTML5" ./docs/demo/index.html -popd diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..eea3b14 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..cc1884c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: Introduction +nav_order: 1 +permalink: / +--- + +{% include_relative README.md %} diff --git a/docs/media/flow_diagram.svg b/docs/media/flow_diagram.svg new file mode 100644 index 0000000..2529ccb --- /dev/null +++ b/docs/media/flow_diagram.svg @@ -0,0 +1,2988 @@ + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + (1) + _gui_input() + + (2) + data_sent() + + (4) + _draw() + + (3) + write() + + + + diff --git a/icon.png b/docs/media/icon.png similarity index 100% rename from icon.png rename to docs/media/icon.png diff --git a/docs/media/live_demo_button.png b/docs/media/live_demo_button.png new file mode 100644 index 0000000..a4a96cc Binary files /dev/null and b/docs/media/live_demo_button.png differ diff --git a/docs/media/logo.png b/docs/media/logo.png new file mode 100644 index 0000000..eb2eab5 Binary files /dev/null and b/docs/media/logo.png differ diff --git a/docs/media/logo.svg b/docs/media/logo.svg new file mode 100644 index 0000000..ad5b0e5 --- /dev/null +++ b/docs/media/logo.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + GodotXterm + + diff --git a/docs/media/pty_diagram.png b/docs/media/pty_diagram.png new file mode 100644 index 0000000..b780094 Binary files /dev/null and b/docs/media/pty_diagram.png differ diff --git a/docs/media/pty_diagram.svg b/docs/media/pty_diagram.svg new file mode 100644 index 0000000..fca109f --- /dev/null +++ b/docs/media/pty_diagram.svg @@ -0,0 +1,486 @@ + + + + + + + + + + PTY + bash + Terminal + Pseudo ter-minal master + Pseudo ter-minal slave + (/dev/pts/...) + User + fork() + Kernel space + User space + stdin + read() + stdoutstderr + write() + stdin() + stdoutstderr + keyboard input + terminal output + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Godot + + diff --git a/docs/media/screenshot_editor.png b/docs/media/screenshot_editor.png new file mode 100644 index 0000000..23bc70f Binary files /dev/null and b/docs/media/screenshot_editor.png differ diff --git a/docs/media/screenshot_retro_term.jpg b/docs/media/screenshot_retro_term.jpg new file mode 100644 index 0000000..0bdca06 Binary files /dev/null and b/docs/media/screenshot_retro_term.jpg differ diff --git a/docs/media/screenshot_the_guest.png b/docs/media/screenshot_the_guest.png new file mode 100644 index 0000000..2fc5cee Binary files /dev/null and b/docs/media/screenshot_the_guest.png differ diff --git a/docs/media/screenshot_xterminate.png b/docs/media/screenshot_xterminate.png new file mode 100644 index 0000000..eb538c4 Binary files /dev/null and b/docs/media/screenshot_xterminate.png differ diff --git a/docs/media/view_it_on_github_button.png b/docs/media/view_it_on_github_button.png new file mode 100644 index 0000000..e991290 Binary files /dev/null and b/docs/media/view_it_on_github_button.png differ diff --git a/docs/screenshot.png b/docs/screenshot.png deleted file mode 100644 index 9afa0f7..0000000 Binary files a/docs/screenshot.png and /dev/null differ diff --git a/docs/setup/building_from_source.md b/docs/setup/building_from_source.md new file mode 100644 index 0000000..b679106 --- /dev/null +++ b/docs/setup/building_from_source.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Building From Source +parent: Setup +nav_order: 2 +permalink: /setup/building-from-source +--- + +# Building From Source + +Building GodotXterm from source consists of four steps: + +1. Clone git submodules. +2. Compile libuv using CMake. +3. Compile godot-cpp using scons. +4. Compile libtsm and libgodotxterm using scons. + +This plugin follows the same format as the [GDNative C++ Example](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-cpp-example.html). So if you can compile that example then you are 90% of the way there. The main difference is using CMake to compile libuv. + +## Dependencies + +- [Git](https://git-scm.com/) (to clone git submodules) +- [SCons](https://scons.org/) (a software construction tool) +- A C/C++ compiler (i.e. [gcc](https://gcc.gnu.org/), [llvm](https://llvm.org/), [MSVC](https://visualstudio.microsoft.com/vs/features/cplusplus/)) +- [CMake](https://cmake.org/) (to compile libuv) + +## The Easy Way + +Run the build script in `addons/godot-xterm/native`: +``` +cd addons/godot_xterm/native +./build.sh +``` +On Windows you can use `git-bash` to run this script. +Provided the dependencies above are installed then it should "just work™". + +Binaries for your platform will be installed in `addons/godot_xterm/native/bin`. + +The [build.sh] script accepts args `--target` which can be set to `debug` (default) or `release` and `--disable-pty` to compile only the dependencies of [Terminal] node and not [PTY] node (even on platforms that support it). + +### The Hard Way + +If you are having trouble compiling, study the [build.sh] script and the GitHub actions workflow in [main.yml] to see what commands are being run and how dependencies are installed. You can also dig into the [SConstruct](https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/native/SConstruct) file, and don't forget to refer back to the [GDNative C++ Example](https://docs.godotengine.org/en/stable/tutorials/plugins/gdnative/gdnative-cpp-example.html). + +Also feel free to open a new discussion in the [discussions](https://github.com/lihop/godot-xterm/discussions) section of this project. + +## Cross Compiling + +Although the SConstruct file contains some logic for cross-compiling, it has never been tested. If you want compile for other platforms consider forking this repo and then pushing your changes to GitHub. The workflow defined in [main.yml] will run and build the library for all supported platforms (Linux, macOS, Windows, and HTML5). + +Additionally, If you have `docker` and `docker-compose` installed, the [build.sh] script will also try to build the HTML5 binary inside a docker container and copy them to `addons/godot_xterm/native/bin`. + +[PTY]: /api/pty +[Terminal]: /api/terminal +[build.sh]: https://github.com/lihop/godot-xterm/blob/stable/addons/godot_xterm/native/build.sh +[main.yml]: https://github.com/lihop/godot-xterm/blob/stable/.github/workflows/main.yml diff --git a/docs/setup/precompiled_binaries.md b/docs/setup/precompiled_binaries.md new file mode 100644 index 0000000..10690e0 --- /dev/null +++ b/docs/setup/precompiled_binaries.md @@ -0,0 +1,54 @@ +--- +layout: default +title: Precompiled Binaries +parent: Setup +nav_order: 1 +permalink: /setup/precompiled-binaries +--- + +# Precompiled Binaries +{: .no_toc } + +Installing GodotXterm using precompiled binaries means that you wont be required +to use a C/C++ compiler to build the project from source. It is simply a matter +of copying files to the correct location in your project. These files can be +installed from several sources: + +1. TOC +{:toc} + +**Note:** precompiled binaries will only work with certain versions of Godot +(usually the current stable release). If you need binaries for a different or +custom Godot version, or want to make modifications to the C/C++ code, please +refer to the section on [Building From Source](/setup/building-from-source). + +## Godot Asset Library +GodotXterm can be installed from the [Godot Asset Library](https://godotengine.org/asset-library/asset/1007). +See the [Godot Asset Library documentation](https://docs.godotengine.org/en/stable/community/asset_library/using_assetlib.html) for more info on how to use it. + +## Gd-plug Plugin Manager +If you are using the gd-plug plugin manager you can add the following line to your `plug.gd` file: +``` +plug("lihop/godot-xterm-dist", {commit = "a1131a562e8e8f0c57b0ddf61de7fa015d463ba0", include = ["addons/godot_xterm"]}) +``` +Replace the commit hash with the hash of the GodotXterm version you wish to install. +See [tags](https://github.com/lihop/godot-xterm-dist/tags) for a list of versions and their corresponding commit hashes. +See the [gd-plug documentation](https://github.com/imjp94/gd-plug/blob/master/README.md) for more info on how to use it. + +## Manual Installation +Alternatively, GodotXterm can be installed manually in two steps: +1. Copy the [`addons/godot_xterm`](https://github.com/lihop/godot-xterm/tree/stable/addons/godot_xterm) directory to the `addons` directory of your Godot project. +2. Copy the GDNative binaries into `addons/godot_xterm/native/bin` directory. + +The easiest way to obtain the GDNative binaries is to download them from [the Releases page](https://github.com/lihop/godot-xterm/releases). +Download the zip archive named `libgodot-xterm-release.zip` and extract its contents into the `/addons/godot_xterm/native/bin` directory of your project. +After this your `addons/godot_xterm/native/bin` directory should contain the following files: +- `libgodot-xterm.javascript.32.wasm` +- `libgodot-xterm.linux.32.so` +- `libgodot-xterm.linux.64.so` +- `libgodot-xterm.osx.64.dylib` +- `libgodot-xterm.windows.32.dll` +- `libgodot-xterm.windows.64.dll` + +Debug builds are also available on the Releases page if required. +Download and unzip `libgodot-xterm-debug.zip` instead of `libgodot-xterm-release.zip` to the same location. diff --git a/docs/setup/setup.md b/docs/setup/setup.md new file mode 100644 index 0000000..33eac90 --- /dev/null +++ b/docs/setup/setup.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Setup +nav_order: 2 +has_children: true +permalink: /setup +--- + +# Setup diff --git a/docs/wiki b/docs/wiki deleted file mode 160000 index 0d47069..0000000 --- a/docs/wiki +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 0d47069302d615c09611ee90a0a820986a9b1d00 diff --git a/icon.png.import b/icon.png.import deleted file mode 100644 index a4c02e6..0000000 --- a/icon.png.import +++ /dev/null @@ -1,35 +0,0 @@ -[remap] - -importer="texture" -type="StreamTexture" -path="res://.import/icon.png-487276ed1e3a0c39cad0279d744ee560.stex" -metadata={ -"vram_texture": false -} - -[deps] - -source_file="res://icon.png" -dest_files=[ "res://.import/icon.png-487276ed1e3a0c39cad0279d744ee560.stex" ] - -[params] - -compress/mode=0 -compress/lossy_quality=0.7 -compress/hdr_mode=0 -compress/bptc_ldr=0 -compress/normal_map=0 -flags/repeat=0 -flags/filter=true -flags/mipmaps=false -flags/anisotropic=false -flags/srgb=2 -process/fix_alpha_border=true -process/premult_alpha=false -process/HDR_as_SRGB=false -process/invert_color=false -process/normal_map_invert_y=false -stream=false -size_limit=0 -detect_3d=true -svg/scale=1.0 diff --git a/project.godot b/project.godot index 624eba4..e5da24c 100644 --- a/project.godot +++ b/project.godot @@ -28,7 +28,7 @@ _global_script_class_icons={ config/name="Godot Xterm" run/main_scene="res://examples/menu/menu.tscn" -config/icon="res://icon.png" +config/icon="res://docs/media/icon.png" [display]