Make ancient gcc happy

The new User Notifications Framework is only available on macOS 10.14 and above, while the old NSUserNotification API is deprecated in macOS 11 (Big Sur) and will probably be removed in the future.
This commit compiles a simple test program to see if the Framework is available and then uses either the new or the old API.

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+indent_style = spaces
+indent_size = 4
+end_of_line = lf
+trim_trailing_whitespace = true
+
+[{Makefile,*.terminfo}]
+indent_style = tab
+
+# Autogenerated files with tabs below this line.
+
+[kitty/{unicode-data.c,emoji.h,wcwidth-std.h}]
+indent_style = tab
+
+[kittens/unicode_input/names.h]
+indent_style = tab
+
+[glfw/wayland-*-protocol.{c,h}]
+indent_style = tab

.gitattributes

@@ -0,0 +1,13 @@
+kitty/wcwidth-std.h linguist-generated=true
+kitty/emoji.h linguist-generated=true
+kitty/keys.h linguist-generated=true
+kitty/charsets.c linguist-generated=true
+kitty/key_encoding.py linguist-generated=true
+kitty/unicode-data.c linguist-generated=true
+kitty/rgb.py linguist-generated=true
+kitty/gl-wrapper.* linguist-generated=true
+kitty/glfw-wrapper.* linguist-generated=true
+kitty/parse-graphics-command.h linguist-generated=true
+glfw/*.c linguist-vendored=true
+glfw/*.h linguist-vendored=true
+kittens/unicode_input/names.h linguist-generated=true

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+patreon: kovidgoyal
+liberapay: kovidgoyal
+custom: https://sw.kovidgoyal.net/kitty/support.html

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Create a bug report
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. XXX
+2. YYY
+3. ZZZ
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment details**
+OS: Name and version of operating system(s)
+
+```
+Output of kitty --debug-config
+```
+
+**Additional context**
+Try to reproduce the problem with `kitty --config NONE` if you cannot then post a minimal kitty.conf that reproduces the problem. If the problem involves interaction with some other terminal program post a minimal config for that program to reproduce the problem as well.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/ci.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPLv3 Copyright: 2020, Kovid Goyal <kovid at kovidgoyal.net>
+
+import io
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import tarfile
+from urllib.request import urlopen
+
+is_bundle = os.environ.get('KITTY_BUNDLE') == '1'
+is_macos = 'darwin' in sys.platform.lower()
+SW = None
+
+
+def run(*a):
+    if len(a) == 1:
+        a = shlex.split(a[0])
+    print(' '.join(map(shlex.quote, a)))
+    sys.stdout.flush()
+    ret = subprocess.Popen(a).wait()
+    if ret != 0:
+        raise SystemExit(ret)
+
+
+def install_deps():
+    print('Installing kitty dependencies...')
+    sys.stdout.flush()
+    if is_macos:
+        items = (x.strip() for x in open('Brewfile').readlines() if not x.startswith('#'))
+        run('brew', 'install', *items)
+    else:
+        run('sudo apt-get update')
+        run('sudo apt-get install -y libgl1-mesa-dev libxi-dev libxrandr-dev libxinerama-dev'
+            ' libxcursor-dev libxcb-xkb-dev libdbus-1-dev libxkbcommon-dev libharfbuzz-dev'
+            ' libpng-dev liblcms2-dev libfontconfig-dev libxkbcommon-x11-dev libcanberra-dev')
+    if is_bundle:
+        install_bundle()
+    else:
+        run('pip install Pillow pygments')
+
+
+def build_kitty():
+    python = shutil.which('python3') if is_bundle else sys.executable
+    cmd = '{} setup.py build --verbose'.format(python)
+    if os.environ.get('KITTY_SANITIZE') == '1':
+        cmd += ' --debug --sanitize'
+    run(cmd)
+
+
+def test_kitty():
+    run('./kitty/launcher/kitty +launch test.py')
+
+
+def package_kitty():
+    py = 'python3' if is_macos else 'python'
+    run(py + ' setup.py linux-package --update-check-interval=0 --verbose')
+    if is_macos:
+        run('python3 setup.py kitty.app --update-check-interval=0 --verbose')
+        run('kitty.app/Contents/MacOS/kitty +runpy "from kitty.constants import *; print(kitty_exe())"')
+
+
+def replace_in_file(path, src, dest):
+    with open(path, 'r+') as f:
+        n = f.read().replace(src, dest)
+        f.seek(0), f.truncate()
+        f.write(n)
+
+
+def setup_bundle_env():
+    global SW
+    os.environ['SW'] = SW = '/Users/Shared/kitty-build/sw/sw' if is_macos else os.path.join(os.environ['GITHUB_WORKSPACE'], 'sw')
+    os.environ['PKG_CONFIG_PATH'] = SW + '/lib/pkgconfig'
+    if is_macos:
+        os.environ['PATH'] = '{}:{}'.format('/usr/local/opt/sphinx-doc/bin', os.environ['PATH'])
+    else:
+        os.environ['LD_LIBRARY_PATH'] = SW + '/lib'
+        os.environ['PYTHONHOME'] = SW
+    os.environ['PATH'] = '{}:{}'.format(os.path.join(SW, 'bin'), os.environ['PATH'])
+
+
+def install_bundle():
+    cwd = os.getcwd()
+    os.makedirs(SW)
+    os.chdir(SW)
+    with urlopen('https://download.calibre-ebook.com/ci/kitty/{}-64.tar.xz'.format(
+            'macos' if is_macos else 'linux')) as f:
+        data = f.read()
+    with tarfile.open(fileobj=io.BytesIO(data), mode='r:xz') as tf:
+        tf.extractall()
+    if not is_macos:
+        replaced = 0
+        for dirpath, dirnames, filenames in os.walk('.'):
+            for f in filenames:
+                if f.endswith('.pc') or (f.endswith('.py') and f.startswith('_sysconfig')):
+                    replace_in_file(os.path.join(dirpath, f), '/sw/sw', SW)
+                    replaced += 1
+        if replaced < 2:
+            raise SystemExit('Failed to replace path to SW in bundle')
+    os.chdir(cwd)
+
+
+def main():
+    if is_bundle:
+        setup_bundle_env()
+    else:
+        if not is_macos and 'pythonLocation' in os.environ:
+            os.environ['LD_LIBRARY_PATH'] = '{}/lib'.format(os.environ['pythonLocation'])
+    action = sys.argv[-1]
+    if action in ('build', 'package'):
+        install_deps()
+    if action == 'build':
+        build_kitty()
+    elif action == 'package':
+        package_kitty()
+    elif action == 'test':
+        test_kitty()
+    else:
+        raise SystemExit('Unknown action: ' + action)
+
+
+if __name__ == '__main__':
+    main()

.github/workflows/ci.yml

@@ -0,0 +1,132 @@
+name: CI
+on: [push, pull_request]
+env:
+    CI: 'true'
+    ASAN_OPTIONS: leak_check_at_exit=0
+    LC_ALL: en_US.UTF-8
+    LANG: en_US.UTF-8
+
+jobs:
+    linux:
+        name: Linux (python=${{ matrix.pyver }} cc=${{ matrix.cc }} sanitize=${{ matrix.sanitize }})
+        runs-on: ubuntu-latest
+        env:
+            CC: ${{ matrix.cc }}
+            KITTY_SANITIZE: ${{ matrix.sanitize }}
+
+        strategy:
+            matrix:
+                python: [a, b, c]
+                cc: [gcc, clang]
+                include:
+                    - python: a
+                      pyver: 3.6
+                      sanitize: 0
+
+                    - python: b
+                      pyver: 3.7
+                      sanitize: 1
+
+                    - python: c
+                      pyver: 3.8
+                      sanitize: 1
+
+
+                exclude:
+                    - python: a
+                      cc: clang
+                    - python: b
+                      cc: clang
+                    - python: c
+                      cc: gcc
+
+        steps:
+            - name: Checkout source code
+              uses: actions/checkout@master
+              with:
+                fetch-depth: 10
+            - name: Set up Python ${{ matrix.pyver }}
+              uses: actions/setup-python@master
+              with:
+                python-version: ${{ matrix.pyver }}
+
+            - name: Build kitty
+              run: python .github/workflows/ci.py build
+
+            - name: Test kitty
+              run: python .github/workflows/ci.py test
+
+    linux-package:
+        name: Linux package
+        runs-on: ubuntu-latest
+        env:
+            CFLAGS: -funsigned-char
+        steps:
+            - name: Checkout source code
+              uses: actions/checkout@master
+              with:
+                fetch-depth: 10
+
+            - name: Test for trailing whitespace
+              run: if grep -Inr '\s$' kitty kitty_tests kittens docs *.py *.asciidoc *.rst .gitattributes .gitignore; then echo Trailing whitespace found, aborting.; exit 1; fi
+
+            - name: Set up Python
+              uses: actions/setup-python@master
+              with:
+                python-version: 3.8
+
+            - name: Install build-only deps
+              run: pip install flake8 mypy sphinx
+
+            - name: Run pyflakes
+              run: python -m flake8 --count .
+
+            - name: Build kitty package
+              run: python .github/workflows/ci.py package
+
+            - name: Run mypy
+              run: python test.py mypy
+
+            - name: Build man page
+              run: make FAIL_WARN=-W man
+
+            - name: Build HTML docs
+              run: make FAIL_WARN=-W html
+
+    bundle:
+        name: Bundle test (${{ matrix.os }})
+        runs-on: ${{ matrix.os }}
+        strategy:
+            matrix:
+                os: [ubuntu-latest, macos-latest]
+        env:
+            KITTY_BUNDLE: 1
+        steps:
+            - name: Checkout source code
+              uses: actions/checkout@master
+              with:
+                fetch-depth: 10
+
+            - name: Build kitty
+              run: which python3 && python3 .github/workflows/ci.py build
+
+            - name: Test kitty
+              run: python3 .github/workflows/ci.py test
+
+    brew:
+        name: macOS Brew
+        runs-on: macos-latest
+        steps:
+            - name: Checkout source code
+              uses: actions/checkout@master
+              with:
+                  fetch-depth: 10
+
+            - name: Build kitty
+              run: python3 .github/workflows/ci.py build
+
+            - name: Test kitty
+              run: python3 .github/workflows/ci.py test
+
+            - name: Build kitty package
+              run: python3 .github/workflows/ci.py package

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,41 @@
+name: "Code scanning - action"
+
+on:
+  push:
+    branches: [master, ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [master]
+  schedule:
+    - cron: '0 22 * * 5'
+
+jobs:
+  CodeQL-Build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        # We must fetch at least the immediate parents so that if this is
+        # a pull request then we can checkout the head.
+        fetch-depth: 2
+
+    # If this run was triggered by a pull request event, then checkout
+    # the head of the pull request instead of the merge commit.
+    - run: git checkout HEAD^2
+      if: ${{ github.event_name == 'pull_request' }}
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      # Override language selection by uncommenting this and choosing your languages
+      # with:
+      #   languages: go, javascript, csharp, python, cpp, java
+
+    - name: Build kitty
+      run: python3 .github/workflows/ci.py build
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.gitignore

@@ -1,9 +1,21 @@
-*.js
-*.pyj-cached
 *.so
-.build-cache
-tags
-build
-README.html
-linux-package
-logo/*.iconset
+*.pyc
+*.pyo
+*_stub.pyi
+/.dmypy.json
+/tags
+/build/
+/linux-package/
+/kitty.app/
+/compile_commands.json
+/link_commands.json
+/glad/out/
+/kitty/launcher/
+/*.dSYM/
+__pycache__/
+/glfw/wayland-*-client-protocol.[ch]
+/docs/_build/
+/docs/generated/
+/.mypy_cache
+.DS_Store
+bypy/b

.ignore

@@ -0,0 +1 @@
+kittens/unicode_input/names.h

.travis.yml

@@ -1,83 +0,0 @@
-matrix:
-    fast_finish: true
-    include:
-        - os: linux
-          dist: trusty
-          group: beta
-          sudo: false
-          env:
-            - CC=gcc ASANLIB=libasan.so.0 ASAN_ARG=--asan
-          language: python
-          python: "3.5"
-          addons:
-            apt:
-              packages:
-                - libfontconfig1-dev
-                - libglew-dev
-                - libxi-dev
-                - libxrandr-dev
-                - libxinerama-dev
-                - libxcursor-dev
-
-        - os: linux
-          dist: trusty
-          group: beta
-          sudo: false
-          env:
-            - CC=clang RUN_FLAKE=1 BUILD_PKG=1
-          language: python
-          python: "3.5"
-          addons:
-            apt:
-              packages:
-                - libfontconfig1-dev
-                - libglew-dev
-                - libxi-dev
-                - libxrandr-dev
-                - libxinerama-dev
-                - libxcursor-dev
-                - clang
-        - os: osx
-          language: generic
-          env: SWBASE=/Users/Shared/buildbot/sw SW=$SWBASE/sw PATH=$SW/bin:$PATH
-
-        - os: osx
-          language: generic
-          env: USE_BREW=1 BUILD_PKG=1
-
-install: |
-    set -e
-    if [[ "$RUN_FLAKE" == "1" ]]; then pip install flake8; fi
-    if [[ "$TRAVIS_OS_NAME" == 'osx' ]]; then
-        if [[ "$USE_BREW" == "1" ]]; then
-            brew update;
-            brew install python3;
-            brew install glfw;
-        else
-            mkdir -p $SW;
-            curl https://download.calibre-ebook.com/travis/kitty/osx.tar.xz | tar xJ -C $SW;
-        fi
-    else
-        wget -O glfw-3.2.1.zip https://github.com/glfw/glfw/archive/3.2.1.zip
-        unzip glfw-3.2.1.zip
-        cd glfw-3.2.1
-        cmake -DBUILD_SHARED_LIBS=ON -DGLFW_BUILD_EXAMPLES=OFF -DGLFW_BUILD_TESTS=OFF -DGLFW_BUILD_DOCS=OFF -DCMAKE_INSTALL_PREFIX=$HOME/glfw
-        make
-        make install
-        cd ..
-    fi
-    pkg-config --cflags glfw3
-    set +e
-
-env:
-    global:
-        - PKG_CONFIG_PATH=$HOME/glfw/lib/pkgconfig
-        - LD_LIBRARY_PATH=$HOME/glfw/lib
-        - ASAN_OPTIONS=leak_check_at_exit=0
-        - PYTHON=python3
-before_script:
-    - $PYTHON setup.py build --debug $ASAN_ARG;
-script:
-    - LD_PRELOAD=$ASANLIB $PYTHON setup.py test
-    - if [[ "$RUN_FLAKE" == "1" ]]; then flake8 --count .; fi
-    - if [[ "$BUILD_PKG" == "1" ]]; then $PYTHON setup.py linux-package; fi

=template.py

@@ -1,5 +0,0 @@
-#!/usr/bin/env python
-# vim:fileencoding=utf-8
-# License: GPL v3 Copyright: %YEAR%, %USER% <%MAIL%>
-
-%HERE%

Brewfile

@@ -0,0 +1,5 @@
+pkg-config
+python
+imagemagick
+harfbuzz
+sphinx-doc

CHANGELOG.rst

@@ -0,0 +1 @@
+See https://sw.kovidgoyal.net/kitty/changelog.html

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+### Reporting bugs
+
+Please first search existing bug reports (especially closed ones) for a report
+that matches your issue.
+
+When reporting a bug, provide full details of your environment, that means, at
+a minimum, kitty version, OS and OS version, kitty config (ideally a minimal
+config to reproduce the issue with).
+
+
+### Contributing code
+
+Install [the dependencies](https://sw.kovidgoyal.net/kitty/build.html#dependencies)
+using your favorite package manager. Build and run kitty [from
+source](https://sw.kovidgoyal.net/kitty/build.html#install-and-run-from-source).
+
+Make a fork, submit your Pull Request. If it's a large/controversial change, open an issue
+beforehand to discuss it, so that you don't waste your time making a pull
+request that gets rejected.
+
+If the code you are submitting is reasonably easily testable, please contribute
+tests as well (see the `kitty_tests/` sub-directory for existing tests, which
+can be run with `./test.py`).
+
+That's it.

INSTALL.md

@@ -0,0 +1,3 @@
+To build from source: <https://sw.kovidgoyal.net/kitty/build.html>
+
+Pre-built binaries: <https://sw.kovidgoyal.net/kitty/binary.html>

LICENSE

@@ -1,7 +1,7 @@
                     GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
@@ -645,7 +645,7 @@ the "copyright" line and a pointer to where the full notice is found.
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Also add information on how to contact you by electronic and paper mail.
 
@@ -664,11 +664,11 @@ might be different; for a GUI interface, you would use an "about box".
   You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU GPL, see
-<http://www.gnu.org/licenses/>.
+<https://www.gnu.org/licenses/>.
 
   The GNU General Public License does not permit incorporating your program
 into proprietary programs.  If your program is a subroutine library, you
 may consider it more useful to permit linking proprietary applications with
 the library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.  But first, please read
-<http://www.gnu.org/philosophy/why-not-lgpl.html>.
+<https://www.gnu.org/philosophy/why-not-lgpl.html>.

Makefile

@@ -1,5 +1,43 @@
+ifdef V
+	VVAL=--verbose
+endif
+ifdef VERBOSE
+	VVAL=--verbose
+endif
+
 all:
-	python3 setup.py
+	python3 setup.py $(VVAL)
 
 test:
-	python3 setup.py test
+	python3 setup.py $(VVAL) test
+
+clean:
+	python3 setup.py $(VVAL) clean
+
+# A debug build
+debug:
+	python3 setup.py build $(VVAL) --debug
+
+debug-event-loop:
+	python3 setup.py build $(VVAL) --debug --extra-logging=event-loop
+
+# Build with the ASAN and UBSAN sanitizers
+asan:
+	python3 setup.py build $(VVAL) --debug --sanitize
+
+profile:
+	python3 setup.py build $(VVAL) --profile
+
+app:
+	python3 setup.py kitty.app $(VVAL)
+
+man:
+	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs man
+
+html:
+	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs html
+
+linkcheck:
+	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs linkcheck
+
+docs: man html

README.asciidoc

@@ -1,326 +1,5 @@
-= kitty - A terminal emulator
-:toc:
-:toc-placement!:
-// START_SHORTCUT_BLOCK
-:sc_close_tab: pass:quotes[`ctrl+shift+q`]
-:sc_close_window: pass:quotes[`ctrl+shift+w`]
-:sc_copy_to_clipboard: pass:quotes[`ctrl+shift+c`]
-:sc_eighth_window: pass:quotes[`ctrl+shift+8`]
-:sc_fifth_window: pass:quotes[`ctrl+shift+5`]
-:sc_first_window: pass:quotes[`ctrl+shift+1`]
-:sc_fourth_window: pass:quotes[`ctrl+shift+4`]
-:sc_move_tab_backward: pass:quotes[`ctrl+shift+,`]
-:sc_move_tab_forward: pass:quotes[`ctrl+shift+.`]
-:sc_move_window_backward: pass:quotes[`ctrl+shift+b`]
-:sc_move_window_forward: pass:quotes[`ctrl+shift+f`]
-:sc_move_window_to_top: pass:quotes[`ctrl+shift+``]
-:sc_new_tab: pass:quotes[`ctrl+shift+t`]
-:sc_new_window: pass:quotes[`ctrl+shift+enter`]
-:sc_next_layout: pass:quotes[`ctrl+shift+l`]
-:sc_next_tab: pass:quotes[`ctrl+shift+right`]
-:sc_next_window: pass:quotes[`ctrl+shift+]`]
-:sc_ninth_window: pass:quotes[`ctrl+shift+9`]
-:sc_paste_from_clipboard: pass:quotes[`ctrl+shift+v`]
-:sc_paste_from_selection: pass:quotes[`ctrl+shift+s` or `shift+insert`]
-:sc_previous_tab: pass:quotes[`ctrl+shift+left`]
-:sc_previous_window: pass:quotes[`ctrl+shift+[`]
-:sc_scroll_end: pass:quotes[`ctrl+shift+end`]
-:sc_scroll_home: pass:quotes[`ctrl+shift+home`]
-:sc_scroll_line_down: pass:quotes[`ctrl+shift+down` or `ctrl+shift+j`]
-:sc_scroll_line_up: pass:quotes[`ctrl+shift+up` or `ctrl+shift+k`]
-:sc_scroll_page_down: pass:quotes[`ctrl+shift+page_down`]
-:sc_scroll_page_up: pass:quotes[`ctrl+shift+page_up`]
-:sc_second_window: pass:quotes[`ctrl+shift+2`]
-:sc_seventh_window: pass:quotes[`ctrl+shift+7`]
-:sc_show_scrollback: pass:quotes[`ctrl+shift+h`]
-:sc_sixth_window: pass:quotes[`ctrl+shift+6`]
-:sc_tenth_window: pass:quotes[`ctrl+shift+0`]
-:sc_third_window: pass:quotes[`ctrl+shift+3`]
-// END_SHORTCUT_BLOCK
+= kitty - the fast, featureful, GPU based, terminal emulator
 
-++++
-<img align="left" role="left" src="logo/kitty.png?raw=true"/>
-++++
-image::https://travis-ci.org/kovidgoyal/kitty.svg?branch=master[Build status, link=https://travis-ci.org/kovidgoyal/kitty]
+See https://sw.kovidgoyal.net/kitty/
 
-== Major Features
-
-* Supports tiling multiple terminal windows side by side in different
-layouts without needing to use an extra program like tmux
-
-* Supports all modern terminal features: unicode, true-color, mouse
-protocol, focus tracking, bracketed paste and so on.
-
-* Allows you to view the scrollback buffer in a separate window
-using your favorite pager program such as less
-
-* Support startup sessions which allow you to specify the window/tab layout,
-working directories and programs to run on startup.
-
-* Easily hackable (UI layer written in python, inner loops in C for
-speed). Less than ten thousand lines of code.
-
-* Uses OpenGL for rendering, offloads rendering work to the GPU for lower system load.
-
-* Cross-platform support: kitty currently works on Linux and macOS, but because it
-uses only OpenGL for rendering, it should be trivial to port to
-other platforms. 
-
-image::screenshot.png?raw=true[Screenshot, showing three programs in the "Tall" layout]
-
-toc::[]
-
-
-== Installation
-
-kitty is designed to run from source, for easy hackability. Make sure
-the following dependencies are installed first.
-
-=== Dependencies
-
-* python >= 3.5
-* glfw   >= 3.2
-* glew   >= 2.0 (not needed on macOS)
-* fontconfig (not needed on macOS)
-* xdpyinfo and xsel (only on X11 based systems)
-* gcc or clang (required only for building)
-* pkg-config (required only for building)
-
-=== Install and run from source
-
-....
-git clone https://github.com/kovidgoyal/kitty && cd kitty
-....
-
-Now build the C parts of kitty with the following command:
-
-....
-python3 setup.py build
-....
-
-You can run kitty, as:
-
-....
-python3 /path/to/kitty/folder
-....
-
-=== Linux packages
-
-* Arch linux: AUR git package https://aur.archlinux.org/packages/kitty-git/
-
-
-=== macOS packages
-
-kitty is available as a macOS `dmg` file for easy installation from the
-link:../../releases[releases page].  You can also run kitty directly from
-source using the above install from source instructions, after installing its
-two dependencies (`python >= 3.5` and `glfw >= 3.2` using http://brew.sh/[brew]
-or a similar package manager)
-
-
-== Design philosophy
-
-kitty is designed for power keyboard users. To that end all its controls
-work with the keyboard (although it fully supports mouse interactions as
-well). It's configuration is a simple, human editable, single file for
-easy reproducability (I like to store config files in source control).
-
-The code in kitty is designed to be simple, modular and hackable. It is
-written in a mix of C (for performance sensitive parts) and Python (for
-easy hackability of the UI). It does not depend on any large and complex
-UI toolkit, using only OpenGL for rendering everything.
-
-Finally, kitty is designed from the ground up to support all modern
-terminal features, such as unicode, true color, bold/italic fonts, text
-formatting, etc. It even extends existing text formatting escape codes,
-to add support for features not available elsewhere, such as colored and
-styled (curly) underlines. One of the design goals of kitty is to be
-easily extensible so that new features can be added in the future with
-relatively less effort.
-
-== Tabs and Windows
-
-kitty is capable of running multiple programs organized into tabs and
-windows. The top level of organization is the _Tab_. Each tab consists
-of one or more _windows_. The windows can be arranged in multiple
-different layouts, like windows are organized in a tiling window
-manager. The keyboard controls (which are all customizable) for tabs and
-windows are:
-
-[[scrolling-shortcuts]]
-[options="header"]
-
-=== Scrolling
-
-|===
-|Action |Shortcut
-
-|Scroll line up   | {sc_scroll_line_up}
-|Scroll line down | {sc_scroll_line_down}
-|Scroll page up   | {sc_scroll_page_up}
-|Scroll page down | {sc_scroll_page_down}
-|Scroll to top    | {sc_scroll_home}
-|Scroll to bottom | {sc_scroll_end}
-
-|===
-
-[options="header"]
-
-=== Tabs
-
-|===
-|Action |Shortcut
-
-|New tab   | {sc_new_tab}
-|Close tab | {sc_close_tab}
-|Next tab  | {sc_next_tab}
-|Previous tab | {sc_previous_tab}
-|Next layout | {sc_next_layout}
-|Move tab forward | {sc_move_tab_forward}
-|Move tab backward | {sc_move_tab_backward}
-
-|===
-
-
-[options="header"]
-
-=== Windows
-
-|===
-|Action |Shortcut
-
-|New window   | {sc_new_window}
-|Close window | {sc_close_window}
-|Next window  | {sc_next_window}
-|Previous window | {sc_previous_window}
-|Move window forward | {sc_move_window_forward}
-|Move window backward | {sc_move_window_backward}
-|Move window to top | {sc_move_window_to_top}
-|Focus specific window (windows are counted clockwise from the top left corner) | {sc_first_window}, {sc_second_window} ... {sc_tenth_window}
-
-|===
-
-
-== The scrollback buffer
-
-kitty supports scrolling back to view history, just like most terminals. You
-can use either the <<scrolling-shortcuts,keyboard shortcuts>> or the mouse
-scroll wheel to do so.  However, kitty has an extra, neat feature. Sometimes you
-need to explore the scrollback buffer in more detail, maybe search for some
-text or refer to it side-by-side while typing in a follow-up command. kitty
-allows you to do this by pressing the {sc_show_scrollback} key-combination,
-which will open the scrollback buffer in a new window, using your favorite
-pager program (which is `less` by default). You can then explore the scrollback
-buffer using whatever program you normally use. Colors and text formatting are
-preserved.
-
-
-== Miscellaneous features
-
-You can double click to select a word and triple click to select a line. You can also
-hold down `ctrl+shift` and click on a URL to open it in a browser.
-
-
-== Layouts
-
-Currently, there are two layouts available,
-
-* Stack -- Only a single maximized window is shown at a time
-* Tall -- One window is shown full height on the left, the rest of the windows are shown one below the other on the right.
-
-You can switch between layouts using the {sc_next_layout} key combination.
-
-Writing a new layout only requires about thirty lines of code, so if there is
-some layout you want, take a look at link:kitty/layout.py[layout.py] and submit
-a pull request!
-
-
-== Configuration
-
-kitty is highly customizable, everything from keyboard shortcuts, to
-painting frames-per-second. See the heavily commented
-link:kitty/kitty.conf[default config file]. By default kitty looks for a
-config file in the OS config directory (usually
-`~/.config/kitty/kitty.conf` on Linux and
-`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a specific
-path via the `--config` option.
-
-== Startup Sessions
-
-You can control the tabs, window layout, working directory, startup
-programs, etc. by creating a "session" file and using the `--session`
-command line flag. For example:
-
-....
-# Set the window layout for the current tab
-layout tall
-# Set the working directory for the current tab
-cd ~
-# Create a window and run the specified command in it
-launch zsh
-launch vim
-launch irssi --profile x
-
-# Create a new tab (the part after new_tab is the optional tab name which will
-# be displayed in the tab bar, if omitted, the title of the active window will
-# be used instead)
-new_tab my tab
-cd ~/somewhere
-# Set the layouts allowed in this tab
-enabled_layouts tall, stack
-# Set the current layout
-layout stack
-launch zsh
-# Make the current window the active (focused) window
-focus
-launch emacs
-....
-
-== Protocol Extensions
-
-kitty has a few extensions to the xterm protocol, to enable advanced features,
-see link:protocol-extensions.asciidoc[Protocol Extensions].
-
-
-== Font control
-
-kitty has extremely flexible and powerful font selection features. You can
-specify individual families for the regular, bold, italic and bold+italic
-fonts. You can even specify specific font families for specific ranges of
-unicode characters. This allows precise control over text rendering. It can
-come in handy for applications like powerline, without the need to use patched
-fonts. See the various font related configuration directives in the
-link:kitty/kitty.conf[config file].
-
-== Note for Linux/macOS packagers
-
-While kitty does use python, it is not a traditional python package, so please do not install it in site-packages.
-Instead run,
-
-```
-python3 setup.py linux-package
-```
-
-This will install kitty into the directory `linux-package`. You can run kitty
-with `linux-package/bin/kitty`.  All the files needed to run kitty will be in
-`linux-package/lib/kitty`. The terminfo file will be installed into
-`linux-package/share/terminfo`. Simply copy these files into `/usr` to install
-kitty. In other words, `linux-package` is the staging area into which kitty is
-installed. You can choose a different staging area, by passing the `--prefix`
-argument to `setup.py`.
-
-You should probably split kitty into two packages, `kitty-terminfo` that
-installs the terminfo file and `kitty` that installs the main program.
-This allows users to install the terminfo file on servers into which they ssh,
-without needing to install all of kitty.
-
-This applies to creating packages for kitty for macOS package managers such as
-brew or MacPorts as well.
-
-== Resources on terminal behavior
-
-http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
-
-https://en.wikipedia.org/wiki/C0_and_C1_control_codes
-
-http://vt100.net/
+image:https://github.com/kovidgoyal/kitty/workflows/CI/badge.svg["Build status", link="https://github.com/kovidgoyal/kitty/actions?query=workflow%3ACI"]

__main__.py

@@ -1,7 +1,121 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 # vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2015, Kovid Goyal <kovid at kovidgoyal.net>
 
+import sys
+import os
+from typing import List
 
-from kitty.main import main
-main()
+
+def icat(args: List[str]) -> None:
+    from kittens.runner import run_kitten as rk
+    sys.argv = args
+    rk('icat')
+
+
+def list_fonts(args: List[str]) -> None:
+    from kitty.fonts.list import main as list_main
+    list_main(args)
+
+
+def remote_control(args: List[str]) -> None:
+    from kitty.remote_control import main as rc_main
+    rc_main(args)
+
+
+def runpy(args: List[str]) -> None:
+    sys.argv = ['kitty'] + args[2:]
+    exec(args[1])
+
+
+def hold(args: List[str]) -> None:
+    import subprocess
+    ret = subprocess.Popen(args[1:]).wait()
+    sys.stdin.read()
+    raise SystemExit(ret)
+
+
+def complete(args: List[str]) -> None:
+    from kitty.complete import main as complete_main
+    complete_main(args[1:], entry_points, namespaced_entry_points)
+
+
+def launch(args: List[str]) -> None:
+    import runpy
+    sys.argv = args[1:]
+    exe = args[1]
+    if exe.startswith(':'):
+        import shutil
+        q = shutil.which(exe[1:])
+        if not q:
+            raise SystemExit('{} not found in PATH'.format(args[1][1:]))
+        exe = q
+    runpy.run_path(exe, run_name='__main__')
+
+
+def run_kitten(args: List[str]) -> None:
+    try:
+        kitten = args[1]
+    except IndexError:
+        from kittens.runner import list_kittens
+        list_kittens()
+        raise SystemExit(1)
+    sys.argv = args[1:]
+    from kittens.runner import run_kitten as rk
+    rk(kitten)
+
+
+def namespaced(args: List[str]) -> None:
+    func = namespaced_entry_points[args[1]]
+    func(args[1:])
+
+
+entry_points = {
+    # These two are here for backwards compat
+    'icat': icat,
+    'list-fonts': list_fonts,
+    'runpy': runpy,
+    'launch': launch,
+    'kitten': run_kitten,
+
+    '@': remote_control,
+    '+': namespaced,
+}
+namespaced_entry_points = {k: v for k, v in entry_points.items() if k[0] not in '+@'}
+namespaced_entry_points['hold'] = hold
+namespaced_entry_points['complete'] = complete
+
+
+def setup_openssl_environment() -> None:
+    # Workaround for Linux distros that have still failed to get their heads
+    # out of their asses and implement a common location for SSL certificates.
+    # It's not that hard people, there exists a wonderful tool called the symlink
+    # See https://www.mobileread.com/forums/showthread.php?t=256095
+    if 'SSL_CERT_FILE' not in os.environ and 'SSL_CERT_DIR' not in os.environ:
+        if os.access('/etc/pki/tls/certs/ca-bundle.crt', os.R_OK):
+            os.environ['SSL_CERT_FILE'] = '/etc/pki/tls/certs/ca-bundle.crt'
+            setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_FILE')
+        elif os.path.isdir('/etc/ssl/certs'):
+            os.environ['SSL_CERT_DIR'] = '/etc/ssl/certs'
+            setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_DIR')
+
+
+def main() -> None:
+    if getattr(sys, 'frozen', False) and 'darwin' not in sys.platform.lower():
+        setup_openssl_environment()
+    first_arg = '' if len(sys.argv) < 2 else sys.argv[1]
+    func = entry_points.get(first_arg)
+    if func is None:
+        if first_arg.startswith('@'):
+            remote_control(['@', first_arg[1:]] + sys.argv[2:])
+        elif first_arg.startswith('+'):
+            namespaced(['+', first_arg[1:]] + sys.argv[2:])
+        else:
+            from kitty.main import main as kitty_main
+            kitty_main()
+    else:
+        func(sys.argv[1:])
+
+
+if __name__ == '__main__':
+    main()

build-terminfo

@@ -1,24 +1,48 @@
 #!/usr/bin/env python3
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2019, Kovid Goyal <kovid at kovidgoyal.net>
 
+import glob
 import os
-import sys
+import re
 import shutil
 import subprocess
+import sys
+import tempfile
 
-base = os.path.dirname(os.path.abspath(__file__))
-os.chdir(base)
-sys.path.insert(0, base)
 
-from kitty.terminfo import generate_terminfo  # noqa
+def compile_terminfo(base):
+    with tempfile.TemporaryDirectory() as tdir:
+        proc = subprocess.run(['tic', '-x', '-o' + tdir, 'terminfo/kitty.terminfo'], check=True, stderr=subprocess.PIPE)
+        regex = '^"terminfo/kitty.terminfo", line [0-9]+, col [0-9]+, terminal \'xterm-kitty\': older tic versions may treat the description field as an alias$'
+        for error in proc.stderr.decode('utf-8').splitlines():
+            if not re.match(regex, error):
+                print(error, file=sys.stderr)
+        tfiles = glob.glob(os.path.join(tdir, '*', 'xterm-kitty'))
+        if not tfiles:
+            raise SystemExit('tic failed to output the compiled kitty terminfo file')
 
-with open('terminfo/kitty.terminfo', 'w') as f:
-    f.write(generate_terminfo())
+        tfile = tfiles[0]
+        directory, xterm_kitty = os.path.split(tfile)
+        _, directory = os.path.split(directory)
+        odir = os.path.join(base, directory)
+        os.makedirs(odir, exist_ok=True)
+        ofile = os.path.join(odir, xterm_kitty)
+        shutil.move(tfile, ofile)
 
-os.environ['TERMINFO'] = os.path.join(base, 'terminfo')
-subprocess.check_call(['tic', 'terminfo/kitty.terminfo'])
-# On OS X tic puts the compiled database into a different directory
-try:
-    os.mkdir('terminfo/78')
-except FileExistsError:
-    pass
-shutil.copy2('terminfo/x/xterm-kitty', 'terminfo/78')
+
+def generate_terminfo():
+    base = os.path.dirname(os.path.abspath(__file__))
+    os.chdir(base)
+    sys.path.insert(0, base)
+
+    from kitty.terminfo import generate_terminfo
+
+    with open('terminfo/kitty.terminfo', 'w') as f:
+        f.write(generate_terminfo())
+
+    compile_terminfo(os.path.join(base, 'terminfo'))
+
+
+if __name__ == '__main__':
+    generate_terminfo()

bypy/init_env.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPLv3 Copyright: 2020, Kovid Goyal <kovid at kovidgoyal.net>
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from contextlib import suppress
+
+from bypy.constants import (
+    LIBDIR, PREFIX, PYTHON, SRC as KITTY_DIR, ismacos, worker_env
+)
+from bypy.utils import run_shell
+
+
+def read_src_file(name):
+    with open(os.path.join(KITTY_DIR, 'kitty', name), 'rb') as f:
+        return f.read().decode('utf-8')
+
+
+def initialize_constants():
+    kitty_constants = {}
+    src = read_src_file('constants.py')
+    nv = re.search(r'Version\((\d+), (\d+), (\d+)\)', src)
+    kitty_constants['version'] = '%s.%s.%s' % (nv.group(1), nv.group(2), nv.group(3))
+    kitty_constants['appname'] = re.search(
+            r'appname: str\s+=\s+(u{0,1})[\'"]([^\'"]+)[\'"]', src
+    ).group(2)
+    return kitty_constants
+
+
+def run(*args, **extra_env):
+    env = os.environ.copy()
+    env.update(worker_env)
+    env.update(extra_env)
+    env['SW'] = PREFIX
+    env['LD_LIBRARY_PATH'] = LIBDIR
+    if ismacos:
+        env['PKGCONFIG_EXE'] = os.path.join(PREFIX, 'bin', 'pkg-config')
+    cwd = env.pop('cwd', KITTY_DIR)
+    return subprocess.call(list(args), env=env, cwd=cwd)
+
+
+def build_c_extensions(ext_dir, args):
+    writeable_src_dir = os.path.join(ext_dir, 'src')
+    shutil.copytree(
+        KITTY_DIR, writeable_src_dir, symlinks=True,
+        ignore=shutil.ignore_patterns('b', 'build', 'dist', '*_commands.json', '*.o'))
+
+    # Build the launcher as it is needed for the spawn test
+    with suppress(FileNotFoundError):
+        os.remove(os.path.join(writeable_src_dir, 'kitty', 'launcher', 'kitty'))
+    if run(PYTHON, 'setup.py', 'build-launcher', cwd=writeable_src_dir) != 0:
+        print('Building of kitty launcher failed', file=sys.stderr)
+        os.chdir(KITTY_DIR)
+        run_shell()
+        raise SystemExit('Building of kitty launcher failed')
+
+    cmd = [PYTHON, 'setup.py']
+    bundle = 'macos-freeze' if ismacos else 'linux-freeze'
+    cmd.append(bundle)
+    dest = kitty_constants['appname'] + ('.app' if ismacos else '')
+    dest = os.path.join(ext_dir, dest)
+    cmd += ['--prefix', dest]
+    if run(*cmd, cwd=writeable_src_dir) != 0:
+        print('Building of kitty package failed', file=sys.stderr)
+        os.chdir(KITTY_DIR)
+        run_shell()
+        raise SystemExit('Building of kitty package failed')
+    return ext_dir
+
+
+def run_tests(path_to_kitty, cwd_on_failure):
+    kw = {'cwd': cwd_on_failure}
+    if not ismacos:
+        # this is needed for the spawn test which starts an interpreter
+        # using the kitty launcher.
+        kw['PYTHONHOME'] = PREFIX
+    ret = run(PYTHON, 'test.py', **kw)
+    if ret != 0:
+        os.chdir(cwd_on_failure)
+        print(
+            'running kitty tests failed with return code:', ret, file=sys.stderr)
+        run_shell()
+        raise SystemExit('running kitty tests failed')
+
+
+if __name__ == 'program':
+    kitty_constants = initialize_constants()

bypy/linux.conf

@@ -0,0 +1,3 @@
+image 'https://partner-images.canonical.com/core/xenial/current/ubuntu-xenial-core-cloudimg-{}-root.tar.gz'
+
+deps 'bison flex libxcursor-dev libxrandr-dev libxi-dev libxinerama-dev libgl1-mesa-dev libxcb-xkb-dev libfontconfig1-dev libdbus-1-dev'

bypy/linux/__main__.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPLv3 Copyright: 2020, Kovid Goyal <kovid at kovidgoyal.net>
+
+import errno
+import os
+import shutil
+import stat
+import subprocess
+import tarfile
+import time
+
+from bypy.constants import (
+    OUTPUT_DIR, PREFIX, is64bit, python_major_minor_version
+)
+from bypy.utils import get_dll_path, py_compile, walk
+
+j = os.path.join
+self_dir = os.path.dirname(os.path.abspath(__file__))
+arch = 'x86_64' if is64bit else 'i686'
+
+py_ver = '.'.join(map(str, python_major_minor_version()))
+iv = globals()['init_env']
+kitty_constants = iv['kitty_constants']
+
+
+def binary_includes():
+    return tuple(map(get_dll_path, (
+            'expat', 'sqlite3', 'ffi', 'z', 'lzma', 'png16', 'lcms2',
+
+            # dont include freetype because fontconfig is closely coupled to it
+            # and also distros often patch freetype
+            # 'iconv.so.2', 'pcre.so.1', 'graphite2.so.3', 'glib-2.0.so.0', 'freetype.so.6',
+
+            'harfbuzz', 'xkbcommon', 'xkbcommon-x11',
+            'ncursesw', 'readline',
+        ))) + (
+                get_dll_path('bz2', 2), get_dll_path('ssl', 2), get_dll_path('crypto', 2),
+                get_dll_path('python' + py_ver, 2),
+        )
+
+
+class Env:
+
+    def __init__(self, package_dir):
+        self.base = package_dir
+        self.lib_dir = j(self.base, 'lib')
+        self.py_dir = j(self.lib_dir, 'python' + py_ver)
+        os.makedirs(self.py_dir)
+        self.bin_dir = j(self.base, 'bin')
+
+
+def ignore_in_lib(base, items, ignored_dirs=None):
+    ans = []
+    if ignored_dirs is None:
+        ignored_dirs = {'.svn', '.bzr', '.git', 'test', 'tests', 'testing'}
+    for name in items:
+        path = j(base, name)
+        if os.path.isdir(path):
+            if name in ignored_dirs or not os.path.exists(j(path, '__init__.py')):
+                if name != 'plugins':
+                    ans.append(name)
+        else:
+            if name.rpartition('.')[-1] not in ('so', 'py'):
+                ans.append(name)
+    return ans
+
+
+def import_site_packages(srcdir, dest):
+    if not os.path.exists(dest):
+        os.mkdir(dest)
+    for x in os.listdir(srcdir):
+        ext = x.rpartition('.')[-1]
+        f = j(srcdir, x)
+        if ext in ('py', 'so'):
+            shutil.copy2(f, dest)
+        elif ext == 'pth' and x != 'setuptools.pth':
+            for line in open(f, 'rb').read().splitlines():
+                src = os.path.abspath(j(srcdir, line))
+                if os.path.exists(src) and os.path.isdir(src):
+                    import_site_packages(src, dest)
+        elif os.path.exists(j(f, '__init__.py')):
+            shutil.copytree(f, j(dest, x), ignore=ignore_in_lib)
+
+
+def copy_libs(env):
+    print('Copying libs...')
+
+    for x in binary_includes():
+        dest = env.bin_dir if '/bin/' in x else env.lib_dir
+        shutil.copy2(x, dest)
+
+
+def copy_python(env):
+    print('Copying python...')
+    srcdir = j(PREFIX, 'lib/python' + py_ver)
+
+    for x in os.listdir(srcdir):
+        y = j(srcdir, x)
+        ext = os.path.splitext(x)[1]
+        if os.path.isdir(y) and x not in ('test', 'hotshot', 'distutils', 'tkinter', 'turtledemo',
+                                          'site-packages', 'idlelib', 'lib2to3', 'dist-packages'):
+            shutil.copytree(y, j(env.py_dir, x), ignore=ignore_in_lib)
+        if os.path.isfile(y) and ext in ('.py', '.so'):
+            shutil.copy2(y, env.py_dir)
+
+    srcdir = j(srcdir, 'site-packages')
+    dest = j(env.py_dir, 'site-packages')
+    import_site_packages(srcdir, dest)
+    py_compile(env.py_dir)
+    py_compile(os.path.join(env.base, 'lib', 'kitty'))
+
+
+def is_elf(path):
+    with open(path, 'rb') as f:
+        return f.read(4) == b'\x7fELF'
+
+
+def fix_permissions(files):
+    for path in files:
+        os.chmod(path, 0o755)
+
+
+STRIPCMD = ['strip']
+
+
+def find_binaries(env):
+    files = {j(env.bin_dir, x) for x in os.listdir(env.bin_dir)} | {
+        x for x in {
+            j(os.path.dirname(env.bin_dir), x) for x in os.listdir(env.bin_dir)} if os.path.exists(x)}
+    for x in walk(env.lib_dir):
+        x = os.path.realpath(x)
+        if x not in files and is_elf(x):
+            files.add(x)
+    return files
+
+
+def strip_files(files, argv_max=(256 * 1024)):
+    """ Strip a list of files """
+    while files:
+        cmd = list(STRIPCMD)
+        pathlen = sum(len(s) + 1 for s in cmd)
+        while pathlen < argv_max and files:
+            f = files.pop()
+            cmd.append(f)
+            pathlen += len(f) + 1
+        if len(cmd) > len(STRIPCMD):
+            all_files = cmd[len(STRIPCMD):]
+            unwritable_files = tuple(filter(None, (None if os.access(x, os.W_OK) else (x, os.stat(x).st_mode) for x in all_files)))
+            [os.chmod(x, stat.S_IWRITE | old_mode) for x, old_mode in unwritable_files]
+            subprocess.check_call(cmd)
+            [os.chmod(x, old_mode) for x, old_mode in unwritable_files]
+
+
+def strip_binaries(files):
+    print('Stripping %d files...' % len(files))
+    before = sum(os.path.getsize(x) for x in files)
+    strip_files(files)
+    after = sum(os.path.getsize(x) for x in files)
+    print('Stripped %.1f MB' % ((before - after) / (1024 * 1024.)))
+
+
+def create_tarfile(env, compression_level='9'):
+    print('Creating archive...')
+    base = OUTPUT_DIR
+    try:
+        shutil.rmtree(base)
+    except OSError as err:
+        if err.errno != errno.ENOENT:
+            raise
+    os.mkdir(base)
+    dist = os.path.join(base, '%s-%s-%s.tar' % (kitty_constants['appname'], kitty_constants['version'], arch))
+    with tarfile.open(dist, mode='w', format=tarfile.PAX_FORMAT) as tf:
+        cwd = os.getcwd()
+        os.chdir(env.base)
+        try:
+            for x in os.listdir('.'):
+                tf.add(x)
+        finally:
+            os.chdir(cwd)
+    print('Compressing archive...')
+    ans = dist.rpartition('.')[0] + '.txz'
+    start_time = time.time()
+    subprocess.check_call(['xz', '--threads=0', '-f', '-' + compression_level, dist])
+    secs = time.time() - start_time
+    print('Compressed in %d minutes %d seconds' % (secs // 60, secs % 60))
+    os.rename(dist + '.xz', ans)
+    print('Archive %s created: %.2f MB' % (
+        os.path.basename(ans), os.stat(ans).st_size / (1024.**2)))
+
+
+def main():
+    args = globals()['args']
+    ext_dir = globals()['ext_dir']
+    if not args.skip_tests:
+        run_tests = iv['run_tests']
+        run_tests(None, os.path.join(ext_dir, 'src'))
+    env = Env(os.path.join(ext_dir, kitty_constants['appname']))
+    copy_libs(env)
+    copy_python(env)
+    files = find_binaries(env)
+    fix_permissions(files)
+    if not args.dont_strip:
+        strip_binaries(files)
+    create_tarfile(env, args.compression_level)
+
+
+if __name__ == '__main__':
+    main()

bypy/macos.conf

@@ -0,0 +1,6 @@
+# Requires installation of XCode 10.3 and Python 3 and
+# python3 -m pip install certifi
+
+vm_name 'macos-kitty-build'
+root '/Users/Shared/kitty-build'
+python '/usr/local/bin/python3'

bypy/macos/__main__.py

@@ -0,0 +1,460 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPLv3 Copyright: 2020, Kovid Goyal <kovid at kovidgoyal.net>
+
+import glob
+import json
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import zipfile
+
+from bypy.constants import PREFIX, PYTHON, SW, python_major_minor_version
+from bypy.macos_sign import (
+    codesign, create_entitlements_file, make_certificate_useable, notarize_app,
+    verify_signature
+)
+from bypy.utils import current_dir, py_compile, run_shell, timeit, walk
+
+iv = globals()['init_env']
+kitty_constants = iv['kitty_constants']
+join = os.path.join
+basename = os.path.basename
+abspath = os.path.abspath
+APPNAME = kitty_constants['appname']
+VERSION = kitty_constants['version']
+py_ver = '.'.join(map(str, python_major_minor_version()))
+
+
+def flush(func):
+    def ff(*args, **kwargs):
+        sys.stdout.flush()
+        sys.stderr.flush()
+        ret = func(*args, **kwargs)
+        sys.stdout.flush()
+        sys.stderr.flush()
+        return ret
+
+    return ff
+
+
+def flipwritable(fn, mode=None):
+    """
+    Flip the writability of a file and return the old mode. Returns None
+    if the file is already writable.
+    """
+    if os.access(fn, os.W_OK):
+        return None
+    old_mode = os.stat(fn).st_mode
+    os.chmod(fn, stat.S_IWRITE | old_mode)
+    return old_mode
+
+
+STRIPCMD = ('/usr/bin/strip', '-x', '-S', '-')
+
+
+def strip_files(files, argv_max=(256 * 1024)):
+    """
+    Strip a list of files
+    """
+    tostrip = [(fn, flipwritable(fn)) for fn in files if os.path.exists(fn)]
+    while tostrip:
+        cmd = list(STRIPCMD)
+        flips = []
+        pathlen = sum(len(s) + 1 for s in cmd)
+        while pathlen < argv_max:
+            if not tostrip:
+                break
+            added, flip = tostrip.pop()
+            pathlen += len(added) + 1
+            cmd.append(added)
+            flips.append((added, flip))
+        else:
+            cmd.pop()
+            tostrip.append(flips.pop())
+        os.spawnv(os.P_WAIT, cmd[0], cmd)
+        for args in flips:
+            flipwritable(*args)
+
+
+def files_in(folder):
+    for record in os.walk(folder):
+        for f in record[-1]:
+            yield os.path.join(record[0], f)
+
+
+def expand_dirs(items, exclude=lambda x: x.endswith('.so')):
+    items = set(items)
+    dirs = set(x for x in items if os.path.isdir(x))
+    items.difference_update(dirs)
+    for x in dirs:
+        items.update({y for y in files_in(x) if not exclude(y)})
+    return items
+
+
+def do_sign(app_dir):
+    with current_dir(os.path.join(app_dir, 'Contents')):
+        # Sign all .so files
+        so_files = {x for x in files_in('.') if x.endswith('.so')}
+        codesign(so_files)
+        # Sign everything else in Frameworks
+        with current_dir('Frameworks'):
+            fw = set(glob.glob('*.framework'))
+            codesign(fw)
+            items = set(os.listdir('.')) - fw
+            codesign(expand_dirs(items))
+
+    # Now sign the main app
+    codesign(app_dir)
+    verify_signature(app_dir)
+
+
+def sign_app(app_dir, notarize):
+    # Copied from iTerm2: https://github.com/gnachman/iTerm2/blob/master/iTerm2.entitlements
+    create_entitlements_file({
+        'com.apple.security.automation.apple-events': True,
+        'com.apple.security.cs.allow-jit': True,
+        'com.apple.security.device.audio-input': True,
+        'com.apple.security.device.camera': True,
+        'com.apple.security.personal-information.addressbook': True,
+        'com.apple.security.personal-information.calendars': True,
+        'com.apple.security.personal-information.location': True,
+        'com.apple.security.personal-information.photos-library': True,
+    })
+    with make_certificate_useable():
+        do_sign(app_dir)
+        if notarize:
+            notarize_app(app_dir)
+
+
+class Freeze(object):
+
+    FID = '@executable_path/../Frameworks'
+
+    def __init__(self, build_dir, dont_strip=False, sign_installers=False, notarize=False):
+        self.build_dir = build_dir
+        self.sign_installers = sign_installers
+        self.notarize = notarize
+        self.dont_strip = dont_strip
+        self.contents_dir = join(self.build_dir, 'Contents')
+        self.resources_dir = join(self.contents_dir, 'Resources')
+        self.frameworks_dir = join(self.contents_dir, 'Frameworks')
+        self.to_strip = []
+        self.warnings = []
+        self.py_ver = py_ver
+        self.python_stdlib = join(self.resources_dir, 'Python', 'lib', 'python' + self.py_ver)
+        self.site_packages = self.python_stdlib  # hack to avoid needing to add site-packages to path
+
+        self.run()
+
+    def run_shell(self):
+        with current_dir(self.contents_dir):
+            run_shell()
+
+    def run(self):
+        ret = 0
+        self.add_python_framework()
+        self.add_site_packages()
+        self.add_stdlib()
+        self.add_misc_libraries()
+        self.compile_py_modules()
+        self.fix_dependencies_in_kitty()
+        if not self.dont_strip:
+            self.strip_files()
+        # self.run_shell()
+
+        ret = self.makedmg(self.build_dir, APPNAME + '-' + VERSION)
+
+        return ret
+
+    @flush
+    def strip_files(self):
+        print('\nStripping files...')
+        strip_files(self.to_strip)
+
+    @flush
+    def set_id(self, path_to_lib, new_id):
+        old_mode = flipwritable(path_to_lib)
+        subprocess.check_call(
+            ['install_name_tool', '-id', new_id, path_to_lib])
+        if old_mode is not None:
+            flipwritable(path_to_lib, old_mode)
+
+    @flush
+    def get_dependencies(self, path_to_lib):
+        install_name = subprocess.check_output(
+            ['otool', '-D', path_to_lib]).decode('utf-8').splitlines()[-1].strip()
+        raw = subprocess.check_output(['otool', '-L', path_to_lib]).decode('utf-8')
+        for line in raw.splitlines():
+            if 'compatibility' not in line or line.strip().endswith(':'):
+                continue
+            idx = line.find('(')
+            path = line[:idx].strip()
+            yield path, path == install_name
+
+    @flush
+    def get_local_dependencies(self, path_to_lib):
+        for x, is_id in self.get_dependencies(path_to_lib):
+            for y in (PREFIX + '/lib/', PREFIX + '/python/Python.framework/'):
+                if x.startswith(y):
+                    if y == PREFIX + '/python/Python.framework/':
+                        y = PREFIX + '/python/'
+                    yield x, x[len(y):], is_id
+                    break
+
+    @flush
+    def change_dep(self, old_dep, new_dep, is_id, path_to_lib):
+        cmd = ['-id', new_dep] if is_id else ['-change', old_dep, new_dep]
+        subprocess.check_call(['install_name_tool'] + cmd + [path_to_lib])
+
+    @flush
+    def fix_dependencies_in_lib(self, path_to_lib):
+        self.to_strip.append(path_to_lib)
+        old_mode = flipwritable(path_to_lib)
+        for dep, bname, is_id in self.get_local_dependencies(path_to_lib):
+            ndep = self.FID + '/' + bname
+            self.change_dep(dep, ndep, is_id, path_to_lib)
+        ldeps = list(self.get_local_dependencies(path_to_lib))
+        if ldeps:
+            print('\nFailed to fix dependencies in', path_to_lib)
+            print('Remaining local dependencies:', ldeps)
+            raise SystemExit(1)
+        if old_mode is not None:
+            flipwritable(path_to_lib, old_mode)
+
+    @flush
+    def add_python_framework(self):
+        print('\nAdding Python framework')
+        src = join(PREFIX + '/python', 'Python.framework')
+        x = join(self.frameworks_dir, 'Python.framework')
+        curr = os.path.realpath(join(src, 'Versions', 'Current'))
+        currd = join(x, 'Versions', basename(curr))
+        rd = join(currd, 'Resources')
+        os.makedirs(rd)
+        shutil.copy2(join(curr, 'Resources', 'Info.plist'), rd)
+        shutil.copy2(join(curr, 'Python'), currd)
+        self.set_id(
+            join(currd, 'Python'),
+            self.FID + '/Python.framework/Versions/%s/Python' % basename(curr))
+        self.fix_dependencies_in_lib(join(self.contents_dir, 'MacOS', 'kitty'))
+        # The following is needed for codesign
+        with current_dir(x):
+            os.symlink(basename(curr), 'Versions/Current')
+            for y in ('Python', 'Resources'):
+                os.symlink('Versions/Current/%s' % y, y)
+
+    @flush
+    def install_dylib(self, path, set_id=True):
+        shutil.copy2(path, self.frameworks_dir)
+        if set_id:
+            self.set_id(
+                join(self.frameworks_dir, basename(path)),
+                self.FID + '/' + basename(path))
+        self.fix_dependencies_in_lib(join(self.frameworks_dir, basename(path)))
+
+    @flush
+    def add_misc_libraries(self):
+        for x in (
+                'sqlite3.0',
+                'z.1',
+                'harfbuzz.0',
+                'png16.16',
+                'lcms2.2',
+                'crypto.1.1',
+                'ssl.1.1',
+        ):
+            print('\nAdding', x)
+            x = 'lib%s.dylib' % x
+            src = join(PREFIX, 'lib', x)
+            shutil.copy2(src, self.frameworks_dir)
+            dest = join(self.frameworks_dir, x)
+            self.set_id(dest, self.FID + '/' + x)
+            self.fix_dependencies_in_lib(dest)
+        base = join(self.frameworks_dir, 'kitty')
+        for lib in walk(base):
+            if lib.endswith('.so'):
+                self.set_id(lib, self.FID + '/' + os.path.relpath(lib, self.frameworks_dir))
+                self.fix_dependencies_in_lib(lib)
+
+    @flush
+    def add_package_dir(self, x, dest=None):
+        def ignore(root, files):
+            ans = []
+            for y in files:
+                ext = os.path.splitext(y)[1]
+                if ext not in ('', '.py', '.so') or \
+                        (not ext and not os.path.isdir(join(root, y))):
+                    ans.append(y)
+
+            return ans
+
+        if dest is None:
+            dest = self.site_packages
+        dest = join(dest, basename(x))
+        shutil.copytree(x, dest, symlinks=True, ignore=ignore)
+        self.postprocess_package(x, dest)
+        for f in walk(dest):
+            if f.endswith('.so'):
+                self.fix_dependencies_in_lib(f)
+
+    @flush
+    def fix_dependencies_in_kitty(self):
+        for f in walk(join(self.resources_dir, 'kitty')):
+            if f.endswith('.so'):
+                self.fix_dependencies_in_lib(f)
+
+    @flush
+    def postprocess_package(self, src_path, dest_path):
+        pass
+
+    @flush
+    def add_stdlib(self):
+        print('\nAdding python stdlib')
+        src = PREFIX + '/python/Python.framework/Versions/Current/lib/python' + self.py_ver
+        dest = self.python_stdlib
+        if not os.path.exists(dest):
+            os.makedirs(dest)
+        for x in os.listdir(src):
+            if x in ('site-packages', 'config', 'test', 'lib2to3', 'lib-tk',
+                     'lib-old', 'idlelib', 'plat-mac', 'plat-darwin',
+                     'site.py', 'distutils', 'turtledemo', 'tkinter'):
+                continue
+            x = join(src, x)
+            if os.path.isdir(x):
+                self.add_package_dir(x, dest)
+            elif os.path.splitext(x)[1] in ('.so', '.py'):
+                shutil.copy2(x, dest)
+                dest2 = join(dest, basename(x))
+                if dest2.endswith('.so'):
+                    self.fix_dependencies_in_lib(dest2)
+
+    @flush
+    def add_site_packages(self):
+        print('\nAdding site-packages')
+        os.makedirs(self.site_packages)
+        sys_path = json.loads(subprocess.check_output([
+            PYTHON, '-c', 'import sys, json; json.dump(sys.path, sys.stdout)']))
+        paths = reversed(tuple(map(abspath, [x for x in sys_path if x.startswith('/') and not x.startswith('/Library/')])))
+        upaths = []
+        for x in paths:
+            if x not in upaths and (x.endswith('.egg') or x.endswith('/site-packages')):
+                upaths.append(x)
+        for x in upaths:
+            print('\t', x)
+            tdir = None
+            try:
+                if not os.path.isdir(x):
+                    zf = zipfile.ZipFile(x)
+                    tdir = tempfile.mkdtemp()
+                    zf.extractall(tdir)
+                    x = tdir
+                self.add_modules_from_dir(x)
+                self.add_packages_from_dir(x)
+            finally:
+                if tdir is not None:
+                    shutil.rmtree(tdir)
+        self.remove_bytecode(self.site_packages)
+
+    @flush
+    def add_modules_from_dir(self, src):
+        for x in glob.glob(join(src, '*.py')) + glob.glob(join(src, '*.so')):
+            shutil.copy2(x, self.site_packages)
+            if x.endswith('.so'):
+                self.fix_dependencies_in_lib(x)
+
+    @flush
+    def add_packages_from_dir(self, src):
+        for x in os.listdir(src):
+            x = join(src, x)
+            if os.path.isdir(x) and os.path.exists(join(x, '__init__.py')):
+                if self.filter_package(basename(x)):
+                    continue
+                self.add_package_dir(x)
+
+    @flush
+    def filter_package(self, name):
+        return name in ('Cython', 'modulegraph', 'macholib', 'py2app',
+                        'bdist_mpkg', 'altgraph')
+
+    @flush
+    def remove_bytecode(self, dest):
+        for x in os.walk(dest):
+            root = x[0]
+            for f in x[-1]:
+                if os.path.splitext(f) == '.pyc':
+                    os.remove(join(root, f))
+
+    @flush
+    def compile_py_modules(self):
+        print('\nCompiling Python modules')
+        self.remove_bytecode(join(self.resources_dir, 'Python'))
+        py_compile(join(self.resources_dir, 'Python'))
+        self.remove_bytecode(join(self.resources_dir, 'kitty'))
+        py_compile(join(self.resources_dir, 'kitty'))
+
+    @flush
+    def makedmg(self, d, volname, internet_enable=True, format='ULFO'):
+        ''' Copy a directory d into a dmg named volname '''
+        print('\nMaking dmg...')
+        sys.stdout.flush()
+        destdir = os.path.join(SW, 'dist')
+        try:
+            shutil.rmtree(destdir)
+        except FileNotFoundError:
+            pass
+        os.mkdir(destdir)
+        dmg = os.path.join(destdir, volname + '.dmg')
+        if os.path.exists(dmg):
+            os.unlink(dmg)
+        tdir = tempfile.mkdtemp()
+        appdir = os.path.join(tdir, os.path.basename(d))
+        shutil.copytree(d, appdir, symlinks=True)
+        if self.sign_installers:
+            with timeit() as times:
+                sign_app(appdir, self.notarize)
+            print('Signing completed in %d minutes %d seconds' % tuple(times))
+        os.symlink('/Applications', os.path.join(tdir, 'Applications'))
+        size_in_mb = int(
+            subprocess.check_output(['du', '-s', '-k', tdir]).decode('utf-8')
+            .split()[0]) / 1024.
+        cmd = [
+            '/usr/bin/hdiutil', 'create', '-srcfolder', tdir, '-volname',
+            volname, '-format', format
+        ]
+        if 190 < size_in_mb < 250:
+            # We need -size 255m because of a bug in hdiutil. When the size of
+            # srcfolder is close to 200MB hdiutil fails with
+            # diskimages-helper: resize request is above maximum size allowed.
+            cmd += ['-size', '255m']
+        print('\nCreating dmg...')
+        with timeit() as times:
+            subprocess.check_call(cmd + [dmg])
+            if internet_enable:
+                subprocess.check_call(
+                    ['/usr/bin/hdiutil', 'internet-enable', '-yes', dmg])
+        print('dmg created in %d minutes and %d seconds' % tuple(times))
+        shutil.rmtree(tdir)
+        size = os.stat(dmg).st_size / (1024 * 1024.)
+        print('\nInstaller size: %.2fMB\n' % size)
+        return dmg
+
+
+def main():
+    args = globals()['args']
+    ext_dir = globals()['ext_dir']
+    if not args.skip_tests:
+        run_tests = iv['run_tests']
+        run_tests(None, os.path.join(ext_dir, 'src'))
+    Freeze(
+        os.path.join(ext_dir, kitty_constants['appname'] + '.app'),
+        dont_strip=args.dont_strip,
+        sign_installers=args.sign_installers,
+        notarize=args.notarize
+    )
+
+
+if __name__ == '__main__':
+    main()

bypy/rsync.conf

@@ -0,0 +1 @@
+to_vm_excludes '/build /dist /kitty/launcher/kitty /.build-cache /tags __pycache__ /*_commands.json *.so *.pyd *.pyc'

bypy/sources.json

@@ -0,0 +1,264 @@
+[
+    {
+        "name": "zlib",
+        "unix": {
+            "filename": "zlib-1.2.11.tar.xz",
+            "hash": "sha256:4ff941449631ace0d4d203e3483be9dbc9da454084111f97ea0a2114e19bf066",
+            "urls": ["https://zlib.net/{filename}"]
+        }
+    },
+
+    {
+        "name": "bzip2",
+        "os": "linux",
+        "unix": {
+            "filename": "bzip2-1.0.8.tar.gz",
+            "hash": "sha256:ab5a03176ee106d3f0fa90e381da478ddae405918153cca248e682cd0c4a2269",
+            "urls": ["https://www.sourceware.org/pub/bzip2/bzip2-latest.tar.gz"]
+        }
+    },
+
+    {
+        "name": "pkg-config",
+        "os": "macos",
+        "unix": {
+            "filename": "pkg-config-0.29.2.tar.gz",
+            "hash": "sha256:6fc69c01688c9458a57eb9a1664c9aba372ccda420a02bf4429fe610e7e7d591",
+            "urls": ["https://pkg-config.freedesktop.org/releases/{filename}"]
+        }
+    },
+
+
+    {
+        "name": "expat",
+        "unix": {
+            "filename": "expat-2.2.6.tar.bz2",
+            "hash": "sha256:17b43c2716d521369f82fc2dc70f359860e90fa440bea65b3b85f0b246ea81f2",
+            "urls": ["https://github.com/libexpat/libexpat/releases/download/R_2_2_6/{filename}"]
+        }
+    },
+
+
+    {
+        "name": "xkbcommon",
+        "os": "linux",
+        "unix": {
+            "filename": "libxkbcommon-0.10.0.tar.xz",
+            "hash": "sha256:57c3630cdc38fb4734cd57fa349e92244f5ae3862813e533cedbd86721a0b6f2",
+            "urls": ["http://xkbcommon.org/download/{filename}"]
+        }
+    },
+
+    {
+        "name": "sqlite",
+        "unix": {
+            "filename": "sqlite-autoconf-3310100.tar.gz",
+            "hash": "sha1:0c30f5b22152a8166aa3bebb0f4bc1f3e9cc508b",
+            "urls": ["https://www.sqlite.org/2020/{filename}"]
+        }
+    },
+
+
+    {
+        "name": "libffi",
+        "unix": {
+            "filename": "libffi-3.2.1.tar.gz",
+            "hash": "sha1:280c265b789e041c02e5c97815793dfc283fb1e6",
+            "urls": ["ftp://sourceware.org/pub/libffi/{filename}"]
+        }
+    },
+
+    {
+        "name": "openssl",
+        "unix": {
+            "filename": "openssl-1.1.1g.tar.gz",
+            "hash": "sha256:ddb04774f1e32f0c49751e21b67216ac87852ceb056b75209af2443400636d46",
+            "urls": ["https://www.openssl.org/source/{filename}"]
+        }
+    },
+
+    {
+        "name": "ncurses",
+        "os": "linux",
+        "unix": {
+            "filename": "ncurses-6.2.tar.gz",
+            "hash": "sha256:30306e0c76e0f9f1f0de987cf1c82a5c21e1ce6568b9227f7da5b71cbea86c9d",
+            "urls": ["https://invisible-mirror.net/archives/ncurses/{filename}"]
+        }
+    },
+
+    {
+        "name": "readline",
+        "os": "linux",
+        "unix": {
+            "filename": "readline-8.0.tar.gz",
+            "hash": "sha256:e339f51971478d369f8a053a330a190781acb9864cf4c541060f12078948e461",
+            "urls": ["http://ftp.gnu.org/gnu/readline/{filename}"]
+        }
+    },
+
+    {
+        "name": "xz",
+        "os": "macos,linux",
+        "unix": {
+            "filename": "xz-5.2.5.tar.gz",
+            "hash": "sha256:f6f4910fd033078738bd82bfba4f49219d03b17eb0794eb91efbae419f4aba10",
+            "urls": ["https://tukaani.org/xz/{filename}"]
+        }
+    },
+
+    {
+        "name": "python",
+        "unix": {
+            "filename": "Python-3.8.3.tar.xz",
+            "hash": "sha256:dfab5ec723c218082fe3d5d7ae17ecbdebffa9a1aea4d64aa3a2ecdd2e795864",
+            "urls": ["https://www.python.org/ftp/python/3.8.3/{filename}"]
+        }
+    },
+
+    {
+        "name": "setuptools",
+        "unix": {
+            "filename": "setuptools-41.0.1.zip",
+            "hash": "sha256:a222d126f5471598053c9a77f4b5d4f26eaa1f150ad6e01dcf1a42e185d05613",
+            "urls": ["pypi"]
+        }
+    },
+
+    {
+        "name": "pygments",
+        "unix": {
+            "filename": "Pygments-2.6.1.tar.gz",
+            "hash": "sha256:647344a061c249a3b74e230c739f434d7ea4d8b1d5f3721bc0f3558049b38f44",
+            "urls": ["pypi"]
+        }
+    },
+
+    {
+        "name": "cmake",
+        "os": "macos",
+        "unix": {
+            "filename": "cmake-3.6.0.tar.gz",
+            "hash": "sha1:6b0d2d7d93c2e74f8890c4b8b824deb3b36d24b6",
+            "urls": ["https://cmake.org/files/v3.6/{filename}"]
+        }
+    },
+
+    {
+        "name": "libpng",
+        "unix": {
+            "filename": "libpng-1.6.37.tar.xz",
+            "hash": "sha256:505e70834d35383537b6491e7ae8641f1a4bed1876dbfe361201fc80868d88ca",
+            "urls": ["http://downloads.sourceforge.net/sourceforge/libpng/{filename}"]
+        }
+    },
+
+    {
+        "name": "lcms2",
+        "unix": {
+            "filename": "lcms2-2.11.tar.gz",
+            "hash": "sha256:478c9c3938d7a91b1171de4616f8b04308a8676d73eadc19505b7ace41327f28",
+            "urls": ["https://github.com/mm2/Little-CMS/archive/2.11/{filename}"]
+        }
+    },
+
+    {
+        "name": "graphite",
+        "os": "linux",
+        "unix": {
+            "filename": "graphite2-1.3.5.tgz",
+            "hash": "md5:5b8d22a8bbf031838e31432868c0109c",
+            "urls": ["http://downloads.sourceforge.net/silgraphite/{filename}"]
+        }
+    },
+
+    {
+        "name": "pcre",
+        "os": "linux",
+        "unix": {
+            "filename": "pcre-8.42.tar.bz2",
+            "hash": "md5:085b6aa253e0f91cae70b3cdbe8c1ac2",
+            "urls": ["https://ftp.pcre.org/pub/pcre/{filename}"]
+        }
+    },
+
+    {
+        "name": "iconv",
+        "os": "linux",
+        "unix": {
+            "filename": "libiconv-1.16.tar.gz",
+            "hash": "sha256:e6a1b1b589654277ee790cce3734f07876ac4ccfaecbee8afa0b649cf529cc04",
+            "urls": ["https://ftp.gnu.org/pub/gnu/libiconv/{filename}"]
+        }
+    },
+
+    {
+        "name": "glib",
+        "os": "linux",
+        "unix": {
+            "filename": "glib-2.65.1.tar.xz",
+            "hash": "sha256:bc63bf6c32713e0ee1dddc28e03f23b4a20c78bcb9a2c5b0f4eea41e46fb9cee",
+            "urls": ["https://ftp.gnome.org/pub/GNOME/sources/glib/2.65/{filename}"]
+        }
+    },
+
+    {
+        "name": "freetype",
+        "os": "linux",
+        "unix": {
+            "filename": "freetype-2.9.1.tar.bz2",
+            "hash": "md5:60ef7d8160cd4bf8cb118ee9d65367ca",
+            "urls": ["https://download.savannah.gnu.org/releases/freetype/{filename}"]
+        }
+    },
+
+    {
+        "name": "fontconfig",
+        "os": "linux",
+        "unix": {
+            "filename": "fontconfig-2.12.0.tar.bz2",
+            "hash": "sha256:b433e4efff1f68fdd8aac221ed1df3ff1e580ffedbada020a703fe64017d8224",
+            "urls": ["http://www.fontconfig.org/release/{filename}"]
+        }
+    },
+
+    {
+        "name": "harfbuzz",
+        "unix": {
+            "filename": "harfbuzz-1.7.2.tar.bz2",
+            "hash": "sha256:a790585e35c1a87f0dcc23580c84b7cc2324e6f67a2946178d278c2a36c790cb",
+            "urls": ["https://www.freedesktop.org/software/harfbuzz/release/{filename}"]
+        }
+    },
+
+    {
+        "name": "libxml2",
+        "os": "linux",
+        "unix": {
+            "filename": "libxml2-2.9.4.tar.gz",
+            "hash": "sha1:958ae70baf186263a4bd801a81dd5d682aedd1db",
+            "urls": ["ftp://xmlsoft.org/libxml2/{filename}"]
+        }
+    },
+
+    {
+        "name": "wayland",
+        "os": "linux",
+        "unix": {
+            "filename": "wayland-1.18.0.tar.xz",
+            "hash": "sha256:4675a79f091020817a98fd0484e7208c8762242266967f55a67776936c2e294d",
+            "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
+        }
+    },
+
+    {
+        "name": "wayland-protocols",
+        "os": "linux",
+        "unix": {
+            "filename": "wayland-protocols-1.20.tar.xz",
+            "hash": "sha256:9782b7a1a863d82d7c92478497d13c758f52e7da4f197aa16443f73de77e4de7",
+            "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
+        }
+    }
+
+]

count-lines-of-code

@@ -1,2 +1,27 @@
-#!/bin/bash
-cloc --exclude-list-file <(echo -e 'kitty/wcwidth9.h\nkitty/unicode-data.h\nkitty/gl.h\nkitty/glfw.c\nkitty/glfw.h\nkitty/charsets.c\nkitty/key_encoding.py') kitty
+#!/usr/bin/env python
+
+import subprocess
+
+files_to_exclude = '''\
+kitty/wcwidth-std.h
+kitty/glfw.c
+kitty/keys.h
+kitty/charsets.c
+kitty/unicode-data.c
+kitty/key_encoding.py
+kitty/rgb.py
+kitty/gl.h
+kitty/gl-wrapper.h
+kitty/gl-wrapper.c
+kitty/glfw-wrapper.h
+kitty/glfw-wrapper.c
+kitty/emoji.h
+kittens/unicode_input/names.h
+kitty/parse-graphics-command.h
+'''
+
+p = subprocess.Popen([
+    'cloc', '--exclude-list-file', '/dev/stdin', 'kitty', 'kittens'
+], stdin=subprocess.PIPE)
+p.communicate(files_to_exclude.encode('utf-8'))
+raise SystemExit(p.wait())

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -j auto -T $(FAIL_WARN)
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = kitty
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,122 @@
+/*
+ * custom.css
+ * Copyright (C) 2018 Kovid Goyal
+ *
+ * Distributed under terms of the MIT license.
+ */
+
+.float-left-img {
+    float: left;
+    margin-right: 1em;
+    margin-bottom: 1em;
+}
+
+.float-right-img { float: right; margin-left: 1em; margin-bottom: 1em }
+
+.half-with-img { max-width: 50% }
+
+.fit-img { max-width: 95% }
+
+div.body p, div.body dd, div.body li, div.body blockquote {
+    text-align: justify;
+}
+
+pre {
+    white-space: pre-wrap;
+}
+
+pre.pre {
+    white-space: pre;
+}
+
+a[href], input[type="submit"] { cursor: pointer; }
+
+img[style] {
+    /* Used for :scale: images to have them render properly but still popup when clicked */
+    width: auto !important;
+    height: auto !important;
+}
+
+a {
+    text-decoration: none !important;
+    border-bottom: none !important;
+}
+
+body div.document {
+    margin-top: 1ex;
+}
+
+.major-features li {
+    margin-top: 0.75ex;
+    margin-bottom: 0.75ex;
+}
+
+.support-form input[type=submit] {
+    border-radius: 6px;
+    box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px;
+    background: linear-gradient(rgb(255, 236, 100) 5%, rgb(255, 171, 35) 100%) rgb(255, 236, 100);
+    border: 1px solid rgb(255, 170, 34);
+    display: inline-block;
+    color: rgb(51, 51, 51);
+    font-family: Arial;
+    font-size: 15px;
+    font-weight: bold;
+    padding: 6px 24px;
+    text-decoration: none;
+    text-shadow: rgb(255, 238, 102) 0px 1px 0px;
+}
+
+.support-form input[type=submit]:hover {
+    background: linear-gradient(rgb(255, 171, 35) 5%, rgb(255, 236, 100) 100%) rgb(255, 171, 35);
+}
+
+.support-form input[type=submit]:focus {
+    outline: 0;
+}
+
+
+div.sphinxsidebar {
+    font-size: inherit;
+    line-height: inherit;
+    max-height: 100%;
+    overflow-y: auto;
+}
+
+#sidebartoc li {
+    margin-top: 0.75ex;
+    margin-bottom: 0.75ex;
+}
+
+#sidebartoc ul {
+    list-style: none !important;
+}
+
+#sidebartoc a[href]:hover {
+    color: red;
+}
+
+
+.green {
+    color: green;
+}
+
+.cyan {
+    color: blue;
+}
+
+.env {
+    font-style: italic;
+}
+
+.italic {
+    font-style: italic;
+}
+
+.bold {
+    font-weight: bold;
+}
+
+.title {
+    font-size: larger;
+    font-weight: bold
+}

docs/_templates/layout.html

@@ -0,0 +1,6 @@
+{% extends "!layout.html" %}
+
+{%- block extrahead %}
+<!-- kitty analytics placeholder -->
+  {{ super() }}
+{% endblock %}

docs/_templates/localtoc.html

@@ -0,0 +1,6 @@
+{%- if display_toc %}
+<div>&nbsp;</div>
+<div id="sidebartoc">
+  {{ toc }}
+</div>
+{%- endif %}

docs/_templates/searchbox.html

@@ -0,0 +1,22 @@
+{#
+    basic/searchbox.html
+    ~~~~~~~~~~~~~~~~~~~~
+
+    Sphinx sidebar template: quick search box.
+
+    :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{%- if pagename != "search" and builder != "singlehtml" %}
+<div id="searchbox" style="display: none" role="search">
+    <div class="searchformwrapper">
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" name="q" placeholder="{{ _('Search') }}" />
+      <input type="submit" value="{{ _('Go') }}" style="cursor: pointer" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </div>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+{%- endif %}

docs/_templates/support.html

@@ -0,0 +1,7 @@
+{% if pagename != "support" %}
+<div id="support" style="text-align: center">
+    <form class="support-form" action="{{ pathto('support') }}" title="{{ _('Donate to support kitty development') }}">
+        <input type="submit" value="{{ _('Support kitty') }}">
+    </form>
+</div>
+{% endif %}

docs/binary.rst

@@ -0,0 +1,91 @@
+kitty - Binary install
+========================
+
+.. |ins| replace:: curl -L :literal:`https://sw.kovidgoyal.net/kitty/installer.sh` | sh /dev/stdin
+
+.. highlight:: sh
+
+You can install pre-built binaries of |kitty| if you are on macOS or Linux using
+the following simple command:
+
+.. parsed-literal::
+    :class: pre
+
+    |ins|
+
+
+The binaries will be installed in the standard location for your OS,
+:file:`/Applications/kitty.app` on macOS and :file:`~/.local/kitty.app` on
+Linux. The installer only touches files in that directory. To update kitty,
+simply re-run the command.
+
+
+Manually installing
+---------------------
+
+If something goes wrong or you simply do not want to run the installer, you can
+manually download and install |kitty| from the `GitHub releases page
+<https://github.com/kovidgoyal/kitty/releases>`_. If you are on macOS, download
+the :file:`.dmg` and install as normal. If you are on Linux, download the tarball
+and extract it into a directory. The |kitty| executable will be in the
+:file:`bin` sub-directory.
+
+Desktop integration on Linux
+--------------------------------
+
+If you want the kitty icon to appear in the taskbar and an entry for it to be
+present in the menus, you will need to install the :file:`kitty.desktop` file.
+The details of the following procedure may need to be adjusted for your
+particular desktop, but it should work for most major desktop environments.
+
+.. code-block:: sh
+
+    # Create a symbolic link to add kitty to PATH (assuming ~/.local/bin is in
+    # your PATH)
+    ln -s ~/.local/kitty.app/bin/kitty ~/.local/bin/
+    # Place the kitty.desktop file somewhere it can be found by the OS
+    cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications
+    # Update the path to the kitty icon in the kitty.desktop file
+    sed -i "s|Icon=kitty|Icon=/home/$USER/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png|g" ~/.local/share/applications/kitty.desktop
+
+
+
+Customizing the installation
+--------------------------------
+
+* You can specify a different install location, with ``dest``:
+
+  .. parsed-literal::
+     :class: pre
+
+     |ins| \\
+         dest=/some/other/location
+
+* You can tell the installer not to launch |kitty| after installing it with
+  ``launch=n``:
+
+  .. parsed-literal::
+     :class: pre
+
+     |ins| \\
+         launch=n
+
+* You can use a previously downloaded dmg/tarball, with ``installer``:
+
+  .. parsed-literal::
+     :class: pre
+
+     |ins| \\
+         installer=/path/to/dmg or tarball
+
+Uninstalling
+----------------
+
+All the installer does is copy the kitty files into the install directory. To
+uninstall, simply delete that directory.
+
+
+Building from source
+------------------------
+
+|kitty| is easy to build from source, follow the :doc:`instructions <build>`.

docs/build.rst

@@ -0,0 +1,122 @@
+Building kitty from source
+==============================
+
+.. image:: https://github.com/kovidgoyal/kitty/workflows/CI/badge.svg
+  :alt: Build status
+  :target: https://github.com/kovidgoyal/kitty/actions?query=workflow%3ACI
+
+
+|kitty| is designed to run from source, for easy hackability. Make sure
+the following dependencies are installed first.
+
+Dependencies
+----------------
+
+Run-time dependencies:
+
+    * python >= 3.5
+    * harfbuzz >= 1.5.0
+    * zlib
+    * libpng
+    * liblcms2
+    * freetype (not needed on macOS)
+    * fontconfig (not needed on macOS)
+    * libcanberra (not needed on macOS)
+    * ImageMagick (optional, needed to use the ``kitty icat`` tool to display images in the terminal)
+    * pygments (optional, need for syntax highlighting in ``kitty +kitten diff``)
+
+Build-time dependencies:
+
+    * gcc or clang
+    * pkg-config
+    * For building on Linux in addition to the above dependencies you might also need to install the ``-dev`` packages for:
+      ``libdbus-1-dev``, ``libxcursor-dev``, ``libxrandr-dev``, ``libxi-dev``, ``libxinerama-dev``, ``libgl1-mesa-dev``, ``libxkbcommon-x11-dev``, ``libfontconfig-dev``, and ``libpython-dev``,
+      if they are not already installed by your distro.
+
+Install and run from source
+------------------------------
+
+.. code-block:: sh
+
+    git clone https://github.com/kovidgoyal/kitty && cd kitty
+
+Now build the native code parts of |kitty| with the following command::
+
+    make
+
+You can run |kitty|, as::
+
+    ./kitty/launcher/kitty
+
+If that works, you can create a symlink to the launcher in :file:`~/bin` or
+some other directory on your PATH so that you can run |kitty| using
+just ``kitty``.
+
+
+Building kitty.app on macOS from source
+-------------------------------------------
+
+Run::
+
+    make app
+
+This :file:`kitty.app` unlike the released one does not include its own copy of
+python and the other dependencies. So if you ever un-install/upgrade those dependencies
+you might have to rebuild the app.
+
+.. note::
+   The released :file:`kitty.dmg` includes all dependencies, unlike the
+   :file:`kitty.app` built above and is built automatically by using the
+   :file:`kitty` branch of `build-calibre
+   <https://github.com/kovidgoyal/build-calibre>`_ however, that is designed to
+   run on Linux and is not for the faint of heart.
+
+
+.. note::
+   Apple disallows certain functionality, such as notifications for unsigned applications.
+   If you need this functionality, you can try signing the built kitty.app with
+   a self signed certificate, see for example, `here
+   <https://stackoverflow.com/questions/27474751/how-can-i-codesign-an-app-without-being-in-the-mac-developer-program/27474942>`_.
+
+
+Note for Linux/macOS packagers
+----------------------------------
+
+The released |kitty| source code is available as a `tarball`_ from
+`the GitHub releases page <https://github.com/kovidgoyal/kitty/releases>`_.
+
+While |kitty| does use python, it is not a traditional python package, so please
+do not install it in site-packages.
+Instead run::
+
+    python3 setup.py linux-package
+
+This will install |kitty| into the directory :file:`linux-package`. You can run |kitty|
+with :file:`linux-package/bin/kitty`.  All the files needed to run kitty will be in
+:file:`linux-package/lib/kitty`. The terminfo file will be installed into
+:file:`linux-package/share/terminfo`. Simply copy these files into :file:`/usr` to install
+|kitty|. In other words, :file:`linux-package` is the staging area into which |kitty| is
+installed. You can choose a different staging area, by passing the ``--prefix``
+argument to :file:`setup.py`.
+
+You should probably split |kitty| into two packages, :file:`kitty-terminfo` that
+installs the terminfo file and :file:`kitty` that installs the main program.
+This allows users to install the terminfo file on servers into which they ssh,
+without needing to install all of |kitty|.
+
+.. note::
+        You need a couple of extra dependencies to build linux-package.
+        :file:`tic` to compile terminfo files, usually found in the
+        development package of :file:`ncurses`. Also, if you are building from
+        a git checkout instead of the released source code tarball, you will
+        need :file:`sphinx-build` from the `Sphinx documentation generator
+        <https://www.sphinx-doc.org/>`_.
+
+This applies to creating packages for |kitty| for macOS package managers such as
+brew or MacPorts as well.
+
+
+.. note::
+        |kitty| has its own update check mechanism, if you would like to turn
+        it off for your package, use
+        ``python3 setup.py linux-package --update-check-interval=0``

docs/conf.py

@@ -0,0 +1,612 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# https://www.sphinx-doc.org/en/master/config
+
+import os
+import re
+import subprocess
+import sys
+import time
+from functools import partial
+from typing import (
+    Any, Callable, Dict, Iterable, List, Match, Optional, Sequence, Tuple,
+    Union
+)
+
+from docutils import nodes
+from docutils.parsers.rst.roles import set_classes
+from pygments.lexer import RegexLexer, bygroups  # type: ignore
+from pygments.token import (  # type: ignore
+    Comment, Keyword, Literal, Name, Number, String, Whitespace
+)
+from sphinx import addnodes  # type: ignore
+from sphinx.environment.adapters.toctree import TocTree  # type: ignore
+from sphinx.util.logging import getLogger  # type: ignore
+
+kitty_src = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if kitty_src not in sys.path:
+    sys.path.insert(0, kitty_src)
+
+from kitty.conf.definition import Option, Shortcut  # noqa
+from kitty.constants import str_version  # noqa
+
+
+# config {{{
+# -- Project information -----------------------------------------------------
+
+project = 'kitty'
+copyright = time.strftime('%Y, Kovid Goyal')
+author = 'Kovid Goyal'
+building_man_pages = 'man' in sys.argv
+
+# The short X.Y version
+version = str_version
+# The full version, including alpha/beta/rc tags
+release = str_version
+logger = getLogger(__name__)
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+needs_sphinx = '1.7'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language: Optional[str] = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = [
+    '_build', 'Thumbs.db', '.DS_Store',
+    'generated/cli-*.rst', 'generated/conf-*.rst'
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+rst_prolog = '''
+.. |kitty| replace:: *kitty*
+.. |version| replace:: VERSION
+.. _tarball: https://github.com/kovidgoyal/kitty/releases/download/vVERSION/kitty-VERSION.tar.xz
+.. role:: green
+.. role:: italic
+.. role:: bold
+.. role:: cyan
+.. role:: title
+.. role:: env
+
+'''.replace('VERSION', str_version)
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'logo': 'kitty.png',
+    'show_powered_by': False,
+    'fixed_sidebar': True,
+    'sidebar_collapse': True,
+    'github_button': False,
+    'github_banner': True,
+    'github_user': 'kovidgoyal',
+    'github_repo': 'kitty',
+    # increase contrast of link color with text color
+    'link': '#00587d',
+    'link_hover': 'green',
+}
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static', '../logo/kitty.png']
+html_context = {
+    'css_files': ['_static/custom.css']
+}
+html_favicon = '../logo/kitty.png'
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+html_sidebars = {
+    '**': [
+        'about.html',
+        'support.html',
+        'searchbox.html',
+        'localtoc.html',
+        'relations.html',
+    ]
+}
+html_show_sourcelink = False
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('invocation', 'kitty', 'kitty Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'kitty', 'kitty Documentation',
+     author, 'kitty', 'A cross-platform, fast, feature full, GPU based terminal emulator',
+     'Miscellaneous'),
+]
+# }}}
+
+
+# GitHub linking inline roles {{{
+
+def num_role(which: str, name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
+    ' Link to a github issue '
+    try:
+        issue_num = int(text)
+        if issue_num <= 0:
+            raise ValueError
+    except ValueError:
+        msg = inliner.reporter.error(
+            'GitHub issue number must be a number greater than or equal to 1; '
+            '"%s" is invalid.' % text, line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    url = f'https://github.com/kovidgoyal/kitty/{which}/{issue_num}'
+    set_classes(options)
+    node = nodes.reference(rawtext, f'#{issue_num}', refuri=url, **options)
+    return [node], []
+
+
+def commit_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
+    ' Link to a github commit '
+    try:
+        commit_id = subprocess.check_output(
+            f'git rev-list --max-count=1 --skip=# {text}'.split()).decode('utf-8').strip()
+    except Exception:
+        msg = inliner.reporter.error(
+            f'GitHub commit id "{text}" not recognized.', line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    url = f'https://github.com/kovidgoyal/kitty/commit/{commit_id}'
+    set_classes(options)
+    short_id = subprocess.check_output(
+        f'git rev-list --max-count=1 --abbrev-commit --skip=# {commit_id}'.split()).decode('utf-8').strip()
+    node = nodes.reference(rawtext, f'commit: {short_id}', refuri=url, **options)
+    return [node], []
+# }}}
+
+
+# Sidebar ToC {{{
+def create_toc(app: Any, pagename: str) -> Optional[Any]:
+    tt = TocTree(app.env)
+    toctree = tt.get_toc_for(pagename, app.builder)
+    if toctree is not None:
+        subtree = toctree[toctree.first_child_matching_class(nodes.list_item)]
+        bl = subtree.first_child_matching_class(nodes.bullet_list)
+        if bl is None:
+            return None  # Empty ToC
+        subtree = subtree[bl]
+        # for li in subtree.traverse(nodes.list_item):
+        #     modify_li(li)
+        # subtree['ids'] = [ID]
+        return app.builder.render_partial(subtree)['fragment']
+
+
+def add_html_context(app: Any, pagename: str, templatename: str, context: Any, *args: Any) -> None:
+    if 'toc' in context:
+        context['toc'] = create_toc(app, pagename) or context['toc']
+# }}}
+
+
+# CLI docs {{{
+def write_cli_docs(all_kitten_names: Iterable[str]) -> None:
+    from kitty.launch import options_spec as launch_options_spec
+    from kitty.cli import option_spec_as_rst
+    with open('generated/launch.rst', 'w') as f:
+        f.write(option_spec_as_rst(
+            appname='launch', ospec=launch_options_spec, heading_char='_',
+            message='''\
+Launch an arbitrary program in a new kitty window/tab. Note that
+if you specify a program-to-run you can use the special placeholder
+:code:`@selection` which will be replaced by the current selection.
+'''
+        ))
+    with open('generated/cli-kitty.rst', 'w') as f:
+        f.write(option_spec_as_rst(appname='kitty').replace(
+            'kitty --to', 'kitty @ --to'))
+    as_rst = partial(option_spec_as_rst, heading_char='_')
+    from kitty.rc.base import all_command_names, command_for_name
+    from kitty.remote_control import global_options_spec, cli_msg
+    with open('generated/cli-kitty-at.rst', 'w') as f:
+        p = partial(print, file=f)
+        p('kitty @\n' + '-' * 80)
+        p('.. program::', 'kitty @')
+        p('\n\n' + as_rst(
+            global_options_spec, message=cli_msg, usage='command ...', appname='kitty @'))
+        from kitty.rc.base import cli_params_for
+        for cmd_name in sorted(all_command_names()):
+            func = command_for_name(cmd_name)
+            p(f'.. _at_{func.name}:\n')
+            p('kitty @', func.name + '\n' + '-' * 120)
+            p('.. program::', 'kitty @', func.name)
+            p('\n\n' + as_rst(*cli_params_for(func)))
+    from kittens.runner import get_kitten_cli_docs
+    for kitten in all_kitten_names:
+        data = get_kitten_cli_docs(kitten)
+        if data:
+            with open(f'generated/cli-kitten-{kitten}.rst', 'w') as f:
+                p = partial(print, file=f)
+                p('.. program::', f'kitty +kitten {kitten}')
+                p('\n\n' + option_spec_as_rst(
+                    data['options'], message=data['help_text'], usage=data['usage'], appname=f'kitty +kitten {kitten}',
+                    heading_char='^'))
+
+# }}}
+
+
+def write_remote_control_protocol_docs() -> None:  # {{{
+    from kitty.rc.base import all_command_names, command_for_name, RemoteCommand
+    field_pat = re.compile(r'\s*([a-zA-Z0-9_+]+)\s*:\s*(.+)')
+
+    def format_cmd(p: Callable, name: str, cmd: RemoteCommand) -> None:
+        p(name)
+        p('-' * 80)
+        lines = (cmd.__doc__ or '').strip().splitlines()
+        fields = []
+        for line in lines:
+            m = field_pat.match(line)
+            if m is None:
+                p(line)
+            else:
+                fields.append((m.group(1), m.group(2)))
+        if fields:
+            p('\nFields are:\n')
+            for (name, desc) in fields:
+                if '+' in name:
+                    title = name.replace('+', ' (required)')
+                else:
+                    title = name
+                    defval = cmd.get_default(name.replace('-', '_'), cmd)
+                    if defval is not cmd:
+                        title = f'{title} (default: {defval})'
+                    else:
+                        title = f'{title} (optional)'
+                p(f':code:`{title}`')
+                p(' ', desc), p()
+        p(), p()
+
+    with open('generated/rc.rst', 'w') as f:
+        p = partial(print, file=f)
+        for name in sorted(all_command_names()):
+            cmd = command_for_name(name)
+            if not cmd.__doc__:
+                continue
+            name = name.replace('_', '-')
+            format_cmd(p, name, cmd)
+# }}}
+
+
+# config file docs {{{
+
+class ConfLexer(RegexLexer):
+    name = 'Conf'
+    aliases = ['conf']
+    filenames = ['*.conf']
+
+    tokens = {
+        'root': [
+            (r'#.*?$', Comment.Single),
+            (r'\s+$', Whitespace),
+            (r'\s+', Whitespace),
+            (r'(include)(\s+)(.+?)$', bygroups(Comment.Preproc, Whitespace, Name.Namespace)),
+            (r'(map)(\s+)(\S+)(\s+)', bygroups(
+                Keyword.Declaration, Whitespace, String, Whitespace), 'action'),
+            (r'(symbol_map)(\s+)(\S+)(\s+)(.+?)$', bygroups(
+                Keyword.Declaration, Whitespace, String, Whitespace, Literal)),
+            (r'([a-zA-Z_0-9]+)(\s+)', bygroups(
+                Name.Variable, Whitespace), 'args'),
+        ],
+        'action': [
+            (r'[a-z_0-9]+$', Name.Function, 'root'),
+            (r'[a-z_0-9]+', Name.Function, 'args'),
+        ],
+        'args': [
+            (r'\s+', Whitespace, 'args'),
+            (r'\b(yes|no)\b$', Number.Bin, 'root'),
+            (r'\b(yes|no)\b', Number.Bin, 'args'),
+            (r'[+-]?[0-9]+\s*$', Number.Integer, 'root'),
+            (r'[+-]?[0-9.]+\s*$', Number.Float, 'root'),
+            (r'[+-]?[0-9]+', Number.Integer, 'args'),
+            (r'[+-]?[0-9.]+', Number.Float, 'args'),
+            (r'#[a-fA-F0-9]{3,6}\s*$', String, 'root'),
+            (r'#[a-fA-F0-9]{3,6}\s*', String, 'args'),
+            (r'.+', String, 'root'),
+        ],
+    }
+
+
+class SessionLexer(RegexLexer):
+    name = 'Session'
+    aliases = ['session']
+    filenames = ['*.session']
+
+    tokens = {
+        'root': [
+            (r'#.*?$', Comment.Single),
+            (r'[a-z][a-z0-9_]+', Name.Function, 'args'),
+        ],
+        'args': [
+            (r'.*?$', Literal, 'root'),
+        ]
+    }
+
+
+def link_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
+    m = re.match(r'(.+)\s+<(.+?)>', text)
+    if m is None:
+        msg = inliner.reporter.error(f'link "{text}" not recognized', line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    text, url = m.group(1, 2)
+    set_classes(options)
+    node = nodes.reference(rawtext, text, refuri=url, **options)
+    return [node], []
+
+
+def expand_opt_references(conf_name: str, text: str) -> str:
+    conf_name += '.'
+
+    def expand(m: Match) -> str:
+        ref = m.group(1)
+        if '<' not in ref and '.' not in ref:
+            full_ref = conf_name + ref
+            return ':opt:`{} <{}>`'.format(ref, full_ref)
+        return str(m.group())
+
+    return re.sub(r':opt:`(.+?)`', expand, text)
+
+
+opt_aliases: Dict[str, str] = {}
+shortcut_slugs: Dict[str, Tuple[str, str]] = {}
+
+
+def parse_opt_node(env: Any, sig: str, signode: Any) -> str:
+    """Transform an option description into RST nodes."""
+    count = 0
+    firstname = ''
+    for potential_option in sig.split(', '):
+        optname = potential_option.strip()
+        if count:
+            signode += addnodes.desc_addname(', ', ', ')
+        text = optname.split('.', 1)[-1]
+        signode += addnodes.desc_name(text, text)
+        if not count:
+            firstname = optname
+            signode['allnames'] = [optname]
+        else:
+            signode['allnames'].append(optname)
+            opt_aliases[optname] = firstname
+        count += 1
+    if not firstname:
+        raise ValueError('{} is not a valid opt'.format(sig))
+    return firstname
+
+
+def parse_shortcut_node(env: Any, sig: str, signode: Any) -> str:
+    """Transform a shortcut description into RST nodes."""
+    conf_name, text = sig.split('.', 1)
+    signode += addnodes.desc_name(text, text)
+    return sig
+
+
+def render_conf(conf_name: str, all_options: Iterable[Union['Option', Sequence['Shortcut']]]) -> str:
+    from kitty.conf.definition import merged_opts, Option, Group
+    ans = ['.. default-domain:: conf', '']
+    a = ans.append
+    current_group: Optional[Group] = None
+    all_options_ = list(all_options)
+    kitty_mod = 'kitty_mod'
+
+    def render_group(group: Group) -> None:
+        a('')
+        a(f'.. _conf-{conf_name}-{group.name}:')
+        a('')
+        a(group.short_text)
+        heading_level = '+' if '.' in group.name else '^'
+        a(heading_level * (len(group.short_text) + 20))
+        a('')
+        if group.start_text:
+            a(group.start_text)
+            a('')
+
+    def handle_group_end(group: Group) -> None:
+        if group.end_text:
+            assert current_group is not None
+            a(''), a(current_group.end_text)
+
+    def handle_group(new_group: Group, new_group_is_shortcut: bool = False) -> None:
+        nonlocal current_group
+        if new_group is not current_group:
+            if current_group:
+                handle_group_end(current_group)
+            current_group = new_group
+            render_group(current_group)
+
+    def handle_option(i: int, opt: Option) -> None:
+        nonlocal kitty_mod
+        if not opt.long_text or not opt.add_to_docs:
+            return
+        handle_group(opt.group)
+        if opt.name == 'kitty_mod':
+            kitty_mod = opt.defval_as_string
+        mopts = list(merged_opts(all_options_, opt, i))
+        a('.. opt:: ' + ', '.join(conf_name + '.' + mo.name for mo in mopts))
+        a('.. code-block:: conf')
+        a('')
+        sz = max(len(x.name) for x in mopts)
+        for mo in mopts:
+            a(('    {:%ds} {}' % sz).format(mo.name, mo.defval_as_string))
+        a('')
+        if opt.long_text:
+            a(expand_opt_references(conf_name, opt.long_text))
+            a('')
+
+    def handle_shortcuts(shortcuts: Sequence[Shortcut]) -> None:
+        sc = shortcuts[0]
+        handle_group(sc.group, True)
+        sc_text = f'{conf_name}.{sc.short_text}'
+        a('.. shortcut:: ' + sc_text)
+        shortcuts = [s for s in shortcuts if s.add_to_default]
+        shortcut_slugs[f'{conf_name}.{sc.name}'] = (sc_text, sc.key.replace('kitty_mod', kitty_mod))
+        if shortcuts:
+            a('.. code-block:: conf')
+            a('')
+            for x in shortcuts:
+                if x.add_to_default:
+                    a('    map {} {}'.format(x.key.replace('kitty_mod', kitty_mod), x.action_def))
+        a('')
+        if sc.long_text:
+            a(expand_opt_references(conf_name, sc.long_text))
+            a('')
+
+    for i, opt in enumerate(all_options_):
+        if isinstance(opt, Option):
+            handle_option(i, opt)
+        else:
+            handle_shortcuts(opt)
+
+    if current_group:
+        handle_group_end(current_group)
+    return '\n'.join(ans)
+
+
+def process_opt_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
+    conf_name, opt = target.partition('.')[::2]
+    if not opt:
+        conf_name, opt = 'kitty', conf_name
+    full_name = conf_name + '.' + opt
+    return title, opt_aliases.get(full_name, full_name)
+
+
+def process_shortcut_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
+    conf_name, slug = target.partition('.')[::2]
+    if not slug:
+        conf_name, slug = 'kitty', conf_name
+    full_name = conf_name + '.' + slug
+    try:
+        target, stitle = shortcut_slugs[full_name]
+    except KeyError:
+        logger.warning('Unknown shortcut: {}'.format(target), location=refnode)
+    else:
+        if not has_explicit_title:
+            title = stitle
+    return title, target
+
+
+def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None:
+    app.add_lexer('conf', ConfLexer)
+    app.add_object_type(
+        'opt', 'opt',
+        indextemplate="pair: %s; Config Setting",
+        parse_node=parse_opt_node,
+    )
+    # Warn about opt references that could not be resolved
+    opt_role = app.registry.domain_roles['std']['opt']
+    opt_role.warn_dangling = True
+    opt_role.process_link = process_opt_link
+
+    app.add_object_type(
+        'shortcut', 'sc',
+        indextemplate="pair: %s; Keyboard Shortcut",
+        parse_node=parse_shortcut_node,
+    )
+    sc_role = app.registry.domain_roles['std']['sc']
+    sc_role.warn_dangling = True
+    sc_role.process_link = process_shortcut_link
+
+    def generate_default_config(all_options: Dict[str, Union[Option, Sequence[Shortcut]]], name: str) -> None:
+        from kitty.conf.definition import as_conf_file
+        with open(f'generated/conf-{name}.rst', 'w', encoding='utf-8') as f:
+            print('.. highlight:: conf\n', file=f)
+            f.write(render_conf(name, all_options.values()))
+
+        conf_name = re.sub(r'^kitten-', '', name) + '.conf'
+        with open(f'generated/conf/{conf_name}', 'w', encoding='utf-8') as f:
+            text = '\n'.join(as_conf_file(all_options.values()))
+            print(text, file=f)
+
+    from kitty.config_data import all_options
+    generate_default_config(all_options, 'kitty')
+
+    from kittens.runner import get_kitten_conf_docs
+    for kitten in all_kitten_names:
+        all_options = get_kitten_conf_docs(kitten)
+        if all_options:
+            generate_default_config(all_options, f'kitten-{kitten}')
+# }}}
+
+
+def setup(app: Any) -> None:
+    os.makedirs('generated/conf', exist_ok=True)
+    from kittens.runner import all_kitten_names
+    kn = all_kitten_names()
+    write_cli_docs(kn)
+    write_remote_control_protocol_docs()
+    write_conf_docs(app, kn)
+    app.add_lexer('session', SessionLexer)
+    app.add_role('link', link_role)
+    app.add_role('iss', partial(num_role, 'issues'))
+    app.add_role('pull', partial(num_role, 'pull'))
+    app.add_role('commit', commit_role)
+    app.connect('html-page-context', add_html_context)

docs/conf.rst

@@ -0,0 +1,44 @@
+:tocdepth: 2
+
+Configuring kitty
+===============================
+
+.. highlight:: conf
+
+|kitty| is highly customizable, everything from keyboard shortcuts, to painting
+frames-per-second. See below for an overview of all customization
+possibilities.
+
+You can open the config file within kitty by pressing :sc:`edit_config_file`.
+You can also display the current configuration by running ``kitty
+--debug-config``.
+
+.. _confloc:
+
+|kitty| looks for a config file in the OS config directories (usually
+:file:`~/.config/kitty/kitty.conf`) but you can pass a specific path via the
+:option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY``
+environment variable. See the :option:`kitty --config` option for full details.
+
+Comments can be added to the config file as lines starting with the ``#``
+character. This works only if the ``#`` character is the first character
+in the line.
+
+You can include secondary config files via the :code:`include` directive.  If
+you use a relative path for include, it is resolved with respect to the
+location of the current config file. Note that environment variables are
+expanded, so :code:`${USER}.conf` becomes :file:`name.conf` if
+:code:`USER=name`.  For example::
+
+     include other.conf
+
+
+.. include:: /generated/conf-kitty.rst
+
+
+Sample kitty.conf
+^^^^^^^^^^^^^^^^^^^^^
+
+You can download a sample :file:`kitty.conf` file with all default settings and
+comments describing each setting by clicking: :download:`sample kitty.conf
+</generated/conf/kitty.conf>`.

docs/faq.rst

@@ -0,0 +1,261 @@
+Frequently Asked Questions
+==============================
+
+.. highlight:: sh
+
+.. contents::
+
+Some special symbols are rendered small/truncated in kitty?
+-----------------------------------------------------------
+
+The number of cells a unicode character takes up are controlled by the unicode
+standard.  All characters are rendered in a single cell unless the unicode
+standard says they should be rendered in two cells. When a symbol does not fit,
+it will either be rescaled to be smaller or truncated (depending on how much
+extra space it needs). This is often different from other terminals which just
+let the character overflow into neighboring cells, which is fine if the
+neighboring cell is empty, but looks terrible if it is not.
+
+Some programs, like powerline, vim with fancy gutter symbols/status-bar, etc.
+misuse unicode characters from the private use area to represent symbols. Often
+these symbols are square and should be rendered in two cells.  However, since
+private use area symbols all have their width set to one in the unicode
+standard, |kitty| renders them either smaller or truncated. The exception is if
+these characters are followed by a space or empty cell in which case kitty
+makes use of the extra cell to render them in two cells.
+
+
+Using a color theme with a background color does not work well in vim?
+-----------------------------------------------------------------------
+
+First make sure you have not changed the TERM environment variable, it should
+be ``xterm-kitty``. vim uses *background color erase* even if the terminfo file
+does not contain the ``bce`` capability. This is a bug in vim. You can work around
+it by adding the following to your vimrc::
+
+    let &t_ut=''
+
+See :ref:`here <ext_styles>` for why |kitty| does not support background color erase.
+
+
+I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
+-----------------------------------------------------------------------------------------------------------------------
+
+This happens because the |kitty| terminfo files are not available on the server.
+You can ssh in using the following command which will automatically copy the
+terminfo files to the server::
+
+    kitty +kitten ssh myserver
+
+If for some reason that does not work (typically because the server is using a
+non POSIX compliant shell), you can use the following one-liner instead (it
+is slower as it needs to ssh into the server twice, but will work with most
+servers)::
+
+    infocmp xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
+
+If you are behind a proxy (like Balabit) that prevents this, you must redirect the
+1st command to a file, copy that to the server and run ``tic`` manually.  If you
+connect to a server, embedded or Android system that doesn't have ``tic``, copy over
+your local file terminfo to the other system as :file:`~/.terminfo/x/xterm-kitty`.
+
+Really, the correct solution for this is to convince the OpenSSH maintainers to
+have ssh do this automatically, if possible, when connecting to a server, so that
+all terminals work transparently.
+
+If the server is running FreeBSD, or another system that relies on termcap
+rather than terminfo, you will need to convert the terminfo file on your local
+machine by running (on local machine with |kitty|)::
+
+    infocmp -C xterm-kitty
+
+The output of this command is the termcap description, which should be appended
+to :file:`/usr/share/misc/termcap` on the remote server. Then run the following
+command to apply your change (on the server)::
+
+    cap_mkdb /usr/share/misc/termcap
+
+
+Keys such as arrow keys, backspace, delete, home/end, etc. do not work when using su or sudo?
+-------------------------------------------------------------------------------------------------
+
+Make sure the TERM environment variable, is ``xterm-kitty``.  And either the
+TERMINFO environment variable points to a directory containing :file:`x/xterm-kitty`
+or that file is under :file:`~/.terminfo/x/`.
+
+Note that ``sudo`` might remove TERMINFO.  Then setting it at the shell prompt can
+be too late, because command line editing may not be reinitialized.  In that case
+you can either ask ``sudo`` to set it or if that is not supported, insert an ``env``
+command before starting the shell, or, if not possible, after sudo start another
+Shell providing the right terminfo path::
+
+    sudo … TERMINFO=$HOME/.terminfo bash -i
+    sudo … env TERMINFO=$HOME/.terminfo bash -i
+    TERMINFO=/home/ORIGINALUSER/.terminfo exec bash -i
+
+You can configure sudo to preserve TERMINFO by running ``sudo
+visudo`` and adding the following line::
+
+    Defaults env_keep += "TERM TERMINFO"
+
+If you have double width characters in your prompt, you may also need to
+explicitly set a UTF-8 locale, like::
+
+    export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8
+
+
+How do I change the colors in a running kitty instance?
+------------------------------------------------------------
+
+You can either use the
+`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands>`_
+to set colors or you can define keyboard shortcuts to set colors, for example::
+
+    map f1 set_colors --configured /path/to/some/config/file/colors.conf
+
+Or you can enable :doc:`remote control <remote-control>` for |kitty| and use :ref:`at_set-colors`.
+The shortcut mapping technique has the same syntax as the remote control
+command, for details, see :ref:`at_set-colors`.
+
+A list of pre-made color themes for kitty is available at:
+`kitty-themes <https://github.com/dexpota/kitty-themes>`_
+
+Examples of using OSC escape codes to set colors::
+
+    Change the default foreground color:
+    printf '\x1b]10;#ff0000\x1b\\'
+    Change the default background color:
+    printf '\x1b]11;blue\x1b\\'
+    Change the cursor color:
+    printf '\x1b]12;blue\x1b\\'
+    Change the selection background color:
+    printf '\x1b]17;blue\x1b\\'
+    Change the selection foreground color:
+    printf '\x1b]19;blue\x1b\\'
+    Change the nth color (0 - 255):
+    printf '\x1b]4;n;green\x1b\\'
+
+You can use various syntaxes/names for color specifications in the above
+examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`_
+for full details.
+
+If a ``?`` is given rather than a color specification, kitty will respond
+with the current value for the specified color.
+
+
+How do I specify command line options for kitty on macOS?
+---------------------------------------------------------------
+
+Apple does not want you to use command line options with GUI applications. To
+workaround that limitation, |kitty| will read command line options from the file
+:file:`<kitty config dir>/macos-launch-services-cmdline` when it is launched
+from the GUI, i.e. by clicking the |kitty| application icon or using ``open -a kitty``.
+Note that this file is *only read* when running via the GUI.
+
+You can, of course, also run |kitty| from a terminal with command line options, using:
+:file:`/Applications/kitty.app/Contents/MacOS/kitty`.
+
+And within |kitty| itself, you can always run |kitty| using just `kitty` as it
+cleverly adds itself to the ``PATH``.
+
+
+kitty is not able to use my favorite font?
+---------------------------------------------
+
+|kitty| achieves its stellar performance by caching alpha masks of each rendered
+character on the GPU, so that every character needs to be rendered only once.
+This means it is a strictly character cell based display.  As such it can use
+only monospace fonts, since every cell in the grid has to be the same size. If
+your font is not listed in ``kitty list-fonts`` it means that it is not
+monospace. On Linux you can list all monospace fonts with::
+
+    fc-list : family spacing outline scalable | grep -e spacing=100 -e spacing=90 | grep -e outline=True | grep -e scalable=True
+
+Note that the spacing property is calculated by fontconfig based on actual
+glyph widths in the font. If for some reason fontconfig concludes your favorite
+monospace font does not have ``spacing=100`` you can override it by using the
+following :file:`~/.config/fontconfig/fonts.conf`::
+
+    <?xml version="1.0"?>
+    <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+    <fontconfig>
+    <match target="font">
+        <test name="family">
+            <string>Your Font Family Name</string>
+        </test>
+        <edit name="spacing">
+            <int>100</int>
+        </edit>
+    </match>
+    </fontconfig>
+
+After creating (or modifying) this file, you may need to run the following
+command to rebuild your fontconfig cache::
+
+    fc-cache -r
+
+Then, the font will be available in ``kitty list-fonts``.
+
+
+How can I assign a single global shortcut to bring up the kitty terminal?
+-----------------------------------------------------------------------------
+
+Bringing up applications on a single key press is the job of the window
+manager/desktop environment. For ways to do it with kitty (or indeed any
+terminal) in different environments,
+see `here <https://github.com/kovidgoyal/kitty/issues/45>`_.
+
+
+How do I map key presses in kitty to different keys in the terminal program?
+--------------------------------------------------------------------------------------
+
+This is accomplished by using ``map`` with :sc:`send_text <send_text>` in :file:`kitty.conf`.
+For example::
+
+    map alt+s send_text all \x13
+
+This maps :kbd:`alt+s` to :kbd:`ctrl+s`. To figure out what bytes to use for
+the :sc:`send_text <send_text>` you can use the ``showkey`` utility. Run::
+
+    showkey -a
+
+Then press the key you want to emulate. On macOS, this utility is currently not
+available. The manual way to figure it out is:
+
+    1. Look up your key's decimal value in the table at the bottom of `this
+       page <http://ascii-table.com/ansi-escape-sequences.php>`_ or any
+       ANSI escape sequence table. There are different modifiers for :kbd:`ctrl`,
+       :kbd:`alt`, etc. For e.g., for :kbd:`ctrl+s`, find the ``S`` row and look at
+       the third column value, ``19``.
+
+    2. Convert the decimal value to hex with ``kitty +runpy "print(hex(19))"``.
+       This shows the hex value, ``13`` in this case.
+
+    3. Use ``\x(hexval)`` in your ``send_text`` command in kitty. So in this example, ``\x13``
+
+
+I am using tmux and have a problem
+--------------------------------------
+
+First, terminal multiplexers are `a bad idea
+<https://github.com/kovidgoyal/kitty/issues/391#issuecomment-638320745>`_, do
+not use them, if at all possible. kitty contains features that do all of what
+tmux does, but better, with the exception of remote persistence (:iss:`391`).
+If you still want to use tmux, read on.
+
+Image display will not work, see `tmux issue
+<https://github.com/tmux/tmux/issues/1391>`_.
+
+If you are using tmux with multiple terminals or you start it under one
+terminal and then switch to another and these terminals have different TERM
+variables, tmux will break. You will need to restart it as tmux does not
+support multiple terminfo definitions.
+
+Copying to clipboard via OSC 52 will not work, because tmux does not support
+the extended version of that protocol, you will need to add ``no-append`` to
+:opt:`clipboard_control` in kitty.conf.
+
+If you use any of the advanced features that kitty has innovated, such as
+styled underlines, desktop notifications, extended keyboard support, etc.
+they may or may not work, depending on the whims of tmux's maintainer, your
+version of tmux, etc.

docs/graphics-protocol.rst

@@ -0,0 +1,479 @@
+:tocdepth: 3
+
+The terminal graphics protocol
+==================================
+
+The goal of this specification is to create a flexible and performant protocol
+that allows the program running in the terminal, hereafter called the *client*,
+to render arbitrary pixel (raster) graphics to the screen of the terminal
+emulator. The major design goals are
+
+ * Should not require terminal emulators to understand image formats.
+ * Should allow specifying graphics to be drawn at individual pixel positions.
+ * The graphics should integrate with the text, in particular it should be possible to draw graphics
+   below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically.
+ * Should use optimizations when the client is running on the same computer as the terminal emulator.
+
+For some discussion regarding the design choices, see `#33
+<https://github.com/kovidgoyal/kitty/issues/33>`_.
+
+To see a quick demo, inside a |kitty| terminal run::
+
+    kitty +kitten icat path/to/some/image.png
+
+You can also see a screenshot with more sophisticated features such as
+alpha-blending and text over graphics.
+
+.. image:: https://user-images.githubusercontent.com/1308621/31647475-1188ab66-b326-11e7-8d26-24b937f1c3e8.png
+    :alt: Demo of graphics rendering in kitty
+    :align: center
+
+Some programs that use the kitty graphics protocol:
+
+ * `termpdf.py <https://github.com/dsanson/termpdf.py>`_ - a terminal PDF/DJVU/CBR viewer
+ * `ranger <https://github.com/ranger/ranger>`_ - a terminal file manager, with
+   image previews, see this `PR <https://github.com/ranger/ranger/pull/1077>`_
+ * :doc:`kitty-diff <kittens/diff>` - a side-by-side terminal diff program with support for images
+ * `pixcat <https://github.com/mirukana/pixcat>`_ - a third party CLI and python library that wraps the graphics protocol
+ * `neofetch <https://github.com/dylanaraps/neofetch>`_ - A command line system
+   information tool
+
+
+.. contents::
+
+
+Getting the window size
+-------------------------
+
+In order to know what size of images to display and how to position them, the
+client must be able to get the window size in pixels and the number of cells
+per row and column. This can be done by using the ``TIOCGWINSZ`` ioctl.  Some
+code to demonstrate its use
+
+In C:
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <sys/ioctl.h>
+
+    int main(int argc, char **argv) {
+        struct winsize sz;
+        ioctl(0, TIOCGWINSZ, &sz);
+        printf("number of rows: %i, number of columns: %i, screen width: %i, screen height: %i\n", sz.ws_row, sz.ws_col, sz.ws_xpixel, sz.ws_ypixel);
+        return 0;
+    }
+
+In Python:
+
+.. code-block:: python
+
+    import array, fcntl, sys, termios
+    buf = array.array('H', [0, 0, 0, 0])
+    fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, buf)
+    print('number of rows: {}, number of columns: {}, screen width: {}, screen height: {}'.format(*buf))
+
+Note that some terminals return ``0`` for the width and height values. Such
+terminals should be modified to return the correct values.  Examples of
+terminals that return correct values: ``kitty, xterm``
+
+You can also use the *CSI t* escape code to get the screen size. Send
+``<ESC>[14t`` to ``STDOUT`` and kitty will reply on ``STDIN`` with
+``<ESC>[4;<height>;<width>t`` where ``height`` and ``width`` are the window
+size in pixels. This escape code is supported in many terminals, not just
+kitty.
+
+A minimal example
+------------------
+
+Some minimal python code to display PNG images in kitty, using the most basic
+features of the graphics protocol:
+
+.. code-block:: python
+
+   import sys
+   from base64 import standard_b64encode
+
+   def serialize_gr_command(cmd, payload=None):
+      cmd = ','.join('{}={}'.format(k, v) for k, v in cmd.items())
+      ans = []
+      w = ans.append
+      w(b'\033_G'), w(cmd.encode('ascii'))
+      if payload:
+         w(b';')
+         w(payload)
+      w(b'\033\\')
+      return b''.join(ans)
+
+   def write_chunked(cmd, data):
+      data = standard_b64encode(data)
+      while data:
+         chunk, data = data[:4096], data[4096:]
+         m = 1 if data else 0
+         cmd['m'] = m
+         sys.stdout.buffer.write(serialize_gr_command(cmd, chunk))
+         sys.stdout.flush()
+         cmd.clear()
+
+   with open(sys.argv[-1], 'rb') as f:
+      write_chunked({'a': 'T', 'f': 100}, f.read())
+
+
+Save this script as :file:`png.py`, then you can use it to display any PNG
+file in kitty as::
+
+   python png.py file.png
+
+
+The graphics escape code
+---------------------------
+
+All graphics escape codes are of the form::
+
+    <ESC>_G<control data>;<payload><ESC>\
+
+This is a so-called *Application Programming Command (APC)*. Most terminal
+emulators ignore APC codes, making it safe to use.
+
+The control data is a comma-separated list of ``key=value`` pairs.  The payload
+is arbitrary binary data, base64-encoded to prevent interoperation problems
+with legacy terminals that get confused by control codes within an APC code.
+The meaning of the payload is interpreted based on the control data.
+
+The first step is to transmit the actual image data.
+
+Transferring pixel data
+--------------------------
+
+The first consideration when transferring data between the client and the
+terminal emulator is the format in which to do so. Since there is a vast and
+growing number of image formats in existence, it does not make sense to have
+every terminal emulator implement support for them. Instead, the client should
+send simple pixel data to the terminal emulator. The obvious downside to this
+is performance, especially when the client is running on a remote machine.
+Techniques for remedying this limitation are discussed later. The terminal
+emulator must understand pixel data in three formats, 24-bit RGB, 32-bit RGBA and
+PNG. This is specified using the ``f`` key in the control data. ``f=32`` (which is the
+default) indicates 32-bit RGBA data and ``f=24`` indicates 24-bit RGB data and ``f=100``
+indicates PNG data. The PNG format is supported for convenience and a compact way
+of transmitting paletted images.
+
+RGB and RGBA data
+~~~~~~~~~~~~~~~~~~~
+
+In these formats the pixel data is stored directly as 3 or 4 bytes per pixel,
+respectively. The colors in the data **must** be in the *sRGB color space*.  When
+specifying images in this format, the image dimensions **must** be sent in the
+control data. For example::
+
+    <ESC>_Gf=24,s=10,v=20;<payload><ESC>\
+
+Here the width and height are specified using the ``s`` and ``v`` keys respectively. Since
+``f=24`` there are three bytes per pixel and therefore the pixel data must be ``3 * 10 * 20 = 600``
+bytes.
+
+PNG data
+~~~~~~~~~~~~~~~
+
+In this format any PNG image can be transmitted directly.  For example::
+
+    <ESC>_Gf=100;<payload><ESC>\
+
+
+The PNG format is specified using the ``f=100`` key. The width and height of
+the image will be read from the PNG data itself. Note that if you use both PNG and
+compression, then you must provide the ``S`` key with the size of the PNG data.
+
+
+Compression
+~~~~~~~~~~~~~
+
+The client can send compressed image data to the terminal emulator, by specifying the
+``o`` key. Currently, only zlib based deflate compression is supported, which is specified using
+``o=z``. For example::
+
+    <ESC>_Gf=24,s=10,v=20,o=z;<payload><ESC>\
+
+This is the same as the example from the RGB data section, except that the
+payload is now compressed using deflate. The terminal emulator will decompress
+it before rendering. You can specify compression for any format. The terminal
+emulator will decompress before interpreting the pixel data.
+
+
+The transmission medium
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The transmission medium is specified using the ``t`` key. The ``t`` key defaults to ``d``
+and can take the values:
+
+==================    ============
+Value of `t`          Meaning
+==================    ============
+``d``                 Direct (the data is transmitted within the escape code itself)
+``f``                 A simple file
+``t``                 A temporary file, the terminal emulator will delete the file after reading the pixel data. For security reasons
+                      the terminal emulator should only delete the file if it
+                      is in a known temporary directory, such as :file:`/tmp`,
+                      :file:`/dev/shm`, :file:`TMPDIR env var if present` and any platform
+                      specific temporary directories.
+``s``                 A `POSIX shared memory object <http://man7.org/linux/man-pages/man7/shm_overview.7.html>`_.
+                      The terminal emulator will delete it after reading the pixel data
+==================    ============
+
+Local client
+^^^^^^^^^^^^^^
+
+First let us consider the local client techniques (files and shared memory). Some examples::
+
+    <ESC>_Gf=100,t=f;<encoded /path/to/file.png><ESC>\
+
+Here we tell the terminal emulator to read PNG data from the specified file of
+the specified size::
+
+    <ESC>_Gs=10,v=2,t=s,o=z;<encoded /some-shared-memory-name><ESC>\
+
+Here we tell the terminal emulator to read compressed image data from
+the specified shared memory object.
+
+The client can also specify a size and offset to tell the terminal emulator
+to only read a part of the specified file. The is done using the ``S`` and ``O``
+keys respectively. For example::
+
+    <ESC>_Gs=10,v=2,t=s,S=80,O=10;<encoded /some-shared-memory-name><ESC>\
+
+This tells the terminal emulator to read ``80`` bytes starting from the offset ``10``
+inside the specified shared memory buffer.
+
+
+Remote client
+^^^^^^^^^^^^^^^^
+
+Remote clients, those that are unable to use the filesystem/shared memory to
+transmit data, must send the pixel data directly using escape codes. Since
+escape codes are of limited maximum length, the data will need to be chunked up
+for transfer. This is done using the ``m`` key. The pixel data must first be
+base64 encoded then chunked up into chunks no larger than ``4096`` bytes. The client
+then sends the graphics escape code as usual, with the addition of an ``m`` key that
+must have the value ``1`` for all but the last chunk, where it must be ``0``. For example,
+if the data is split into three chunks, the client would send the following
+sequence of escape codes to the terminal emulator::
+
+    <ESC>_Gs=100,v=30,m=1;<encoded pixel data first chunk><ESC>\
+    <ESC>_Gm=1;<encoded pixel data second chunk><ESC>\
+    <ESC>_Gm=0;<encoded pixel data last chunk><ESC>\
+
+Note that only the first escape code needs to have the full set of control
+codes such as width, height, format etc. Subsequent chunks must have
+only the ``m`` key. The client **must** finish sending all chunks for a single image
+before sending any other graphics related escape codes. Note that the cursor
+position used to display the image **must** be the position when the final chunk is
+received. Finally, terminals must not display anything, until the entire sequence is
+received and validated.
+
+
+Querying support and available transmission mediums
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since a client has no a-priori knowledge of whether it shares a filesystem/shared memory
+with the terminal emulator, it can send an id with the control data, using the ``i`` key
+(which can be an arbitrary positive integer up to 4294967295, it must not be zero).
+If it does so, the terminal emulator will reply after trying to load the image, saying
+whether loading was successful or not. For example::
+
+    <ESC>_Gi=31,s=10,v=2,t=s;<encoded /some-shared-memory-name><ESC>\
+
+to which the terminal emulator will reply (after trying to load the data)::
+
+    <ESC>_Gi=31;error message or OK<ESC>\
+
+Here the ``i`` value will be the same as was sent by the client in the original
+request.  The message data will be a ASCII encoded string containing only
+printable characters and spaces. The string will be ``OK`` if reading the pixel
+data succeeded or an error message.
+
+Sometimes, using an id is not appropriate, for example, if you do not want to
+replace a previously sent image with the same id, or if you are sending a dummy
+image and do not want it stored by the terminal emulator. In that case, you can
+use the *query action*, set ``a=q``. Then the terminal emulator will try to load
+the image and respond with either OK or an error, as above, but it will not
+replace an existing image with the same id, nor will it store the image.
+
+While as of May 2020, kitty is the only terminal emulator to support this
+graphics protocol, we intend that any terminal emulator that wishes to support
+it can. To check if a terminal emulator supports the graphics protocol the best way
+is to send the above *query action* followed by a request for the
+`primary device attributes <https://vt100.net/docs/vt510-rm/DA1.html>`. If you
+get back an answer for the device attributes without getting back an answer for
+the *query action* the terminal emulator does not support the graphics
+protocol.
+
+This means that terminal emulators that support the graphics protocol, **must**
+reply to *query actions* immediately without processing other input. Most
+terminal emulators handle input in a FIFO manner, anyway.
+
+So for example, you could send::
+
+      <ESC>_Gi=31,s=1,v=1,a=q,t=d,f=24;<NUL><NUL><NUL><ESC>\<ESC>[c
+
+If you get back a response to the graphics query, the terminal emulator supports
+the protocol, if you get back a response to the device attributes query without
+a response to the graphics query, it does not.
+
+
+Display images on screen
+-----------------------------
+
+Every transmitted image can be displayed an arbitrary number of times on the
+screen, in different locations, using different parts of the source image, as
+needed. You can either simultaneously transmit and display an image using the
+action ``a=T``, or first transmit the image with a id, such as ``i=10`` and then display
+it with ``a=p,i=10`` which will display the previously transmitted image at the current
+cursor position. When specifying an image id, the terminal emulator will reply with an
+acknowledgement code, which will be either::
+
+    <ESC>_Gi=<id>;OK<ESC>\
+
+when the image referred to by id was found, or::
+
+    <ESC>_Gi=<id>;ENOENT:<some detailed error msg><ESC>\
+
+when the image with the specified id was not found. This is similar to the
+scheme described above for querying available transmission media, except that
+here we are querying if the image with the specified id is available or needs to
+be re-transmitted.
+
+Controlling displayed image layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The image is rendered at the current cursor position, from the upper left corner of
+the current cell. You can also specify extra ``X=3`` and ``Y=4`` pixel offsets to display from
+a different origin within the cell. Note that the offsets must be smaller that the size of the cell.
+
+By default, the entire image will be displayed (images wider than the available
+width will be truncated on the right edge). You can choose a source rectangle (in pixels)
+as the part of the image to display. This is done with the keys: ``x, y, w, h`` which specify
+the top-left corner, width and height of the source rectangle.
+
+You can also ask the terminal emulator to display the image in a specified rectangle
+(num of columns / num of lines), using the control codes ``c,r``. ``c`` is the number of columns
+and `r` the number of rows. The image will be scaled (enlarged/shrunk) as needed to fit
+the specified area. Note that if you specify a start cell offset via the ``X,Y`` keys, it is not
+added to the number of rows/columns.
+
+Finally, you can specify the image *z-index*, i.e. the vertical stacking order. Images
+placed in the same location with different z-index values will be blended if
+they are semi-transparent. You can specify z-index values using the ``z`` key.
+Negative z-index values mean that the images will be drawn under the text. This
+allows rendering of text on top of images. Negative z-index values below
+INT32_MIN/2 (-1,073,741,824) will be drawn under cells with non-default background
+colors.
+
+Deleting images
+---------------------
+
+Images can be deleted by using the delete action ``a=d``. If specified without any
+other keys, it will delete all images visible on screen. To delete specific images,
+use the `d` key as described in the table below. Note that each value of d has
+both a lowercase and an uppercase variant. The lowercase variant only deletes the
+images without necessarily freeing up the stored image data, so that the images can be
+re-displayed without needing to resend the data. The uppercase variants will delete
+the image data as well, provided that the image is not referenced elsewhere, such as in the
+scrollback buffer. The values of the ``x`` and ``y`` keys are the same as cursor positions (i.e.
+``x=1, y=1`` is the top left cell).
+
+=================    ============
+Value of ``d``       Meaning
+=================    ============
+``a`` or ``A``       Delete all images visible on screen
+``i`` or ``I``       Delete all images with the specified id, specified using the ``i`` key.
+``c`` or ``C``       Delete all images that intersect with the current cursor position.
+``p`` or ``P``       Delete all images that intersect a specific cell, the cell is specified using the ``x`` and ``y`` keys
+``q`` or ``Q``       Delete all images that intersect a specific cell having a specific z-index. The cell and z-index is specified using the ``x``, ``y`` and ``z`` keys.
+``x`` or ``X``       Delete all images that intersect the specified column, specified using the ``x`` key.
+``y`` or ``Y``       Delete all images that intersect the specified row, specified using the ``y`` key.
+``z`` or ``Z``       Delete all images that have the specified z-index, specified using the ``z`` key.
+=================    ============
+
+
+
+Some examples::
+
+    <ESC>_Ga=d<ESC>\             # delete all visible images
+    <ESC>_Ga=d,d=i,i=10<ESC>\    # delete the image with id=10, without freeing data
+    <ESC>_Ga=d,d=Z,z=-1<ESC>\    # delete the images with z-index -1, also freeing up image data
+    <ESC>_Ga=d,d=p,x=3,y=4<ESC>\ # delete all images that intersect the cell at (3, 4), without freeing data
+
+Image persistence and storage quotas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to avoid *Denial-of-Service* attacks, terminal emulators should have a
+maximum storage quota for image data. It should allow at least a few full
+screen images.  For example the quota in kitty is 320MB per buffer. When adding
+a new image, if the total size exceeds the quota, the terminal emulator should
+delete older images to make space for the new one.
+
+
+Control data reference
+---------------------------
+
+The table below shows all the control data keys as well as what values they can
+take, and the default value they take when missing. All integers are 32-bit.
+
+=======  ====================  =========  =================
+Key      Value                 Default    Description
+=======  ====================  =========  =================
+``a``    Single character.     ``t``      The overall action this graphics command is performing.
+         ``(t, T, q, p, d)``
+**Keys for image transmission**
+-----------------------------------------------------------
+``f``    Positive integer.     ``32``     The format in which the image data is sent.
+         ``(24, 32, 100)``.
+``t``    Single character.     ``d``      The transmission medium used.
+         ``(d, f, t, s)``.
+``s``    Positive integer.     ``0``      The width of the image being sent.
+``v``    Positive integer.     ``0``      The height of the image being sent.
+``S``    Positive integer.     ``0``      The size of data to read from a file.
+``O``    Positive integer.     ``0``      The offset from which to read data from a file.
+``i``    Positive integer.
+         ``(0 - 4294967295)``  ``0``      The image id
+``o``    Single character.     ``null``   The type of data compression.
+         ``only z``
+``m``    zero or one           ``0``      Whether there is more chunked data available.
+**Keys for image display**
+-----------------------------------------------------------
+``x``    Positive integer      ``0``      The left edge (in pixels) of the image area to display
+``y``    Positive integer      ``0``      The top edge (in pixels) of the image area to display
+``w``    Positive integer      ``0``      The width (in pixels) of the image area to display. By default, the entire width is used.
+``h``    Positive integer      ``0``      The height (in pixels) of the image area to display. By default, the entire height is used
+``X``    Positive integer      ``0``      The x-offset within the first cell at which to start displaying the image
+``Y``    Positive integer      ``0``      The y-offset within the first cell at which to start displaying the image
+``c``    Positive integer      ``0``      The number of columns to display the image over
+``r``    Positive integer      ``0``      The number of rows to display the image over
+``z``    32-bit integer        ``0``      The *z-index* vertical stacking order of the image
+**Keys for deleting images**
+-----------------------------------------------------------
+``d``    Single character.     ``a``      What to delete.
+         ``(a, A, c, C, i,
+         I, p, P, q, Q, x, X,
+         y, Y, z, Z)``.
+=======  ====================  =========  =================
+
+
+Interaction with other terminal actions
+--------------------------------------------
+
+When resetting the terminal, all images that are visible on the screen must be
+cleared.  When switching from the main screen to the alternate screen buffer
+(1049 private mode) all images in the alternate screen must be cleared, just as
+all text is cleared. The clear screen escape code (usually ``<ESC>[2J``) should
+also clear all images. This is so that the clear command works.
+
+The other commands to erase text must have no effect on graphics.
+The dedicated delete graphics commands must be used for those.
+
+When scrolling the screen (such as when using index cursor movement commands,
+or scrolling through the history buffer), images must be scrolled along with
+text. When page margins are defined and the index commands are used, only
+images that are entirely within the page area (between the margins) must be
+scrolled. When scrolling them would cause them to extend outside the page area,
+they must be clipped.

docs/index.rst

@@ -0,0 +1,526 @@
+:tocdepth: 2
+
+==========================================================
+kitty - the fast, featureful, GPU based terminal emulator
+==========================================================
+
+.. container:: major-features
+
+    * Offloads rendering to the GPU for :doc:`lower system load <performance>` and
+      buttery smooth scrolling.  Uses threaded rendering to minimize input latency.
+
+    * Supports all modern terminal features: :doc:`graphics (images)
+      <graphics-protocol>`, unicode, `true-color
+      <https://gist.github.com/XVilka/8346728>`_,
+      OpenType ligatures, mouse protocol, :doc:`hyperlinks <open_actions>`,
+      focus tracking, `bracketed paste <https://cirw.in/blog/bracketed-paste>`_
+      and several :doc:`new terminal protocol extensions
+      <protocol-extensions>`.
+
+    * Supports tiling multiple terminal windows side by side in different
+      :ref:`layouts <layouts>` without needing to use an extra program like tmux
+
+    * Can be :doc:`controlled from scripts or the shell prompt <remote-control>`,
+      even over SSH.
+
+    * Has a framework for :ref:`kittens`, small terminal programs that can be used to
+      extend |kitty|'s functionality.  For example, they are used for
+      :doc:`Unicode input <kittens/unicode-input>`, :doc:`Hints <kittens/hints>` and
+      :doc:`Side-by-side diff <kittens/diff>`.
+
+    * Supports :ref:`startup sessions <sessions>` which allow you to specify
+      the window/tab layout, working directories and programs to run on startup.
+
+    * Cross-platform: |kitty| works on Linux and macOS, but because it uses only
+      OpenGL for rendering, it should be trivial to port to other Unix-like platforms.
+
+    * Allows you to open :ref:`the scrollback buffer <scrollback>` in a
+      separate window using arbitrary programs of your choice. This is useful for
+      browsing the history comfortably in a pager or editor.
+
+    * Has :ref:`multiple copy/paste buffers <cpbuf>`, like vim.
+
+
+.. figure:: screenshots/screenshot.png
+    :alt: Screenshot, showing three programs in the 'Tall' layout
+    :align: center
+    :scale: 100%
+
+    Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
+
+
+.. _quickstart:
+
+Quickstart
+--------------
+
+Pre-built binaries of |kitty| are available for both macOS and Linux.
+See the :doc:`binary install instructions </binary>`. You can
+:doc:`build from source </build>`.
+
+You can also use your favorite package manager to install the |kitty| package.
+|kitty| packages are available for:
+`macOS with Homebrew (Cask) <https://formulae.brew.sh/cask/kitty>`_,
+`macOS and Linux with Nix <https://nixos.org/nixos/packages.html?channel=nixpkgs-unstable&query=kitty>`_,
+`Ubuntu <https://launchpad.net/ubuntu/+source/kitty>`_,
+`Debian <https://packages.debian.org/buster/kitty>`_,
+`openSUSE <https://build.opensuse.org/package/show/X11:terminals/kitty>`_,
+`Arch Linux <https://www.archlinux.org/packages/community/x86_64/kitty/>`_,
+`Gentoo <https://packages.gentoo.org/packages/x11-terms/kitty>`_,
+`Fedora <https://src.fedoraproject.org/rpms/kitty>`_,
+`Void Linux <https://github.com/void-linux/void-packages/blob/master/srcpkgs/kitty/template>`_,
+and `Solus <https://dev.getsol.us/source/kitty/>`_.
+
+See :doc:`Configuring kitty <conf>` for help on configuring |kitty| and
+:doc:`Invocation <invocation>` for the command line arguments |kitty| supports.
+
+
+.. contents::
+
+
+Design philosophy
+-------------------
+
+|kitty| is designed for power keyboard users. To that end all its controls
+work with the keyboard (although it fully supports mouse interactions as
+well). Its configuration is a simple, human editable, single file for
+easy reproducibility (I like to store configuration in source control).
+
+The code in |kitty| is designed to be simple, modular and hackable. It is
+written in a mix of C (for performance sensitive parts) and Python (for
+easy hackability of the UI). It does not depend on any large and complex
+UI toolkit, using only OpenGL for rendering everything.
+
+Finally, |kitty| is designed from the ground up to support all modern
+terminal features, such as unicode, true color, bold/italic fonts, text
+formatting, etc. It even extends existing text formatting escape codes,
+to add support for features not available elsewhere, such as colored and
+styled (curly) underlines. One of the design goals of |kitty| is to be
+easily extensible so that new features can be added in the future with
+relatively little effort.
+
+Tabs and Windows
+-------------------
+
+|kitty| is capable of running multiple programs organized into tabs and
+windows. The top level of organization is the *Tab*. Each tab consists
+of one or more *windows*. The windows can be arranged in multiple
+different layouts, like windows are organized in a tiling window
+manager. The keyboard controls (which are all customizable) for tabs and
+windows are:
+
+Scrolling
+~~~~~~~~~~~~~~
+
+========================    =======================
+Action                      Shortcut
+========================    =======================
+Scroll line up              :sc:`scroll_line_up` (also :kbd:`⌥+⌘+⇞` and :kbd:`⌘+↑` on macOS)
+Scroll line down            :sc:`scroll_line_down` (also :kbd:`⌥+⌘+⇟` and :kbd:`⌘+↓` on macOS)
+Scroll page up              :sc:`scroll_page_up` (also :kbd:`⌘+⇞` on macOS)
+Scroll page down            :sc:`scroll_page_down` (also :kbd:`⌘+⇟` on macOS)
+Scroll to top               :sc:`scroll_home` (also :kbd:`⌘+↖` on macOS)
+Scroll to bottom            :sc:`scroll_end` (also :kbd:`⌘+↘` on macOS)
+========================    =======================
+
+Tabs
+~~~~~~~~~~~
+
+========================    =======================
+Action                      Shortcut
+========================    =======================
+New tab                     :sc:`new_tab` (also :kbd:`⌘+t` on macOS)
+Close tab                   :sc:`close_tab` (also :kbd:`⌘+w` on macOS)
+Next tab                    :sc:`next_tab` (also :kbd:`^+⇥` and :kbd:`⇧+⌘+]` on macOS)
+Previous tab                :sc:`previous_tab` (also :kbd:`⇧+^+⇥` and :kbd:`⇧+⌘+[` on macOS)
+Next layout                 :sc:`next_layout`
+Move tab forward            :sc:`move_tab_forward`
+Move tab backward           :sc:`move_tab_backward`
+Set tab title               :sc:`set_tab_title` (also :kbd:`⇧+⌘+i` on macOS)
+========================    =======================
+
+
+Windows
+~~~~~~~~~~~~~~~~~~
+
+========================    =======================
+Action                      Shortcut
+========================    =======================
+New window                  :sc:`new_window` (also :kbd:`⌘+↩` on macOS)
+New OS window               :sc:`new_os_window` (also :kbd:`⌘+n` on macOS)
+Close window                :sc:`close_window` (also :kbd:`⇧+⌘+d` on macOS)
+Next window                 :sc:`next_window`
+Previous window             :sc:`previous_window`
+Move window forward         :sc:`move_window_forward`
+Move window backward        :sc:`move_window_backward`
+Move window to top          :sc:`move_window_to_top`
+Focus specific window       :sc:`first_window`, :sc:`second_window` ... :sc:`tenth_window`
+                            (also :kbd:`⌘+1`, :kbd:`⌘+2` ... :kbd:`⌘+9` on macOS)
+                            (clockwise from the top-left)
+========================    =======================
+
+Additionally, you can define shortcuts in :file:`kitty.conf` to focus neighboring
+windows and move windows around (similar to window movement in vim)::
+
+   map ctrl+left neighboring_window left
+   map shift+left move_window right
+   map ctrl+down neighboring_window down
+   map shift+down move_window up
+   ...
+
+You can also define a shortcut to switch to the previously active window::
+
+   map ctrl+p nth_window -1
+
+``nth_window`` will focus the nth window for positive numbers and the
+previously active windows for negative numbers.
+
+.. _detach_window:
+
+You can define shortcuts to detach the current window and
+move it to another tab or another OS window::
+
+    # moves the window into a new OS window
+    map ctrl+f2 detach_window
+    # moves the window into a new Tab
+    map ctrl+f3 detach_window new-tab
+    # asks which tab to move the window into
+    map ctrl+f4 detach_window ask
+
+Similarly, you can detach the current tab, with::
+
+    # moves the tab into a new OS window
+    map ctrl+f2 detach_tab
+    # asks which OS Window to move the tab into
+    map ctrl+f4 detach_tab ask
+
+Finally, you can define a shortcut to close all windows in a tab other than
+the currently active window::
+
+    map f9 close_other_windows_in_tab
+
+
+Other keyboard shortcuts
+----------------------------------
+
+==================================  =======================
+Action                              Shortcut
+==================================  =======================
+Copy to clipboard                   :sc:`copy_to_clipboard` (also :kbd:`⌘+c` on macOS)
+Paste from clipboard                :sc:`paste_from_clipboard` (also :kbd:`⌘+v` on macOS)
+Paste from selection                :sc:`paste_from_selection`
+Increase font size                  :sc:`increase_font_size` (also :kbd:`⌘++` on macOS)
+Decrease font size                  :sc:`decrease_font_size` (also :kbd:`⌘+-` on macOS)
+Restore font size                   :sc:`reset_font_size` (also :kbd:`⌘+0` on macOS)
+Toggle fullscreen                   :sc:`toggle_fullscreen` (also :kbd:`^+⌘+f` on macOS)
+Toggle maximized                    :sc:`toggle_maximized`
+Input unicode character             :sc:`input_unicode_character`
+Click URL using the keyboard        :sc:`open_url`
+Reset the terminal                  :sc:`reset_terminal`
+Pass current selection to program   :sc:`pass_selection_to_program`
+Edit |kitty| config file            :sc:`edit_config_file`
+Open a |kitty| shell                :sc:`kitty_shell`
+Increase background opacity         :sc:`increase_background_opacity`
+Decrease background opacity         :sc:`decrease_background_opacity`
+Full background opacity             :sc:`full_background_opacity`
+Reset background opacity            :sc:`reset_background_opacity`
+==================================  =======================
+
+
+.. _layouts:
+
+Layouts
+----------
+
+A layout is an arrangement of multiple kitty *windows* inside a top-level OS window. You can create a new window
+using the :sc:`new_window` key combination.
+
+Currently, there are six layouts available:
+
+* **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom
+* **Grid** -- All windows are shown in a grid
+* **Horizontal** -- All windows are shown side-by-side
+* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits
+* **Stack** -- Only a single maximized window is shown at a time
+* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right
+* **Vertical** -- All windows are shown one below the other
+
+By default, all layouts are enabled and you can switch between layouts using
+the :sc:`next_layout` key combination. You can also create shortcuts to select
+particular layouts, and choose which layouts you want to enable/disable, see
+:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in
+:opt:`enabled_layouts` becomes the default layout.
+
+For more details on the layouts and how to use them see :doc:`layouts`.
+
+.. _kittens:
+
+Kittens
+------------------
+
+|kitty| has a framework for easily creating terminal programs that make use of
+its advanced features. These programs are called kittens. They are used both
+to add features to |kitty| itself and to create useful standalone programs.
+Some prominent kittens:
+
+:doc:`icat <kittens/icat>`
+    Display images in the terminal
+
+
+:doc:`diff <kittens/diff>`
+    A fast, side-by-side diff for the terminal with syntax highlighting and
+    images
+
+
+:doc:`Unicode Input <kittens/unicode-input>`
+    Easily input arbitrary unicode characters in |kitty| by name or hex code.
+
+
+:doc:`Hints <kittens/hints>`
+    Select and open/paste/insert arbitrary text snippets such as URLs,
+    filenames, words, lines, etc from the terminal screen.
+
+
+:doc:`Panel <kittens/panel>`
+    Draw a GPU accelerated dock panel on your desktop showing the output
+    from an arbitrary terminal program.
+
+:doc:`Clipboard <kittens/clipboard>`
+    Copy/paste to the clipboard from shell scripts, even over SSH.
+
+You can also :doc:`Learn to create your own kittens <kittens/custom>`.
+
+
+Configuring kitty
+-------------------
+
+|kitty| is highly configurable, everything from keyboard shortcuts to
+painting frames-per-second. For details and a sample :file:`kitty.conf`,
+see the :doc:`configuration docs <conf>`.
+
+
+Remote control
+------------------
+
+|kitty| has a very powerful system that allows you to control it from the
+:doc:`shell prompt, even over SSH <remote-control>`. You can change colors,
+fonts, open new windows, tabs, set their titles, change window layout, get text
+from one window and send text to another, etc, etc. The possibilities are
+endless. See the :doc:`tutorial <remote-control>` to get started.
+
+.. _sessions:
+
+Startup Sessions
+------------------
+
+You can control the tabs, window layout, working directory, startup programs,
+etc. by creating a "session" file and using the :option:`kitty --session`
+command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
+For example:
+
+.. code-block:: session
+
+    # Set the window layout for the current tab
+    layout tall
+    # Set the working directory for windows in the current tab
+    cd ~
+    # Create a window and run the specified command in it
+    launch zsh
+    # Create a window with some environment variables set and run
+    # vim in it
+    launch env FOO=BAR vim
+    # Set the title for the next window
+    title Chat with x
+    launch irssi --profile x
+
+    # Create a new tab (the part after new_tab is the optional tab
+    # name which will be displayed in the tab bar, if omitted, the
+    # title of the active window will be used instead)
+    new_tab my tab
+    cd ~/somewhere
+    # Set the layouts allowed in this tab
+    enabled_layouts tall, stack
+    # Set the current layout
+    layout stack
+    launch zsh
+
+    # Create a new OS window
+    new_os_window
+    # set new window size to 80x25 cells
+    os_window_size 80c 25c
+    # set the --class for the new OS window
+    os_window_class mywindow
+    launch sh
+    # Make the current window the active (focused) window
+    focus
+    launch emacs
+
+    # Add a watcher that will be called with various events that occur
+    # on all subsequent windows. See the documentation of the launch command
+    # for details on watchers.
+    watcher /some/python/file.py
+    launch mpd
+    launch irssi
+    # Remove the watcher for further windows
+    watcher clear
+
+
+Mouse features
+-------------------
+
+* You can hold down :kbd:`ctrl+shift` and click on a URL to open it in a browser.
+* You can double click to select a word and then drag to select more words.
+* You can triple click to select a line and then drag to select more lines.
+* You can right click to extend a previous selection.
+* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in
+  columns (see also :opt:`rectangle_select_modifiers`).
+* Selecting text automatically copies it to the primary clipboard (on
+  platforms with a primary clipboard).
+* You can select text with kitty even when a terminal program has grabbed
+  the mouse by holding down the :kbd:`shift` key (see also
+  :opt:`terminal_select_modifiers`).
+
+
+Font control
+-----------------
+
+|kitty| has extremely flexible and powerful font selection features. You can
+specify individual families for the regular, bold, italic and bold+italic
+fonts. You can even specify specific font families for specific ranges of
+unicode characters. This allows precise control over text rendering. It can
+come in handy for applications like powerline, without the need to use patched
+fonts. See the various font related configuration directives in
+:ref:`conf-kitty-fonts`.
+
+
+.. _scrollback:
+
+The scrollback buffer
+-----------------------
+
+|kitty| supports scrolling back to view history, just like most terminals. You
+can use either keyboard shortcuts or the mouse scroll wheel to do so.  However,
+|kitty| has an extra, neat feature. Sometimes you need to explore the
+scrollback buffer in more detail, maybe search for some text or refer to it
+side-by-side while typing in a follow-up command. |kitty| allows you to do this
+by pressing the :sc:`show_scrollback` key-combination, which will open the
+scrollback buffer in your favorite pager program (which is ``less`` by default).
+Colors and text formatting are preserved. You can explore the scrollback buffer
+comfortably within the pager.
+
+Additionally, you can pipe the contents of the scrollback buffer to an
+arbitrary, command running in a new window, tab or overlay, for example::
+
+   map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
+
+Would open the scrollback buffer in a new window when you press the :kbd:`F1`
+key. See :sc:`show_scrollback` for details.
+
+If you wish to store very large amounts of scrollback to view using the piping or
+:sc:`show_scrollback` features, you can use the :opt:`scrollback_pager_history_size`
+option.
+
+.. _cpbuf:
+
+Multiple copy/paste buffers
+-----------------------------
+
+In addition to being able to copy/paste from the system clipboard, in |kitty| you
+can also setup an arbitrary number of copy paste buffers. To do so, simply add
+something like the following to your :file:`kitty.conf`::
+
+   map f1 copy_to_buffer a
+   map f2 paste_from_buffer a
+
+This will allow you to press :kbd:`F1` to copy the current selection to an
+internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
+names are arbitrary strings, so you can define as many such buffers as you
+need.
+
+Marks
+-------------
+
+kitty has the ability to mark text on the screen based on regular expressions.
+This can be useful to highlight words or phrases when browsing output from long
+running programs or similar. To learn how this feature works, see :doc:`marks`.
+
+
+Frequently Asked Questions
+---------------------------------
+
+The list of Frequently Asked Questions (*FAQ*) is :doc:`available here <faq>`.
+
+.. _completion:
+
+
+Cool integrations for kitty with other CLI tools
+--------------------------------------------------
+
+kitty provides extremely powerful interfaces such as :doc:`remote-control` and
+:doc:`kittens/custom` and :doc:`kittens/icat`
+that allow it to be integrated with other tools seamlessly. For a list of such
+user created integrations, see: :doc:`integrations`.
+
+Completion for kitty
+---------------------------------
+
+|kitty| comes with completion for the ``kitty`` command for popular shells.
+
+
+bash
+~~~~~~~~
+
+Add the following to your :file:`~/.bashrc`
+
+.. code-block:: sh
+
+   source <(kitty + complete setup bash)
+
+Older versions of bash (for example, v3.2) do not support
+process substitution with the source command, in which
+case you can try an alternative:
+
+.. code-block:: sh
+
+    source /dev/stdin <<<"$(kitty + complete setup bash)"
+
+
+zsh
+~~~~~~~~~
+
+Add the following to your :file:`~/.zshrc`
+
+.. code-block:: sh
+
+    autoload -Uz compinit
+    compinit
+    # Completion for kitty
+    kitty + complete setup zsh | source /dev/stdin
+
+The important thing above is to make sure the call to |kitty| to load the zsh
+completions happens after the call to :file:`compinit`.
+
+
+fish
+~~~~~~~~
+
+For versions of fish earlier than 3.0.0, add the following to your
+:file:`~/.config/fish/config.fish`. Later versions source completions by default.
+
+.. code-block:: sh
+
+   kitty + complete setup fish | source
+
+
+Changelog
+------------------
+
+See :doc:`changelog`.
+
+.. toctree::
+    :hidden:
+    :glob:
+
+    *
+    kittens/*
+    generated/rc

docs/installer.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+import atexit
+import json
+import os
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+
+py3 = sys.version_info[0] > 2
+is64bit = platform.architecture()[0] == '64bit'
+is_macos = 'darwin' in sys.platform.lower()
+if is_macos:
+    mac_ver = tuple(map(int, platform.mac_ver()[0].split('.')))
+    if mac_ver[:2] < (10, 12):
+        raise SystemExit('Your version of macOS is too old, at least 10.12 is required')
+
+try:
+    __file__
+    from_file = True
+except NameError:
+    from_file = False
+
+if py3:
+    unicode = str
+    raw_input = input
+    import urllib.request as urllib
+
+    def encode_for_subprocess(x):
+        return x
+else:
+    from future_builtins import map
+    import urllib2 as urllib
+
+    def encode_for_subprocess(x):
+        if isinstance(x, unicode):
+            x = x.encode('utf-8')
+        return x
+
+
+def run(*args):
+    if len(args) == 1:
+        args = shlex.split(args[0])
+    args = list(map(encode_for_subprocess, args))
+    ret = subprocess.Popen(args).wait()
+    if ret != 0:
+        raise SystemExit(ret)
+
+
+class Reporter:  # {{{
+
+    def __init__(self, fname):
+        self.fname = fname
+        self.last_percent = 0
+
+    def __call__(self, blocks, block_size, total_size):
+        percent = (blocks*block_size)/float(total_size)
+        report = '\rDownloaded {:.1%}         '.format(percent)
+        if percent - self.last_percent > 0.05:
+            self.last_percent = percent
+            print(report, end='')
+            sys.stdout.flush()
+# }}}
+
+
+def get_latest_release_data():
+    print('Checking for latest release on GitHub...')
+    req = urllib.Request('https://api.github.com/repos/kovidgoyal/kitty/releases/latest', headers={'Accept': 'application/vnd.github.v3+json'})
+    try:
+        res = urllib.urlopen(req).read().decode('utf-8')
+    except Exception as err:
+        raise SystemExit('Failed to contact {} with error: {}'.format(req.get_full_url(), err))
+    data = json.loads(res)
+    html_url = data['html_url'].replace('/tag/', '/download/').rstrip('/')
+    for asset in data.get('assets', ()):
+        name = asset['name']
+        if is_macos:
+            if name.endswith('.dmg'):
+                return html_url + '/' + name, asset['size']
+        else:
+            if name.endswith('.txz'):
+                if is64bit:
+                    if name.endswith('-x86_64.txz'):
+                        return html_url + '/' + name, asset['size']
+                else:
+                    if name.endswith('-i686.txz'):
+                        return html_url + '/' + name, asset['size']
+    raise SystemExit('Failed to find the installer package on github')
+
+
+def do_download(url, size, dest):
+    print('Will download and install', os.path.basename(dest))
+    reporter = Reporter(os.path.basename(dest))
+
+    # Get content length and check if range is supported
+    rq = urllib.urlopen(url)
+    headers = rq.info()
+    sent_size = int(headers['content-length'])
+    if sent_size != size:
+        raise SystemExit('Failed to download from {} Content-Length ({}) != {}'.format(url, sent_size, size))
+    with open(dest, 'wb') as f:
+        while f.tell() < size:
+            raw = rq.read(8192)
+            if not raw:
+                break
+            f.write(raw)
+            reporter(f.tell(), 1, size)
+    rq.close()
+    if os.path.getsize(dest) < size:
+        raise SystemExit('Download failed, try again later')
+    print('\rDownloaded {} bytes'.format(os.path.getsize(dest)))
+
+
+def clean_cache(cache, fname):
+    for x in os.listdir(cache):
+        if fname not in x:
+            os.remove(os.path.join(cache, x))
+
+
+def download_installer(url, size):
+    fname = url.rpartition('/')[-1]
+    tdir = tempfile.gettempdir()
+    cache = os.path.join(tdir, 'kitty-installer-cache')
+    if not os.path.exists(cache):
+        os.makedirs(cache)
+    clean_cache(cache, fname)
+    dest = os.path.join(cache, fname)
+    if os.path.exists(dest) and os.path.getsize(dest) == size:
+        print('Using previously downloaded', fname)
+        return dest
+    if os.path.exists(dest):
+        os.remove(dest)
+    do_download(url, size, dest)
+    return dest
+
+
+def macos_install(dmg, dest='/Applications', launch=True):
+    mp = tempfile.mkdtemp()
+    atexit.register(shutil.rmtree, mp)
+    run('hdiutil', 'attach', dmg, '-mountpoint', mp)
+    try:
+        os.chdir(mp)
+        app = 'kitty.app'
+        d = os.path.join(dest, app)
+        if os.path.exists(d):
+            shutil.rmtree(d)
+        dest = os.path.join(dest, app)
+        run('ditto', '-v', app, dest)
+        print('Successfully installed kitty into', dest)
+        if launch:
+            run('open', dest)
+    finally:
+        os.chdir('/')
+        run('hdiutil', 'detach', mp)
+
+
+def linux_install(installer, dest=os.path.expanduser('~/.local'), launch=True):
+    dest = os.path.join(dest, 'kitty.app')
+    if os.path.exists(dest):
+        shutil.rmtree(dest)
+    os.makedirs(dest)
+    print('Extracting tarball...')
+    run('tar', '-C', dest, '-xJof', installer)
+    print('kitty successfully installed to', dest)
+    kitty = os.path.join(dest, 'bin', 'kitty')
+    print('Use', kitty, 'to run kitty')
+    if launch:
+        run(kitty, '--detach')
+
+
+def main(dest=None, launch=True, installer=None):
+    if not dest:
+        if is_macos:
+            dest = '/Applications'
+        else:
+            dest = os.path.expanduser('~/.local')
+    machine = os.uname()[4]
+    if machine and machine.lower().startswith('arm'):
+        raise SystemExit(
+            'You are running on an ARM system. The kitty binaries are only'
+            ' available for x86 systems. You will have to build from'
+            ' source.')
+    if not installer:
+        url, size = get_latest_release_data()
+        installer = download_installer(url, size)
+    else:
+        installer = os.path.abspath(installer)
+        if not os.access(installer, os.R_OK):
+            raise SystemExit('Could not read from: {}'.format(installer))
+    if is_macos:
+        macos_install(installer, dest=dest, launch=launch)
+    else:
+        linux_install(installer, dest=dest, launch=launch)
+
+
+def script_launch():
+    # To test: python3 -c "import runpy; runpy.run_path('installer.py', run_name='script_launch')"
+    def path(x):
+        return os.path.expandvars(os.path.expanduser(x))
+
+    def to_bool(x):
+        return x.lower() in {'y', 'yes', '1', 'true'}
+
+    type_map = {x: path for x in 'dest installer'.split()}
+    type_map['launch'] = to_bool
+    kwargs = {}
+
+    for arg in sys.argv[1:]:
+        if arg:
+            m = re.match('([a-z_]+)=(.+)', arg)
+            if m is None:
+                raise SystemExit('Unrecognized command line argument: ' + arg)
+            k = m.group(1)
+            if k not in type_map:
+                raise SystemExit('Unrecognized command line argument: ' + arg)
+            kwargs[k] = type_map[k](m.group(2))
+    main(**kwargs)
+
+
+def update_intaller_wrapper():
+    # To run: python3 -c "import runpy; runpy.run_path('installer.py', run_name='update_wrapper')" installer.sh
+    with open(__file__, 'rb') as f:
+        src = f.read().decode('utf-8')
+    wrapper = sys.argv[-1]
+    with open(wrapper, 'r+b') as f:
+        raw = f.read().decode('utf-8')
+        nraw = re.sub(r'^# HEREDOC_START.+^# HEREDOC_END', lambda m: '# HEREDOC_START\n{}\n# HEREDOC_END'.format(src), raw, flags=re.MULTILINE | re.DOTALL)
+        if 'update_intaller_wrapper()' not in nraw:
+            raise SystemExit('regex substitute of HEREDOC failed')
+        f.seek(0), f.truncate()
+        f.write(nraw.encode('utf-8'))
+
+
+if __name__ == '__main__' and from_file:
+    main()
+elif __name__ == 'update_wrapper':
+    update_intaller_wrapper()
+elif __name__ == 'script_launch':
+    script_launch()

docs/installer.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+#
+# installer.sh
+# Copyright (C) 2018 Kovid Goyal <kovid at kovidgoyal.net>
+#
+# Distributed under terms of the GPLv3 license.
+#
+
+python=$(command -v python3)
+if [ -z "$python" ]; then
+    python=$(command -v python2)
+fi
+if [ -z "$python" ]; then
+    python=$(command -v python2.7)
+fi
+if [ -z "$python" ]; then
+    python=$(command -v python)
+fi
+if [ -z "$python" ]; then
+    python=python
+fi
+
+echo Using python executable: $python
+
+$python -c "import sys; script_launch=lambda:sys.exit('Download of installer failed!'); exec(sys.stdin.read()); script_launch()" "$@" <<'INSTALLER_HEREDOC'
+# {{{
+# HEREDOC_START
+# HEREDOC_END
+# }}}
+INSTALLER_HEREDOC

docs/integrations.rst

@@ -0,0 +1,118 @@
+Integrations with other tools
+================================
+
+kitty provides extremely powerful interfaces such as :doc:`remote-control` and
+:doc:`kittens/custom` and :doc:`kittens/icat`
+that allow it to be integrated with other tools seamlessly.
+
+
+Image and document viewers
+----------------------------
+
+Powered by kitty's :doc:`graphics-protocol` there exist many tools for viewing
+images and other types of documents directly in your terminal, even over SSH.
+
+`termpdf.py <https://github.com/dsanson/termpdf.py>`_
+    a terminal PDF/DJVU/CBR viewer
+
+`mdcat <https://github.com/lunaryorn/mdcat>`_
+    Display markdown files nicely formatted with images in the terminal
+
+`ranger <https://github.com/ranger/ranger>`_
+    a terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+
+`nnn <https://github.com/jarun/nnn/>`_
+    another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+
+`hunter <https://github.com/rabite0/hunter>`_
+    another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+
+`koneko <https://github.com/twenty5151/koneko>`_
+    browse images from the pixiv artist community directly in kitty
+
+
+System and data visualisation tools
+---------------------------------------
+
+`neofetch <https://github.com/dylanaraps/neofetch>`_
+    A command line system information tool that shows images using kitty's graphics protocol
+
+`matplotlib <https://github.com/jktr/matplotlib-backend-kitty>`_
+    show matplotlib plots directly in kitty
+
+`KittyTerminalImages.jl <https://github.com/simonschoelly/KittyTerminalImages.jl>`_
+    show images from Julia directly in kitty
+
+`gnuplot <http://www.gnuplot.info/>`_
+    a graphing and data visualization tool that can be made to display its
+    output in kitty with the following bash snippet::
+
+        function iplot {
+            cat <<EOF | gnuplot
+            set terminal pngcairo enhanced font 'Fira Sans,10'
+            set autoscale
+            set samples 1000
+            set output '|kitty +kitten icat --stdin yes'
+            set object 1 rectangle from screen 0,0 to screen 1,1 fillcolor rgb"#fdf6e3" behind
+            plot $@
+            set output '/dev/null'
+            EOF
+        }
+
+   Add this to bashrc and then to plot a function, simply do::
+
+        iplot 'sin(x*3)*exp(x*.2)'
+
+
+Editor integration
+-----------------------
+
+kitty can be integrated into many different terminal editors to add features
+such a split windows, previews, REPLs etc.
+
+
+`kakoune <https://kakoune.org/>`_
+    integrates with kitty to use native kitty windows for its windows/panels and REPLs.
+
+`vim-slime <https://github.com/jpalardy/vim-slime#kitty>`_
+    uses kitty remote control for a Lisp REPL.
+
+`vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
+    allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
+
+`vim-test <https://github.com/vim-test/vim-test>`_
+    allows easily running tests in a terminal window
+
+
+Scrollback manipulation
+-------------------------
+
+`kitty-search <https://github.com/trygveaa/kitty-kitten-search>`_
+    Live incremental search of the scrollback buffer.
+
+`kitty-grab <https://github.com/yurikhan/kitty_grab>`_
+    keyboard based text selection for the kitty scrollback buffer.
+
+
+
+Miscellaneous
+------------------
+
+`kitty-smart-tab <https://github.com/yurikhan/kitty-smart-tab>`_
+    use keys to either control tabs or pass them onto running applications if
+    no tabs are present
+
+`kitty-smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
+    use keys to either scroll or pass them onto running applications if
+    no scrollback buffer is present
+
+`reload keybindings <https://github.com/kovidgoyal/kitty/issues/1292#issuecomment-582388769>`_
+    reload key bindings from :file:`kitty.conf` without needing to restart
+    kitty
+
+`kitti3 <https://github.com/LandingEllipse/kitti3>`_
+    allow using kitty as a drop-down terminal under the i3 window manager
+
+`weechat-hints <https://github.com/GermainZ/kitty-weechat-hints>`_
+    URL hints kitten for WeeChat that works without having to use WeeChat's
+    raw-mode.

docs/invocation.rst

@@ -0,0 +1,6 @@
+The kitty command line interface
+====================================
+
+.. program:: kitty
+
+.. include:: generated/cli-kitty.rst

docs/key-encoding.rst

@@ -0,0 +1,128 @@
+Key encoding for extended keyboard protocol
+===============================================
+
+See :ref:`extended-key-protocol` for more information and `this table in JSON
+format <https://github.com/kovidgoyal/kitty/blob/master/key_encoding.json>`_.
+
+=====================   ======================
+Name                    Encoded representation
+0                       ``G``
+1                       ``H``
+2                       ``I``
+3                       ``J``
+4                       ``K``
+5                       ``L``
+6                       ``M``
+7                       ``N``
+8                       ``O``
+9                       ``P``
+A                       ``S``
+APOSTROPHE              ``B``
+B                       ``T``
+BACKSLASH               ``t``
+BACKSPACE               ``1``
+C                       ``U``
+CAPS LOCK               ``:``
+COMMA                   ``C``
+D                       ``V``
+DELETE                  ``3``
+DOWN                    ``6``
+E                       ``W``
+END                     ``-``
+ENTER                   ``z``
+EQUAL                   ``R``
+ESCAPE                  ``y``
+F                       ``X``
+F1                      ``/``
+F10                     ``]``
+F11                     ``{``
+F12                     ``}``
+F13                     ``@``
+F14                     ``%``
+F15                     ``$``
+F16                     ``#``
+F17                     ``BA``
+F18                     ``BB``
+F19                     ``BC``
+F2                      ``*``
+F20                     ``BD``
+F21                     ``BE``
+F22                     ``BF``
+F23                     ``BG``
+F24                     ``BH``
+F25                     ``BI``
+F3                      ``?``
+F4                      ``&``
+F5                      ``<``
+F6                      ``>``
+F7                      ``(``
+F8                      ``)``
+F9                      ``[``
+G                       ``Y``
+GRAVE ACCENT            ``v``
+H                       ``Z``
+HOME                    ``.``
+I                       ``a``
+INSERT                  ``2``
+J                       ``b``
+K                       ``c``
+KP 0                    ``BJ``
+KP 1                    ``BK``
+KP 2                    ``BL``
+KP 3                    ``BM``
+KP 4                    ``BN``
+KP 5                    ``BO``
+KP 6                    ``BP``
+KP 7                    ``BQ``
+KP 8                    ``BR``
+KP 9                    ``BS``
+KP ADD                  ``BX``
+KP DECIMAL              ``BT``
+KP DIVIDE               ``BU``
+KP ENTER                ``BY``
+KP EQUAL                ``BZ``
+KP MULTIPLY             ``BV``
+KP SUBTRACT             ``BW``
+L                       ``d``
+LEFT                    ``5``
+LEFT ALT                ``Bc``
+LEFT BRACKET            ``s``
+LEFT CONTROL            ``Bb``
+LEFT SHIFT              ``Ba``
+LEFT SUPER              ``Bd``
+M                       ``e``
+MINUS                   ``D``
+N                       ``f``
+NUM LOCK                ``=``
+O                       ``g``
+P                       ``h``
+PAGE DOWN               ``9``
+PAGE UP                 ``8``
+PAUSE                   ``!``
+PERIOD                  ``E``
+PRINT SCREEN            ``^``
+Q                       ``i``
+R                       ``j``
+RIGHT                   ``4``
+RIGHT ALT               ``Bg``
+RIGHT BRACKET           ``u``
+RIGHT CONTROL           ``Bf``
+RIGHT SHIFT             ``Be``
+RIGHT SUPER             ``Bh``
+S                       ``k``
+SCROLL LOCK             ``+``
+SEMICOLON               ``Q``
+SLASH                   ``F``
+SPACE                   ``A``
+T                       ``l``
+TAB                     ``0``
+U                       ``m``
+UP                      ``7``
+V                       ``n``
+W                       ``o``
+WORLD 1                 ``w``
+WORLD 2                 ``x``
+X                       ``p``
+Y                       ``q``
+Z                       ``r``
+=====================   ======================

docs/kittens/clipboard.rst

@@ -0,0 +1,27 @@
+clipboard - copy/paste to the system clipboard
+==================================================
+
+.. highlight:: sh
+
+
+The ``clipboard`` kitten can be used to read or write to the system clipboard
+from the shell. It even works over SSH. Using it is as simple as::
+
+    echo hooray | kitty +kitten clipboard
+
+All text received on :file:`stdin` is copied to the clipboard.
+
+To get text from the clipboard you have to enable reading of the clipboard
+in :opt:`clipboard_control` in :file:`kitty.conf`. Once you do that, you can
+use::
+
+    kitty +kitten clipboard --get-clipboard
+
+
+.. program:: kitty +kitten clipboard
+
+
+Command Line Interface
+--------------------------
+
+.. include:: /generated/cli-kitten-clipboard.rst

docs/kittens/custom.rst

@@ -0,0 +1,202 @@
+Custom kittens
+=================
+
+You can easily create your own kittens to extend kitty. They are just
+terminal programs written in Python. When launching a kitten, kitty will
+open an overlay window over the current window and optionally pass the
+contents of the current window/scrollback to the kitten over its :file:`STDIN`.
+The kitten can then perform whatever actions it likes, just as a normal
+terminal program. After execution of the kitten is complete, it has access
+to the running kitty instance so it can perform arbitrary actions
+such as closing windows, pasting text, etc.
+
+Let's see a simple example of creating a kitten. It will ask the user for some
+input and paste it into the terminal window.
+
+Create a file in the kitty config folder, :file:`~/.config/kitty/mykitten.py`
+(you might need to adjust the path to wherever the kitty config folder is on
+your machine).
+
+
+.. code-block:: python
+
+    def main(args: List[str]) -> str:
+        # this is the main entry point of the kitten, it will be executed in
+        # the overlay window when the kitten is launched
+        answer = input('Enter some text: ')
+        # whatever this function returns will be available in the
+        # handle_result() function
+        return answer
+
+    def handle_result(args: List[str], answer: str, target_window_id: int, boss: kitty.boss.Boss) -> None:
+        # get the kitty window into which to paste answer
+        w = boss.window_id_map.get(target_window_id)
+        if w is not None:
+            w.paste(answer)
+
+
+Now in :file:`kitty.conf` add the lines::
+
+    map ctrl+k kitten mykitten.py
+
+
+Start kitty and press :kbd:`ctrl+k` and you should see the kitten running.
+The best way to develop your own kittens is to modify one of the built in
+kittens. Look in the kittens sub-directory of the kitty source code for those.
+Or see below for a list of :ref:`third-party kittens <external_kittens>`,
+that other kitty users have created.
+
+
+Passing arguments to kittens
+------------------------------
+
+You can pass arguments to kittens by defining them in the map directive in
+:file:`kitty.conf`. For example::
+
+    map ctrl+k kitten mykitten.py arg1 arg2
+
+These will be available as the ``args`` parameter in the ``main()`` and
+``handle_result()`` functions. Note also that the current working directory
+of the kitten is set to the working directory of whatever program is
+running in the active kitty window. The special argument ``@selection``
+is replaced by the currently selected text in the active kitty window.
+
+
+Passing the contents of the screen to the kitten
+---------------------------------------------------
+
+If you would like your kitten to have access to the contents of the screen
+and/or the scrollback buffer, you just need to add an annotation to the ``handle_result()``
+function, telling kitty what kind of input your kitten would like. For example:
+
+.. code-block:: py
+
+    # in main, STDIN is for the kitten process and will contain
+    # the contents of the screen
+    def main(args):
+        return sys.stdin.read()
+
+    # in handle_result, STDIN is for the kitty process itself, rather
+    # than the kitten process and should not be read from.
+    from kittens.tui.handler import result_handler
+    @result_handler(type_of_input='text')
+    def handle_result(args, stdin_data, target_window_id, boss):
+        pass
+
+
+This will send the plain text of the active window to the kitten's
+:file:`STDIN`. For text with formatting escape codes, use ``ansi``
+instead. If you want line wrap markers as well, use ``screen-ansi``
+or just ``screen``. For the scrollback buffer as well, use
+``history``, ``ansi-history`` or ``screen-history``. To get
+the currently selected text, use ``selection``.
+
+
+Using kittens to script kitty, without any terminal UI
+-----------------------------------------------------------
+
+If you would like your kitten to script kitty, without bothering to write a
+terminal program, you can tell the kittens system to run the
+``handle_result()`` function without first running the ``main()`` function.
+
+For example, here is a kitten that "zooms/unzooms" the current terminal window
+by switching to the stack layout or back to the previous layout.
+
+Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
+
+.. code-block:: py
+
+    def main(args):
+        pass
+
+    from kittens.tui.handler import result_handler
+    @result_handler(no_ui=True)
+    def handle_result(args, answer, target_window_id, boss):
+        tab = boss.active_tab
+        if tab is not None:
+            if tab.current_layout.name == 'stack':
+                tab.last_used_layout()
+            else:
+                tab.goto_layout('stack')
+
+
+Now in kitty.conf add::
+
+    map f11 kitten zoom_toggle.py
+
+Pressing :kbd:`F11` will now act as a zoom toggle function. You can get even
+more fancy, switching the kitty OS window to fullscreen as well as changing the
+layout, by simply adding the line::
+
+    boss.toggle_fullscreen()
+
+
+To the ``handle_result()`` function, above.
+
+
+.. _send_mouse_event:
+
+Sending mouse events
+--------------------
+
+If the program running in a window is receiving mouse events you can simulate
+those using::
+
+    from kitty.fast_data_types import send_mouse_event
+    send_mouse_event(screen, x, y, button, action, mods)
+
+``screen`` is the ``screen`` attribute of the window you want to send the event
+to. ``x`` and ``y`` are the 0-indexed coordinates. ``button`` is a number using
+the same numbering as X11 (left: ``1``, middle: ``2``, right: ``3``, scroll up:
+``4``, scroll down: ``5``, scroll left: ``6``, scroll right: ``7``, back:
+``8``, forward: ``9``). ``action`` is one of ``PRESS``, ``RELEASE``, ``DRAG``
+or ``MOVE``. ``mods`` is a bitmask of ``GLFW_MOD_{mod}`` where ``{mod}`` is one
+of ``SHIFT``, ``CONTROL`` or ``ALT``. All the mentioned constants are imported
+from ``kitty.fast_data_types``.
+
+For example, to send a left click at position x: 2, y: 3 to the active window::
+
+    from kitty.fast_data_types import send_mouse_event, PRESS
+    send_mouse_event(boss.active_window.screen, 2, 3, 1, PRESS, 0)
+
+The function will only send the event if the program is receiving events of
+that type, and will return ``True`` if it sent the event, and ``False`` if not.
+
+
+Debugging kittens
+--------------------
+
+The part of the kitten that runs in ``main()`` is just a normal program and
+the output of print statements will be visible in the kitten window. Or
+alternately, you can use::
+
+    from kittens.tui.loop import debug
+    debug('whatever')
+
+The ``debug()`` function is just like ``print()`` except that the output
+will appear in the ``STDOUT`` of the kitty process inside which the kitten is
+running.
+
+The ``handle_result()`` part of the kitten runs inside the kitty process.
+The output of print statements will go to the ``STDOUT`` of the kitty process.
+So if you run kitty from another kitty instance, the output will be visible
+in the first kitty instance.
+
+.. _external_kittens:
+
+Kittens created by kitty users
+---------------------------------------------
+
+`vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
+    Allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
+
+`smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
+    Makes the kitty scroll bindings work in full screen applications
+
+`insert password <https://github.com/kovidgoyal/kitty/issues/1222>`_
+    Insert a password from a CLI password manager, taking care to only do it at
+    a password prompt.
+
+`weechat-hints <https://github.com/GermainZ/kitty-weechat-hints>`_
+    URL hints kitten for WeeChat that works without having to use WeeChat's
+    raw-mode.

docs/kittens/diff.rst

@@ -0,0 +1,157 @@
+kitty-diff - A fast side-by-side diff tool with syntax highlighting and images
+================================================================================
+
+.. highlight:: sh
+
+Major Features
+-----------------
+
+.. container:: major-features
+
+    * Displays diffs side-by-side in the kitty terminal
+
+    * Does syntax highlighting of the displayed diffs, asynchronously, for maximum
+      speed
+
+    * Displays images as well as text diffs, even over SSH
+
+    * Does recursive directory diffing
+
+
+.. figure:: ../screenshots/diff.png
+   :alt: Screenshot, showing a sample diff
+   :align: center
+   :scale: 100%
+
+   Screenshot, showing a sample diff
+
+.. contents::
+
+
+Installation
+---------------
+
+Simply :ref:`install kitty <quickstart>`.  You also need
+to have either the `git <https://git-scm.com/>`_ program or the ``diff`` program
+installed. Additionally, for syntax highlighting to work,
+`pygments <http://pygments.org/>`_ must be installed (note that pygments is
+included in the macOS kitty app).
+
+
+Usage
+--------
+
+In the kitty terminal, run::
+
+    kitty +kitten diff file1 file2
+
+to see the diff between file1 and file2.
+
+Create an alias in your shell's startup file to shorten the command, for example:
+
+.. code-block:: sh
+
+    alias d="kitty +kitten diff"
+
+Now all you need to do to diff two files is::
+
+    d file1 file2
+
+You can also pass directories instead of files to see the recursive diff of the
+directory contents.
+
+
+Keyboard controls
+----------------------
+
+=========================   ===========================
+Action                      Shortcut
+=========================   ===========================
+Quit                        :kbd:`q, Ctrl+c, Esc`
+Scroll line up              :kbd:`k, up`
+Scroll line down            :kbd:`j, down`
+Scroll page up              :kbd:`PgUp`
+Scroll page down            :kbd:`PgDn`
+Scroll to top               :kbd:`Home`
+Scroll to bottom            :kbd:`End`
+Scroll to next page         :kbd:`Space, PgDn`
+Scroll to previous page     :kbd:`PgUp`
+Scroll to next change       :kbd:`n`
+Scroll to previous change   :kbd:`p`
+Increase lines of context   :kbd:`+`
+Decrease lines of context   :kbd:`-`
+All lines of context        :kbd:`a`
+Restore default context     :kbd:`=`
+Search forwards             :kbd:`/`
+Search backwards            :kbd:`?`
+Clear search                :kbd:`Esc`
+Scroll to next match        :kbd:`>, .`
+Scroll to previous match    :kbd:`<, ,`
+=========================   ===========================
+
+
+Integrating with git
+-----------------------
+
+Add the following to `~/.gitconfig`:
+
+.. code-block:: ini
+
+    [diff]
+        tool = kitty
+        guitool = kitty.gui
+    [difftool]
+        prompt = false
+        trustExitCode = true
+    [difftool "kitty"]
+        cmd = kitty +kitten diff $LOCAL $REMOTE
+    [difftool "kitty.gui"]
+        cmd = kitty kitty +kitten diff $LOCAL $REMOTE
+
+Now to use kitty-diff to view git diffs, you can simply do::
+
+    git difftool --no-symlinks --dir-diff
+
+Once again, creating an alias for this command is useful.
+
+
+Why does this work only in kitty?
+----------------------------------------
+
+The diff kitten makes use of various features that are :doc:`kitty only
+</protocol-extensions>`,  such as the :doc:`kitty graphics protocol
+</graphics-protocol>`, the :ref:`extended keyboard protocol
+<extended-key-protocol>`, etc. It also leverages terminal program
+infrastructure I created for all of kitty's other kittens to reduce the amount
+of code needed (the entire implementation is under 2000 lines of code).
+
+And fundamentally, it's kitty only because I wrote it for myself, and I am
+highly unlikely to use any other terminals :)
+
+
+
+Configuration
+------------------------
+
+You can configure the colors used, keyboard shortcuts, the diff implementation,
+the default lines of context, etc.  by creating a :file:`diff.conf` file in
+your :ref:`kitty config folder <confloc>`. See below for the supported
+configuration directives.
+
+
+.. include:: /generated/conf-kitten-diff.rst
+
+
+Command Line Interface
+-------------------------
+
+.. include:: /generated/cli-kitten-diff.rst
+
+
+
+Sample diff.conf
+-----------------
+
+You can download a sample :file:`diff.conf` file with all default settings and
+comments describing each setting by clicking: :download:`sample diff.conf
+</generated/conf/diff.conf>`.

docs/kittens/hints.rst

@@ -0,0 +1,89 @@
+Hints
+==========
+
+|kitty| has a *hints mode* to select and act on arbitrary text snippets currently
+visible on the screen.  For example, you can press :sc:`open_url`
+to choose any URL visible on the screen and then open it using your system
+browser.
+
+.. figure:: ../screenshots/hints_mode.png
+    :alt: URL hints mode
+    :align: center
+    :scale: 100%
+
+    URL hints mode
+
+Similarly, you can press :sc:`insert_selected_path` to
+select anything that looks like a path or filename and then insert it into the
+terminal, very useful for picking files from the output of a ``git`` or ``ls`` command and
+adding them to the command line for the next command.
+
+You can also press :sc:`goto_file_line` to select anything that looks
+like a path or filename followed by a colon and a line number and open
+the file in vim at the specified line number. The patterns and editor
+to be used can be modified using options passed to the kitten. For example::
+
+    map ctrl+g kitten hints --type=linenum --linenum-action=tab nvim +{line} {path}
+
+will open the selected file in a new tab inside neovim when you press
+:kbd:`ctrl+g`.
+
+The hints kitten is very powerful to see more detailed help on its various
+options and modes of operation, see below. You can use these options to
+create mappings in :file:`kitty.conf` to select various different text
+snippets. See :sc:`insert_selected_path` for examples.
+
+Completely customizing the matching and actions of the kitten
+---------------------------------------------------------------
+
+The hints kitten supports writing simple python scripts that can be used to
+completely customize how it finds matches and what happens when a match is
+selected. This allows the hints kitten to provide the user interface, while
+you can provide the logic for finding matches and performing actions on them.
+This is best illustrated with an example. Create the file
+:file:`custom-hints.py` in the kitty config directory with the following
+contents:
+
+.. code-block:: python
+
+    import re
+
+    def mark(text, args, Mark, extra_cli_args, *a):
+        # This function is responsible for finding all
+        # matching text. extra_cli_args are any extra arguments
+        # passed on the command line when invoking the kitten.
+        # We mark all individual word for potential selection
+        for idx, m in enumerate(re.finditer(r'\w+', text)):
+            start, end = m.span()
+            mark_text = text[start:end].replace('\n', '').replace('\0', '')
+            # The empty dictionary below will be available as groupdicts
+            # in handle_result() and can contain arbitrary data.
+            yield Mark(idx, start, end, mark_text, {})
+
+
+    def handle_result(args, data, target_window_id, boss, extra_cli_args, *a):
+        # This function is responsible for performing some
+        # action on the selected text.
+        # matches is a list of the selected entries and groupdicts contains
+        # the arbitrary data associated with each entry in mark() above
+        matches, groupdicts = [], []
+        for m, g in zip(data['match'], data['groupdicts']):
+            if m:
+                matches.append(m), groupdicts.append(g)
+        for word, match_data in zip(matches, groupdicts):
+            # Lookup the word in a dictionary, the open_url function
+            # will open the provided url in the system browser
+            boss.open_url(f'https://www.google.com/search?q=define:{word}')
+
+Now run kitty with::
+
+    kitty -o 'map f1 kitten hints --customize-processing custom-hints.py'
+
+When you press the :kbd:`F1` key you will be able to select a word to
+look it up in the Google dictionary.
+
+
+Command Line Interface
+-------------------------
+
+.. include:: ../generated/cli-kitten-hints.rst

docs/kittens/hyperlinked_grep.rst

@@ -0,0 +1,61 @@
+Hyperlinked grep
+=================
+
+This kitten allows you to search your files using `ripgrep
+<https://www.google.com/search?q=ripgrep>`_ and open the results
+directly in your favorite editor in the terminal, at the line containing
+the search result, simply by clicking on the result you want.
+
+To set it up, first create :file:`~/.config/kitty/open-actions.conf` with the
+following contents:
+
+.. code:: conf
+
+    # Open any file with a fragment in vim, fragments are generated
+    # by the hyperlink_grep kitten and nothing else so far.
+    protocol file
+    fragment_matches [0-9]+
+    action launch --type=overlay vim +${FRAGMENT} ${FILE_PATH}
+
+    # Open text files without fragments in the editor
+    protocol file
+    mime text/*
+    action launch --type=overlay ${EDITOR} ${FILE_PATH}
+
+
+Now, run a search with::
+
+    kitty +kitten hyperlinked_grep something
+
+Hold down the :kbd:`ctrl+shift` keys and click on any of the
+result lines, to open the file in vim at the matching line. If
+you use some editor other than vim, you should adjust the
+:file:`open-actions.conf` file accordingly.
+
+Finally, add an alias to your shell's rc files to invoke the kitten as ``hg``::
+
+    alias hg='kitty +kitten hyperlink_grep'
+
+
+You can now run searches with::
+
+    hg some-search-term
+
+If you want to enable completion, for the kitten, you can delegate completion
+to rg. For ZSH, you do that with::
+
+    compdef _rg kitty +kitten hyperlinked_grep
+
+
+To learn more about kitty's powerful framework for customizing URL click
+actions, :doc:`see here <../open_actions>`.
+
+Hopefully, someday this functionality will make it into some `upstream grep
+<https://github.com/BurntSushi/ripgrep/issues/665>`_
+program directly removing the need for this kitten.
+
+
+.. note::
+   While you can pass any of ripgrep's comand line options to the kitten and
+   they will be forwarded to rg, do not use options that change the output
+   formatting as the kitten works by parsing the output from ripgrep.

docs/kittens/icat.rst

@@ -0,0 +1,41 @@
+icat - Display images in the terminal
+========================================
+
+The ``icat`` kitten can be used to display arbitrary images in the |kitty|
+terminal. Using it is as simple as::
+
+    kitty +kitten icat image.jpeg
+
+It supports all image types supported by `ImageMagick
+<https://www.imagemagick.org>`_. It even works over SSH. For details, see
+the :doc:`kitty graphics protocol </graphics-protocol>`.
+
+You might want to create an alias in your shell's configuration files::
+
+   alias icat="kitty +kitten icat"
+
+Then you can simply use ``icat image.png`` to view images.
+
+.. note::
+
+    `ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to
+    work.
+
+.. note::
+
+    kitty's image display protocol may not work when used within a terminal
+    multiplexer such as ``screen`` or ``tmux``, depending on whether the
+    multiplexer has added support for it or not.
+
+
+.. program:: kitty +kitten icat
+
+
+The ``icat`` kitten has various command line arguments to allow it to be used
+from inside other programs to display images. In particular, :option:`--place`,
+:option:`--detect-support` and :option:`--print-window-size`.
+
+Command Line Interface
+--------------------------
+
+.. include:: /generated/cli-kitten-icat.rst

docs/kittens/panel.rst

@@ -0,0 +1,43 @@
+Draw a GPU accelerated dock panel on your desktop
+====================================================================================================
+
+.. highlight:: sh
+
+
+You can use this kitten to draw a GPU accelerated panel on the edge
+of your screen, that shows the output from an arbitrary terminal program.
+
+It is useful for showing status information or notifications on your desktop
+using terminal programs instead of GUI toolkits.
+
+
+.. figure:: ../screenshots/panel.png
+   :alt: Screenshot, showing a sample panel
+   :align: center
+   :scale: 100%
+
+   Screenshot, showing a sample panel
+
+
+The screenshot above shows a sample panel that displays the current desktop and
+window title as well as miscellaneous system information such as network
+activity, CPU load, date/time, etc.
+
+.. note::
+
+    This kitten currently only works on X11 desktops
+
+Using this kitten is simple, for example::
+
+    kitty +kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s'
+
+This will show ``Hello, world.`` at the top edge of your screen for five
+seconds. Here the terminal program we are running is ``sh`` with a script to
+print out ``Hello, world!``. You can make the terminal program as complex as
+you like, as demonstrated in the screenshot above.
+
+
+Command Line Interface
+-------------------------
+
+.. include:: ../generated/cli-kitten-panel.rst

docs/kittens/remote_file.rst

@@ -0,0 +1,35 @@
+Remote files
+==============
+
+|kitty| has the ability to easily *Edit*, *Open* or *Download* files
+from a computer into which you are SSHed. In your SSH session run::
+
+    ls --hyperlink=auto
+
+Then hold down :kbd:`ctrl+shift` and click the name of the file.
+
+.. figure:: ../screenshots/remote_file.png
+    :alt: Remote file actions
+    :align: center
+    :scale: 100%
+
+    Remote file actions
+
+|kitty| will ask you what you want to do with the remote file. You can choose
+to *Edit* it in which case kitty will download it and open it locally in your
+``EDITOR``. As you make changes to the file, they are automatically transferred
+to the remote computer. Note that this happens without needing to install *any*
+special software on the server, beyond ``ls`` that supports hyperlinks.
+
+.. note::
+   Nested SSH sessions are not supported. The kitten will always try to copy
+   remote files from the first SSH host. This is because there is no way for
+   |kitty| to detect and follow a nested SSH session robustly.
+
+.. note::
+   If you have not setup automatic password-less SSH access, then, when
+   editing starts you will be asked to enter your password just once,
+   thereafter the SSH connection will be re-used.
+
+Similarly, you can choose to save the file to the local computer or download
+and open it in its default file handler.

docs/kittens/unicode-input.rst

@@ -0,0 +1,33 @@
+Unicode input
+================
+
+You can input unicode characters by name, hex code, recently used and even an editable favorites list.
+Press :sc:`input_unicode_character` to start the unicode input widget, shown below.
+
+.. figure:: ../screenshots/unicode.png
+    :alt: A screenshot of the unicode input widget
+    :align: center
+    :scale: 100%
+
+    A screenshot of the unicode input widget
+
+In :guilabel:`Code` mode, you enter a unicode character by typing in the hex code for the
+character and pressing enter, for example, type in ``2716`` and press enter to get
+✖. You can also choose a character from the list of recently used characters by
+typing a leading period and then the two character index and pressing Enter.
+The up and down arrow keys can be used to choose the previous and next unicode
+symbol respectively.
+
+In :guilabel:`Name` mode you instead type words from the character name and use the arrow
+keys/tab to select the character from the displayed matches. You can also type
+a leading period and the index for the match if you don't like to use arrow
+keys.
+
+You can switch between modes using either the function keys or by pressing
+:kbd:`Ctrl+[` and :kbd:`Ctrl+]`.
+
+
+Command Line Interface
+-------------------------
+
+.. include:: ../generated/cli-kitten-unicode_input.rst

docs/launch.rst

@@ -0,0 +1,99 @@
+Launching programs in new windows/tabs
+========================================
+
+.. program:: launch
+
+
+|kitty| has a :code:`launch` action that can be used to run arbitrary programs
+in new windows/tabs. It can be mapped to user defined shortcuts in kitty.conf.
+It is very powerful and allows sending the contents of
+the current window to the launched program, as well as many other options.
+
+In the simplest form, you can use it to open a new kitty window running the
+shell, as shown below::
+
+    map f1 launch
+
+To run a different program simply pass the command line as arguments to
+launch::
+
+    map f1 launch vim path/to/some/file
+
+
+To open a new window with the same working directory as the currently
+active window::
+
+    map f1 launch --cwd=current
+
+To open the new window in a new tab::
+
+    map f1 launch --type=tab
+
+To pass the contents of the current screen and scrollback to the started process::
+
+    map f1 launch --stdin-source=@screen_scrollback less
+
+There are many more powerful options, refer to the complete list below.
+
+The piping environment
+--------------------------
+
+When using :option:`launch --stdin-source`, the program to which the data is
+piped has a special environment variable declared, ``KITTY_PIPE_DATA`` whose
+contents are::
+
+   KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
+
+where ``scrolled_by`` is the number of lines kitty is currently scrolled by,
+``cursor_(x|y)`` is the position of the cursor on the screen with ``(1,1)``
+being the top left corner and ``{lines},{columns}`` being the number of rows
+and columns of the screen.
+
+
+Special arguments
+-------------------
+
+There are a few special placeholder arguments that can be specified as part of
+the command line. Namely ``@selection`` which is replaced by the current
+selection and ``@active-kitty-window-id`` which is replaced by the id of the
+currently active kitty window. For example::
+
+    map f1 launch my-program @active-kitty-window-id
+
+
+Watching launched windows
+---------------------------
+
+The :option:`launch --watcher` option allows you to specify python functions
+that will be called at specific events, such as when the window is resized or
+closed. Simply specify the path to a python module that specifies callback
+functions for the events you are interested in, for example:
+
+.. code-block:: python
+
+    def on_resize(boss, window, data):
+        # Here data will contain old_geometry and new_geometry
+
+    def on_focus_change(boss, window, data):
+        # Here data kill contain focused
+
+    def on_close(boss, window, data):
+        # called when window is closed, typically when the program running in
+        # it exits.
+
+
+Every callback is passed a reference to the global ``Boss`` object as well as
+the ``Window`` object the action is occurring on. The ``data`` object is
+mapping that contains event dependent data. Some useful methods and attributes
+for the ``Window`` object are: ``as_text(as_ans=False, add_history=False,
+add_wrap_markers=False, alternate_screen=False)`` with which you can get the
+contents of the window and its scrollback buffer. Similarly,
+``window.child.pid`` is the PID of the processes that was launched
+in the window and ``window.id`` is the internal kitty ``id`` of the
+window.
+
+
+Syntax reference
+------------------
+
+.. include:: /generated/launch.rst

docs/layouts.rst

@@ -0,0 +1,258 @@
+Layouts
+============
+
+kitty has the ability to define its own windows that can be tiled next to each
+other in arbitrary arrangements, based on *Layouts*, see below for examples:
+
+
+.. figure:: screenshots/screenshot.png
+    :alt: Screenshot, showing three programs in the 'Tall' layout
+    :align: center
+    :scale: 100%
+
+    Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
+
+
+.. figure:: screenshots/splits.png
+    :alt: Screenshot, showing windows in the 'Splits' layout
+    :align: center
+    :scale: 100%
+
+    Screenshot, showing windows with arbitrary arrangement in the 'Splits'
+    layout
+
+
+There are many different layouts available. They are all enabled by default,
+you can switch layouts using :sc:`next_layout`. To control which layouts
+are available use :opt:`enabled_layouts`, the first listed layout becomes
+the default. Individual layouts and how to use them are described below.
+
+.. contents::
+
+
+The Stack Layout
+------------------
+
+This is the simplest layout it displays a single window using all available
+space, other windows are hidden behind it. It has no options::
+
+    enabled_layouts stack
+
+
+The Tall Layout
+------------------
+
+Displays one (or optionally more) full height windows on the left half of the
+screen. Remaining windows are tiled vertically on the right half of the screen.
+There are options to control how the screen is split horizontally ``bias``
+(an integer between ``10`` and ``90``) and options to control how many
+full-height windows there are ``full_size`` (a positive integer). The
+``mirrored`` option when set to ``true`` will cause the short windows to be
+on the left side of the screen instead of the right. The syntax
+for the options is shown below::
+
+    enabled_layouts tall:bias=50;full_size=1;mirrored=false
+
+    ┌──────────────┬───────────────┐
+    │              │               │
+    │              │               │
+    │              │               │
+    │              ├───────────────┤
+    │              │               │
+    │              │               │
+    │              │               │
+    │              ├───────────────┤
+    │              │               │
+    │              │               │
+    │              │               │
+    └──────────────┴───────────────┘
+
+In addition, you can map keys to increase or decrease the number of full size
+windows, for example::
+
+   map ctrl+[ layout_action decrease_num_full_size_windows
+   map ctrl+] layout_action increase_num_full_size_windows
+
+
+The Fat Layout
+----------------
+
+Displays one (or optionally more) full width windows on the top half of the
+screen. Remaining windows are tiled horizontally on the bottom half of the screen.
+There are options to control how the screen is split vertically ``bias``
+(an integer between ``10`` and ``90``) and options to control how many
+full-height windows there are ``full_size`` (a positive integer). The
+``mirrored`` option when set to ``true`` will cause the narrow windows to be
+on the top of the screen instead of the bottom. The syntax for the options is
+shown below::
+
+    enabled_layouts fat:bias=50;full_size=1;mirrored=false
+
+    ┌──────────────────────────────┐
+    │                              │
+    │                              │
+    │                              │
+    │                              │
+    ├─────────┬──────────┬─────────┤
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    └─────────┴──────────┴─────────┘
+
+
+The Grid Layout
+--------------------
+
+Display windows in a balanced grid with all windows the same size except the
+last column if there are not enough windows to fill the grid. Has no options::
+
+    enabled_layouts grid
+
+    ┌─────────┬──────────┬─────────┐
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    ├─────────┼──────────┼─────────┤
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    └─────────┴──────────┴─────────┘
+
+
+.. _splits_layout:
+
+The Splits Layout
+--------------------
+
+This is the most flexible layout. You can create any arrangement of windows
+by splitting exiting windows repeatedly. To best use this layout you should
+define a few extra keybindings in :file:`kitty.conf`::
+
+    map F5 launch --location=hsplit
+    map F6 launch --location=vsplit
+    map F7 layout_action rotate
+
+    map shift+up move_window up
+    map shift+left move_window left
+    map shift+right move_window right
+    map shift+down move_window down
+
+    map ctrl+left neighboring_window left
+    map ctrl+right neighboring_window right
+    map ctrl+up neighboring_window up
+    map ctrl+down neighboring_window down
+
+Now you can create horizontal and vertical splits by using :kbd:`F5` and
+:kbd:`F6`. You can move them around using :kbd:`shift+arrow keys`
+and you can move focus to neighboring windows using :kbd:`ctrl+arrow keys`.
+You can switch an existing split from horizontal to vertical and vice versa
+using :kbd:`F7`. Finally, windows can be resized using :ref:`window_resizing`.
+
+This layout takes one option, ``split_axis`` that controls whether new windows
+are placed into vertical or horizontal splits, by default::
+
+    enabled_layouts splits:split_axis=horizontal
+
+    ┌──────────────┬───────────────┐
+    │              │               │
+    │              │               │
+    │              │               │
+    │              ├───────┬───────┤
+    │              │       │       │
+    │              │       │       │
+    │              │       │       │
+    │              ├───────┴───────┤
+    │              │               │
+    │              │               │
+    │              │               │
+    └──────────────┴───────────────┘
+
+
+
+The Horizontal Layout
+------------------------
+
+All windows are shown side by side. Has no options::
+
+    enabled_layouts horizontal
+
+    ┌─────────┬──────────┬─────────┐
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    │         │          │         │
+    └─────────┴──────────┴─────────┘
+
+
+The Vertical Layout
+-----------------------
+
+All windows are shown one below the other. Has no options::
+
+    enabled_layouts vertical
+
+    ┌──────────────────────────────┐
+    │                              │
+    │                              │
+    │                              │
+    ├──────────────────────────────┤
+    │                              │
+    │                              │
+    │                              │
+    ├──────────────────────────────┤
+    │                              │
+    │                              │
+    │                              │
+    └──────────────────────────────┘
+
+
+.. _window_resizing:
+
+Resizing windows
+------------------
+
+You can resize windows inside layouts. Press :sc:`start_resizing_window` (also
+:kbd:`⌘+r` on macOS) to enter resizing mode and follow the on-screen
+instructions.  In a given window layout only some operations may be possible
+for a particular window. For example, in the Tall layout you can make the first
+window wider/narrower, but not taller/shorter. Note that what you are resizing
+is actually not a window, but a row/column in the layout, all windows in that
+row/column will be resized.
+
+You can also define shortcuts in :file:`kitty.conf` to make the active window
+wider, narrower, taller, or shorter by mapping to the ``resize_window``
+action, for example::
+
+   map ctrl+left resize_window narrower
+   map ctrl+right resize_window wider
+   map ctrl+up resize_window taller
+   map ctrl+down resize_window shorter 3
+
+The ``resize_window`` action has a second, optional argument to control
+the resizing increment (a positive integer that defaults to 1).
+
+
+Some layouts take options to control their behavior. For example, the ``fat``
+and ``tall`` layouts accept the ``bias`` and ``full_size`` options to control
+how the available space is split up.
+To specify the option, in :opt:`kitty.conf <enabled_layouts>` use::
+
+    enabled_layouts tall:bias=70;full_size=2
+
+This will have ``2`` instead of a single tall window, that occupy ``70%``
+instead of ``50%`` of available width. ``bias`` can be any number between 10
+and 90.
+
+Writing a new layout only requires about two hundred lines of code, so if there
+is some layout you want, take a look at one of the existing layouts in the
+`layout <https://github.com/kovidgoyal/kitty/tree/master/kitty/layout>`_
+package and submit a pull request!

docs/marks.rst

@@ -0,0 +1,125 @@
+Marks
+=================
+
+
+kitty has the ability to mark text on the screen based on regular expressions.
+This can be useful to highlight words or phrases when browsing output from long
+running programs or similar. Lets start with a few examples:
+
+Suppose we want to be able to highlight the word ERROR in the current window.
+Add the following to :file:`kitty.conf`::
+
+    map f1 toggle_marker text 1 ERROR
+
+Now when you press :kbd:`F1` all instances of the word :code:`ERROR` will be
+highlighted. To turn off the highlighting, press :kbd:`F1` again.
+If you want to make it case-insensitive, use::
+
+    map f1 toggle_marker itext 1 ERROR
+
+To make it match only complete words, use::
+
+    map f1 toggle_marker regex 1 \bERROR\b
+
+Suppose you want to highlight both :code:`ERROR` and :code:`WARNING`, case
+insensitively::
+
+    map f1 toggle_marker iregex 1 \bERROR\b 2 \bWARNING\b
+
+kitty supports up to 3 mark groups (the numbers in the commands above). You
+can control the colors used for these groups in :file:`kitty.conf` with::
+
+    mark1_foreground red
+    mark1_background gray
+    mark2_foreground green
+    ...
+
+
+.. note::
+    For performance reasons, matching is done per line only, and only when that line is
+    altered in any way. So you cannot match text that stretches across multiple
+    lines.
+
+
+Creating markers dynamically
+---------------------------------
+
+If you want to create markers dynamically rather than pre-defining them in
+:file:`kitty.conf` you can do so as follows::
+
+    map f1 create_marker
+    map f2 remove_marker
+
+Then pressing :kbd:`F1` will allow you to enter the marker definition and set
+it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
+the same syntax as ``toggle_marker`` above. Note that while creating
+markers, the prompt has history so you can easily re-use previous marker
+expressions.
+
+You can also use the facilities for :doc:`remote-control` to dynamically
+add/remove markers.
+
+
+Scrolling to marks
+--------------------
+
+kitty has an action to scroll to the next line that contains a mark. You can
+use it by mapping it to some shortcut in :file:`kitty.conf`::
+
+    map ctrl+p scroll_to_mark prev
+    map ctrl+n scroll_to_mark next
+
+Then pressing :kbd:`ctrl+p` will scroll to the first line in the scrollback
+buffer above the current top line that contains a mark. Pressing :kbd:`ctrl+n`
+will scroll to show the first line below the current last line that contains
+a mark. If you wish to jump to a mark of a specific type, you can add that to
+the mapping::
+
+    map ctrl+1 scroll_to_mark prev 1
+
+Which will scroll only to marks of type 1.
+
+
+The full syntax for creating marks
+-------------------------------------
+
+The syntax of the :code:`toggle_marker` command is::
+
+    toggle_marker <marker-type> <specification>
+
+Here :code:`marker-type` is one of:
+
+    * :code:`text` - simple substring matching
+    * :code:`itext` - case-insensitive substring matching
+    * :code:`regex` - A python regular expression
+    * :code:`iregex` - A case-insensitive python regular expression
+    * :code:`function` - An arbitrary function defined in a python file, see
+      :ref:`marker_funcs`.
+
+.. _marker_funcs:
+
+Arbitrary marker functions
+-----------------------------
+
+You can create your own marker functions. Create a python file named
+:file:`mymarker.py` and in it create a :code:`marker` function. This
+function receives the text of the line as input and must yield three numbers,
+the starting character position, the ending character position and the mark
+group (1-3). For example:
+
+.. code-block::
+
+    def marker(text):
+        # Function to highlight the letter X
+        for i, ch in enumerate(text):
+            if ch.lower() == 'x':
+                yield i, i, 3
+
+
+Save this file somewhere and in :file:`kitty.conf`, use::
+
+    map f1 toggle_marker function /path/to/mymarker.py
+
+If you save the file in the kitty config directory, you can use::
+
+    map f1 toggle_marker function mymarker.py

docs/open_actions.rst

@@ -0,0 +1,91 @@
+Customizing the actions taken when clicking on links
+======================================================
+
+|kitty| has support for `terminal hyperlinks <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These
+are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
+``mdcat``, etc. You can customize exactly what happens when clicking on these hyperlinks
+in |kitty|.
+
+You can tell kitty to take arbitrarily many, complex actions
+when a link is clicked. Let us illustrate with some examples, first. Create
+the file :file:`~/.config/kitty/open-actions.conf` with the following:
+
+.. code:: conf
+
+    # Open any image in the full kitty window by clicking on it
+    protocol file
+    mime image/*
+    action launch --type=overlay kitty +kitten icat --hold ${FILE_PATH}
+
+Now, run ``ls --hyperlink=auto`` in kitty and click on the filename of an
+image, holding down :kbd:`ctrl+shift`. It will be opened over the current
+window. Press any key to close it.
+
+Each entry in :file:`open-actions.conf` consists of one or more
+:ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more
+``action`` entries. In the example above kitty uses the :doc:`launch <launch>`
+action which can be used to run external programs. Entries are separated by
+blank lines.
+
+Actions are very powerful, anything that you can map to a key combination in
+`kitty.conf` can be used as an action. You can specify more than one action per
+entry if you like, for example:
+
+
+.. code:: conf
+
+    # Tail a log file (*.log) in a new OS Window and reduce its font size
+    protocol file
+    ext log
+    action launch --title ${FILE} --type=os-window tail -f ${FILE_PATH}
+    action change_font_size current -2
+
+
+In the action specification you can expand environment variables, as shown in
+the examples above. In addition to regular environment variables, there are
+some special variables, documented below:
+
+``URL``
+    The full URL being opened
+
+``FILE_PATH``
+    The path portion of the URL (unquoted)
+
+``FILE``
+    The file portion of the path of the URL (unquoted)
+
+``FRAGMENT``
+    The fragment (unquoted), if any of the URL or the empty string.
+
+.. _matching_criteria:
+
+Matching criteria
+------------------
+
+An entry in :file:`open-actions.conf` must have one or more matching criteria.
+URLs that match all criteria for an entry will trigger that entries' actions.
+Processing stops at the first matching entry, so put more specific matching
+criteria at the start of the list. Entries in the file are separated by blank
+lines. The various available criteria are:
+
+``protocol``
+    A comma separated list of protocols, for example: ``http, https``. If
+    absent, there is no constraint on protocol
+
+``url``
+    A regular expression that must match against the entire (unquoted) URL
+
+``fragment_matches``
+    A regular expression that must match against the fragment (part after #) in
+    the URL
+
+``mime``
+    A comma separated list of MIME types, for example: ``text/*, image/*,
+    application/pdf``
+
+``ext``
+    A comma separated list of file extensions, for example: ``jpeg, tar.gz``
+
+``file``
+    A shell glob pattern that must match the filename, for example:
+    ``image-??.png``

docs/performance.rst

@@ -0,0 +1,59 @@
+|kitty| Performance
+===================
+
+The main goals for |kitty| performance are user perceived latency while typing
+and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to find
+an optimum balance for these. To that end it keeps a cache of each rendered
+glyph in video RAM so that font rendering is not a bottleneck.  Interaction
+with child programs takes place in a separate thread from rendering, to improve
+smoothness.
+
+There are two parameters you can tune to adjust the performance. :opt:`repaint_delay`
+and :opt:`input_delay`. These control the artificial delays introduced into the
+render loop to reduce CPU usage. See :ref:`conf-kitty-performance` for details.
+See also the :opt:`sync_to_monitor` option to further decrease latency at the cost
+of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
+
+You can generate detailed per-function performance data using `gperftools
+<https://github.com/gperftools/gperftools>`_. Build |kitty| with `make
+profile`. Run kitty and perform the task you want to analyse, for example,
+scrolling a large file with `less`. After you quit, function call statistics
+will be printed to `stdout` and you can use tools like *kcachegrind* for more
+detailed analysis.
+
+Here are some CPU usage numbers for the task of scrolling a file continuously
+in less.  The CPU usage is for the terminal process and X together and is
+measured using htop.  The measurements are taken at the same font and window
+size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz`` CPU
+with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
+7770/8760 / R7 250X]`` GPU.
+
+==============   =========================
+Terminal         CPU usage (X + terminal)
+==============   =========================
+|kitty|          6 - 8%
+xterm            5 - 7% (but scrolling was extremely janky)
+termite          10 - 13%
+urxvt            12 - 14%
+gnome-terminal   15 - 17%
+konsole          29 - 31%
+==============   =========================
+
+
+As you can see, |kitty| uses much less CPU than all terminals, except xterm, but
+its scrolling "smoothness" is much better than that of xterm (at least to my,
+admittedly biased, eyes).
+
+
+.. _perf-cat:
+
+.. note::
+
+    Some people have asked why kitty does not perform better than terminal XXX in
+    the test of sinking large amounts of data, such as catting a large text
+    file. The answer is because this is not a goal for kitty. kitty
+    deliberately throttles input parsing and output rendering to minimize
+    resource usage while still being able to sink output faster than any real
+    world program can produce it. Reducing CPU usage, and hence battery drain
+    while achieving instant response times and smooth scrolling to a human eye
+    is a far more important goal.

docs/pipe.rst

@@ -0,0 +1,98 @@
+Working with the screen and history buffer contents
+======================================================
+
+.. warning::
+    The pipe action has been deprecated in favor of the
+    :doc:`launch <launch>` action which is more powerful.
+
+You can pipe the contents of the current screen and history buffer as
+:file:`STDIN` to an arbitrary program using the ``pipe`` function. The program
+can be displayed in a kitty window or overlay.
+
+For example, the following in :file:`kitty.conf` will open the scrollback
+buffer in less in an overlay window, when you press :kbd:`F1`::
+
+    map f1 pipe @ansi overlay less +G -R
+
+The syntax of the ``pipe`` function is::
+
+   pipe <input placeholder> <destination window type> <command line to run>
+
+
+The piping environment
+--------------------------
+
+The program to which the data is piped has a special environment variable
+declared, ``KITTY_PIPE_DATA`` whose contents are::
+
+   KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
+
+where ``scrolled_by`` is the number of lines kitty is currently scrolled by,
+``cursor_(x|y)`` is the position of the cursor on the screen with ``(1,1)``
+being the top left corner and ``{lines},{columns}`` being the number of rows
+and columns of the screen.
+
+You can choose where to run the pipe program:
+
+``overlay``
+   An overlay window over the current kitty window
+
+``window``
+   A new kitty window
+
+``os_window``
+   A new top-level window
+
+``tab``
+   A new window in a new tab
+
+``clipboard, primary``
+   Copy the text directly to the clipboard. In this case the specified program
+   is not run, so use some dummy program name for it.
+
+``none``
+   Run it in the background
+
+
+Input placeholders
+--------------------
+
+There are various different kinds of placeholders
+
+``@selection``
+   Plain text, currently selected text
+
+``@text``
+   Plain text, current screen + scrollback buffer
+
+``@ansi``
+   Text with formatting, current screen + scrollback buffer
+
+``@screen``
+   Plain text, only current screen
+
+``@ansi_screen``
+   Text with formatting, only current screen
+
+``@alternate``
+   Plain text, secondary screen. The secondary screen is the screen not currently displayed. For
+   example if you run a fullscreen terminal application, the secondary screen will
+   be the screen you return to when quitting the application.
+
+``@ansi_alternate``
+   Text with formatting, secondary screen.
+
+``@alternate_scrollback``
+   Plain text, secondary screen + scrollback, if any.
+
+``@ansi_alternate_scrollback``
+   Text with formatting, secondary screen + scrollback, if any.
+
+``none``
+   No input
+
+
+You can also add the suffix ``_wrap`` to the placeholder, in which case kitty
+will insert the carriage return at every line wrap location (where long lines
+are wrapped at screen edges). This is useful if you want to pipe to program
+that wants to duplicate the screen layout of the screen.

docs/protocol-extensions.rst

@@ -0,0 +1,353 @@
+Extensions to the xterm protocol
+===================================
+
+|kitty| has a few extensions to the xterm protocol, to enable advanced features.
+These are typically in the form of new or re-purposed escape codes. While these
+extensions are currently |kitty| specific, it would be nice to get some of them
+adopted more broadly, to push the state of terminal emulators forward.
+
+The goal of these extensions is to be as small and unobtrusive as possible,
+while filling in some gaps in the existing xterm protocol. In particular, one
+of the goals of this specification is explicitly not to "re-imagine" the tty.
+The tty should remain what it is -- a device for efficiently processing text
+received as a simple byte stream. Another objective is to only move the minimum
+possible amount of extra functionality into the terminal program itself. This
+is to make it as easy to implement these protocol extensions as possible,
+thereby hopefully encouraging their widespread adoption.
+
+If you wish to discuss these extensions, propose additions/changes to them
+please do so by opening issues in the github bug tracker.
+
+.. contents::
+
+Colored and styled underlines
+-------------------------------
+
+|kitty| supports colored and styled (wavy) underlines. This is of particular
+use in terminal editors such as vim and emacs to display red, wavy underlines
+under mis-spelled words and/or syntax errors. This is done by re-purposing some
+SGR escape codes that are not used in modern terminals (`CSI codes
+<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences>`_)
+
+To set the underline style::
+
+    <ESC>[4:0m  # this is no underline
+    <ESC>[4:1m  # this is a straight underline
+    <ESC>[4:2m  # this is a double underline
+    <ESC>[4:3m  # this is a curly underline
+    <ESC>[4:4m  # this is a dotted underline (not implemented in kitty)
+    <ESC>[4:5m  # this is a dashed underline (not implemented in kitty)
+    <ESC>[4m    # this is a straight underline (for backwards compat)
+    <ESC>[24m   # this is no underline (for backwards compat)
+
+To set the underline color (this is reserved and as far as I can tell not actually used for anything)::
+
+    <ESC>[58...m
+
+This works exactly like the codes ``38, 48`` that are used to set foreground and
+background color respectively.
+
+To reset the underline color (also previously reserved and unused)::
+
+    <ESC>[59m
+
+The underline color must remain the same under reverse video, if it has a
+color, if not, it should follow the foreground color.
+
+To detect support for this feature in a terminal emulator, query the terminfo database
+for the ``Su`` boolean capability.
+
+Graphics rendering
+---------------------
+
+See :doc:`/graphics-protocol` for a description
+of this protocol to enable drawing of arbitrary raster images in the terminal.
+
+
+.. _extended-key-protocol:
+
+Keyboard handling
+-------------------
+
+There are various problems with the current state of keyboard handling. They
+include:
+
+* No way to use modifiers other than ``Ctrl`` and ``Alt``
+
+* No way to reliably use multiple modifier keys, other than, ``Shift+Alt``.
+
+* No way to handle different types of keyboard events, such as press, release or repeat
+
+* No reliable way to distinguish single ``Esc`` keypresses from the start of a
+  escape sequence. Currently, client programs use fragile timing related hacks
+  for this, leading to bugs, for example:
+  `neovim #2035 <https://github.com/neovim/neovim/issues/2035>`_.
+
+There are already two distinct keyboard handling modes, *normal mode* and
+*application mode*. These modes generate different escape sequences for the
+various special keys (arrow keys, function keys, home/end etc.) Most terminals
+start out in normal mode, however, most shell programs like ``bash`` switch them to
+application mode. We propose adding a third mode, named *full mode* that addresses
+the shortcomings listed above.
+
+Switching to the new *full mode* is accomplished using the standard private
+mode DECSET escape sequence::
+
+    <ESC>[?2017h
+
+and to leave *full mode*, use DECRST::
+
+    <ESC>[?2017l
+
+The number ``2017`` above is not used for any existing modes, as far as I know.
+Client programs can query if the terminal emulator is in *full mode* by using
+the standard `DECRQM <https://vt100.net/docs/vt510-rm/DECRQM.html>`_ escape sequence.
+
+The new mode works as follows:
+
+  * All printable key presses without modifier keys are sent just as in the
+    *normal mode*. This means all printable ASCII characters and in addition,
+    ``Enter``, ``Space`` and ``Backspace``. Also any unicode characters generated by
+    platform specific extended input modes, such as using the ``AltGr`` key. This
+    is done so that client programs that are not aware of this mode can still
+    handle basic text entry, so if a *full mode* using program crashes and does
+    not reset, the user can still issue a ``reset`` command in the shell to restore
+    normal key handling. Note that this includes pressing the ``Shift`` modifier
+    and printable keys. Note that this means there are no repeat and release
+    events for these keys and also for the left and right shift keys.
+
+  * For non printable keys and key combinations including one or more modifiers,
+    an escape sequence encoding the key event is sent. For details on the
+    escape sequence, see below.
+
+The escape sequence encodes the following properties:
+
+  * Type of event: ``press,repeat,release``
+  * Modifiers pressed at the time of the event
+  * The actual key being pressed
+
+Schematically::
+
+    <ESC>_K<type><modifiers><key><ESC>\
+
+Where ``<type>`` is one of ``p`` -- press, ``r`` -- release and ``t`` -- repeat.
+Modifiers is a bitmask represented as a single base64 digit.  Shift -- ``0x1``,
+Alt -- ``0x2``, Control -- ``0x4`` and Super -- ``0x8``.  ``<key>`` is a number
+(encoded in base85) corresponding to the key pressed. The key name to number
+mapping is defined in :doc:`this table <key-encoding>`.
+
+Client programs must ignore events for keys they do not know. The mapping in
+the above table is stable and will never change, however, new codes might be
+added to it in the future, for new keys.
+
+For example::
+
+    <ESC>_KpGp<ESC>\  is  <Ctrl>+<Alt>+x (press)
+    <ESC>_KrP8<ESC>\  is  <Ctrl>+<Alt>+<Shift>+<Super>+PageUp (release)
+
+This encoding means each key event is represented by 8 or 9 printable ascii
+only bytes, for maximum robustness.
+
+To see the full mode in action, run::
+
+   kitty +kitten key_demo
+
+Support for this mode is indicated by the ``fullkbd`` boolean capability
+in the terminfo database, in case querying for it via DECQRM is inconvenient.
+
+.. _ext_styles:
+
+Setting text styles/colors in arbitrary regions of the screen
+------------------------------------------------------------------
+
+There already exists an escape code to set *some* text attributes in arbitrary
+regions of the screen, `DECCARA
+<https://vt100.net/docs/vt510-rm/DECCARA.html>`_.  However, it is limited to
+only a few attributes. |kitty| extends this to work with *all* SGR attributes.
+So, for example, this can be used to set the background color in an arbitrary
+region of the screen.
+
+The motivation for this extension is the various problems with the existing
+solution for erasing to background color, namely the *background color erase
+(bce)* capability. See
+`this discussion <https://github.com/kovidgoyal/kitty/issues/160#issuecomment-346470545>`_
+and `this FAQ <https://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`_
+for a summary of problems with *bce*.
+
+For example, to set the background color to blue in a
+rectangular region of the screen from (3, 4) to (10, 11), you use::
+
+    <ESC>[2*x<ESC>[4;3;11;10;44$r<ESC>[*x
+
+
+Saving and restoring the default foreground/background/selection/cursor colors
+---------------------------------------------------------------------------------
+
+It is often useful for a full screen application with its own color themes
+to set the default foreground, background, selection and cursor colors. This
+allows for various performance optimizations when drawing the screen. The
+problem is that if the user previously used the escape codes to change these
+colors herself, then running the full screen application will lose her
+changes even after it exits. To avoid this, kitty introduces a new pair of
+*OSC* escape codes to push and pop the current color values from a stack::
+
+    <ESC>]30001<ESC>\  # push onto stack
+    <ESC>]30101<ESC>\  # pop from stack
+
+These escape codes save/restore the so called *dynamic colors*, default
+background, default foreground, selection background, selection foreground and
+cursor color.
+
+
+Pasting to clipboard
+----------------------
+
+|kitty| implements the OSC 52 escape code protocol to get/set the clipboard
+contents (controlled via the :opt:`clipboard_control` setting). There is one
+difference in kitty's implementation compared to some other terminal emulators.
+|kitty| allows sending arbitrary amounts of text to the clipboard. It does so
+by modifying the protocol slightly. Successive OSC 52 escape codes to set the
+clipboard will concatenate, so::
+
+    <ESC>]52;c;<payload1><ESC>\
+    <ESC>]52;c;<payload2><ESC>\
+
+will result in the clipboard having the contents ``payload1 + payload2``. To
+send a new string to the clipboard send an OSC 52 sequence with an invalid payload
+first, for example::
+
+    <ESC>]52;c;!<ESC>\
+
+Here ``!`` is not valid base64 encoded text, so it clears the clipboard.
+Further, since it is invalid, it should be ignored by terminal emulators
+that do not support this extension, thereby making it safe to use, simply
+always send it before starting a new OSC 52 paste, even if you aren't chunking
+up large pastes, that way kitty won't concatenate your paste, and it will have
+no ill-effects in other terminal emulators.
+
+In case you're using software that can't be easily adapted to this
+protocol extension, it can be disabled by specifying ``no-append`` to the
+:opt:`clipboard_control` setting.
+
+
+.. _desktop_notifications:
+
+
+Desktop notifications
+---------------------------------
+
+|kitty| implements an extensible escape code (OSC 99) to show desktop
+notifications. It is easy to use from shell scripts and fully extensible to
+show title and body.  Clicking on the notification can optionally focus the
+window it came from, and/or send an escape code back to the application running
+in that window.
+
+The design of the escape code is partially based on the discussion in
+the defunct
+`terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`_
+
+The escape code has the form::
+
+    <OSC> 99 ; metadata ; payload <terminator>
+
+Here ``<OSC>`` is :code:`<ESC>]` and ``<terminator>`` is :code:`<ESC><backslash>`.  The
+metadata is a section of colon separated :code:`key=value` pairs. Every key
+must be a single character from the set :code:`[a-zA-Z]` and every value must
+be a character from the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The
+payload must be interpreted based on the metadata section. The two semi-colons
+*must* always be present even when no metadata is present.
+
+Before going into details, lets see how one can display a simple, single line
+notification from a shell script::
+
+    printf '\x1b]99;;Hello world\x1b\\'
+
+To show a message with a title and a body::
+
+    printf '\x1b]99;i=1:d=0;Hello world\x1b\\'
+    printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\'
+
+The most important key in the metadata is the ``p`` key, it controls how the
+payload is interpreted. A value of ``title`` means the payload is setting the
+title for the notification. A value of ``body`` means it is setting the body,
+and so on, see the table below for full details.
+
+The design of the escape code is fundamentally chunked, this is because
+different terminal emulators have different limits on how large a single escape
+code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
+key is the *notification id* which can be any string containing the characters
+``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and
+can only take the values ``0`` and ``1``. A value of ``0`` means the
+notification is not yet done and the terminal emulator should hold off
+displaying it. A value of ``1`` means the notification is done, and should be
+displayed. You can specify the title or body multiple times and the terminal
+emulator will concatenate them, thereby allowing arbitrarily long text
+(terminal emulators are free to impose a sensible limit to avoid
+Denial-of-Service attacks).
+
+Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
+text with no embedded escape codes, or UTF-8 text that is base64 encoded, in
+which case there must be an ``e=1`` key in the metadata to indicate the payload
+is base64 encoded.
+
+When the user clicks the notification, a couple of things can happen, the
+terminal emulator can focus the window from which the notification came, and/or
+it can send back an escape code to the application indicating the notification
+was activated. This is controlled by the ``a`` key which takes a comma
+separated set of values, ``report`` and ``focus``. The value ``focus`` means
+focus the window from which the notification was issued and is the default.
+``report`` means send an escape code back to the application. The format of the
+escape code is::
+
+    <OSC> 99 ; i=identifier ; <terminator>
+
+The value of ``identifier`` comes from the ``i`` key in the escape code sent by
+the application. If the application sends no identifier, then the terminal
+*must* use ``i=0``. Actions can be preceded by a negative sign to turn them
+off, so for example if you do not want any action, turn off the default
+``focus`` action with::
+
+    a=-focus
+
+Complete specification of all the metadata keys is in the table below. If a
+terminal emulator encounters a key in the metadata it does not understand,
+the key *must* be ignored, to allow for future extensibility of this escape
+code. Similarly if values for known keys are unknown, the terminal emulator
+*should* either ignore the entire escape code or perform a best guess effort
+to display it based on what it does understand.
+
+.. note::
+   It is possible to extend this escape code to allow specifying an icon for
+   the notification, however, given that some platforms, such as macOS, dont
+   allow displaying custom icons on a notification, at all, it was decided to
+   leave it out of the spec for the time being.
+
+   Similarly, features such a scheduled notifications could be added in future
+   revisions.
+
+
+=======  ====================  =========  =================
+Key      Value                 Default    Description
+=======  ====================  =========  =================
+``a``    Comma separated list  ``focus``  What action to perform when the
+         of ``report``,                   notification is clicked
+         ``focus``, with
+         optional leading
+         ``-``
+
+``d``    ``0`` or ``1``        ``1``      Indicates if the notification is
+                                          complete or not.
+
+``e``    ``0`` or ``1``        ``0``      If set to ``1`` means the payload is base64 encoded UTF-8,
+                                          otherwise it is plain UTF-8 text with no C0 control codes in it
+
+``i``    ``[a-zA-Z0-9-_+.]``   ``0``      Identifier for the notification
+
+``p``    One of ``title`` or   ``title``  Whether the payload is the notification title or body. If a
+         ``body``.                        notification has no title, the body will be used as title.
+=======  ====================  =========  =================
+
+
+.. note::
+   |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
+   desktop notifications.

docs/rc_protocol.rst

@@ -0,0 +1,29 @@
+Documentation for the kitty remote control protocol
+======================================================
+
+The kitty remote control protocol is a simple protocol that involves sending
+data to kitty in the form of JSON. Any individual command of kitty has the
+form::
+
+    <ESC>P@kitty-cmd<JSON object><ESC>\
+
+Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form::
+
+    {
+        "cmd": "command name",
+        "version": <kitty version>,
+        "no_response": Optional Boolean,
+        "payload": <Optional JSON object>,
+    }
+
+The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are developing a
+standalone client, use the kitty version that you are developing against. Using
+a version greater than the version of the kitty instance you are talking to,
+will cause a failure.
+
+Set ``no_response`` to ``true`` if you don't want a response from kitty.
+
+The optional payload is a JSON object that is specific to the actual command being sent.
+The fields in the object for every command are documented below.
+
+.. include:: generated/rc.rst

docs/remote-control.rst

@@ -0,0 +1,156 @@
+:tocdepth: 2
+
+Controlling kitty from scripts or the shell
+==============================================
+
+.. highlight:: sh
+
+Tutorial
+----------
+
+|kitty| can be controlled from scripts or the shell prompt. You can open new
+windows, send arbitrary text input to any window, name windows and tabs, etc.
+Let's walk through a few examples of controlling |kitty|.
+
+Start by running |kitty| as::
+
+    kitty -o allow_remote_control=yes -o enabled_layouts=tall
+
+In order for control to work, :opt:`allow_remote_control` must be enabled in
+:file:`kitty.conf`. Here we turn it on explicitly at the command line.
+
+Now, in the new |kitty| window, enter the command::
+
+    kitty @ launch --title Output --keep-focus cat
+
+This will open a new window, running the ``cat`` program that will appear next
+to the current window.
+
+Let's send some text to this new window::
+
+    kitty @ send-text --match cmdline:cat Hello, World
+
+This will make ``Hello, World`` show up in the window running the ``cat`` program.
+The :option:`kitty @ send-text --match` option is very powerful, it allows selecting windows by their
+titles, the command line of the program running in the window, the working
+directory of the program running in the window, etc.  See ``kitty @ send-text
+--help`` for details.
+
+More usefully, you can pipe the output of a command running in one window to
+another window, for example::
+
+    ls | kitty @ send-text --match title:Output --stdin
+
+This will show the output of ls in the output window instead of the current
+window. You can use this technique to, for example, show the output of running
+``make`` in your editor in a different window. The possibilities are endless.
+
+You can even have things you type show up in a different window. Run::
+
+    kitty @ send-text --match title:Output --stdin
+
+And type some text, it will show up in the output window, instead of the current
+window. Type ``Ctrl+D`` when you are ready to stop.
+
+Now, let's open a new tab::
+
+   kitty @ launch --type=tab --tab-title "My Tab" --keep-focus bash
+
+This will open a new tab running the bash shell with the title "My Tab".
+We can change the title of the tab with::
+
+   kitty @ set-tab-title --match title:My  New Title
+
+Let's change the title of the current tab::
+
+   kitty @ set-tab-title Master Tab
+
+Now lets switch to the newly opened tab::
+
+   kitty @ focus-tab --match title:New
+
+Similarly, to focus the previously opened output window (which will also switch
+back to the old tab, automatically)::
+
+   kitty @ focus-window --match title:Output
+
+You can get a listing of available tabs and windows, by running::
+
+   kitty @ ls
+
+This outputs a tree of data in JSON format. The top level of the tree is all
+operating system kitty windows. Each OS window has an id and a list of tabs.
+Each tab has its own id, a title and a list of windows. Each window has an id,
+title, current working directory, process id (PID) and command-line of the
+process running in the window. You can use this information with :option:`kitty @ focus-window --match`
+to control individual windows.
+
+As you can see, it is very easy to control |kitty| using the
+``kitty @`` messaging system. This tutorial touches only the
+surface of what is possible. See ``kitty @ --help`` for more details.
+
+Note that in the example's above, ``kitty @`` messaging works only when run inside a |kitty| window,
+not anywhere. But, within a |kitty| window it even works over SSH. If you want to control
+|kitty| from programs/scripts not running inside a |kitty| window, you have to implement a couple of
+extra steps. First start |kitty| as::
+
+    kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty
+
+The :option:`kitty --listen-on` option tells |kitty| to listen for control messages at the
+specified path. See ``kitty --help`` for details. Now you can control this
+instance of |kitty| using the :option:`kitty @ --to` command line argument to ``kitty @``. For example::
+
+    kitty @ --to unix:/tmp/mykitty ls
+
+
+Note that if all you want to do is run a single |kitty| "daemon" and have subsequent
+|kitty| invocations appear as new top-level windows, you can use the simpler :option:`kitty --single-instance`
+option, see ``kitty --help`` for that.
+
+The builtin kitty shell
+--------------------------
+
+You can explore the |kitty| command language more easily using the builtin |kitty|
+shell. Run ``kitty @`` with no arguments and you will be dropped into the |kitty|
+shell with completion for |kitty| command names and options.
+
+You can even open the |kitty| shell inside a running |kitty| using a simple
+keyboard shortcut (:sc:`kitty_shell` by default). This has the added
+advantage that you don't need to use ``allow_remote_control`` to make it work.
+
+
+Allowing only some windows to control kitty
+----------------------------------------------
+
+If you do not want to allow all programs running in |kitty| to control it, you can selectively
+enable remote control for only some |kitty| windows. Simply create a shortcut
+such as::
+
+    map ctrl+k launch --allow-remote-control some_program
+
+Then programs running in windows created with that shortcut can use ``kitty @``
+to control kitty. Note that any program with the right level of permissions can
+still write to the pipes of any other program on the same computer and
+therefore can control |kitty|. It can, however, be useful to block programs
+running on other computers (for example, over ssh) or as other users.
+
+Mapping key presses to remote control commands
+--------------------------------------------------
+
+If you wish to trigger a remote control command easily with just a keypress,
+you can map it in :file:`kitty.conf`. For example::
+
+    map F1 remote_control set-spacing margin=30
+
+Then pressing the :kbd:`F1` key will set the active window margins to 30.
+The syntax for what follows :code:`remote_control` is exactly the same
+as the syntax for what follows :code:`kitty @` above.
+
+
+Documentation for the remote control protocol
+-----------------------------------------------
+
+If you wish to develop your own client to talk to |kitty|, you
+can use the :doc:`rc_protocol`.
+
+.. include:: generated/cli-kitty-at.rst

docs/support.html

@@ -0,0 +1,69 @@
+<style>
+.support-button {
+    border-radius: 6px;
+    box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px;
+    display: inline-block;
+    cursor: pointer;
+    color: rgb(51, 51, 51);
+    font-size: inherit;
+    font-family: Arial;
+    font-weight: bold;
+    padding: 8px 24px;
+    text-decoration: none;
+}
+
+.support-button:hover {
+    transform: scale(1.5);
+}
+
+.support-button {
+    outline: 0;
+}
+.support-button:visited {
+    color: rgb(51, 51, 51);
+    outline: 0;
+}
+
+#support-buttons > div {
+    margin-top: 3ex;
+    text-align: center;
+}
+
+#paypal input[type=submit] {
+    background: linear-gradient(rgb(255, 236, 100) 5%, rgb(255, 171, 35) 100%) rgb(255, 236, 100);
+    border: 1px solid rgb(255, 171, 35);
+}
+
+#liberapay a {
+    background: linear-gradient(rgb(92, 184, 92) 5%, rgb(62, 142, 62) 100%) rgb(92, 184, 92);
+    border: 1px solid rgb(62, 142, 62);
+    color: rgb(51, 51, 51);
+}
+
+#patreon a {
+    background: linear-gradient(rgb(11, 100, 163) 5%, rgb(5, 45, 73) 100%) rgb(11, 100, 163);
+    border: 1px solid rgb(5, 45, 73);
+    color: #eee;
+}
+</style>
+
+<div id="support-buttons">
+<div id="patreon">
+    <a class="support-button" href="https://www.patreon.com/bePatron?u=917933">Patronage via Patreon</a>
+</div>
+
+<div>
+    <form id="paypal" action="https://www.paypal.com/cgi-bin/webscr" method="post" title="Contribute to support calibre development">
+        <input type="hidden" name="cmd" value="_s-xclick" />
+        <input type="hidden" name="hosted_button_id" value="FEELASHWEL5HS" />
+        <input class="support-button" type="submit" name="submit" value="One time support via PayPal" />
+        <img alt="" border="0" src="https://www.paypalobjects.com/en_GB/i/scr/pixel.gif" width="1" height="1" />
+    </form>
+</div>
+
+<div id="liberapay">
+    <a class="support-button" href="https://liberapay.com/kovidgoyal/donate">Patronage via Liberapay</a>
+</div>
+
+</div>
+

docs/support.rst

@@ -0,0 +1,23 @@
+Support kitty development
+===========================
+
+My goal with |kitty| is to move the stagnant terminal ecosystem forward.  To that
+end kitty has many foundational features, such as: :doc:`image support
+<graphics-protocol>`, :doc:`superlative performance <performance>`,
+:doc:`various enhancements to the terminal protocol <protocol-extensions>`,
+etc. These features allow the development of rich terminal applications, such
+as :doc:`Side-by-side diff <kittens/diff>` and :doc:`Unicode input
+<kittens/unicode-input>`.
+
+If you wish to support this mission and see the terminal ecosystem evolve,
+consider donating so that I can devote more time to |kitty| development.
+I have personally written `almost all kitty code
+<https://github.com/kovidgoyal/kitty/graphs/contributors>`_.
+
+You can choose to make either a one-time payment via PayPal or become a
+*patron* of kitty development via the Patreon or Liberapay services
+below:
+
+
+.. raw:: html
+    :file: support.html

gen-apc-parsers.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+# License: GPLv3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+import subprocess
+from collections import defaultdict
+from typing import Any, DefaultDict, Dict, FrozenSet, List, Tuple, Union
+
+KeymapType = Dict[str, Tuple[str, Union[FrozenSet[str], str]]]
+
+
+def resolve_keys(keymap: KeymapType) -> DefaultDict[str, List[str]]:
+    ans: DefaultDict[str, List[str]] = defaultdict(list)
+    for ch, (attr, atype) in keymap.items():
+        if isinstance(atype, str) and atype in ('int', 'uint'):
+            q = atype
+        else:
+            q = 'flag'
+        ans[q].append(ch)
+    return ans
+
+
+def enum(keymap: KeymapType) -> str:
+    lines = []
+    for ch, (attr, atype) in keymap.items():
+        lines.append(f"{attr}='{ch}'")
+    return '''
+    enum KEYS {{
+        {}
+    }};
+    '''.format(',\n'.join(lines))
+
+
+def parse_key(keymap: KeymapType) -> str:
+    lines = []
+    for attr, atype in keymap.values():
+        vs = atype.upper() if isinstance(atype, str) and atype in ('uint', 'int') else 'FLAG'
+        lines.append(f'case {attr}: value_state = {vs}; break;')
+    return '        \n'.join(lines)
+
+
+def parse_flag(keymap: KeymapType, type_map: Dict[str, Any], command_class: str) -> str:
+    lines = []
+    for ch in type_map['flag']:
+        attr, allowed_values = keymap[ch]
+        q = ' && '.join(f"g.{attr} != '{x}'" for x in allowed_values)
+        lines.append(f'''
+            case {attr}: {{
+                g.{attr} = screen->parser_buf[pos++] & 0xff;
+                if ({q}) {{
+                    REPORT_ERROR("Malformed {command_class} control block, unknown flag value for {attr}: 0x%x", g.{attr});
+                    return;
+                }};
+            }}
+            break;
+        ''')
+    return '        \n'.join(lines)
+
+
+def parse_number(keymap: KeymapType) -> Tuple[str, str]:
+    int_keys = [f'I({attr})' for attr, atype in keymap.values() if atype == 'int']
+    uint_keys = [f'U({attr})' for attr, atype in keymap.values() if atype == 'uint']
+    return '; '.join(int_keys), '; '.join(uint_keys)
+
+
+def cmd_for_report(report_name: str, keymap: KeymapType, type_map: Dict[str, Any], payload_allowed: bool) -> str:
+    def group(atype: str, conv: str) -> Tuple[str, str]:
+        flag_fmt, flag_attrs = [], []
+        cv = {'flag': 'c', 'int': 'i', 'uint': 'I'}[atype]
+        for ch in type_map[atype]:
+            flag_fmt.append('s' + cv)
+            attr = keymap[ch][0]
+            flag_attrs.append(f'"{attr}", {conv}g.{attr}')
+        return ' '.join(flag_fmt), ', '.join(flag_attrs)
+
+    flag_fmt, flag_attrs = group('flag', '')
+    int_fmt, int_attrs = group('int', '(int)')
+    uint_fmt, uint_attrs = group('uint', '(unsigned int)')
+
+    fmt = f'{flag_fmt} {uint_fmt} {int_fmt}'
+    if payload_allowed:
+        ans = [f'REPORT_VA_COMMAND("s {{{fmt} sI}} y#", "{report_name}",']
+    else:
+        ans = [f'REPORT_VA_COMMAND("s {{{fmt}}}", "{report_name}",']
+    ans.append(',\n     '.join((flag_attrs, uint_attrs, int_attrs)))
+    if payload_allowed:
+        ans.append(', "payload_sz", g.payload_sz, payload, g.payload_sz')
+    ans.append(');')
+    return '\n'.join(ans)
+
+
+def generate(
+    function_name: str,
+    callback_name: str,
+    report_name: str,
+    keymap: KeymapType,
+    command_class: str,
+    initial_key: str = 'a',
+    payload_allowed: bool = True
+) -> str:
+    type_map = resolve_keys(keymap)
+    keys_enum = enum(keymap)
+    handle_key = parse_key(keymap)
+    flag_keys = parse_flag(keymap, type_map, command_class)
+    int_keys, uint_keys = parse_number(keymap)
+    report_cmd = cmd_for_report(report_name, keymap, type_map, payload_allowed)
+    if payload_allowed:
+        payload_after_value = "case ';': state = PAYLOAD; break;"
+        payload = ', PAYLOAD'
+        parr = 'static uint8_t payload[4096];'
+        payload_case = f'''
+            case PAYLOAD: {{
+                sz = screen->parser_buf_pos - pos;
+                const char *err = base64_decode(screen->parser_buf + pos, sz, payload, sizeof(payload), &g.payload_sz);
+                if (err != NULL) {{ REPORT_ERROR("Failed to parse {command_class} command payload with error: %s", err); return; }}
+                pos = screen->parser_buf_pos;
+                }}
+                break;
+        '''
+        callback = f'{callback_name}(screen, &g, payload)'
+    else:
+        payload_after_value = payload = parr = payload_case = ''
+        callback = f'{callback_name}(screen, &g)'
+
+    return f'''
+static inline void
+{function_name}(Screen *screen, PyObject UNUSED *dump_callback) {{
+    unsigned int pos = 1;
+    enum PARSER_STATES {{ KEY, EQUAL, UINT, INT, FLAG, AFTER_VALUE {payload} }};
+    enum PARSER_STATES state = KEY, value_state = FLAG;
+    static {command_class} g;
+    unsigned int i, code;
+    uint64_t lcode;
+    bool is_negative;
+    memset(&g, 0, sizeof(g));
+    size_t sz;
+    {parr}
+    {keys_enum}
+    enum KEYS key = '{initial_key}';
+    if (screen->parser_buf[pos] == ';') state = AFTER_VALUE;
+
+    while (pos < screen->parser_buf_pos) {{
+        switch(state) {{
+            case KEY:
+                key = screen->parser_buf[pos++];
+                state = EQUAL;
+                switch(key) {{
+                    {handle_key}
+                    default:
+                        REPORT_ERROR("Malformed {command_class} control block, invalid key character: 0x%x", key);
+                        return;
+                }}
+                break;
+
+            case EQUAL:
+                if (screen->parser_buf[pos++] != '=') {{
+                    REPORT_ERROR("Malformed {command_class} control block, no = after key, found: 0x%x instead", screen->parser_buf[pos-1]);
+                    return;
+                }}
+                state = value_state;
+                break;
+
+            case FLAG:
+                switch(key) {{
+                    {flag_keys}
+                    default:
+                        break;
+                }}
+                state = AFTER_VALUE;
+                break;
+
+            case INT:
+#define READ_UINT \\
+                for (i = pos; i < MIN(screen->parser_buf_pos, pos + 10); i++) {{ \\
+                    if (screen->parser_buf[i] < '0' || screen->parser_buf[i] > '9') break; \\
+                }} \\
+                if (i == pos) {{ REPORT_ERROR("Malformed {command_class} control block, expecting an integer value for key: %c", key & 0xFF); return; }} \\
+                lcode = utoi(screen->parser_buf + pos, i - pos); pos = i; \\
+                if (lcode > UINT32_MAX) {{ REPORT_ERROR("Malformed {command_class} control block, number is too large"); return; }} \\
+                code = lcode;
+
+                is_negative = false;
+                if(screen->parser_buf[pos] == '-') {{ is_negative = true; pos++; }}
+#define I(x) case x: g.x = is_negative ? 0 - (int32_t)code : (int32_t)code; break
+                READ_UINT;
+                switch(key) {{
+                    {int_keys};
+                    default: break;
+                }}
+                state = AFTER_VALUE;
+                break;
+#undef I
+            case UINT:
+                READ_UINT;
+#define U(x) case x: g.x = code; break
+                switch(key) {{
+                    {uint_keys};
+                    default: break;
+                }}
+                state = AFTER_VALUE;
+                break;
+#undef U
+#undef READ_UINT
+
+            case AFTER_VALUE:
+                switch (screen->parser_buf[pos++]) {{
+                    default:
+                        REPORT_ERROR("Malformed {command_class} control block, expecting a comma or semi-colon after a value, found: 0x%x",
+                                     screen->parser_buf[pos - 1]);
+                        return;
+                    case ',':
+                        state = KEY;
+                        break;
+                    {payload_after_value}
+                }}
+                break;
+
+            {payload_case}
+
+        }} // end switch
+    }} // end while
+
+    switch(state) {{
+        case EQUAL:
+            REPORT_ERROR("Malformed {command_class} control block, no = after key"); return;
+        case INT:
+        case UINT:
+            REPORT_ERROR("Malformed {command_class} control block, expecting an integer value"); return;
+        case FLAG:
+            REPORT_ERROR("Malformed {command_class} control block, expecting a flag value"); return;
+        default:
+            break;
+    }}
+
+    {report_cmd}
+
+    {callback};
+}}
+    '''
+
+
+def write_header(text: str, path: str) -> None:
+    with open(path, 'w') as f:
+        print(f'// This file is generated by {__file__} do not edit!', file=f, end='\n\n')
+        print('#pragma once', file=f)
+        print(text, file=f)
+    subprocess.check_call(['clang-format', '-i', path])
+
+
+def graphics_parser() -> None:
+    flag = frozenset
+    keymap: KeymapType = {
+        'a': ('action', flag('tTqpd')),
+        'd': ('delete_action', flag('aAiIcCpPqQxXyYzZ')),
+        't': ('transmission_type', flag('dfts')),
+        'o': ('compressed', flag('z')),
+        'f': ('format', 'uint'),
+        'm': ('more', 'uint'),
+        'i': ('id', 'uint'),
+        'w': ('width', 'uint'),
+        'h': ('height', 'uint'),
+        'x': ('x_offset', 'uint'),
+        'y': ('y_offset', 'uint'),
+        'v': ('data_height', 'uint'),
+        's': ('data_width', 'uint'),
+        'S': ('data_sz', 'uint'),
+        'O': ('data_offset', 'uint'),
+        'c': ('num_cells', 'uint'),
+        'r': ('num_lines', 'uint'),
+        'X': ('cell_x_offset', 'uint'),
+        'Y': ('cell_y_offset', 'uint'),
+        'z': ('z_index', 'int'),
+    }
+    text = generate('parse_graphics_code', 'screen_handle_graphics_command', 'graphics_command', keymap, 'GraphicsCommand')
+    write_header(text, 'kitty/parse-graphics-command.h')
+
+
+graphics_parser()

gen-wcwidth.py

@@ -0,0 +1,543 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2017, Kovid Goyal <kovid at kovidgoyal.net>
+
+import os
+import re
+import sys
+from collections import defaultdict
+from contextlib import contextmanager
+from datetime import date
+from functools import partial
+from html.entities import html5
+from itertools import groupby
+from operator import itemgetter
+from typing import (
+    Callable, DefaultDict, Dict, FrozenSet, Generator, Iterable, List,
+    Optional, Set, Tuple, Union
+)
+from urllib.request import urlopen
+
+os.chdir(os.path.dirname(os.path.abspath(__file__)))
+
+non_characters = frozenset(range(0xfffe, 0x10ffff, 0x10000))
+non_characters |= frozenset(range(0xffff, 0x10ffff + 1, 0x10000))
+non_characters |= frozenset(range(0xfdd0, 0xfdf0))
+if len(non_characters) != 66:
+    raise SystemExit('non_characters table incorrect')
+emoji_skin_tone_modifiers = frozenset(range(0x1f3fb, 0x1F3FF + 1))
+
+
+def get_data(fname: str, folder: str = 'UCD') -> Iterable[str]:
+    url = f'https://www.unicode.org/Public/{folder}/latest/{fname}'
+    bn = os.path.basename(url)
+    local = os.path.join('/tmp', bn)
+    if os.path.exists(local):
+        with open(local, 'rb') as f:
+            data = f.read()
+    else:
+        data = urlopen(url).read()
+        with open(local, 'wb') as f:
+            f.write(data)
+    for line in data.decode('utf-8').splitlines():
+        line = line.strip()
+        if line and not line.startswith('#'):
+            yield line
+
+
+# Map of class names to set of codepoints in class
+class_maps: Dict[str, Set[int]] = {}
+all_symbols: Set[int] = set()
+name_map: Dict[int, str] = {}
+word_search_map: DefaultDict[str, Set[int]] = defaultdict(set)
+zwj = 0x200d
+flag_codepoints = frozenset(range(0x1F1E6, 0x1F1E6 + 26))
+marks = set(emoji_skin_tone_modifiers) | {zwj} | flag_codepoints
+not_assigned = set(range(0, sys.maxunicode))
+
+
+def parse_ucd() -> None:
+
+    def add_word(w: str, c: int) -> None:
+        if c <= 32 or c == 127 or 128 <= c <= 159:
+            return
+        if len(w) > 1:
+            word_search_map[w.lower()].add(c)
+
+    first: Optional[int] = None
+    for word, c in html5.items():
+        if len(c) == 1:
+            add_word(word.rstrip(';'), ord(c))
+    word_search_map['nnbsp'].add(0x202f)
+    for line in get_data('ucd/UnicodeData.txt'):
+        parts = [x.strip() for x in line.split(';')]
+        codepoint = int(parts[0], 16)
+        name = parts[1] or parts[10]
+        if name == '<control>':
+            name = parts[10]
+        if name:
+            name_map[codepoint] = name
+            for word in name.lower().split():
+                add_word(word, codepoint)
+        category = parts[2]
+        s = class_maps.setdefault(category, set())
+        desc = parts[1]
+        codepoints: Union[Tuple[int, ...], Iterable[int]] = (codepoint,)
+        if first is None:
+            if desc.endswith(', First>'):
+                first = codepoint
+                continue
+        else:
+            codepoints = range(first, codepoint + 1)
+            first = None
+        for codepoint in codepoints:
+            s.add(codepoint)
+            not_assigned.discard(codepoint)
+            if category.startswith('M'):
+                marks.add(codepoint)
+            elif category.startswith('S'):
+                all_symbols.add(codepoint)
+
+    with open('nerd-fonts-glyphs.txt') as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            code, category, name = line.split(' ', 2)
+            codepoint = int(code, 16)
+            if name and codepoint not in name_map:
+                name_map[codepoint] = name.upper()
+                for word in name.lower().split():
+                    add_word(word, codepoint)
+
+    # Some common synonyms
+    word_search_map['bee'] |= word_search_map['honeybee']
+    word_search_map['lambda'] |= word_search_map['lamda']
+    word_search_map['lamda'] |= word_search_map['lambda']
+
+
+def parse_range_spec(spec: str) -> Set[int]:
+    spec = spec.strip()
+    if '..' in spec:
+        chars_ = tuple(map(lambda x: int(x, 16), filter(None, spec.split('.'))))
+        chars = set(range(chars_[0], chars_[1] + 1))
+    else:
+        chars = {int(spec, 16)}
+    return chars
+
+
+def split_two(line: str) -> Tuple[Set[int], str]:
+    spec, rest = line.split(';', 1)
+    spec, rest = spec.strip(), rest.strip().split(' ', 1)[0].strip()
+    return parse_range_spec(spec), rest
+
+
+all_emoji: Set[int] = set()
+emoji_presentation_bases: Set[int] = set()
+narrow_emoji: Set[int] = set()
+wide_emoji: Set[int] = set()
+flags: Dict[int, List[int]] = {}
+
+
+def parse_basic_emoji(spec: str) -> None:
+    parts = list(filter(None, spec.split()))
+    has_emoji_presentation = len(parts) < 2
+    chars = parse_range_spec(parts[0])
+    all_emoji.update(chars)
+    emoji_presentation_bases.update(chars)
+    (wide_emoji if has_emoji_presentation else narrow_emoji).update(chars)
+
+
+def parse_keycap_sequence(spec: str) -> None:
+    base, fe0f, cc = list(filter(None, spec.split()))
+    chars = parse_range_spec(base)
+    all_emoji.update(chars)
+    emoji_presentation_bases.update(chars)
+    narrow_emoji.update(chars)
+
+
+def parse_flag_emoji_sequence(spec: str) -> None:
+    a, b = list(filter(None, spec.split()))
+    left, right = int(a, 16), int(b, 16)
+    chars = {left, right}
+    all_emoji.update(chars)
+    wide_emoji.update(chars)
+    emoji_presentation_bases.update(chars)
+    flags.setdefault(left, []).append(right)
+
+
+def parse_emoji_tag_sequence(spec: str) -> None:
+    a = int(spec.split()[0], 16)
+    all_emoji.add(a)
+    wide_emoji.add(a)
+    emoji_presentation_bases.add(a)
+
+
+def parse_emoji_modifier_sequence(spec: str) -> None:
+    a, b = list(filter(None, spec.split()))
+    char, mod = int(a, 16), int(b, 16)
+    mod
+    all_emoji.add(char)
+    wide_emoji.add(char)
+    emoji_presentation_bases.add(char)
+
+
+def parse_emoji() -> None:
+    for line in get_data('emoji-sequences.txt', 'emoji'):
+        parts = [x.strip() for x in line.split(';')]
+        if len(parts) < 2:
+            continue
+        data, etype = parts[:2]
+        if etype == 'Basic_Emoji':
+            parse_basic_emoji(data)
+        elif etype == 'Emoji_Keycap_Sequence':
+            parse_keycap_sequence(data)
+        elif etype == 'RGI_Emoji_Flag_Sequence':
+            parse_flag_emoji_sequence(data)
+        elif etype == 'RGI_Emoji_Tag_Sequence':
+            parse_emoji_tag_sequence(data)
+        elif etype == 'RGI_Emoji_Modifier_Sequence':
+            parse_emoji_modifier_sequence(data)
+
+
+doublewidth: Set[int] = set()
+ambiguous: Set[int] = set()
+
+
+def parse_eaw() -> None:
+    global doublewidth, ambiguous
+    seen: Set[int] = set()
+    for line in get_data('ucd/EastAsianWidth.txt'):
+        chars, eaw = split_two(line)
+        if eaw == 'A':
+            ambiguous |= chars
+            seen |= chars
+        elif eaw == 'W' or eaw == 'F':
+            doublewidth |= chars
+            seen |= chars
+    doublewidth |= set(range(0x3400, 0x4DBF + 1)) - seen
+    doublewidth |= set(range(0x4E00, 0x9FFF + 1)) - seen
+    doublewidth |= set(range(0xF900, 0xFAFF + 1)) - seen
+    doublewidth |= set(range(0x20000, 0x2FFFD + 1)) - seen
+    doublewidth |= set(range(0x30000, 0x3FFFD + 1)) - seen
+
+
+def get_ranges(items: List[int]) -> Generator[Union[int, Tuple[int, int]], None, None]:
+    items.sort()
+    for k, g in groupby(enumerate(items), lambda m: m[0]-m[1]):
+        group = tuple(map(itemgetter(1), g))
+        a, b = group[0], group[-1]
+        if a == b:
+            yield a
+        else:
+            yield a, b
+
+
+def write_case(spec: Union[Tuple, int], p: Callable) -> None:
+    if isinstance(spec, tuple):
+        p('\t\tcase 0x{:x} ... 0x{:x}:'.format(*spec))
+    else:
+        p('\t\tcase 0x{:x}:'.format(spec))
+
+
+@contextmanager
+def create_header(path: str, include_data_types: bool = True) -> Generator[Callable, None, None]:
+    with open(path, 'w') as f:
+        p = partial(print, file=f)
+        p('// unicode data, built from the unicode standard on:', date.today())
+        p('// see gen-wcwidth.py')
+        if path.endswith('.h'):
+            p('#pragma once')
+        if include_data_types:
+            p('#include "data-types.h"\n')
+            p('START_ALLOW_CASE_RANGE')
+        p()
+        yield p
+        p()
+        if include_data_types:
+            p('END_ALLOW_CASE_RANGE')
+
+
+def gen_emoji() -> None:
+    with create_header('kitty/emoji.h') as p:
+        p('static inline bool\nis_emoji(char_type code) {')
+        p('\tswitch(code) {')
+        for spec in get_ranges(list(all_emoji)):
+            write_case(spec, p)
+            p('\t\t\treturn true;')
+        p('\t\tdefault: return false;')
+        p('\t}')
+        p('\treturn false;\n}')
+
+        p('static inline bool\nis_symbol(char_type code) {')
+        p('\tswitch(code) {')
+        for spec in get_ranges(list(all_symbols)):
+            write_case(spec, p)
+            p('\t\t\treturn true;')
+        p('\t\tdefault: return false;')
+        p('\t}')
+        p('\treturn false;\n}')
+
+
+def category_test(
+    name: str,
+    p: Callable,
+    classes: Iterable[str],
+    comment: str,
+    use_static: bool = False,
+    extra_chars: Union[FrozenSet[int], Set[int]] = frozenset(),
+    exclude: Union[Set[int], FrozenSet[int]] = frozenset(),
+    least_check_return: Optional[str] = None,
+    ascii_range: Optional[str] = None
+) -> None:
+    static = 'static inline ' if use_static else ''
+    chars: Set[int] = set()
+    for c in classes:
+        chars |= class_maps[c]
+    chars |= extra_chars
+    chars -= exclude
+    p(f'{static}bool\n{name}(char_type code) {{')
+    p(f'\t// {comment} ({len(chars)} codepoints)' + ' {{' '{')
+    if least_check_return is not None:
+        least = min(chars)
+        p(f'\tif (LIKELY(code < {least})) return {least_check_return};')
+    if ascii_range is not None:
+        p(f'\tif (LIKELY(0x20 <= code && code <= 0x7e)) return {ascii_range};')
+    p('\tswitch(code) {')
+    for spec in get_ranges(list(chars)):
+        write_case(spec, p)
+        p('\t\t\treturn true;')
+    p('\t} // }}}\n')
+    p('\treturn false;\n}\n')
+
+
+def codepoint_to_mark_map(p: Callable, mark_map: List[int]) -> Dict[int, int]:
+    p('\tswitch(c) { // {{{')
+    rmap = {c: m for m, c in enumerate(mark_map)}
+    for spec in get_ranges(mark_map):
+        if isinstance(spec, tuple):
+            s = rmap[spec[0]]
+            cases = ' '.join(f'case {i}:' for i in range(spec[0], spec[1]+1))
+            p(f'\t\t{cases} return {s} + c - {spec[0]};')
+        else:
+            p(f'\t\tcase {spec}: return {rmap[spec]};')
+    p('default: return 0;')
+    p('\t} // }}}')
+    return rmap
+
+
+def classes_to_regex(classes: Iterable[str], exclude: str = '') -> Iterable[str]:
+    chars: Set[int] = set()
+    for c in classes:
+        chars |= class_maps[c]
+    for x in map(ord, exclude):
+        chars.discard(x)
+
+    def as_string(codepoint: int) -> str:
+        if codepoint < 256:
+            return r'\x{:02x}'.format(codepoint)
+        if codepoint <= 0xffff:
+            return r'\u{:04x}'.format(codepoint)
+        return r'\U{:08x}'.format(codepoint)
+
+    for spec in get_ranges(list(chars)):
+        if isinstance(spec, tuple):
+            yield '{}-{}'.format(*map(as_string, (spec[0], spec[1])))
+        else:
+            yield as_string(spec)
+
+
+def gen_ucd() -> None:
+    cz = {c for c in class_maps if c[0] in 'CZ'}
+    with create_header('kitty/unicode-data.c') as p:
+        p('#include "unicode-data.h"')
+        category_test(
+                'is_combining_char', p,
+                {c for c in class_maps if c.startswith('M')},
+                'M category (marks)',
+                # See https://github.com/harfbuzz/harfbuzz/issues/169
+                extra_chars=emoji_skin_tone_modifiers | {zwj},
+                least_check_return='false'
+        )
+        category_test(
+            'is_ignored_char', p, 'Cc Cf Cs'.split(),
+            'Control characters and non-characters',
+            extra_chars=non_characters, exclude={zwj},
+            ascii_range='false'
+        )
+        category_test('is_word_char', p, {c for c in class_maps if c[0] in 'LN'}, 'L and N categories')
+        category_test('is_CZ_category', p, cz, 'C and Z categories')
+        category_test('is_P_category', p, {c for c in class_maps if c[0] == 'P'}, 'P category (punctuation)')
+        mark_map = [0] + list(sorted(marks))
+        p('char_type codepoint_for_mark(combining_type m) {')
+        p(f'\tstatic char_type map[{len(mark_map)}] =', '{', ', '.join(map(str, mark_map)), '}; // {{{ mapping }}}')
+        p('\tif (m < arraysz(map)) return map[m];')
+        p('\treturn 0;')
+        p('}\n')
+        p('combining_type mark_for_codepoint(char_type c) {')
+        rmap = codepoint_to_mark_map(p, mark_map)
+        p('}\n')
+        with open('kitty/unicode-data.h') as f:
+            unicode_data = f.read()
+        m = re.search(r'^#define VS15 (\d+)', unicode_data, re.M)
+        if m is not None:
+            expected = int(m.group(1))
+        if rmap[0xfe0e] != expected:
+            raise ValueError('The mark for 0xfe0e has changed, you have to update VS15 to {} and VS16 to {} in unicode-data.h'.format(
+                rmap[0xfe0e], rmap[0xfe0f]
+            ))
+    with open('kittens/hints/url_regex.py', 'w') as f:
+        f.write("url_delimiters = '{}'  # noqa".format(''.join(classes_to_regex(cz, exclude='\n'))))
+
+
+def gen_names() -> None:
+    with create_header('kittens/unicode_input/names.h') as p:
+        mark_to_cp = list(sorted(name_map))
+        cp_to_mark = {cp: m for m, cp in enumerate(mark_to_cp)}
+        # Mapping of mark to codepoint name
+        p(f'static const char* name_map[{len(mark_to_cp)}] = {{' ' // {{{')
+        for cp in mark_to_cp:
+            w = name_map[cp].replace('"', '\\"')
+            p(f'\t"{w}",')
+        p("}; // }}}\n")
+
+        # Mapping of mark to codepoint
+        p(f'static const char_type mark_to_cp[{len(mark_to_cp)}] = {{' ' // {{{')
+        p(', '.join(map(str, mark_to_cp)))
+        p('}; // }}}\n')
+
+        # Function to get mark number for codepoint
+        p('static char_type mark_for_codepoint(char_type c) {')
+        codepoint_to_mark_map(p, mark_to_cp)
+        p('}\n')
+        p('static inline const char* name_for_codepoint(char_type cp) {')
+        p('\tchar_type m = mark_for_codepoint(cp); if (m == 0) return NULL;')
+        p('\treturn name_map[m];')
+        p('}\n')
+
+        # Array of all words
+        word_map = tuple(sorted(word_search_map))
+        word_rmap = {w: i for i, w in enumerate(word_map)}
+        p(f'static const char* all_words_map[{len(word_map)}] = {{' ' // {{{')
+        cwords = (w.replace('"', '\\"') for w in word_map)
+        p(', '.join(f'"{w}"' for w in cwords))
+        p('}; // }}}\n')
+
+        # Array of sets of marks for each word
+        word_to_marks = {word_rmap[w]: frozenset(map(cp_to_mark.__getitem__, cps)) for w, cps in word_search_map.items()}
+        all_mark_groups = frozenset(word_to_marks.values())
+        array = [0]
+        mg_to_offset = {}
+        for mg in all_mark_groups:
+            mg_to_offset[mg] = len(array)
+            array.append(len(mg))
+            array.extend(sorted(mg))
+        p(f'static const char_type mark_groups[{len(array)}] = {{' ' // {{{')
+        p(', '.join(map(str, array)))
+        p('}; // }}}\n')
+        offsets_array = []
+        for wi, w in enumerate(word_map):
+            mg = word_to_marks[wi]
+            offsets_array.append(mg_to_offset[mg])
+        p(f'static const char_type mark_to_offset[{len(offsets_array)}] = {{' ' // {{{')
+        p(', '.join(map(str, offsets_array)))
+        p('}; // }}}\n')
+
+        # The trie
+        p('typedef struct { uint32_t children_offset; uint32_t match_offset; } word_trie;\n')
+        all_trie_nodes: List['TrieNode'] = []  # noqa
+
+        class TrieNode:
+
+            def __init__(self) -> None:
+                self.match_offset = 0
+                self.children_offset = 0
+                self.children: Dict[int, int] = {}
+
+            def add_letter(self, letter: int) -> int:
+                if letter not in self.children:
+                    self.children[letter] = len(all_trie_nodes)
+                    all_trie_nodes.append(TrieNode())
+                return self.children[letter]
+
+            def __str__(self) -> str:
+                return f'{{ .children_offset={self.children_offset}, .match_offset={self.match_offset} }}'
+
+        root = TrieNode()
+        all_trie_nodes.append(root)
+
+        def add_word(word_idx: int, word: str) -> None:
+            parent = root
+            for letter in map(ord, word):
+                idx = parent.add_letter(letter)
+                parent = all_trie_nodes[idx]
+            parent.match_offset = offsets_array[word_idx]
+
+        for i, word in enumerate(word_map):
+            add_word(i, word)
+        children_array = [0]
+        for node in all_trie_nodes:
+            if node.children:
+                node.children_offset = len(children_array)
+                children_array.append(len(node.children))
+                for letter, child_offset in node.children.items():
+                    children_array.append((child_offset << 8) | (letter & 0xff))
+
+        p(f'static const word_trie all_trie_nodes[{len(all_trie_nodes)}] = {{' ' // {{{')
+        p(',\n'.join(map(str, all_trie_nodes)))
+        p('\n}; // }}}\n')
+        p(f'static const uint32_t children_array[{len(children_array)}] = {{' ' // {{{')
+        p(', '.join(map(str, children_array)))
+        p('}; // }}}\n')
+
+
+def gen_wcwidth() -> None:
+    seen: Set[int] = set()
+
+    def add(p: Callable, comment: str, chars_: Union[Set[int], FrozenSet[int]], ret: int) -> None:
+        chars = chars_ - seen
+        seen.update(chars)
+        p(f'\t\t// {comment} ({len(chars)} codepoints)' + ' {{' '{')
+        for spec in get_ranges(list(chars)):
+            write_case(spec, p)
+            p(f'\t\t\treturn {ret};')
+        p('\t\t// }}}\n')
+
+    with create_header('kitty/wcwidth-std.h') as p:
+        p('static int\nwcwidth_std(int32_t code) {')
+        p('\tif (LIKELY(0x20 <= code && code <= 0x7e)) return 1;')
+        p('\tswitch(code) {')
+
+        non_printing = class_maps['Cc'] | class_maps['Cf'] | class_maps['Cs']
+        add(p, 'Flags', flag_codepoints, 2)
+        add(p, 'Marks', marks | {0}, 0)
+        add(p, 'Non-printing characters', non_printing, -1)
+        add(p, 'Private use', class_maps['Co'], -3)
+        add(p, 'Text Presentation', narrow_emoji, 1)
+        add(p, 'East Asian ambiguous width', ambiguous, -2)
+        add(p, 'East Asian double width', doublewidth, 2)
+        add(p, 'Emoji Presentation', wide_emoji, 2)
+
+        add(p, 'Not assigned in the unicode character database', not_assigned, -4)
+
+        p('\t\tdefault: return 1;')
+        p('\t}')
+        p('\treturn 1;\n}')
+
+        p('static inline bool\nis_emoji_presentation_base(uint32_t code) {')
+        p('\tswitch(code) {')
+        for spec in get_ranges(list(emoji_presentation_bases)):
+            write_case(spec, p)
+            p('\t\t\treturn true;')
+        p('\t\tdefault: return false;')
+        p('\t}')
+        p('\treturn 1;\n}')
+
+
+parse_ucd()
+parse_emoji()
+parse_eaw()
+gen_ucd()
+gen_wcwidth()
+gen_emoji()
+gen_names()

generate-unicode-data.py

@@ -1,57 +0,0 @@
-#!/usr/bin/env python3
-# vim:fileencoding=utf-8
-# License: GPL v3 Copyright: 2016, Kovid Goyal <kovid at kovidgoyal.net>
-
-import unicodedata
-import itertools
-import sys
-
-IGNORED_CATEGORIES = ('Cc', 'Cf', 'Cs')
-
-
-def ranges(i):
-    for a, b in itertools.groupby(enumerate(i), lambda r: r[1] - r[0]):
-        b = list(b)
-        yield b[0][1], b[-1][1]
-
-
-def generate_data(chars):
-    points, cranges = [], []
-    for l, r in ranges(chars):
-        if l == r:
-            points.append(l)
-        else:
-            cranges.append((l, r))
-    return points, cranges
-
-
-def generate_predicate(name, chars):
-    points, cranges = generate_data(chars)
-    cranges = ['(0x%x %s ch && ch <= 0x%x)' % (l, '<' if l == 0 else '<=', r) for l, r in cranges]
-    points = ['(ch == 0x%x)' % p for p in points]
-    return '''
-static inline bool %s(uint32_t ch) {
-    return %s || %s;
-}
-    ''' % (name, '||'.join(cranges), '||'.join(points))
-
-
-def main():
-    combining_chars = []
-    igchars = []
-    for c in map(chr, range(sys.maxunicode + 1)):
-        if unicodedata.category(c) in IGNORED_CATEGORIES:
-            igchars.append(ord(c))
-        if unicodedata.combining(c):
-            combining_chars.append(ord(c))
-
-    cc = generate_predicate('is_combining_char', combining_chars)
-    ig = generate_predicate('is_ignored_char', igchars)
-    with open('kitty/unicode-data.h', 'w') as f:
-        print('#pragma once', file=f)
-        print(cc, file=f)
-        print(ig, file=f)
-
-
-if __name__ == '__main__':
-    main()

glad/generate.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2017, Kovid Goyal <kovid at kovidgoyal.net>
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+
+
+cmdline = (
+    'glad --out-path {dest} --api gl:core=3.3 '
+    ' --extensions GL_ARB_texture_storage,GL_ARB_copy_image,GL_ARB_multisample,GL_ARB_robustness,GL_KHR_debug '
+    'c --header-only --debug'
+)
+
+
+def clean(x):
+    if os.path.exists(x):
+        shutil.rmtree(x)
+
+
+def regenerate():
+    clean('out')
+
+    subprocess.check_call(
+        shlex.split(cmdline.format(dest='out'))
+    )
+
+
+def strip_trailing_whitespace(c):
+    return re.sub(r'\s+$', '', c, flags=re.MULTILINE) + '\n'
+
+
+def export():
+    with open('out/include/glad/gl.h', 'r', encoding='utf-8') as source:
+        data = source.read()
+        data = strip_trailing_whitespace(data)
+
+        with open('../kitty/gl-wrapper.h', 'w', encoding='utf-8') as dest:
+            dest.write(data)
+
+
+if __name__ == '__main__':
+    os.chdir(os.path.dirname(os.path.abspath(__file__)))
+    regenerate()
+    export()

glfw/backend_utils.c

@@ -0,0 +1,352 @@
+/*
+ * backend_utils.c
+ * Copyright (C) 2018 Kovid Goyal <kovid at kovidgoyal.net>
+ *
+ * Distributed under terms of the GPL3 license.
+ */
+
+#define _GNU_SOURCE
+#include "backend_utils.h"
+#include "internal.h"
+
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <errno.h>
+#include <float.h>
+#include <time.h>
+#include <stdio.h>
+
+#ifdef __NetBSD__
+#define ppoll pollts
+#endif
+
+void
+update_fds(EventLoopData *eld) {
+    for (nfds_t i = 0; i < eld->watches_count; i++) {
+        Watch *w = eld->watches + i;
+        eld->fds[i].fd = w->fd;
+        eld->fds[i].events = w->enabled ? w->events : 0;
+    }
+}
+
+static id_type watch_counter = 0;
+
+id_type
+addWatch(EventLoopData *eld, const char* name, int fd, int events, int enabled, watch_callback_func cb, void *cb_data) {
+    if (eld->watches_count >= sizeof(eld->watches)/sizeof(eld->watches[0])) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Too many watches added");
+        return 0;
+    }
+    Watch *w = eld->watches + eld->watches_count++;
+    w->name = name;
+    w->fd = fd; w->events = events; w->enabled = enabled;
+    w->callback = cb;
+    w->callback_data = cb_data;
+    w->free = NULL;
+    w->id = ++watch_counter;
+    update_fds(eld);
+    return w->id;
+}
+
+#define removeX(which, item_id, update_func) {\
+    for (nfds_t i = 0; i < eld->which##_count; i++) { \
+        if (eld->which[i].id == item_id) { \
+            eld->which##_count--; \
+            if (eld->which[i].callback_data && eld->which[i].free) { \
+                eld->which[i].free(eld->which[i].id, eld->which[i].callback_data); \
+                eld->which[i].callback_data = NULL; eld->which[i].free = NULL; \
+            } \
+            if (i < eld->which##_count) { \
+                memmove(eld->which + i, eld->which + i + 1, sizeof(eld->which[0]) * (eld->which##_count - i)); \
+            } \
+            update_func(eld); break; \
+}}}
+
+void
+removeWatch(EventLoopData *eld, id_type watch_id) {
+    removeX(watches, watch_id, update_fds);
+}
+
+void
+toggleWatch(EventLoopData *eld, id_type watch_id, int enabled) {
+    for (nfds_t i = 0; i < eld->watches_count; i++) {
+        if (eld->watches[i].id == watch_id) {
+            if (eld->watches[i].enabled != enabled) {
+                eld->watches[i].enabled = enabled;
+                update_fds(eld);
+            }
+            break;
+        }
+    }
+}
+
+static id_type timer_counter = 0;
+
+static int
+compare_timers(const void *a_, const void *b_) {
+    const Timer *a = (const Timer*)a_, *b = (const Timer*)b_;
+    return (a->trigger_at > b->trigger_at) ? 1 : (a->trigger_at < b->trigger_at) ? -1 : 0;
+}
+
+static inline void
+update_timers(EventLoopData *eld) {
+    if (eld->timers_count > 1) qsort(eld->timers, eld->timers_count, sizeof(eld->timers[0]), compare_timers);
+}
+
+id_type
+addTimer(EventLoopData *eld, const char *name, monotonic_t interval, int enabled, bool repeats, timer_callback_func cb, void *cb_data, GLFWuserdatafreefun free) {
+    if (eld->timers_count >= sizeof(eld->timers)/sizeof(eld->timers[0])) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Too many timers added");
+        return 0;
+    }
+    Timer *t = eld->timers + eld->timers_count++;
+    t->interval = interval;
+    t->name = name;
+    t->trigger_at = enabled ? monotonic() + interval : MONOTONIC_T_MAX;
+    t->repeats = repeats;
+    t->callback = cb;
+    t->callback_data = cb_data;
+    t->free = free;
+    t->id = ++timer_counter;
+    update_timers(eld);
+    return timer_counter;
+}
+
+void
+removeTimer(EventLoopData *eld, id_type timer_id) {
+    removeX(timers, timer_id, update_timers);
+}
+
+void
+removeAllTimers(EventLoopData *eld) {
+    for (nfds_t i = 0; i < eld->timers_count; i++) {
+        if (eld->timers[i].free && eld->timers[i].callback_data) eld->timers[i].free(eld->timers[i].id, eld->timers[i].callback_data);
+    }
+    eld->timers_count = 0;
+}
+
+void
+toggleTimer(EventLoopData *eld, id_type timer_id, int enabled) {
+    for (nfds_t i = 0; i < eld->timers_count; i++) {
+        if (eld->timers[i].id == timer_id) {
+            monotonic_t trigger_at = enabled ? (monotonic() + eld->timers[i].interval) : MONOTONIC_T_MAX;
+            if (trigger_at != eld->timers[i].trigger_at) {
+                eld->timers[i].trigger_at = trigger_at;
+                update_timers(eld);
+            }
+            break;
+        }
+    }
+}
+
+void
+changeTimerInterval(EventLoopData *eld, id_type timer_id, monotonic_t interval) {
+    for (nfds_t i = 0; i < eld->timers_count; i++) {
+        if (eld->timers[i].id == timer_id) {
+            eld->timers[i].interval = interval;
+            break;
+        }
+    }
+}
+
+
+monotonic_t
+prepareForPoll(EventLoopData *eld, monotonic_t timeout) {
+    for (nfds_t i = 0; i < eld->watches_count; i++) eld->fds[i].revents = 0;
+    if (!eld->timers_count || eld->timers[0].trigger_at == MONOTONIC_T_MAX) return timeout;
+    monotonic_t now = monotonic(), next_repeat_at = eld->timers[0].trigger_at;
+    if (timeout < 0 || now + timeout > next_repeat_at) {
+        timeout = next_repeat_at <= now ? 0 : next_repeat_at - now;
+    }
+    return timeout;
+}
+
+static inline struct timespec
+calc_time(monotonic_t nsec) {
+    struct timespec result;
+    result.tv_sec  = nsec / (1000LL * 1000LL * 1000LL);
+    result.tv_nsec = nsec % (1000LL * 1000LL * 1000LL);
+    return result;
+}
+
+int
+pollWithTimeout(struct pollfd *fds, nfds_t nfds, monotonic_t timeout) {
+    struct timespec tv = calc_time(timeout);
+    return ppoll(fds, nfds, &tv, NULL);
+}
+
+static void
+dispatchEvents(EventLoopData *eld) {
+    for (nfds_t i = 0; i < eld->watches_count; i++) {
+        Watch *ww = eld->watches + i;
+        struct pollfd *pfd = eld->fds + i;
+        if (pfd->revents & ww->events) {
+            ww->ready = 1;
+            if (ww->callback) ww->callback(ww->fd, pfd->revents, ww->callback_data);
+        } else ww->ready = 0;
+    }
+}
+
+unsigned
+dispatchTimers(EventLoopData *eld) {
+    if (!eld->timers_count || eld->timers[0].trigger_at == MONOTONIC_T_MAX) return 0;
+    static struct { timer_callback_func func; id_type id; void* data; bool repeats; } dispatches[sizeof(eld->timers)/sizeof(eld->timers[0])];
+    unsigned num_dispatches = 0;
+    monotonic_t now = monotonic();
+    for (nfds_t i = 0; i < eld->timers_count && eld->timers[i].trigger_at <= now; i++) {
+        eld->timers[i].trigger_at = now + eld->timers[i].interval;
+        dispatches[num_dispatches].func = eld->timers[i].callback;
+        dispatches[num_dispatches].id = eld->timers[i].id;
+        dispatches[num_dispatches].data = eld->timers[i].callback_data;
+        dispatches[num_dispatches].repeats = eld->timers[i].repeats;
+        num_dispatches++;
+    }
+    // we dispatch separately so that the callbacks can modify timers
+    for (unsigned i = 0; i < num_dispatches; i++) {
+        dispatches[i].func(dispatches[i].id, dispatches[i].data);
+        if (!dispatches[i].repeats) {
+            removeTimer(eld, dispatches[i].id);
+        }
+    }
+    if (num_dispatches) update_timers(eld);
+    return num_dispatches;
+}
+
+static void
+drain_wakeup_fd(int fd, EventLoopData* eld) {
+    static char drain_buf[64];
+    eld->wakeup_data_read = false;
+    while(true) {
+        ssize_t ret = read(fd, drain_buf, sizeof(drain_buf));
+        if (ret < 0) {
+            if (errno == EINTR) continue;
+            break;
+        }
+        if (ret > 0) { eld->wakeup_data_read = true; continue; }
+        break;
+    }
+}
+
+static void
+mark_wakep_fd_ready(int fd UNUSED, int events UNUSED, void *data) {
+    ((EventLoopData*)(data))->wakeup_fd_ready = true;
+}
+
+bool
+initPollData(EventLoopData *eld, int display_fd) {
+    if (!addWatch(eld, "display", display_fd, POLLIN, 1, NULL, NULL)) return false;
+#ifdef HAS_EVENT_FD
+    eld->wakeupFd = eventfd(0, EFD_CLOEXEC | EFD_NONBLOCK);
+    if (eld->wakeupFd == -1) return false;
+    const int wakeup_fd = eld->wakeupFd;
+#else
+    if (pipe2(eld->wakeupFds, O_CLOEXEC | O_NONBLOCK) != 0) return false;
+    const int wakeup_fd = eld->wakeupFds[0];
+#endif
+    if (!addWatch(eld, "wakeup", wakeup_fd, POLLIN, 1, mark_wakep_fd_ready, eld)) return false;
+    return true;
+}
+
+void
+check_for_wakeup_events(EventLoopData *eld) {
+#ifdef HAS_EVENT_FD
+    int fd = eld->wakeupFd;
+#else
+    int fd = eld->wakeupFds[0];
+#endif
+    drain_wakeup_fd(fd, eld);
+}
+
+void
+wakeupEventLoop(EventLoopData *eld) {
+#ifdef HAS_EVENT_FD
+    static const uint64_t value = 1;
+    while (write(eld->wakeupFd, &value, sizeof value) < 0 && (errno == EINTR || errno == EAGAIN));
+#else
+    while (write(eld->wakeupFds[1], "w", 1) < 0 && (errno == EINTR || errno == EAGAIN));
+#endif
+}
+
+#ifndef HAS_EVENT_FD
+static inline void
+closeFds(int *fds, size_t count) {
+    while(count--) {
+        if (*fds > 0) {
+            close(*fds);
+            *fds = -1;
+        }
+        fds++;
+    }
+}
+#endif
+
+void
+finalizePollData(EventLoopData *eld) {
+#ifdef HAS_EVENT_FD
+    close(eld->wakeupFd); eld->wakeupFd = -1;
+#else
+    closeFds(eld->wakeupFds, arraysz(eld->wakeupFds));
+#endif
+}
+
+int
+pollForEvents(EventLoopData *eld, monotonic_t timeout, watch_callback_func display_callback) {
+    int read_ok = 0;
+    timeout = prepareForPoll(eld, timeout);
+    EVDBG("pollForEvents final timeout: %.3f", monotonic_t_to_s_double(timeout));
+    int result;
+    monotonic_t end_time = monotonic() + timeout;
+    eld->wakeup_fd_ready = false;
+
+    while(1) {
+        if (timeout >= 0) {
+            errno = 0;
+            result = pollWithTimeout(eld->fds, eld->watches_count, timeout);
+            int saved_errno = errno;
+            if (display_callback) display_callback(result, eld->fds[0].revents && eld->watches[0].events, NULL);
+            dispatchTimers(eld);
+            if (result > 0) {
+                dispatchEvents(eld);
+                read_ok = eld->watches[0].ready;
+                break;
+            }
+            timeout = end_time - monotonic();
+            if (timeout <= 0) break;
+            if (result < 0 && (saved_errno == EINTR || saved_errno == EAGAIN)) continue;
+            break;
+        } else {
+            errno = 0;
+            result = poll(eld->fds, eld->watches_count, -1);
+            int saved_errno = errno;
+            if (display_callback) display_callback(result, eld->fds[0].revents && eld->watches[0].events, NULL);
+            dispatchTimers(eld);
+            if (result > 0) {
+                dispatchEvents(eld);
+                read_ok = eld->watches[0].ready;
+            }
+            if (result < 0 && (saved_errno == EINTR || saved_errno == EAGAIN)) continue;
+            break;
+        }
+    }
+    return read_ok;
+}
+
+// Duplicate a UTF-8 encoded string
+// but cut it so that it has at most max_length bytes plus the null byte.
+// This does not take combining characters into account.
+GLFWAPI char* utf_8_strndup(const char* source, size_t max_length) {
+    if (!source) return NULL;
+    size_t length = strnlen(source, max_length);
+    if (length >= max_length) {
+        for (length = max_length; length > 0; length--) {
+            if ((source[length] & 0xC0) != 0x80) break;
+        }
+    }
+
+    char* result = malloc(length + 1);
+    memcpy(result, source, length);
+    result[length] = 0;
+    return result;
+}

glfw/backend_utils.h

@@ -0,0 +1,98 @@
+//========================================================================
+// GLFW 3.4 Wayland - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2014 Jonas Ådahl <jadahl@gmail.com>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+#pragma once
+#include "../kitty/monotonic.h"
+#include <poll.h>
+#include <unistd.h>
+#include <stdbool.h>
+
+#ifdef __has_include
+#if __has_include(<sys/eventfd.h>)
+#define HAS_EVENT_FD
+#include <sys/eventfd.h>
+#endif
+#else
+#define HAS_EVENT_FD
+#include <sys/eventfd.h>
+#endif
+
+typedef unsigned long long id_type;
+typedef void(*watch_callback_func)(int, int, void*);
+typedef void(*timer_callback_func)(id_type, void*);
+typedef void (* GLFWuserdatafreefun)(id_type, void*);
+
+typedef struct {
+    int fd, events, enabled, ready;
+    watch_callback_func callback;
+    void *callback_data;
+    GLFWuserdatafreefun free;
+    id_type id;
+    const char *name;
+} Watch;
+
+typedef struct {
+    id_type id;
+    monotonic_t interval, trigger_at;
+    timer_callback_func callback;
+    void *callback_data;
+    GLFWuserdatafreefun free;
+    const char *name;
+    bool repeats;
+} Timer;
+
+
+typedef struct {
+    struct pollfd fds[32];
+#ifdef HAS_EVENT_FD
+    int wakeupFd;
+#else
+    int wakeupFds[2];
+#endif
+    bool wakeup_data_read, wakeup_fd_ready;
+    nfds_t watches_count, timers_count;
+    Watch watches[32];
+    Timer timers[128];
+} EventLoopData;
+
+
+void check_for_wakeup_events(EventLoopData *eld);
+id_type addWatch(EventLoopData *eld, const char *name, int fd, int events, int enabled, watch_callback_func cb, void *cb_data);
+void removeWatch(EventLoopData *eld, id_type watch_id);
+void toggleWatch(EventLoopData *eld, id_type watch_id, int enabled);
+id_type addTimer(EventLoopData *eld, const char *name, monotonic_t interval, int enabled, bool repeats, timer_callback_func cb, void *cb_data, GLFWuserdatafreefun free);
+void removeTimer(EventLoopData *eld, id_type timer_id);
+void removeAllTimers(EventLoopData *eld);
+void toggleTimer(EventLoopData *eld, id_type timer_id, int enabled);
+void changeTimerInterval(EventLoopData *eld, id_type timer_id, monotonic_t interval);
+monotonic_t prepareForPoll(EventLoopData *eld, monotonic_t timeout);
+int pollWithTimeout(struct pollfd *fds, nfds_t nfds, monotonic_t timeout);
+int pollForEvents(EventLoopData *eld, monotonic_t timeout, watch_callback_func);
+unsigned dispatchTimers(EventLoopData *eld);
+void finalizePollData(EventLoopData *eld);
+bool initPollData(EventLoopData *eld, int display_fd);
+void wakeupEventLoop(EventLoopData *eld);
+char* utf_8_strndup(const char* source, size_t max_length);

glfw/cocoa_init.m

@@ -0,0 +1,864 @@
+//========================================================================
+// GLFW 3.4 macOS - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2009-2019 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+// It is fine to use C99 in this file because it will not be built with VS
+//========================================================================
+
+#include "internal.h"
+#include "../kitty/monotonic.h"
+#include <sys/param.h> // For MAXPATHLEN
+#include <pthread.h>
+
+// Needed for _NSGetProgname
+#include <crt_externs.h>
+
+// Change to our application bundle's resources directory, if present
+//
+static void changeToResourcesDirectory(void)
+{
+    char resourcesPath[MAXPATHLEN];
+
+    CFBundleRef bundle = CFBundleGetMainBundle();
+    if (!bundle)
+        return;
+
+    CFURLRef resourcesURL = CFBundleCopyResourcesDirectoryURL(bundle);
+
+    CFStringRef last = CFURLCopyLastPathComponent(resourcesURL);
+    if (CFStringCompare(CFSTR("Resources"), last, 0) != kCFCompareEqualTo)
+    {
+        CFRelease(last);
+        CFRelease(resourcesURL);
+        return;
+    }
+
+    CFRelease(last);
+
+    if (!CFURLGetFileSystemRepresentation(resourcesURL,
+                                          true,
+                                          (UInt8*) resourcesPath,
+                                          MAXPATHLEN))
+    {
+        CFRelease(resourcesURL);
+        return;
+    }
+
+    CFRelease(resourcesURL);
+
+    chdir(resourcesPath);
+}
+
+// Set up the menu bar (manually)
+// This is nasty, nasty stuff -- calls to undocumented semi-private APIs that
+// could go away at any moment, lots of stuff that really should be
+// localize(d|able), etc.  Add a nib to save us this horror.
+//
+static void createMenuBar(void)
+{
+    size_t i;
+    NSString* appName = nil;
+    NSDictionary* bundleInfo = [[NSBundle mainBundle] infoDictionary];
+    NSString* nameKeys[] =
+    {
+        @"CFBundleDisplayName",
+        @"CFBundleName",
+        @"CFBundleExecutable",
+    };
+
+    // Try to figure out what the calling application is called
+
+    for (i = 0;  i < sizeof(nameKeys) / sizeof(nameKeys[0]);  i++)
+    {
+        id name = bundleInfo[nameKeys[i]];
+        if (name &&
+            [name isKindOfClass:[NSString class]] &&
+            ![name isEqualToString:@""])
+        {
+            appName = name;
+            break;
+        }
+    }
+
+    if (!appName)
+    {
+        char** progname = _NSGetProgname();
+        if (progname && *progname)
+            appName = @(*progname);
+        else
+            appName = @"GLFW Application";
+    }
+
+    NSMenu* bar = [[NSMenu alloc] init];
+    [NSApp setMainMenu:bar];
+
+    NSMenuItem* appMenuItem =
+        [bar addItemWithTitle:@"" action:NULL keyEquivalent:@""];
+    NSMenu* appMenu = [[NSMenu alloc] init];
+    [appMenuItem setSubmenu:appMenu];
+
+    [appMenu addItemWithTitle:[NSString stringWithFormat:@"About %@", appName]
+                       action:@selector(orderFrontStandardAboutPanel:)
+                keyEquivalent:@""];
+    [appMenu addItem:[NSMenuItem separatorItem]];
+    NSMenu* servicesMenu = [[NSMenu alloc] init];
+    [NSApp setServicesMenu:servicesMenu];
+    [[appMenu addItemWithTitle:@"Services"
+                       action:NULL
+                keyEquivalent:@""] setSubmenu:servicesMenu];
+    [servicesMenu release];
+    [appMenu addItem:[NSMenuItem separatorItem]];
+    [appMenu addItemWithTitle:[NSString stringWithFormat:@"Hide %@", appName]
+                       action:@selector(hide:)
+                keyEquivalent:@"h"];
+    [[appMenu addItemWithTitle:@"Hide Others"
+                       action:@selector(hideOtherApplications:)
+                keyEquivalent:@"h"]
+        setKeyEquivalentModifierMask:NSEventModifierFlagOption | NSEventModifierFlagCommand];
+    [appMenu addItemWithTitle:@"Show All"
+                       action:@selector(unhideAllApplications:)
+                keyEquivalent:@""];
+    [appMenu addItem:[NSMenuItem separatorItem]];
+    [appMenu addItemWithTitle:[NSString stringWithFormat:@"Quit %@", appName]
+                       action:@selector(terminate:)
+                keyEquivalent:@"q"];
+
+    NSMenuItem* windowMenuItem =
+        [bar addItemWithTitle:@"" action:NULL keyEquivalent:@""];
+    [bar release];
+    NSMenu* windowMenu = [[NSMenu alloc] initWithTitle:@"Window"];
+    [NSApp setWindowsMenu:windowMenu];
+    [windowMenuItem setSubmenu:windowMenu];
+
+    [windowMenu addItemWithTitle:@"Minimize"
+                          action:@selector(performMiniaturize:)
+                   keyEquivalent:@"m"];
+    [windowMenu addItemWithTitle:@"Zoom"
+                          action:@selector(performZoom:)
+                   keyEquivalent:@""];
+    [windowMenu addItem:[NSMenuItem separatorItem]];
+    [windowMenu addItemWithTitle:@"Bring All to Front"
+                          action:@selector(arrangeInFront:)
+                   keyEquivalent:@""];
+
+    // TODO: Make this appear at the bottom of the menu (for consistency)
+    [windowMenu addItem:[NSMenuItem separatorItem]];
+    [[windowMenu addItemWithTitle:@"Enter Full Screen"
+                           action:@selector(toggleFullScreen:)
+                    keyEquivalent:@"f"]
+     setKeyEquivalentModifierMask:NSEventModifierFlagControl | NSEventModifierFlagCommand];
+
+    // Prior to Snow Leopard, we need to use this oddly-named semi-private API
+    // to get the application menu working properly.
+    SEL setAppleMenuSelector = NSSelectorFromString(@"setAppleMenu:");
+    [NSApp performSelector:setAppleMenuSelector withObject:appMenu];
+}
+
+// Create key code translation tables
+//
+static void createKeyTables(void)
+{
+    int keycode;
+
+    memset(_glfw.ns.keycodes, -1, sizeof(_glfw.ns.keycodes));
+    memset(_glfw.ns.key_to_keycode, -1, sizeof(_glfw.ns.key_to_keycode));
+
+    _glfw.ns.keycodes[0x1D] = GLFW_KEY_0;
+    _glfw.ns.keycodes[0x12] = GLFW_KEY_1;
+    _glfw.ns.keycodes[0x13] = GLFW_KEY_2;
+    _glfw.ns.keycodes[0x14] = GLFW_KEY_3;
+    _glfw.ns.keycodes[0x15] = GLFW_KEY_4;
+    _glfw.ns.keycodes[0x17] = GLFW_KEY_5;
+    _glfw.ns.keycodes[0x16] = GLFW_KEY_6;
+    _glfw.ns.keycodes[0x1A] = GLFW_KEY_7;
+    _glfw.ns.keycodes[0x1C] = GLFW_KEY_8;
+    _glfw.ns.keycodes[0x19] = GLFW_KEY_9;
+    _glfw.ns.keycodes[0x00] = GLFW_KEY_A;
+    _glfw.ns.keycodes[0x0B] = GLFW_KEY_B;
+    _glfw.ns.keycodes[0x08] = GLFW_KEY_C;
+    _glfw.ns.keycodes[0x02] = GLFW_KEY_D;
+    _glfw.ns.keycodes[0x0E] = GLFW_KEY_E;
+    _glfw.ns.keycodes[0x03] = GLFW_KEY_F;
+    _glfw.ns.keycodes[0x05] = GLFW_KEY_G;
+    _glfw.ns.keycodes[0x04] = GLFW_KEY_H;
+    _glfw.ns.keycodes[0x22] = GLFW_KEY_I;
+    _glfw.ns.keycodes[0x26] = GLFW_KEY_J;
+    _glfw.ns.keycodes[0x28] = GLFW_KEY_K;
+    _glfw.ns.keycodes[0x25] = GLFW_KEY_L;
+    _glfw.ns.keycodes[0x2E] = GLFW_KEY_M;
+    _glfw.ns.keycodes[0x2D] = GLFW_KEY_N;
+    _glfw.ns.keycodes[0x1F] = GLFW_KEY_O;
+    _glfw.ns.keycodes[0x23] = GLFW_KEY_P;
+    _glfw.ns.keycodes[0x0C] = GLFW_KEY_Q;
+    _glfw.ns.keycodes[0x0F] = GLFW_KEY_R;
+    _glfw.ns.keycodes[0x01] = GLFW_KEY_S;
+    _glfw.ns.keycodes[0x11] = GLFW_KEY_T;
+    _glfw.ns.keycodes[0x20] = GLFW_KEY_U;
+    _glfw.ns.keycodes[0x09] = GLFW_KEY_V;
+    _glfw.ns.keycodes[0x0D] = GLFW_KEY_W;
+    _glfw.ns.keycodes[0x07] = GLFW_KEY_X;
+    _glfw.ns.keycodes[0x10] = GLFW_KEY_Y;
+    _glfw.ns.keycodes[0x06] = GLFW_KEY_Z;
+
+    _glfw.ns.keycodes[0x27] = GLFW_KEY_APOSTROPHE;
+    _glfw.ns.keycodes[0x2A] = GLFW_KEY_BACKSLASH;
+    _glfw.ns.keycodes[0x2B] = GLFW_KEY_COMMA;
+    _glfw.ns.keycodes[0x18] = GLFW_KEY_EQUAL;
+    _glfw.ns.keycodes[0x32] = GLFW_KEY_GRAVE_ACCENT;
+    _glfw.ns.keycodes[0x21] = GLFW_KEY_LEFT_BRACKET;
+    _glfw.ns.keycodes[0x1B] = GLFW_KEY_MINUS;
+    _glfw.ns.keycodes[0x2F] = GLFW_KEY_PERIOD;
+    _glfw.ns.keycodes[0x1E] = GLFW_KEY_RIGHT_BRACKET;
+    _glfw.ns.keycodes[0x29] = GLFW_KEY_SEMICOLON;
+    _glfw.ns.keycodes[0x2C] = GLFW_KEY_SLASH;
+    _glfw.ns.keycodes[0x0A] = GLFW_KEY_WORLD_1;
+
+    _glfw.ns.keycodes[0x33] = GLFW_KEY_BACKSPACE;
+    _glfw.ns.keycodes[0x39] = GLFW_KEY_CAPS_LOCK;
+    _glfw.ns.keycodes[0x75] = GLFW_KEY_DELETE;
+    _glfw.ns.keycodes[0x7D] = GLFW_KEY_DOWN;
+    _glfw.ns.keycodes[0x77] = GLFW_KEY_END;
+    _glfw.ns.keycodes[0x24] = GLFW_KEY_ENTER;
+    _glfw.ns.keycodes[0x35] = GLFW_KEY_ESCAPE;
+    _glfw.ns.keycodes[0x7A] = GLFW_KEY_F1;
+    _glfw.ns.keycodes[0x78] = GLFW_KEY_F2;
+    _glfw.ns.keycodes[0x63] = GLFW_KEY_F3;
+    _glfw.ns.keycodes[0x76] = GLFW_KEY_F4;
+    _glfw.ns.keycodes[0x60] = GLFW_KEY_F5;
+    _glfw.ns.keycodes[0x61] = GLFW_KEY_F6;
+    _glfw.ns.keycodes[0x62] = GLFW_KEY_F7;
+    _glfw.ns.keycodes[0x64] = GLFW_KEY_F8;
+    _glfw.ns.keycodes[0x65] = GLFW_KEY_F9;
+    _glfw.ns.keycodes[0x6D] = GLFW_KEY_F10;
+    _glfw.ns.keycodes[0x67] = GLFW_KEY_F11;
+    _glfw.ns.keycodes[0x6F] = GLFW_KEY_F12;
+    _glfw.ns.keycodes[0x69] = GLFW_KEY_F13;
+    _glfw.ns.keycodes[0x6B] = GLFW_KEY_F14;
+    _glfw.ns.keycodes[0x71] = GLFW_KEY_F15;
+    _glfw.ns.keycodes[0x6A] = GLFW_KEY_F16;
+    _glfw.ns.keycodes[0x40] = GLFW_KEY_F17;
+    _glfw.ns.keycodes[0x4F] = GLFW_KEY_F18;
+    _glfw.ns.keycodes[0x50] = GLFW_KEY_F19;
+    _glfw.ns.keycodes[0x5A] = GLFW_KEY_F20;
+    _glfw.ns.keycodes[0x73] = GLFW_KEY_HOME;
+    _glfw.ns.keycodes[0x72] = GLFW_KEY_INSERT;
+    _glfw.ns.keycodes[0x7B] = GLFW_KEY_LEFT;
+    _glfw.ns.keycodes[0x3A] = GLFW_KEY_LEFT_ALT;
+    _glfw.ns.keycodes[0x3B] = GLFW_KEY_LEFT_CONTROL;
+    _glfw.ns.keycodes[0x38] = GLFW_KEY_LEFT_SHIFT;
+    _glfw.ns.keycodes[0x37] = GLFW_KEY_LEFT_SUPER;
+    _glfw.ns.keycodes[0x6E] = GLFW_KEY_MENU;
+    _glfw.ns.keycodes[0x47] = GLFW_KEY_NUM_LOCK;
+    _glfw.ns.keycodes[0x79] = GLFW_KEY_PAGE_DOWN;
+    _glfw.ns.keycodes[0x74] = GLFW_KEY_PAGE_UP;
+    _glfw.ns.keycodes[0x7C] = GLFW_KEY_RIGHT;
+    _glfw.ns.keycodes[0x3D] = GLFW_KEY_RIGHT_ALT;
+    _glfw.ns.keycodes[0x3E] = GLFW_KEY_RIGHT_CONTROL;
+    _glfw.ns.keycodes[0x3C] = GLFW_KEY_RIGHT_SHIFT;
+    _glfw.ns.keycodes[0x36] = GLFW_KEY_RIGHT_SUPER;
+    _glfw.ns.keycodes[0x31] = GLFW_KEY_SPACE;
+    _glfw.ns.keycodes[0x30] = GLFW_KEY_TAB;
+    _glfw.ns.keycodes[0x7E] = GLFW_KEY_UP;
+
+    _glfw.ns.keycodes[0x52] = GLFW_KEY_KP_0;
+    _glfw.ns.keycodes[0x53] = GLFW_KEY_KP_1;
+    _glfw.ns.keycodes[0x54] = GLFW_KEY_KP_2;
+    _glfw.ns.keycodes[0x55] = GLFW_KEY_KP_3;
+    _glfw.ns.keycodes[0x56] = GLFW_KEY_KP_4;
+    _glfw.ns.keycodes[0x57] = GLFW_KEY_KP_5;
+    _glfw.ns.keycodes[0x58] = GLFW_KEY_KP_6;
+    _glfw.ns.keycodes[0x59] = GLFW_KEY_KP_7;
+    _glfw.ns.keycodes[0x5B] = GLFW_KEY_KP_8;
+    _glfw.ns.keycodes[0x5C] = GLFW_KEY_KP_9;
+    _glfw.ns.keycodes[0x45] = GLFW_KEY_KP_ADD;
+    _glfw.ns.keycodes[0x41] = GLFW_KEY_KP_DECIMAL;
+    _glfw.ns.keycodes[0x4B] = GLFW_KEY_KP_DIVIDE;
+    _glfw.ns.keycodes[0x4C] = GLFW_KEY_KP_ENTER;
+    _glfw.ns.keycodes[0x51] = GLFW_KEY_KP_EQUAL;
+    _glfw.ns.keycodes[0x43] = GLFW_KEY_KP_MULTIPLY;
+    _glfw.ns.keycodes[0x4E] = GLFW_KEY_KP_SUBTRACT;
+
+    for (keycode = 0; keycode < 256; keycode++)
+    {
+        // Store the reverse translation for faster key name lookup
+        if (_glfw.ns.keycodes[keycode] >= 0)
+            _glfw.ns.key_to_keycode[_glfw.ns.keycodes[keycode]] = keycode;
+    }
+}
+
+// Retrieve Unicode data for the current keyboard layout
+//
+static bool updateUnicodeDataNS(void)
+{
+    if (_glfw.ns.inputSource)
+    {
+        CFRelease(_glfw.ns.inputSource);
+        _glfw.ns.inputSource = NULL;
+        _glfw.ns.unicodeData = nil;
+    }
+
+    for (_GLFWwindow *window = _glfw.windowListHead;  window;  window = window->next)
+        window->ns.deadKeyState = 0;
+
+    _glfw.ns.inputSource = TISCopyCurrentKeyboardLayoutInputSource();
+    if (!_glfw.ns.inputSource)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "Cocoa: Failed to retrieve keyboard layout input source");
+        return false;
+    }
+
+    _glfw.ns.unicodeData =
+        TISGetInputSourceProperty(_glfw.ns.inputSource,
+                                  kTISPropertyUnicodeKeyLayoutData);
+    if (!_glfw.ns.unicodeData)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "Cocoa: Failed to retrieve keyboard layout Unicode data");
+        return false;
+    }
+
+    return true;
+}
+
+// Load HIToolbox.framework and the TIS symbols we need from it
+//
+static bool initializeTIS(void)
+{
+    // This works only because Cocoa has already loaded it properly
+    _glfw.ns.tis.bundle =
+        CFBundleGetBundleWithIdentifier(CFSTR("com.apple.HIToolbox"));
+    if (!_glfw.ns.tis.bundle)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "Cocoa: Failed to load HIToolbox.framework");
+        return false;
+    }
+
+    CFStringRef* kPropertyUnicodeKeyLayoutData =
+        CFBundleGetDataPointerForName(_glfw.ns.tis.bundle,
+                                      CFSTR("kTISPropertyUnicodeKeyLayoutData"));
+    *(void **)&_glfw.ns.tis.CopyCurrentKeyboardLayoutInputSource =
+        CFBundleGetFunctionPointerForName(_glfw.ns.tis.bundle,
+                                          CFSTR("TISCopyCurrentKeyboardLayoutInputSource"));
+    *(void **)&_glfw.ns.tis.GetInputSourceProperty =
+        CFBundleGetFunctionPointerForName(_glfw.ns.tis.bundle,
+                                          CFSTR("TISGetInputSourceProperty"));
+    *(void **)&_glfw.ns.tis.GetKbdType =
+        CFBundleGetFunctionPointerForName(_glfw.ns.tis.bundle,
+                                          CFSTR("LMGetKbdType"));
+
+    if (!kPropertyUnicodeKeyLayoutData ||
+        !TISCopyCurrentKeyboardLayoutInputSource ||
+        !TISGetInputSourceProperty ||
+        !LMGetKbdType)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "Cocoa: Failed to load TIS API symbols");
+        return false;
+    }
+
+    _glfw.ns.tis.kPropertyUnicodeKeyLayoutData =
+        *kPropertyUnicodeKeyLayoutData;
+
+    return updateUnicodeDataNS();
+}
+
+static void
+display_reconfigured(CGDirectDisplayID display UNUSED, CGDisplayChangeSummaryFlags flags, void *userInfo UNUSED)
+{
+    if (flags & kCGDisplayBeginConfigurationFlag) {
+        return;
+    }
+    if (flags & kCGDisplaySetModeFlag) {
+        // GPU possibly changed
+    }
+}
+
+@interface GLFWHelper : NSObject
+@end
+
+@implementation GLFWHelper
+
+- (void)selectedKeyboardInputSourceChanged:(NSObject* )object
+{
+    (void)object;
+    updateUnicodeDataNS();
+}
+
+- (void)doNothing:(id)object
+{
+    (void)object;
+}
+
+@end // GLFWHelper
+
+// Delegate for application related notifications {{{
+
+@interface GLFWApplicationDelegate : NSObject <NSApplicationDelegate>
+@end
+
+@implementation GLFWApplicationDelegate
+
+- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
+{
+    (void)sender;
+    if (_glfw.callbacks.application_close) _glfw.callbacks.application_close(0);
+    return NSTerminateCancel;
+}
+
+static GLFWapplicationshouldhandlereopenfun handle_reopen_callback = NULL;
+
+- (BOOL)applicationShouldHandleReopen:(NSApplication *)sender hasVisibleWindows:(BOOL)flag
+{
+    (void)sender;
+    if (!handle_reopen_callback) return YES;
+    if (handle_reopen_callback(flag)) return YES;
+    return NO;
+}
+
+- (void)applicationDidChangeScreenParameters:(NSNotification *) notification
+{
+    (void)notification;
+    _GLFWwindow* window;
+
+    for (window = _glfw.windowListHead;  window;  window = window->next)
+    {
+        if (window->context.client != GLFW_NO_API)
+            [window->context.nsgl.object update];
+    }
+
+    _glfwPollMonitorsNS();
+}
+
+static GLFWapplicationwillfinishlaunchingfun finish_launching_callback = NULL;
+
+- (void)applicationWillFinishLaunching:(NSNotification *)notification
+{
+    (void)notification;
+    if (_glfw.hints.init.ns.menubar)
+    {
+        // In case we are unbundled, make us a proper UI application
+        [NSApp setActivationPolicy:NSApplicationActivationPolicyRegular];
+
+        // Menu bar setup must go between sharedApplication and finishLaunching
+        // in order to properly emulate the behavior of NSApplicationMain
+
+        if ([[NSBundle mainBundle] pathForResource:@"MainMenu" ofType:@"nib"])
+        {
+            [[NSBundle mainBundle] loadNibNamed:@"MainMenu"
+                                          owner:NSApp
+                                topLevelObjects:&_glfw.ns.nibObjects];
+        }
+        else
+            createMenuBar();
+    }
+    if (finish_launching_callback)
+        finish_launching_callback();
+}
+
+- (void)applicationDidFinishLaunching:(NSNotification *)notification
+{
+    (void)notification;
+    [NSApp stop:nil];
+
+    CGDisplayRegisterReconfigurationCallback(display_reconfigured, NULL);
+    _glfwCocoaPostEmptyEvent();
+}
+
+- (void)applicationWillTerminate:(NSNotification *)aNotification
+{
+    (void)aNotification;
+    CGDisplayRemoveReconfigurationCallback(display_reconfigured, NULL);
+}
+
+- (void)applicationDidHide:(NSNotification *)notification
+{
+    (void)notification;
+    int i;
+
+    for (i = 0;  i < _glfw.monitorCount;  i++)
+        _glfwRestoreVideoModeNS(_glfw.monitors[i]);
+}
+
+@end // GLFWApplicationDelegate
+// }}}
+
+
+@interface GLFWApplication : NSApplication
+- (void)tick_callback;
+- (void)render_frame_received:(id)displayIDAsID;
+@end
+
+@implementation GLFWApplication
+- (void)tick_callback
+{
+    _glfwDispatchTickCallback();
+}
+
+- (void)render_frame_received:(id)displayIDAsID
+{
+    CGDirectDisplayID displayID = [(NSNumber*)displayIDAsID unsignedIntValue];
+    _glfwDispatchRenderFrame(displayID);
+}
+@end
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW internal API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+void* _glfwLoadLocalVulkanLoaderNS(void)
+{
+    CFBundleRef bundle = CFBundleGetMainBundle();
+    if (!bundle)
+        return NULL;
+
+    CFURLRef url =
+        CFBundleCopyAuxiliaryExecutableURL(bundle, CFSTR("libvulkan.1.dylib"));
+    if (!url)
+        return NULL;
+
+    char path[PATH_MAX];
+    void* handle = NULL;
+
+    if (CFURLGetFileSystemRepresentation(url, true, (UInt8*) path, sizeof(path) - 1))
+        handle = _glfw_dlopen(path);
+
+    CFRelease(url);
+    return handle;
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW platform API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+static inline bool
+is_ctrl_tab(NSEvent *event, NSEventModifierFlags modifierFlags) {
+    if (
+            (modifierFlags == NSEventModifierFlagControl &&
+                [event.charactersIgnoringModifiers isEqualToString:@"\t"]) ||
+            (modifierFlags == (NSEventModifierFlagControl | NSEventModifierFlagShift) &&
+                [event.charactersIgnoringModifiers isEqualToString:@"\x19"])
+       ) return true;
+    return false;
+}
+
+static inline bool
+is_cmd_period(NSEvent *event, NSEventModifierFlags modifierFlags) {
+    if (modifierFlags != NSEventModifierFlagCommand) return false;
+    if ([event.charactersIgnoringModifiers isEqualToString:@"."]) return true;
+    return false;
+}
+
+GLFWAPI GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback) {
+    GLFWapplicationshouldhandlereopenfun previous = handle_reopen_callback;
+    handle_reopen_callback = callback;
+    return previous;
+}
+
+GLFWAPI GLFWapplicationwillfinishlaunchingfun glfwSetApplicationWillFinishLaunching(GLFWapplicationwillfinishlaunchingfun callback) {
+    GLFWapplicationwillfinishlaunchingfun previous = finish_launching_callback;
+    finish_launching_callback = callback;
+    return previous;
+}
+
+int _glfwPlatformInit(void)
+{
+    @autoreleasepool {
+
+    _glfw.ns.helper = [[GLFWHelper alloc] init];
+
+    [NSThread detachNewThreadSelector:@selector(doNothing:)
+                             toTarget:_glfw.ns.helper
+                           withObject:nil];
+
+    if (NSApp)
+        _glfw.ns.finishedLaunching = true;
+
+    [GLFWApplication sharedApplication];
+
+    _glfw.ns.delegate = [[GLFWApplicationDelegate alloc] init];
+    if (_glfw.ns.delegate == nil)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "Cocoa: Failed to create application delegate");
+        return false;
+    }
+
+    [NSApp setDelegate:_glfw.ns.delegate];
+
+    NSEvent* (^keydown_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
+    {
+        NSEventModifierFlags modifierFlags = [event modifierFlags] & NSEventModifierFlagDeviceIndependentFlagsMask;
+        if (is_ctrl_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
+            // Cocoa swallows Ctrl+Tab to cycle between views
+            [[NSApp keyWindow].contentView keyDown:event];
+        }
+
+        return event;
+    };
+
+    NSEvent* (^keyup_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
+    {
+        NSEventModifierFlags modifierFlags = [event modifierFlags] & NSEventModifierFlagDeviceIndependentFlagsMask;
+        if (modifierFlags & NSEventModifierFlagCommand) {
+            // From http://cocoadev.com/index.pl?GameKeyboardHandlingAlmost
+            // This works around an AppKit bug, where key up events while holding
+            // down the command key don't get sent to the key window.
+            [[NSApp keyWindow] sendEvent:event];
+        }
+        if (is_ctrl_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
+            // Cocoa swallows Ctrl+Tab to cycle between views
+            [[NSApp keyWindow].contentView keyUp:event];
+        }
+
+        return event;
+    };
+
+    _glfw.ns.keyUpMonitor =
+        [NSEvent addLocalMonitorForEventsMatchingMask:NSEventMaskKeyUp
+                                              handler:keyup_block];
+    _glfw.ns.keyDownMonitor =
+        [NSEvent addLocalMonitorForEventsMatchingMask:NSEventMaskKeyDown
+                                              handler:keydown_block];
+
+    if (_glfw.hints.init.ns.chdir)
+        changeToResourcesDirectory();
+
+    // Press and Hold prevents some keys from emitting repeated characters
+    NSDictionary* defaults = @{@"ApplePressAndHoldEnabled":@NO};
+    [[NSUserDefaults standardUserDefaults] registerDefaults:defaults];
+
+    [[NSNotificationCenter defaultCenter]
+        addObserver:_glfw.ns.helper
+           selector:@selector(selectedKeyboardInputSourceChanged:)
+               name:NSTextInputContextKeyboardSelectionDidChangeNotification
+             object:nil];
+
+    createKeyTables();
+
+    _glfw.ns.eventSource = CGEventSourceCreate(kCGEventSourceStateHIDSystemState);
+    if (!_glfw.ns.eventSource)
+        return false;
+
+    CGEventSourceSetLocalEventsSuppressionInterval(_glfw.ns.eventSource, 0.0);
+
+    if (!initializeTIS())
+        return false;
+
+    _glfwPollMonitorsNS();
+    return true;
+
+    } // autoreleasepool
+}
+
+void _glfwPlatformTerminate(void)
+{
+    @autoreleasepool {
+
+    _glfwClearDisplayLinks();
+
+    if (_glfw.ns.inputSource)
+    {
+        CFRelease(_glfw.ns.inputSource);
+        _glfw.ns.inputSource = NULL;
+        _glfw.ns.unicodeData = nil;
+    }
+
+    if (_glfw.ns.eventSource)
+    {
+        CFRelease(_glfw.ns.eventSource);
+        _glfw.ns.eventSource = NULL;
+    }
+
+    if (_glfw.ns.delegate)
+    {
+        [NSApp setDelegate:nil];
+        [_glfw.ns.delegate release];
+        _glfw.ns.delegate = nil;
+    }
+
+    if (_glfw.ns.helper)
+    {
+        [[NSNotificationCenter defaultCenter]
+            removeObserver:_glfw.ns.helper
+                      name:NSTextInputContextKeyboardSelectionDidChangeNotification
+                    object:nil];
+        [[NSNotificationCenter defaultCenter]
+            removeObserver:_glfw.ns.helper];
+        [_glfw.ns.helper release];
+        _glfw.ns.helper = nil;
+    }
+
+    if (_glfw.ns.keyUpMonitor)
+        [NSEvent removeMonitor:_glfw.ns.keyUpMonitor];
+    if (_glfw.ns.keyDownMonitor)
+        [NSEvent removeMonitor:_glfw.ns.keyDownMonitor];
+
+    free(_glfw.ns.clipboardString);
+
+    _glfwTerminateNSGL();
+
+    } // autoreleasepool
+}
+
+const char* _glfwPlatformGetVersionString(void)
+{
+    return _GLFW_VERSION_NUMBER " Cocoa NSGL EGL OSMesa"
+#if defined(_GLFW_BUILD_DLL)
+        " dynamic"
+#endif
+        ;
+}
+
+static GLFWtickcallback tick_callback = NULL;
+static void* tick_callback_data = NULL;
+static bool tick_callback_requested = false;
+static pthread_t main_thread;
+static NSLock *tick_lock = NULL;
+
+
+void _glfwDispatchTickCallback() {
+    if (tick_lock && tick_callback) {
+        [tick_lock lock];
+        while(tick_callback_requested) {
+            tick_callback_requested = false;
+            tick_callback(tick_callback_data);
+        }
+        [tick_lock unlock];
+    }
+}
+
+static void
+request_tick_callback() {
+    if (!tick_callback_requested) {
+        tick_callback_requested = true;
+        [NSApp performSelectorOnMainThread:@selector(tick_callback) withObject:nil waitUntilDone:NO];
+    }
+}
+
+void _glfwPlatformPostEmptyEvent(void)
+{
+    if (pthread_equal(pthread_self(), main_thread)) {
+        request_tick_callback();
+    } else if (tick_lock) {
+        [tick_lock lock];
+        request_tick_callback();
+        [tick_lock unlock];
+    }
+}
+
+
+void _glfwPlatformStopMainLoop(void) {
+    [NSApp stop:nil];
+    _glfwCocoaPostEmptyEvent();
+}
+
+void _glfwPlatformRunMainLoop(GLFWtickcallback callback, void* data) {
+    main_thread = pthread_self();
+    tick_callback = callback;
+    tick_callback_data = data;
+    tick_lock = [NSLock new];
+    [NSApp run];
+    [tick_lock release];
+    tick_lock = NULL;
+    tick_callback = NULL;
+    tick_callback_data = NULL;
+}
+
+
+typedef struct {
+    NSTimer *os_timer;
+    unsigned long long id;
+    bool repeats;
+    monotonic_t interval;
+    GLFWuserdatafun callback;
+    void *callback_data;
+    GLFWuserdatafun free_callback_data;
+} Timer;
+
+static Timer timers[128] = {{0}};
+static size_t num_timers = 0;
+
+static inline void
+remove_timer_at(size_t idx) {
+    if (idx < num_timers) {
+        Timer *t = timers + idx;
+        if (t->os_timer) { [t->os_timer invalidate]; t->os_timer = NULL; }
+        if (t->callback_data && t->free_callback_data) { t->free_callback_data(t->id, t->callback_data); t->callback_data = NULL; }
+        remove_i_from_array(timers, idx, num_timers);
+    }
+}
+
+static void schedule_timer(Timer *t) {
+    t->os_timer = [NSTimer scheduledTimerWithTimeInterval:monotonic_t_to_s_double(t->interval) repeats:(t->repeats ? YES: NO) block:^(NSTimer *os_timer) {
+        for (size_t i = 0; i < num_timers; i++) {
+            if (timers[i].os_timer == os_timer) {
+                timers[i].callback(timers[i].id, timers[i].callback_data);
+                if (!timers[i].repeats) remove_timer_at(i);
+                break;
+            }
+        }
+    }];
+}
+
+unsigned long long _glfwPlatformAddTimer(monotonic_t interval, bool repeats, GLFWuserdatafun callback, void *callback_data, GLFWuserdatafun free_callback) {
+    static unsigned long long timer_counter = 0;
+    if (num_timers >= sizeof(timers)/sizeof(timers[0]) - 1) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Too many timers added");
+        return 0;
+    }
+    Timer *t = timers + num_timers++;
+    t->id = ++timer_counter;
+    t->repeats = repeats;
+    t->interval = interval;
+    t->callback = callback;
+    t->callback_data = callback_data;
+    t->free_callback_data = free_callback;
+    schedule_timer(t);
+    return timer_counter;
+}
+
+void _glfwPlatformRemoveTimer(unsigned long long timer_id) {
+    for (size_t i = 0; i < num_timers; i++) {
+        if (timers[i].id == timer_id) {
+            remove_timer_at(i);
+            break;
+        }
+    }
+}
+
+void _glfwPlatformUpdateTimer(unsigned long long timer_id, monotonic_t interval, bool enabled) {
+    for (size_t i = 0; i < num_timers; i++) {
+        if (timers[i].id == timer_id) {
+            Timer *t = timers + i;
+            if (t->os_timer) { [t->os_timer invalidate]; t->os_timer = NULL; }
+            t->interval = interval;
+            if (enabled) schedule_timer(t);
+            break;
+        }
+    }
+}

glfw/cocoa_joystick.h

@@ -0,0 +1,46 @@
+//========================================================================
+// GLFW 3.4 Cocoa - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2006-2017 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+#include <IOKit/IOKitLib.h>
+#include <IOKit/IOCFPlugIn.h>
+#include <IOKit/hid/IOHIDLib.h>
+#include <IOKit/hid/IOHIDKeys.h>
+
+#define _GLFW_PLATFORM_JOYSTICK_STATE         _GLFWjoystickNS ns
+#define _GLFW_PLATFORM_LIBRARY_JOYSTICK_STATE
+
+#define _GLFW_PLATFORM_MAPPING_NAME "Mac OS X"
+
+// Cocoa-specific per-joystick data
+//
+typedef struct _GLFWjoystickNS
+{
+    IOHIDDeviceRef      device;
+    CFMutableArrayRef   axes;
+    CFMutableArrayRef   buttons;
+    CFMutableArrayRef   hats;
+} _GLFWjoystickNS;
+

glfw/cocoa_joystick.m

@@ -0,0 +1,482 @@
+//========================================================================
+// GLFW 3.4 Cocoa - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2009-2019 Camilla Löwy <elmindreda@glfw.org>
+// Copyright (c) 2012 Torsten Walluhn <tw@mad-cad.net>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+// It is fine to use C99 in this file because it will not be built with VS
+//========================================================================
+
+#include "internal.h"
+
+#include <unistd.h>
+#include <ctype.h>
+#include <string.h>
+
+#include <mach/mach.h>
+#include <mach/mach_error.h>
+
+#include <CoreFoundation/CoreFoundation.h>
+#include <Kernel/IOKit/hidsystem/IOHIDUsageTables.h>
+
+
+// Joystick element information
+//
+typedef struct _GLFWjoyelementNS
+{
+    IOHIDElementRef native;
+    uint32_t        usage;
+    int             index;
+    long            minimum;
+    long            maximum;
+
+} _GLFWjoyelementNS;
+
+
+// Returns the value of the specified element of the specified joystick
+//
+static long getElementValue(_GLFWjoystick* js, _GLFWjoyelementNS* element)
+{
+    IOHIDValueRef valueRef;
+    long value = 0;
+
+    if (js->ns.device)
+    {
+        if (IOHIDDeviceGetValue(js->ns.device,
+                                element->native,
+                                &valueRef) == kIOReturnSuccess)
+        {
+            value = IOHIDValueGetIntegerValue(valueRef);
+        }
+    }
+
+    return value;
+}
+
+// Comparison function for matching the SDL element order
+//
+static CFComparisonResult compareElements(const void* fp,
+                                          const void* sp,
+                                          void* user UNUSED)
+{
+    const _GLFWjoyelementNS* fe = fp;
+    const _GLFWjoyelementNS* se = sp;
+    if (fe->usage < se->usage)
+        return kCFCompareLessThan;
+    if (fe->usage > se->usage)
+        return kCFCompareGreaterThan;
+    if (fe->index < se->index)
+        return kCFCompareLessThan;
+    if (fe->index > se->index)
+        return kCFCompareGreaterThan;
+    return kCFCompareEqualTo;
+}
+
+// Removes the specified joystick
+//
+static void closeJoystick(_GLFWjoystick* js)
+{
+    int i;
+
+    if (!js->present)
+        return;
+
+    for (i = 0;  i < CFArrayGetCount(js->ns.axes);  i++)
+        free((void*) CFArrayGetValueAtIndex(js->ns.axes, i));
+    CFRelease(js->ns.axes);
+
+    for (i = 0;  i < CFArrayGetCount(js->ns.buttons);  i++)
+        free((void*) CFArrayGetValueAtIndex(js->ns.buttons, i));
+    CFRelease(js->ns.buttons);
+
+    for (i = 0;  i < CFArrayGetCount(js->ns.hats);  i++)
+        free((void*) CFArrayGetValueAtIndex(js->ns.hats, i));
+    CFRelease(js->ns.hats);
+
+    _glfwFreeJoystick(js);
+    _glfwInputJoystick(js, GLFW_DISCONNECTED);
+}
+
+// Callback for user-initiated joystick addition
+//
+static void matchCallback(void* context UNUSED,
+                          IOReturn result UNUSED,
+                          void* sender UNUSED,
+                          IOHIDDeviceRef device)
+{
+    int jid;
+    char name[256];
+    char guid[33];
+    CFIndex i;
+    CFTypeRef property;
+    uint32_t vendor = 0, product = 0, version = 0;
+    _GLFWjoystick* js;
+    CFMutableArrayRef axes, buttons, hats;
+
+    for (jid = 0;  jid <= GLFW_JOYSTICK_LAST;  jid++)
+    {
+        if (_glfw.joysticks[jid].ns.device == device)
+            return;
+    }
+
+    axes    = CFArrayCreateMutable(NULL, 0, NULL);
+    buttons = CFArrayCreateMutable(NULL, 0, NULL);
+    hats    = CFArrayCreateMutable(NULL, 0, NULL);
+
+    property = IOHIDDeviceGetProperty(device, CFSTR(kIOHIDProductKey));
+    if (property)
+    {
+        CFStringGetCString(property,
+                           name,
+                           sizeof(name),
+                           kCFStringEncodingUTF8);
+    }
+    else
+        strncpy(name, "Unknown", sizeof(name));
+
+    property = IOHIDDeviceGetProperty(device, CFSTR(kIOHIDVendorIDKey));
+    if (property)
+        CFNumberGetValue(property, kCFNumberSInt32Type, &vendor);
+
+    property = IOHIDDeviceGetProperty(device, CFSTR(kIOHIDProductIDKey));
+    if (property)
+        CFNumberGetValue(property, kCFNumberSInt32Type, &product);
+
+    property = IOHIDDeviceGetProperty(device, CFSTR(kIOHIDVersionNumberKey));
+    if (property)
+        CFNumberGetValue(property, kCFNumberSInt32Type, &version);
+
+    // Generate a joystick GUID that matches the SDL 2.0.5+ one
+    if (vendor && product)
+    {
+        sprintf(guid, "03000000%02x%02x0000%02x%02x0000%02x%02x0000",
+                (uint8_t) vendor, (uint8_t) (vendor >> 8),
+                (uint8_t) product, (uint8_t) (product >> 8),
+                (uint8_t) version, (uint8_t) (version >> 8));
+    }
+    else
+    {
+        sprintf(guid, "05000000%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x00",
+                name[0], name[1], name[2], name[3],
+                name[4], name[5], name[6], name[7],
+                name[8], name[9], name[10]);
+    }
+
+    CFArrayRef elements =
+        IOHIDDeviceCopyMatchingElements(device, NULL, kIOHIDOptionsTypeNone);
+
+    for (i = 0;  i < CFArrayGetCount(elements);  i++)
+    {
+        IOHIDElementRef native = (IOHIDElementRef)
+            CFArrayGetValueAtIndex(elements, i);
+        if (CFGetTypeID(native) != IOHIDElementGetTypeID())
+            continue;
+
+        const IOHIDElementType type = IOHIDElementGetType(native);
+        if ((type != kIOHIDElementTypeInput_Axis) &&
+            (type != kIOHIDElementTypeInput_Button) &&
+            (type != kIOHIDElementTypeInput_Misc))
+        {
+            continue;
+        }
+
+        CFMutableArrayRef target = NULL;
+
+        const uint32_t usage = IOHIDElementGetUsage(native);
+        const uint32_t page = IOHIDElementGetUsagePage(native);
+        if (page == kHIDPage_GenericDesktop)
+        {
+            switch (usage)
+            {
+                case kHIDUsage_GD_X:
+                case kHIDUsage_GD_Y:
+                case kHIDUsage_GD_Z:
+                case kHIDUsage_GD_Rx:
+                case kHIDUsage_GD_Ry:
+                case kHIDUsage_GD_Rz:
+                case kHIDUsage_GD_Slider:
+                case kHIDUsage_GD_Dial:
+                case kHIDUsage_GD_Wheel:
+                    target = axes;
+                    break;
+                case kHIDUsage_GD_Hatswitch:
+                    target = hats;
+                    break;
+                case kHIDUsage_GD_DPadUp:
+                case kHIDUsage_GD_DPadRight:
+                case kHIDUsage_GD_DPadDown:
+                case kHIDUsage_GD_DPadLeft:
+                case kHIDUsage_GD_SystemMainMenu:
+                case kHIDUsage_GD_Select:
+                case kHIDUsage_GD_Start:
+                    target = buttons;
+                    break;
+            }
+        }
+        else if (page == kHIDPage_Simulation)
+        {
+            switch (usage)
+            {
+                case kHIDUsage_Sim_Accelerator:
+                case kHIDUsage_Sim_Brake:
+                case kHIDUsage_Sim_Throttle:
+                case kHIDUsage_Sim_Rudder:
+                case kHIDUsage_Sim_Steering:
+                    target = axes;
+                    break;
+            }
+        }
+        else if (page == kHIDPage_Button || page == kHIDPage_Consumer)
+            target = buttons;
+
+        if (target)
+        {
+            _GLFWjoyelementNS* element = calloc(1, sizeof(_GLFWjoyelementNS));
+            element->native  = native;
+            element->usage   = usage;
+            element->index   = (int) CFArrayGetCount(target);
+            element->minimum = IOHIDElementGetLogicalMin(native);
+            element->maximum = IOHIDElementGetLogicalMax(native);
+            CFArrayAppendValue(target, element);
+        }
+    }
+
+    CFRelease(elements);
+
+    CFArraySortValues(axes, CFRangeMake(0, CFArrayGetCount(axes)),
+                      compareElements, NULL);
+    CFArraySortValues(buttons, CFRangeMake(0, CFArrayGetCount(buttons)),
+                      compareElements, NULL);
+    CFArraySortValues(hats, CFRangeMake(0, CFArrayGetCount(hats)),
+                      compareElements, NULL);
+
+    js = _glfwAllocJoystick(name, guid,
+                            (int) CFArrayGetCount(axes),
+                            (int) CFArrayGetCount(buttons),
+                            (int) CFArrayGetCount(hats));
+
+    js->ns.device  = device;
+    js->ns.axes    = axes;
+    js->ns.buttons = buttons;
+    js->ns.hats    = hats;
+
+    _glfwInputJoystick(js, GLFW_CONNECTED);
+}
+
+// Callback for user-initiated joystick removal
+//
+static void removeCallback(void* context UNUSED,
+                           IOReturn result UNUSED,
+                           void* sender UNUSED,
+                           IOHIDDeviceRef device)
+{
+    int jid;
+
+    for (jid = 0;  jid <= GLFW_JOYSTICK_LAST;  jid++)
+    {
+        if (_glfw.joysticks[jid].ns.device == device)
+        {
+            closeJoystick(_glfw.joysticks + jid);
+            break;
+        }
+    }
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW platform API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+bool _glfwPlatformInitJoysticks(void)
+{
+    CFMutableArrayRef matching;
+    const long usages[] =
+    {
+        kHIDUsage_GD_Joystick,
+        kHIDUsage_GD_GamePad,
+        kHIDUsage_GD_MultiAxisController
+    };
+
+    _glfw.ns.hidManager = IOHIDManagerCreate(kCFAllocatorDefault,
+                                             kIOHIDOptionsTypeNone);
+
+    matching = CFArrayCreateMutable(kCFAllocatorDefault,
+                                    0,
+                                    &kCFTypeArrayCallBacks);
+    if (!matching)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Cocoa: Failed to create array");
+        return false;
+    }
+
+    for (size_t i = 0;  i < sizeof(usages) / sizeof(long);  i++)
+    {
+        const long page = kHIDPage_GenericDesktop;
+
+        CFMutableDictionaryRef dict =
+            CFDictionaryCreateMutable(kCFAllocatorDefault,
+                                      0,
+                                      &kCFTypeDictionaryKeyCallBacks,
+                                      &kCFTypeDictionaryValueCallBacks);
+        if (!dict)
+            continue;
+
+        CFNumberRef pageRef = CFNumberCreate(kCFAllocatorDefault,
+                                             kCFNumberLongType,
+                                             &page);
+        CFNumberRef usageRef = CFNumberCreate(kCFAllocatorDefault,
+                                              kCFNumberLongType,
+                                              &usages[i]);
+        if (pageRef && usageRef)
+        {
+            CFDictionarySetValue(dict,
+                                 CFSTR(kIOHIDDeviceUsagePageKey),
+                                 pageRef);
+            CFDictionarySetValue(dict,
+                                 CFSTR(kIOHIDDeviceUsageKey),
+                                 usageRef);
+            CFArrayAppendValue(matching, dict);
+        }
+
+        if (pageRef)
+            CFRelease(pageRef);
+        if (usageRef)
+            CFRelease(usageRef);
+
+        CFRelease(dict);
+    }
+
+    IOHIDManagerSetDeviceMatchingMultiple(_glfw.ns.hidManager, matching);
+    CFRelease(matching);
+
+    IOHIDManagerRegisterDeviceMatchingCallback(_glfw.ns.hidManager,
+                                               &matchCallback, NULL);
+    IOHIDManagerRegisterDeviceRemovalCallback(_glfw.ns.hidManager,
+                                              &removeCallback, NULL);
+    IOHIDManagerScheduleWithRunLoop(_glfw.ns.hidManager,
+                                    CFRunLoopGetMain(),
+                                    kCFRunLoopDefaultMode);
+    IOHIDManagerOpen(_glfw.ns.hidManager, kIOHIDOptionsTypeNone);
+
+    // Execute the run loop once in order to register any initially-attached
+    // joysticks
+    CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0, false);
+    return true;
+}
+
+void _glfwPlatformTerminateJoysticks(void)
+{
+    int jid;
+
+    for (jid = 0;  jid <= GLFW_JOYSTICK_LAST;  jid++)
+        closeJoystick(_glfw.joysticks + jid);
+
+    if (_glfw.ns.hidManager)
+    {
+        CFRelease(_glfw.ns.hidManager);
+        _glfw.ns.hidManager = NULL;
+    }
+}
+
+
+int _glfwPlatformPollJoystick(_GLFWjoystick* js, int mode)
+{
+    if (mode & _GLFW_POLL_AXES)
+    {
+        CFIndex i;
+
+        for (i = 0;  i < CFArrayGetCount(js->ns.axes);  i++)
+        {
+            _GLFWjoyelementNS* axis = (_GLFWjoyelementNS*)
+                CFArrayGetValueAtIndex(js->ns.axes, i);
+
+            const long raw = getElementValue(js, axis);
+            // Perform auto calibration
+            if (raw < axis->minimum)
+                axis->minimum = raw;
+            if (raw > axis->maximum)
+                axis->maximum = raw;
+
+            const long size = axis->maximum - axis->minimum;
+            if (size == 0)
+                _glfwInputJoystickAxis(js, (int) i, 0.f);
+            else
+            {
+                const float value = (2.f * (raw - axis->minimum) / size) - 1.f;
+                _glfwInputJoystickAxis(js, (int) i, value);
+            }
+        }
+    }
+
+    if (mode & _GLFW_POLL_BUTTONS)
+    {
+        CFIndex i;
+
+        for (i = 0;  i < CFArrayGetCount(js->ns.buttons);  i++)
+        {
+            _GLFWjoyelementNS* button = (_GLFWjoyelementNS*)
+                CFArrayGetValueAtIndex(js->ns.buttons, i);
+            const char value = getElementValue(js, button) - button->minimum;
+            const int state = (value > 0) ? GLFW_PRESS : GLFW_RELEASE;
+            _glfwInputJoystickButton(js, (int) i, state);
+        }
+
+        for (i = 0;  i < CFArrayGetCount(js->ns.hats);  i++)
+        {
+            const int states[9] =
+            {
+                GLFW_HAT_UP,
+                GLFW_HAT_RIGHT_UP,
+                GLFW_HAT_RIGHT,
+                GLFW_HAT_RIGHT_DOWN,
+                GLFW_HAT_DOWN,
+                GLFW_HAT_LEFT_DOWN,
+                GLFW_HAT_LEFT,
+                GLFW_HAT_LEFT_UP,
+                GLFW_HAT_CENTERED
+            };
+
+            _GLFWjoyelementNS* hat = (_GLFWjoyelementNS*)
+                CFArrayGetValueAtIndex(js->ns.hats, i);
+            long state = getElementValue(js, hat) - hat->minimum;
+            if (state < 0 || state > 8)
+                state = 8;
+
+            _glfwInputJoystickHat(js, (int) i, states[state]);
+        }
+    }
+
+    return js->present;
+}
+
+void _glfwPlatformUpdateGamepadGUID(char* guid)
+{
+    if ((strncmp(guid + 4, "000000000000", 12) == 0) &&
+        (strncmp(guid + 20, "000000000000", 12) == 0))
+    {
+        char original[33];
+        strncpy(original, guid, sizeof(original) - 1);
+        sprintf(guid, "03000000%.4s0000%.4s000000000000",
+                original, original + 16);
+    }
+}

glfw/cocoa_monitor.m

@@ -0,0 +1,632 @@
+//========================================================================
+// GLFW 3.4 macOS - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2002-2006 Marcus Geelnard
+// Copyright (c) 2006-2019 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+// It is fine to use C99 in this file because it will not be built with VS
+//========================================================================
+
+#include "internal.h"
+
+#include <stdlib.h>
+#include <limits.h>
+#include <math.h>
+
+#include <IOKit/graphics/IOGraphicsLib.h>
+#include <CoreVideo/CVBase.h>
+#include <CoreVideo/CVDisplayLink.h>
+#include <ApplicationServices/ApplicationServices.h>
+
+
+// Get the name of the specified display, or NULL
+//
+static char* getDisplayName(CGDirectDisplayID displayID)
+{
+    io_iterator_t it;
+    io_service_t service;
+    CFDictionaryRef info;
+
+    if (IOServiceGetMatchingServices(kIOMasterPortDefault,
+                                     IOServiceMatching("IODisplayConnect"),
+                                     &it) != 0)
+    {
+        // This may happen if a desktop Mac is running headless
+        return NULL;
+    }
+
+    while ((service = IOIteratorNext(it)) != 0)
+    {
+        info = IODisplayCreateInfoDictionary(service,
+                                             kIODisplayOnlyPreferredName);
+
+        CFNumberRef vendorIDRef =
+            CFDictionaryGetValue(info, CFSTR(kDisplayVendorID));
+        CFNumberRef productIDRef =
+            CFDictionaryGetValue(info, CFSTR(kDisplayProductID));
+        if (!vendorIDRef || !productIDRef)
+        {
+            CFRelease(info);
+            continue;
+        }
+
+        unsigned int vendorID, productID;
+        CFNumberGetValue(vendorIDRef, kCFNumberIntType, &vendorID);
+        CFNumberGetValue(productIDRef, kCFNumberIntType, &productID);
+
+        if (CGDisplayVendorNumber(displayID) == vendorID &&
+            CGDisplayModelNumber(displayID) == productID)
+        {
+            // Info dictionary is used and freed below
+            break;
+        }
+
+        CFRelease(info);
+    }
+
+    IOObjectRelease(it);
+
+    if (!service)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "Cocoa: Failed to find service port for display");
+        return NULL;
+    }
+
+    CFDictionaryRef names =
+        CFDictionaryGetValue(info, CFSTR(kDisplayProductName));
+
+    CFStringRef nameRef;
+
+    if (!names || !CFDictionaryGetValueIfPresent(names, CFSTR("en_US"),
+                                                 (const void**) &nameRef))
+    {
+        // This may happen if a desktop Mac is running headless
+        CFRelease(info);
+        return NULL;
+    }
+
+    const CFIndex size =
+        CFStringGetMaximumSizeForEncoding(CFStringGetLength(nameRef),
+                                          kCFStringEncodingUTF8);
+    char* name = calloc(size + 1, 1);
+    CFStringGetCString(nameRef, name, size, kCFStringEncodingUTF8);
+
+    CFRelease(info);
+    return name;
+}
+
+// Check whether the display mode should be included in enumeration
+//
+static bool modeIsGood(CGDisplayModeRef mode)
+{
+    uint32_t flags = CGDisplayModeGetIOFlags(mode);
+
+    if (!(flags & kDisplayModeValidFlag) || !(flags & kDisplayModeSafeFlag))
+        return false;
+    if (flags & kDisplayModeInterlacedFlag)
+        return false;
+    if (flags & kDisplayModeStretchedFlag)
+        return false;
+
+#if MAC_OS_X_VERSION_MAX_ALLOWED <= 101100
+    CFStringRef format = CGDisplayModeCopyPixelEncoding(mode);
+    if (CFStringCompare(format, CFSTR(IO16BitDirectPixels), 0) &&
+        CFStringCompare(format, CFSTR(IO32BitDirectPixels), 0))
+    {
+        CFRelease(format);
+        return false;
+    }
+
+    CFRelease(format);
+#endif /* MAC_OS_X_VERSION_MAX_ALLOWED */
+    return true;
+}
+
+// Convert Core Graphics display mode to GLFW video mode
+//
+static GLFWvidmode vidmodeFromCGDisplayMode(CGDisplayModeRef mode,
+                                            double fallbackRefreshRate)
+{
+    GLFWvidmode result;
+    result.width = (int) CGDisplayModeGetWidth(mode);
+    result.height = (int) CGDisplayModeGetHeight(mode);
+    result.refreshRate = (int) round(CGDisplayModeGetRefreshRate(mode));
+
+    if (result.refreshRate == 0)
+        result.refreshRate = (int) round(fallbackRefreshRate);
+
+#if MAC_OS_X_VERSION_MAX_ALLOWED <= 101100
+    CFStringRef format = CGDisplayModeCopyPixelEncoding(mode);
+    if (CFStringCompare(format, CFSTR(IO16BitDirectPixels), 0) == 0)
+    {
+        result.redBits = 5;
+        result.greenBits = 5;
+        result.blueBits = 5;
+    }
+    else
+#endif /* MAC_OS_X_VERSION_MAX_ALLOWED */
+    {
+        result.redBits = 8;
+        result.greenBits = 8;
+        result.blueBits = 8;
+    }
+
+#if MAC_OS_X_VERSION_MAX_ALLOWED <= 101100
+    CFRelease(format);
+#endif /* MAC_OS_X_VERSION_MAX_ALLOWED */
+    return result;
+}
+
+// Starts reservation for display fading
+//
+static CGDisplayFadeReservationToken beginFadeReservation(void)
+{
+    CGDisplayFadeReservationToken token = kCGDisplayFadeReservationInvalidToken;
+
+    if (CGAcquireDisplayFadeReservation(5, &token) == kCGErrorSuccess)
+    {
+        CGDisplayFade(token, 0.3,
+                      kCGDisplayBlendNormal,
+                      kCGDisplayBlendSolidColor,
+                      0.0, 0.0, 0.0,
+                      TRUE);
+    }
+
+    return token;
+}
+
+// Ends reservation for display fading
+//
+static void endFadeReservation(CGDisplayFadeReservationToken token)
+{
+    if (token != kCGDisplayFadeReservationInvalidToken)
+    {
+        CGDisplayFade(token, 0.5,
+                      kCGDisplayBlendSolidColor,
+                      kCGDisplayBlendNormal,
+                      0.0, 0.0, 0.0,
+                      FALSE);
+        CGReleaseDisplayFadeReservation(token);
+    }
+}
+
+// Finds and caches the NSScreen corresponding to the specified monitor
+//
+static bool refreshMonitorScreen(_GLFWmonitor* monitor)
+{
+    if (monitor->ns.screen)
+        return true;
+
+    for (NSScreen* screen in [NSScreen screens])
+    {
+        NSNumber* displayID = [screen deviceDescription][@"NSScreenNumber"];
+
+        // HACK: Compare unit numbers instead of display IDs to work around
+        //       display replacement on machines with automatic graphics
+        //       switching
+        if (monitor->ns.unitNumber == CGDisplayUnitNumber([displayID unsignedIntValue]))
+        {
+            monitor->ns.screen = screen;
+            return true;
+        }
+    }
+
+    _glfwInputError(GLFW_PLATFORM_ERROR, "Cocoa: Failed to find a screen for monitor");
+    return false;
+}
+
+// Returns the display refresh rate queried from the I/O registry
+//
+static double getFallbackRefreshRate(CGDirectDisplayID displayID)
+{
+    double refreshRate = 60.0;
+
+    io_iterator_t it;
+    io_service_t service;
+
+    if (IOServiceGetMatchingServices(kIOMasterPortDefault,
+                                     IOServiceMatching("IOFramebuffer"),
+                                     &it) != 0)
+    {
+        return refreshRate;
+    }
+
+    while ((service = IOIteratorNext(it)) != 0)
+    {
+        const CFNumberRef indexRef =
+            IORegistryEntryCreateCFProperty(service,
+                                            CFSTR("IOFramebufferOpenGLIndex"),
+                                            kCFAllocatorDefault,
+                                            kNilOptions);
+        if (!indexRef)
+            continue;
+
+        uint32_t index = 0;
+        CFNumberGetValue(indexRef, kCFNumberIntType, &index);
+        CFRelease(indexRef);
+
+        if (CGOpenGLDisplayMaskToDisplayID(1 << index) != displayID)
+            continue;
+
+        const CFNumberRef clockRef =
+            IORegistryEntryCreateCFProperty(service,
+                                            CFSTR("IOFBCurrentPixelClock"),
+                                            kCFAllocatorDefault,
+                                            kNilOptions);
+        const CFNumberRef countRef =
+            IORegistryEntryCreateCFProperty(service,
+                                            CFSTR("IOFBCurrentPixelCount"),
+                                            kCFAllocatorDefault,
+                                            kNilOptions);
+
+        uint32_t clock = 0, count = 0;
+
+        if (clockRef)
+        {
+            CFNumberGetValue(clockRef, kCFNumberIntType, &clock);
+            CFRelease(clockRef);
+        }
+
+        if (countRef)
+        {
+            CFNumberGetValue(countRef, kCFNumberIntType, &count);
+            CFRelease(countRef);
+        }
+
+        if (clock > 0 && count > 0)
+            refreshRate = clock / (double) count;
+
+        break;
+    }
+
+    IOObjectRelease(it);
+    return refreshRate;
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW internal API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+void _glfwClearDisplayLinks() {
+    for (size_t i = 0; i < _glfw.ns.displayLinks.count; i++) {
+        if (_glfw.ns.displayLinks.entries[i].displayLink) {
+            CVDisplayLinkStop(_glfw.ns.displayLinks.entries[i].displayLink);
+            CVDisplayLinkRelease(_glfw.ns.displayLinks.entries[i].displayLink);
+            _glfw.ns.displayLinks.entries[i].displayLink = nil;
+            _glfw.ns.displayLinks.entries[i].lastRenderFrameRequestedAt = 0;
+        }
+    }
+    _glfw.ns.displayLinks.count = 0;
+}
+
+static CVReturn displayLinkCallback(
+        CVDisplayLinkRef displayLink UNUSED,
+        const CVTimeStamp* now UNUSED, const CVTimeStamp* outputTime UNUSED,
+        CVOptionFlags flagsIn UNUSED, CVOptionFlags* flagsOut UNUSED, void* userInfo)
+{
+    CGDirectDisplayID displayID = (CGDirectDisplayID)userInfo;
+    NSNumber *arg = [NSNumber numberWithUnsignedInt:displayID];
+    [NSApp performSelectorOnMainThread:@selector(render_frame_received:) withObject:arg waitUntilDone:NO];
+    [arg release];
+    return kCVReturnSuccess;
+}
+
+static inline void createDisplayLink(CGDirectDisplayID displayID) {
+    if (_glfw.ns.displayLinks.count >= sizeof(_glfw.ns.displayLinks.entries)/sizeof(_glfw.ns.displayLinks.entries[0]) - 1) return;
+    for (size_t i = 0; i < _glfw.ns.displayLinks.count; i++) {
+        if (_glfw.ns.displayLinks.entries[i].displayID == displayID) return;
+    }
+    _GLFWDisplayLinkNS *entry = &_glfw.ns.displayLinks.entries[_glfw.ns.displayLinks.count++];
+    memset(entry, 0, sizeof(_GLFWDisplayLinkNS));
+    entry->displayID = displayID;
+    CVDisplayLinkCreateWithCGDisplay(displayID, &entry->displayLink);
+    CVDisplayLinkSetOutputCallback(entry->displayLink, &displayLinkCallback, (void*)(uintptr_t)displayID);
+}
+
+// Poll for changes in the set of connected monitors
+//
+void _glfwPollMonitorsNS(void)
+{
+    uint32_t displayCount;
+
+    CGGetOnlineDisplayList(0, NULL, &displayCount);
+    CGDirectDisplayID* displays = calloc(displayCount, sizeof(CGDirectDisplayID));
+    CGGetOnlineDisplayList(displayCount, displays, &displayCount);
+    _glfwClearDisplayLinks();
+
+    for (int i = 0;  i < _glfw.monitorCount;  i++)
+        _glfw.monitors[i]->ns.screen = nil;
+
+    _GLFWmonitor** disconnected = NULL;
+    uint32_t disconnectedCount = _glfw.monitorCount;
+    if (disconnectedCount)
+    {
+        disconnected = calloc(_glfw.monitorCount, sizeof(_GLFWmonitor*));
+        memcpy(disconnected,
+               _glfw.monitors,
+               _glfw.monitorCount * sizeof(_GLFWmonitor*));
+    }
+
+    for (uint32_t i = 0;  i < displayCount;  i++)
+    {
+        if (CGDisplayIsAsleep(displays[i]))
+            continue;
+
+        // HACK: Compare unit numbers instead of display IDs to work around
+        //       display replacement on machines with automatic graphics
+        //       switching
+        const uint32_t unitNumber = CGDisplayUnitNumber(displays[i]);
+
+        for (uint32_t j = 0;  j < disconnectedCount;  j++)
+        {
+            if (disconnected[j] && disconnected[j]->ns.unitNumber == unitNumber)
+            {
+                disconnected[j] = NULL;
+                break;
+            }
+        }
+
+        const CGSize size = CGDisplayScreenSize(displays[i]);
+        char* name = getDisplayName(displays[i]);
+        if (!name)
+            name = _glfw_strdup("Unknown");
+
+        _GLFWmonitor* monitor = _glfwAllocMonitor(name, (int)size.width, (int)size.height);
+        monitor->ns.displayID  = displays[i];
+        monitor->ns.unitNumber = unitNumber;
+        createDisplayLink(monitor->ns.displayID);
+
+        free(name);
+
+        CGDisplayModeRef mode = CGDisplayCopyDisplayMode(displays[i]);
+        if (CGDisplayModeGetRefreshRate(mode) == 0.0)
+            monitor->ns.fallbackRefreshRate = getFallbackRefreshRate(displays[i]);
+        CGDisplayModeRelease(mode);
+
+        _glfwInputMonitor(monitor, GLFW_CONNECTED, _GLFW_INSERT_LAST);
+    }
+
+    for (uint32_t i = 0;  i < disconnectedCount;  i++)
+    {
+        if (disconnected[i])
+            _glfwInputMonitor(disconnected[i], GLFW_DISCONNECTED, 0);
+    }
+
+    free(disconnected);
+    free(displays);
+    _glfwRestartDisplayLinks();
+}
+
+// Change the current video mode
+//
+void _glfwSetVideoModeNS(_GLFWmonitor* monitor, const GLFWvidmode* desired)
+{
+    GLFWvidmode current;
+    _glfwPlatformGetVideoMode(monitor, &current);
+
+    const GLFWvidmode* best = _glfwChooseVideoMode(monitor, desired);
+    if (_glfwCompareVideoModes(&current, best) == 0)
+        return;
+
+    CFArrayRef modes = CGDisplayCopyAllDisplayModes(monitor->ns.displayID, NULL);
+    const CFIndex count = CFArrayGetCount(modes);
+    CGDisplayModeRef native = NULL;
+
+    for (CFIndex i = 0;  i < count;  i++)
+    {
+        CGDisplayModeRef dm = (CGDisplayModeRef) CFArrayGetValueAtIndex(modes, i);
+        if (!modeIsGood(dm))
+            continue;
+
+        const GLFWvidmode mode =
+            vidmodeFromCGDisplayMode(dm, monitor->ns.fallbackRefreshRate);
+        if (_glfwCompareVideoModes(best, &mode) == 0)
+        {
+            native = dm;
+            break;
+        }
+    }
+
+    if (native)
+    {
+        if (monitor->ns.previousMode == NULL)
+            monitor->ns.previousMode = CGDisplayCopyDisplayMode(monitor->ns.displayID);
+
+        CGDisplayFadeReservationToken token = beginFadeReservation();
+        CGDisplaySetDisplayMode(monitor->ns.displayID, native, NULL);
+        endFadeReservation(token);
+    }
+
+    CFRelease(modes);
+}
+
+// Restore the previously saved (original) video mode
+//
+void _glfwRestoreVideoModeNS(_GLFWmonitor* monitor)
+{
+    if (monitor->ns.previousMode)
+    {
+        CGDisplayFadeReservationToken token = beginFadeReservation();
+        CGDisplaySetDisplayMode(monitor->ns.displayID,
+                                monitor->ns.previousMode, NULL);
+        endFadeReservation(token);
+
+        CGDisplayModeRelease(monitor->ns.previousMode);
+        monitor->ns.previousMode = NULL;
+    }
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW platform API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+void _glfwPlatformFreeMonitor(_GLFWmonitor* monitor UNUSED)
+{
+}
+
+void _glfwPlatformGetMonitorPos(_GLFWmonitor* monitor, int* xpos, int* ypos)
+{
+    const CGRect bounds = CGDisplayBounds(monitor->ns.displayID);
+
+    if (xpos)
+        *xpos = (int) bounds.origin.x;
+    if (ypos)
+        *ypos = (int) bounds.origin.y;
+}
+
+void _glfwPlatformGetMonitorContentScale(_GLFWmonitor* monitor,
+                                         float* xscale, float* yscale)
+{
+    if (!refreshMonitorScreen(monitor))
+        return;
+
+    const NSRect points = [monitor->ns.screen frame];
+    const NSRect pixels = [monitor->ns.screen convertRectToBacking:points];
+
+    if (xscale)
+        *xscale = (float) (pixels.size.width / points.size.width);
+    if (yscale)
+        *yscale = (float) (pixels.size.height / points.size.height);
+}
+
+void _glfwPlatformGetMonitorWorkarea(_GLFWmonitor* monitor,
+                                     int* xpos, int* ypos,
+                                     int* width, int* height)
+{
+    if (!refreshMonitorScreen(monitor))
+        return;
+
+    const NSRect frameRect = [monitor->ns.screen visibleFrame];
+
+    if (xpos)
+        *xpos = (int)frameRect.origin.x;
+    if (ypos)
+        *ypos = (int)_glfwTransformYNS(frameRect.origin.y + frameRect.size.height - 1);
+    if (width)
+        *width = (int)frameRect.size.width;
+    if (height)
+        *height = (int)frameRect.size.height;
+
+}
+
+GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count)
+{
+    *count = 0;
+
+    CFArrayRef modes = CGDisplayCopyAllDisplayModes(monitor->ns.displayID, NULL);
+    const CFIndex found = CFArrayGetCount(modes);
+    GLFWvidmode* result = calloc(found, sizeof(GLFWvidmode));
+
+    for (CFIndex i = 0;  i < found;  i++)
+    {
+        CGDisplayModeRef dm = (CGDisplayModeRef) CFArrayGetValueAtIndex(modes, i);
+        if (!modeIsGood(dm))
+            continue;
+
+        const GLFWvidmode mode =
+            vidmodeFromCGDisplayMode(dm, monitor->ns.fallbackRefreshRate);
+
+        for (CFIndex j = 0;  j < *count;  j++)
+        {
+            if (_glfwCompareVideoModes(result + j, &mode) == 0)
+                break;
+        }
+
+        // Skip duplicate modes
+        if (i < *count)
+            continue;
+
+        (*count)++;
+        result[*count - 1] = mode;
+    }
+
+    CFRelease(modes);
+    return result;
+}
+
+void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode *mode)
+{
+    CGDisplayModeRef native = CGDisplayCopyDisplayMode(monitor->ns.displayID);
+    *mode = vidmodeFromCGDisplayMode(native, monitor->ns.fallbackRefreshRate);
+    CGDisplayModeRelease(native);
+}
+
+bool _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp)
+{
+    uint32_t size = CGDisplayGammaTableCapacity(monitor->ns.displayID);
+    CGGammaValue* values = calloc(size * 3, sizeof(CGGammaValue));
+
+    CGGetDisplayTransferByTable(monitor->ns.displayID,
+                                size,
+                                values,
+                                values + size,
+                                values + size * 2,
+                                &size);
+
+    _glfwAllocGammaArrays(ramp, size);
+
+    for (uint32_t i = 0; i < size; i++)
+    {
+        ramp->red[i]   = (unsigned short) (values[i] * 65535);
+        ramp->green[i] = (unsigned short) (values[i + size] * 65535);
+        ramp->blue[i]  = (unsigned short) (values[i + size * 2] * 65535);
+    }
+
+    free(values);
+    return true;
+}
+
+void _glfwPlatformSetGammaRamp(_GLFWmonitor* monitor, const GLFWgammaramp* ramp)
+{
+    CGGammaValue* values = calloc(ramp->size * 3, sizeof(CGGammaValue));
+
+    for (unsigned int i = 0;  i < ramp->size;  i++)
+    {
+        values[i]                  = ramp->red[i] / 65535.f;
+        values[i + ramp->size]     = ramp->green[i] / 65535.f;
+        values[i + ramp->size * 2] = ramp->blue[i] / 65535.f;
+    }
+
+    CGSetDisplayTransferByTable(monitor->ns.displayID,
+                                ramp->size,
+                                values,
+                                values + ramp->size,
+                                values + ramp->size * 2);
+
+    free(values);
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                        GLFW native API                       //////
+//////////////////////////////////////////////////////////////////////////
+
+GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* handle)
+{
+    _GLFWmonitor* monitor = (_GLFWmonitor*) handle;
+    _GLFW_REQUIRE_INIT_OR_RETURN(kCGNullDirectDisplay);
+    return monitor->ns.displayID;
+}

glfw/cocoa_platform.h

@@ -0,0 +1,244 @@
+//========================================================================
+// GLFW 3.4 macOS - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2009-2019 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+#include <stdint.h>
+#include <dlfcn.h>
+
+#include <Carbon/Carbon.h>
+#if defined(__OBJC__)
+#import <Cocoa/Cocoa.h>
+#import <CoreVideo/CoreVideo.h>
+#else
+typedef void* id;
+typedef void* CVDisplayLinkRef;
+#endif
+
+// NOTE: Many Cocoa enum values have been renamed and we need to build across
+//       SDK versions where one is unavailable or the other deprecated
+//       We use the newer names in code and these macros to handle compatibility
+#if MAC_OS_X_VERSION_MAX_ALLOWED < 101200
+ #define NSBitmapFormatAlphaNonpremultiplied NSAlphaNonpremultipliedBitmapFormat
+ #define NSEventMaskAny NSAnyEventMask
+ #define NSEventMaskKeyUp NSKeyUpMask
+ #define NSEventModifierFlagCapsLock NSAlphaShiftKeyMask
+ #define NSEventModifierFlagCommand NSCommandKeyMask
+ #define NSEventModifierFlagControl NSControlKeyMask
+ #define NSEventModifierFlagDeviceIndependentFlagsMask NSDeviceIndependentModifierFlagsMask
+ #define NSEventModifierFlagOption NSAlternateKeyMask
+ #define NSEventModifierFlagShift NSShiftKeyMask
+ #define NSEventTypeApplicationDefined NSApplicationDefined
+ #define NSWindowStyleMaskBorderless NSBorderlessWindowMask
+ #define NSWindowStyleMaskClosable NSClosableWindowMask
+ #define NSWindowStyleMaskMiniaturizable NSMiniaturizableWindowMask
+ #define NSWindowStyleMaskResizable NSResizableWindowMask
+ #define NSWindowStyleMaskTitled NSTitledWindowMask
+#endif
+
+#if (MAC_OS_X_VERSION_MAX_ALLOWED < 101400)
+ #define NSPasteboardTypeFileURL NSFilenamesPboardType
+ #define NSBitmapFormatAlphaNonpremultiplied NSAlphaNonpremultipliedBitmapFormat
+ #define NSPasteboardTypeString NSStringPboardType
+ #define NSOpenGLContextParameterSurfaceOpacity NSOpenGLCPSurfaceOpacity
+#endif
+
+
+typedef int (* GLFWcocoatextinputfilterfun)(int,int,unsigned int, unsigned long);
+typedef bool (* GLFWapplicationshouldhandlereopenfun)(int);
+typedef void (* GLFWapplicationwillfinishlaunchingfun)(void);
+typedef bool (* GLFWcocoatogglefullscreenfun)(GLFWwindow*);
+typedef void (* GLFWcocoarenderframefun)(GLFWwindow*);
+
+typedef VkFlags VkMacOSSurfaceCreateFlagsMVK;
+typedef VkFlags VkMetalSurfaceCreateFlagsEXT;
+
+typedef struct VkMacOSSurfaceCreateInfoMVK
+{
+    VkStructureType                 sType;
+    const void*                     pNext;
+    VkMacOSSurfaceCreateFlagsMVK    flags;
+    const void*                     pView;
+} VkMacOSSurfaceCreateInfoMVK;
+
+typedef struct VkMetalSurfaceCreateInfoEXT
+{
+    VkStructureType                 sType;
+    const void*                     pNext;
+    VkMetalSurfaceCreateFlagsEXT    flags;
+    const void*                     pLayer;
+} VkMetalSurfaceCreateInfoEXT;
+
+typedef VkResult (APIENTRY *PFN_vkCreateMacOSSurfaceMVK)(VkInstance,const VkMacOSSurfaceCreateInfoMVK*,const VkAllocationCallbacks*,VkSurfaceKHR*);
+typedef VkResult (APIENTRY *PFN_vkCreateMetalSurfaceEXT)(VkInstance,const VkMetalSurfaceCreateInfoEXT*,const VkAllocationCallbacks*,VkSurfaceKHR*);
+
+#include "posix_thread.h"
+#include "cocoa_joystick.h"
+#include "nsgl_context.h"
+
+#define _glfw_dlopen(name) dlopen(name, RTLD_LAZY | RTLD_LOCAL)
+#define _glfw_dlclose(handle) dlclose(handle)
+#define _glfw_dlsym(handle, name) dlsym(handle, name)
+
+#define _GLFW_PLATFORM_WINDOW_STATE         _GLFWwindowNS  ns
+#define _GLFW_PLATFORM_LIBRARY_WINDOW_STATE _GLFWlibraryNS ns
+#define _GLFW_PLATFORM_LIBRARY_TIMER_STATE  _GLFWtimerNS   ns
+#define _GLFW_PLATFORM_MONITOR_STATE        _GLFWmonitorNS ns
+#define _GLFW_PLATFORM_CURSOR_STATE         _GLFWcursorNS  ns
+
+// HIToolbox.framework pointer typedefs
+#define kTISPropertyUnicodeKeyLayoutData _glfw.ns.tis.kPropertyUnicodeKeyLayoutData
+typedef TISInputSourceRef (*PFN_TISCopyCurrentKeyboardLayoutInputSource)(void);
+#define TISCopyCurrentKeyboardLayoutInputSource _glfw.ns.tis.CopyCurrentKeyboardLayoutInputSource
+typedef void* (*PFN_TISGetInputSourceProperty)(TISInputSourceRef,CFStringRef);
+#define TISGetInputSourceProperty _glfw.ns.tis.GetInputSourceProperty
+typedef UInt8 (*PFN_LMGetKbdType)(void);
+#define LMGetKbdType _glfw.ns.tis.GetKbdType
+
+
+// Cocoa-specific per-window data
+//
+typedef struct _GLFWwindowNS
+{
+    id              object;
+    id              delegate;
+    id              view;
+    id              layer;
+
+    bool            maximized;
+    bool            retina;
+
+    // Cached window properties to filter out duplicate events
+    int             width, height;
+    int             fbWidth, fbHeight;
+    float           xscale, yscale;
+
+    // The total sum of the distances the cursor has been warped
+    // since the last cursor motion event was processed
+    // This is kept to counteract Cocoa doing the same internally
+    double          cursorWarpDeltaX, cursorWarpDeltaY;
+
+    // The text input filter callback
+    GLFWcocoatextinputfilterfun textInputFilterCallback;
+    // The toggle fullscreen intercept callback
+    GLFWcocoatogglefullscreenfun toggleFullscreenCallback;
+    // Dead key state
+    UInt32 deadKeyState;
+    // Whether a render frame has been requested for this window
+    bool renderFrameRequested;
+    GLFWcocoarenderframefun renderFrameCallback;
+} _GLFWwindowNS;
+
+typedef struct _GLFWDisplayLinkNS
+{
+    CVDisplayLinkRef displayLink;
+    CGDirectDisplayID displayID;
+    monotonic_t lastRenderFrameRequestedAt;
+} _GLFWDisplayLinkNS;
+
+// Cocoa-specific global data
+//
+typedef struct _GLFWlibraryNS
+{
+    CGEventSourceRef    eventSource;
+    id                  delegate;
+    bool                finishedLaunching;
+    bool                cursorHidden;
+    TISInputSourceRef   inputSource;
+    IOHIDManagerRef     hidManager;
+    id                  unicodeData;
+    id                  helper;
+    id                  keyUpMonitor;
+    id                  keyDownMonitor;
+    id                  nibObjects;
+
+    char                keyName[64];
+    char                text[256];
+    short int           keycodes[256];
+    short int           key_to_keycode[GLFW_KEY_LAST + 1];
+    char*               clipboardString;
+    CGPoint             cascadePoint;
+    // Where to place the cursor when re-enabled
+    double              restoreCursorPosX, restoreCursorPosY;
+    // The window whose disabled cursor mode is active
+    _GLFWwindow*        disabledCursorWindow;
+
+    struct {
+        CFBundleRef     bundle;
+        PFN_TISCopyCurrentKeyboardLayoutInputSource CopyCurrentKeyboardLayoutInputSource;
+        PFN_TISGetInputSourceProperty GetInputSourceProperty;
+        PFN_LMGetKbdType GetKbdType;
+        CFStringRef     kPropertyUnicodeKeyLayoutData;
+    } tis;
+
+    struct {
+        _GLFWDisplayLinkNS entries[256];
+        size_t count;
+    } displayLinks;
+
+} _GLFWlibraryNS;
+
+// Cocoa-specific per-monitor data
+//
+typedef struct _GLFWmonitorNS
+{
+    CGDirectDisplayID   displayID;
+    CGDisplayModeRef    previousMode;
+    uint32_t            unitNumber;
+    id                  screen;
+    double              fallbackRefreshRate;
+
+} _GLFWmonitorNS;
+
+// Cocoa-specific per-cursor data
+//
+typedef struct _GLFWcursorNS
+{
+    id              object;
+
+} _GLFWcursorNS;
+
+// Cocoa-specific global timer data
+//
+typedef struct _GLFWtimerNS
+{
+    uint64_t        frequency;
+
+} _GLFWtimerNS;
+
+
+void _glfwPollMonitorsNS(void);
+void _glfwSetVideoModeNS(_GLFWmonitor* monitor, const GLFWvidmode* desired);
+void _glfwRestoreVideoModeNS(_GLFWmonitor* monitor);
+
+float _glfwTransformYNS(float y);
+
+void* _glfwLoadLocalVulkanLoaderNS(void);
+
+void _glfwClearDisplayLinks(void);
+void _glfwRestartDisplayLinks(void);
+void _glfwDispatchTickCallback(void);
+void _glfwDispatchRenderFrame(CGDirectDisplayID);
+void _glfwShutdownCVDisplayLink(unsigned long long, void*);
+void _glfwCocoaPostEmptyEvent(void);

glfw/context.c

@@ -0,0 +1,591 @@
+//========================================================================
+// GLFW 3.4 - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2002-2006 Marcus Geelnard
+// Copyright (c) 2006-2016 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+// Please use C89 style variable declarations in this file because VS 2010
+//========================================================================
+
+#include "internal.h"
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <limits.h>
+#include <stdio.h>
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW internal API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+// Checks whether the desired context attributes are valid
+//
+// This function checks things like whether the specified client API version
+// exists and whether all relevant options have supported and non-conflicting
+// values
+//
+bool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
+{
+    if (ctxconfig->share)
+    {
+        if (ctxconfig->client == GLFW_NO_API ||
+            ctxconfig->share->context.client == GLFW_NO_API)
+        {
+            _glfwInputError(GLFW_NO_WINDOW_CONTEXT, NULL);
+            return false;
+        }
+    }
+
+    if (ctxconfig->source != GLFW_NATIVE_CONTEXT_API &&
+        ctxconfig->source != GLFW_EGL_CONTEXT_API &&
+        ctxconfig->source != GLFW_OSMESA_CONTEXT_API)
+    {
+        _glfwInputError(GLFW_INVALID_ENUM,
+                        "Invalid context creation API 0x%08X",
+                        ctxconfig->source);
+        return false;
+    }
+
+    if (ctxconfig->client != GLFW_NO_API &&
+        ctxconfig->client != GLFW_OPENGL_API &&
+        ctxconfig->client != GLFW_OPENGL_ES_API)
+    {
+        _glfwInputError(GLFW_INVALID_ENUM,
+                        "Invalid client API 0x%08X",
+                        ctxconfig->client);
+        return false;
+    }
+
+    if (ctxconfig->client == GLFW_OPENGL_API)
+    {
+        if ((ctxconfig->major < 1 || ctxconfig->minor < 0) ||
+            (ctxconfig->major == 1 && ctxconfig->minor > 5) ||
+            (ctxconfig->major == 2 && ctxconfig->minor > 1) ||
+            (ctxconfig->major == 3 && ctxconfig->minor > 3))
+        {
+            // OpenGL 1.0 is the smallest valid version
+            // OpenGL 1.x series ended with version 1.5
+            // OpenGL 2.x series ended with version 2.1
+            // OpenGL 3.x series ended with version 3.3
+            // For now, let everything else through
+
+            _glfwInputError(GLFW_INVALID_VALUE,
+                            "Invalid OpenGL version %i.%i",
+                            ctxconfig->major, ctxconfig->minor);
+            return false;
+        }
+
+        if (ctxconfig->profile)
+        {
+            if (ctxconfig->profile != GLFW_OPENGL_CORE_PROFILE &&
+                ctxconfig->profile != GLFW_OPENGL_COMPAT_PROFILE)
+            {
+                _glfwInputError(GLFW_INVALID_ENUM,
+                                "Invalid OpenGL profile 0x%08X",
+                                ctxconfig->profile);
+                return false;
+            }
+
+            if (ctxconfig->major <= 2 ||
+                (ctxconfig->major == 3 && ctxconfig->minor < 2))
+            {
+                // Desktop OpenGL context profiles are only defined for version 3.2
+                // and above
+
+                _glfwInputError(GLFW_INVALID_VALUE,
+                                "Context profiles are only defined for OpenGL version 3.2 and above");
+                return false;
+            }
+        }
+
+        if (ctxconfig->forward && ctxconfig->major <= 2)
+        {
+            // Forward-compatible contexts are only defined for OpenGL version 3.0 and above
+            _glfwInputError(GLFW_INVALID_VALUE,
+                            "Forward-compatibility is only defined for OpenGL version 3.0 and above");
+            return false;
+        }
+    }
+    else if (ctxconfig->client == GLFW_OPENGL_ES_API)
+    {
+        if (ctxconfig->major < 1 || ctxconfig->minor < 0 ||
+            (ctxconfig->major == 1 && ctxconfig->minor > 1) ||
+            (ctxconfig->major == 2 && ctxconfig->minor > 0))
+        {
+            // OpenGL ES 1.0 is the smallest valid version
+            // OpenGL ES 1.x series ended with version 1.1
+            // OpenGL ES 2.x series ended with version 2.0
+            // For now, let everything else through
+
+            _glfwInputError(GLFW_INVALID_VALUE,
+                            "Invalid OpenGL ES version %i.%i",
+                            ctxconfig->major, ctxconfig->minor);
+            return false;
+        }
+    }
+
+    if (ctxconfig->robustness)
+    {
+        if (ctxconfig->robustness != GLFW_NO_RESET_NOTIFICATION &&
+            ctxconfig->robustness != GLFW_LOSE_CONTEXT_ON_RESET)
+        {
+            _glfwInputError(GLFW_INVALID_ENUM,
+                            "Invalid context robustness mode 0x%08X",
+                            ctxconfig->robustness);
+            return false;
+        }
+    }
+
+    if (ctxconfig->release)
+    {
+        if (ctxconfig->release != GLFW_RELEASE_BEHAVIOR_NONE &&
+            ctxconfig->release != GLFW_RELEASE_BEHAVIOR_FLUSH)
+        {
+            _glfwInputError(GLFW_INVALID_ENUM,
+                            "Invalid context release behavior 0x%08X",
+                            ctxconfig->release);
+            return false;
+        }
+    }
+
+    return true;
+}
+
+// Retrieves the attributes of the current context
+//
+bool _glfwRefreshContextAttribs(_GLFWwindow* window,
+                                    const _GLFWctxconfig* ctxconfig)
+{
+    int i;
+    _GLFWwindow* previous;
+    const char* version;
+    const char* prefixes[] =
+    {
+        "OpenGL ES-CM ",
+        "OpenGL ES-CL ",
+        "OpenGL ES ",
+        NULL
+    };
+
+    window->context.source = ctxconfig->source;
+    window->context.client = GLFW_OPENGL_API;
+
+    previous = _glfwPlatformGetTls(&_glfw.contextSlot);
+    glfwMakeContextCurrent((GLFWwindow*) window);
+
+    window->context.GetIntegerv = (PFNGLGETINTEGERVPROC)
+        window->context.getProcAddress("glGetIntegerv");
+    window->context.GetString = (PFNGLGETSTRINGPROC)
+        window->context.getProcAddress("glGetString");
+    if (!window->context.GetIntegerv || !window->context.GetString)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Entry point retrieval is broken");
+        glfwMakeContextCurrent((GLFWwindow*) previous);
+        return false;
+    }
+
+    version = (const char*) window->context.GetString(GL_VERSION);
+    if (!version)
+    {
+        if (ctxconfig->client == GLFW_OPENGL_API)
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "OpenGL version string retrieval is broken");
+        }
+        else
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "OpenGL ES version string retrieval is broken");
+        }
+
+        glfwMakeContextCurrent((GLFWwindow*) previous);
+        return false;
+    }
+
+    for (i = 0;  prefixes[i];  i++)
+    {
+        const size_t length = strlen(prefixes[i]);
+
+        if (strncmp(version, prefixes[i], length) == 0)
+        {
+            version += length;
+            window->context.client = GLFW_OPENGL_ES_API;
+            break;
+        }
+    }
+
+    if (!sscanf(version, "%d.%d.%d",
+                &window->context.major,
+                &window->context.minor,
+                &window->context.revision))
+    {
+        if (window->context.client == GLFW_OPENGL_API)
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "No version found in OpenGL version string");
+        }
+        else
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "No version found in OpenGL ES version string");
+        }
+
+        glfwMakeContextCurrent((GLFWwindow*) previous);
+        return false;
+    }
+
+    if (window->context.major < ctxconfig->major ||
+        (window->context.major == ctxconfig->major &&
+         window->context.minor < ctxconfig->minor))
+    {
+        // The desired OpenGL version is greater than the actual version
+        // This only happens if the machine lacks {GLX|WGL}_ARB_create_context
+        // /and/ the user has requested an OpenGL version greater than 1.0
+
+        // For API consistency, we emulate the behavior of the
+        // {GLX|WGL}_ARB_create_context extension and fail here
+
+        if (window->context.client == GLFW_OPENGL_API)
+        {
+            _glfwInputError(GLFW_VERSION_UNAVAILABLE,
+                            "Requested OpenGL version %i.%i, got version %i.%i",
+                            ctxconfig->major, ctxconfig->minor,
+                            window->context.major, window->context.minor);
+        }
+        else
+        {
+            _glfwInputError(GLFW_VERSION_UNAVAILABLE,
+                            "Requested OpenGL ES version %i.%i, got version %i.%i",
+                            ctxconfig->major, ctxconfig->minor,
+                            window->context.major, window->context.minor);
+        }
+
+        glfwMakeContextCurrent((GLFWwindow*) previous);
+        return false;
+    }
+
+    if (window->context.major >= 3)
+    {
+        // OpenGL 3.0+ uses a different function for extension string retrieval
+        // We cache it here instead of in glfwExtensionSupported mostly to alert
+        // users as early as possible that their build may be broken
+
+        window->context.GetStringi = (PFNGLGETSTRINGIPROC)
+            window->context.getProcAddress("glGetStringi");
+        if (!window->context.GetStringi)
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "Entry point retrieval is broken");
+            glfwMakeContextCurrent((GLFWwindow*) previous);
+            return false;
+        }
+    }
+
+    if (window->context.client == GLFW_OPENGL_API)
+    {
+        // Read back context flags (OpenGL 3.0 and above)
+        if (window->context.major >= 3)
+        {
+            GLint flags;
+            window->context.GetIntegerv(GL_CONTEXT_FLAGS, &flags);
+
+            if (flags & GL_CONTEXT_FLAG_FORWARD_COMPATIBLE_BIT)
+                window->context.forward = true;
+
+            if (flags & GL_CONTEXT_FLAG_DEBUG_BIT)
+                window->context.debug = true;
+            else if (glfwExtensionSupported("GL_ARB_debug_output") &&
+                     ctxconfig->debug)
+            {
+                // HACK: This is a workaround for older drivers (pre KHR_debug)
+                //       not setting the debug bit in the context flags for
+                //       debug contexts
+                window->context.debug = true;
+            }
+
+            if (flags & GL_CONTEXT_FLAG_NO_ERROR_BIT_KHR)
+                window->context.noerror = true;
+        }
+
+        // Read back OpenGL context profile (OpenGL 3.2 and above)
+        if (window->context.major >= 4 ||
+            (window->context.major == 3 && window->context.minor >= 2))
+        {
+            GLint mask;
+            window->context.GetIntegerv(GL_CONTEXT_PROFILE_MASK, &mask);
+
+            if (mask & GL_CONTEXT_COMPATIBILITY_PROFILE_BIT)
+                window->context.profile = GLFW_OPENGL_COMPAT_PROFILE;
+            else if (mask & GL_CONTEXT_CORE_PROFILE_BIT)
+                window->context.profile = GLFW_OPENGL_CORE_PROFILE;
+            else if (glfwExtensionSupported("GL_ARB_compatibility"))
+            {
+                // HACK: This is a workaround for the compatibility profile bit
+                //       not being set in the context flags if an OpenGL 3.2+
+                //       context was created without having requested a specific
+                //       version
+                window->context.profile = GLFW_OPENGL_COMPAT_PROFILE;
+            }
+        }
+
+        // Read back robustness strategy
+        if (glfwExtensionSupported("GL_ARB_robustness"))
+        {
+            // NOTE: We avoid using the context flags for detection, as they are
+            //       only present from 3.0 while the extension applies from 1.1
+
+            GLint strategy;
+            window->context.GetIntegerv(GL_RESET_NOTIFICATION_STRATEGY_ARB,
+                                        &strategy);
+
+            if (strategy == GL_LOSE_CONTEXT_ON_RESET_ARB)
+                window->context.robustness = GLFW_LOSE_CONTEXT_ON_RESET;
+            else if (strategy == GL_NO_RESET_NOTIFICATION_ARB)
+                window->context.robustness = GLFW_NO_RESET_NOTIFICATION;
+        }
+    }
+    else
+    {
+        // Read back robustness strategy
+        if (glfwExtensionSupported("GL_EXT_robustness"))
+        {
+            // NOTE: The values of these constants match those of the OpenGL ARB
+            //       one, so we can reuse them here
+
+            GLint strategy;
+            window->context.GetIntegerv(GL_RESET_NOTIFICATION_STRATEGY_ARB,
+                                        &strategy);
+
+            if (strategy == GL_LOSE_CONTEXT_ON_RESET_ARB)
+                window->context.robustness = GLFW_LOSE_CONTEXT_ON_RESET;
+            else if (strategy == GL_NO_RESET_NOTIFICATION_ARB)
+                window->context.robustness = GLFW_NO_RESET_NOTIFICATION;
+        }
+    }
+
+    if (glfwExtensionSupported("GL_KHR_context_flush_control"))
+    {
+        GLint behavior;
+        window->context.GetIntegerv(GL_CONTEXT_RELEASE_BEHAVIOR, &behavior);
+
+        if (behavior == GL_NONE)
+            window->context.release = GLFW_RELEASE_BEHAVIOR_NONE;
+        else if (behavior == GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH)
+            window->context.release = GLFW_RELEASE_BEHAVIOR_FLUSH;
+    }
+
+    // Clearing the front buffer to black to avoid garbage pixels left over from
+    // previous uses of our bit of VRAM
+    {
+        PFNGLCLEARPROC glClear = (PFNGLCLEARPROC)
+            window->context.getProcAddress("glClear");
+        glClear(GL_COLOR_BUFFER_BIT);
+        window->context.swapBuffers(window);
+    }
+
+    glfwMakeContextCurrent((GLFWwindow*) previous);
+    return true;
+}
+
+// Searches an extension string for the specified extension
+//
+bool _glfwStringInExtensionString(const char* string, const char* extensions)
+{
+    const char* start = extensions;
+
+    for (;;)
+    {
+        const char* where;
+        const char* terminator;
+
+        where = strstr(start, string);
+        if (!where)
+            return false;
+
+        terminator = where + strlen(string);
+        if (where == start || *(where - 1) == ' ')
+        {
+            if (*terminator == ' ' || *terminator == '\0')
+                break;
+        }
+
+        start = terminator;
+    }
+
+    return true;
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                        GLFW public API                       //////
+//////////////////////////////////////////////////////////////////////////
+
+GLFWAPI void glfwMakeContextCurrent(GLFWwindow* handle)
+{
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    _GLFWwindow* previous = _glfwPlatformGetTls(&_glfw.contextSlot);
+
+    _GLFW_REQUIRE_INIT();
+
+    if (window && window->context.client == GLFW_NO_API)
+    {
+        _glfwInputError(GLFW_NO_WINDOW_CONTEXT,
+                        "Cannot make current with a window that has no OpenGL or OpenGL ES context");
+        return;
+    }
+
+    if (previous)
+    {
+        if (!window || window->context.source != previous->context.source)
+            previous->context.makeCurrent(NULL);
+    }
+
+    if (window)
+        window->context.makeCurrent(window);
+}
+
+GLFWAPI GLFWwindow* glfwGetCurrentContext(void)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+    return _glfwPlatformGetTls(&_glfw.contextSlot);
+}
+
+GLFWAPI void glfwSwapBuffers(GLFWwindow* handle)
+{
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    assert(window != NULL);
+
+    _GLFW_REQUIRE_INIT();
+
+    if (window->context.client == GLFW_NO_API)
+    {
+        _glfwInputError(GLFW_NO_WINDOW_CONTEXT,
+                        "Cannot swap buffers of a window that has no OpenGL or OpenGL ES context");
+        return;
+    }
+
+    window->context.swapBuffers(window);
+}
+
+GLFWAPI void glfwSwapInterval(int interval)
+{
+    _GLFWwindow* window;
+
+    _GLFW_REQUIRE_INIT();
+
+    window = _glfwPlatformGetTls(&_glfw.contextSlot);
+    if (!window)
+    {
+        _glfwInputError(GLFW_NO_CURRENT_CONTEXT,
+                        "Cannot set swap interval without a current OpenGL or OpenGL ES context");
+        return;
+    }
+
+    window->context.swapInterval(interval);
+}
+
+GLFWAPI int glfwExtensionSupported(const char* extension)
+{
+    _GLFWwindow* window;
+    assert(extension != NULL);
+
+    _GLFW_REQUIRE_INIT_OR_RETURN(false);
+
+    window = _glfwPlatformGetTls(&_glfw.contextSlot);
+    if (!window)
+    {
+        _glfwInputError(GLFW_NO_CURRENT_CONTEXT,
+                        "Cannot query extension without a current OpenGL or OpenGL ES context");
+        return false;
+    }
+
+    if (*extension == '\0')
+    {
+        _glfwInputError(GLFW_INVALID_VALUE, "Extension name cannot be an empty string");
+        return false;
+    }
+
+    if (window->context.major >= 3)
+    {
+        int i;
+        GLint count;
+
+        // Check if extension is in the modern OpenGL extensions string list
+
+        window->context.GetIntegerv(GL_NUM_EXTENSIONS, &count);
+
+        for (i = 0;  i < count;  i++)
+        {
+            const char* en = (const char*)
+                window->context.GetStringi(GL_EXTENSIONS, i);
+            if (!en)
+            {
+                _glfwInputError(GLFW_PLATFORM_ERROR,
+                                "Extension string retrieval is broken");
+                return false;
+            }
+
+            if (strcmp(en, extension) == 0)
+                return true;
+        }
+    }
+    else
+    {
+        // Check if extension is in the old style OpenGL extensions string
+
+        const char* extensions = (const char*)
+            window->context.GetString(GL_EXTENSIONS);
+        if (!extensions)
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "Extension string retrieval is broken");
+            return false;
+        }
+
+        if (_glfwStringInExtensionString(extension, extensions))
+            return true;
+    }
+
+    // Check if extension is in the platform-specific string
+    return window->context.extensionSupported(extension);
+}
+
+GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname)
+{
+    _GLFWwindow* window;
+    assert(procname != NULL);
+
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+
+    window = _glfwPlatformGetTls(&_glfw.contextSlot);
+    if (!window)
+    {
+        _glfwInputError(GLFW_NO_CURRENT_CONTEXT,
+                        "Cannot query entry point without a current OpenGL or OpenGL ES context");
+        return NULL;
+    }
+
+    return window->context.getProcAddress(procname);
+}

glfw/dbus_glfw.c

@@ -0,0 +1,350 @@
+//========================================================================
+// GLFW 3.4 XKB - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2018 Kovid Goyal <kovid@kovidgoyal.net>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+
+#include "internal.h"
+#include "dbus_glfw.h"
+#include "../kitty/monotonic.h"
+#include <stdlib.h>
+#include <string.h>
+
+static inline void
+report_error(DBusError *err, const char *fmt, ...) {
+    static char buf[1024];
+    va_list args;
+    va_start(args, fmt);
+    int n = vsnprintf(buf, sizeof(buf), fmt, args);
+    va_end(args);
+    snprintf(buf + n, sizeof(buf), ". DBUS error: %s", err->message);
+    _glfwInputError(GLFW_PLATFORM_ERROR, "%s", buf);
+    dbus_error_free(err);
+}
+
+static _GLFWDBUSData *dbus_data = NULL;
+static DBusConnection *session_bus = NULL;
+
+bool
+glfw_dbus_init(_GLFWDBUSData *dbus, EventLoopData *eld) {
+    dbus->eld = eld;
+    dbus_data = dbus;
+    return true;
+}
+
+static void
+on_dbus_watch_ready(int fd UNUSED, int events, void *data) {
+    DBusWatch *watch = (DBusWatch*)data;
+    unsigned int flags = 0;
+    if (events & POLLERR) flags |= DBUS_WATCH_ERROR;
+    if (events & POLLHUP) flags |= DBUS_WATCH_HANGUP;
+    if (events & POLLIN) flags |= DBUS_WATCH_READABLE;
+    if (events & POLLOUT) flags |= DBUS_WATCH_WRITABLE;
+    dbus_watch_handle(watch, flags);
+}
+
+static inline int
+events_for_watch(DBusWatch *watch) {
+    int events = 0;
+    unsigned int flags = dbus_watch_get_flags(watch);
+    if (flags & DBUS_WATCH_READABLE) events |= POLLIN;
+    if (flags & DBUS_WATCH_WRITABLE) events |= POLLOUT;
+    return events;
+}
+
+static dbus_bool_t
+add_dbus_watch(DBusWatch *watch, void *data) {
+    id_type watch_id = addWatch(dbus_data->eld, data, dbus_watch_get_unix_fd(watch), events_for_watch(watch), dbus_watch_get_enabled(watch), on_dbus_watch_ready, watch);
+    if (!watch_id) return FALSE;
+    id_type *idp = malloc(sizeof(id_type));
+    if (!idp) return FALSE;
+    *idp = watch_id;
+    dbus_watch_set_data(watch, idp, free);
+    return TRUE;
+}
+
+static void
+remove_dbus_watch(DBusWatch *watch, void *data UNUSED) {
+    id_type *idp = dbus_watch_get_data(watch);
+    if (idp) removeWatch(dbus_data->eld, *idp);
+}
+
+static void
+toggle_dbus_watch(DBusWatch *watch, void *data UNUSED) {
+    id_type *idp = dbus_watch_get_data(watch);
+    if (idp) toggleWatch(dbus_data->eld, *idp, dbus_watch_get_enabled(watch));
+}
+
+static void
+on_dbus_timer_ready(id_type timer_id UNUSED, void *data) {
+    if (data) {
+        DBusTimeout *t = (DBusTimeout*)data;
+        dbus_timeout_handle(t);
+    }
+}
+
+
+static dbus_bool_t
+add_dbus_timeout(DBusTimeout *timeout, void *data) {
+    int enabled = dbus_timeout_get_enabled(timeout) ? 1 : 0;
+    monotonic_t interval = ms_to_monotonic_t(dbus_timeout_get_interval(timeout));
+    if (interval < 0) return FALSE;
+    id_type timer_id = addTimer(dbus_data->eld, data, interval, enabled, true, on_dbus_timer_ready, timeout, NULL);
+    if (!timer_id) return FALSE;
+    id_type *idp = malloc(sizeof(id_type));
+    if (!idp) {
+        removeTimer(dbus_data->eld, timer_id);
+        return FALSE;
+    }
+    *idp = timer_id;
+    dbus_timeout_set_data(timeout, idp, free);
+    return TRUE;
+
+}
+
+static void
+remove_dbus_timeout(DBusTimeout *timeout, void *data UNUSED) {
+    id_type *idp = dbus_timeout_get_data(timeout);
+    if (idp) removeTimer(dbus_data->eld, *idp);
+}
+
+static void
+toggle_dbus_timeout(DBusTimeout *timeout, void *data UNUSED) {
+    id_type *idp = dbus_timeout_get_data(timeout);
+    if (idp) toggleTimer(dbus_data->eld, *idp, dbus_timeout_get_enabled(timeout));
+}
+
+
+DBusConnection*
+glfw_dbus_connect_to(const char *path, const char* err_msg, const char *name, bool register_on_bus) {
+    DBusError err;
+    dbus_error_init(&err);
+    DBusConnection *ans = dbus_connection_open_private(path, &err);
+    if (!ans) {
+        report_error(&err, err_msg);
+        return NULL;
+    }
+    dbus_connection_set_exit_on_disconnect(ans, FALSE);
+    dbus_error_free(&err);
+    if (register_on_bus) {
+        if (!dbus_bus_register(ans, &err)) {
+            report_error(&err, err_msg);
+            return NULL;
+        }
+    }
+    if (!dbus_connection_set_watch_functions(ans, add_dbus_watch, remove_dbus_watch, toggle_dbus_watch, (void*)name, NULL)) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to set DBUS watches on connection to: %s", path);
+        dbus_connection_close(ans);
+        dbus_connection_unref(ans);
+        return NULL;
+    }
+    if (!dbus_connection_set_timeout_functions(ans, add_dbus_timeout, remove_dbus_timeout, toggle_dbus_timeout, (void*)name, NULL)) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to set DBUS timeout functions on connection to: %s", path);
+        dbus_connection_close(ans);
+        dbus_connection_unref(ans);
+        return NULL;
+    }
+    return ans;
+}
+
+void
+glfw_dbus_dispatch(DBusConnection *conn) {
+    while(dbus_connection_dispatch(conn) == DBUS_DISPATCH_DATA_REMAINS);
+}
+
+void
+glfw_dbus_session_bus_dispatch() {
+    if (session_bus) glfw_dbus_dispatch(session_bus);
+}
+
+void
+glfw_dbus_terminate(_GLFWDBUSData *dbus UNUSED) {
+    if (dbus_data) {
+        dbus_data->eld = NULL;
+        dbus_data = NULL;
+    }
+    if (session_bus) {
+        dbus_connection_unref(session_bus);
+        session_bus = NULL;
+    }
+}
+
+void
+glfw_dbus_close_connection(DBusConnection *conn) {
+    dbus_connection_close(conn);
+    dbus_connection_unref(conn);
+}
+
+bool
+glfw_dbus_get_args(DBusMessage *msg, const char *failmsg, ...) {
+    DBusError err;
+    dbus_error_init(&err);
+    va_list ap;
+    va_start(ap, failmsg);
+    int firstarg = va_arg(ap, int);
+    bool ret = dbus_message_get_args_valist(msg, &err, firstarg, ap) ? true : false;
+    va_end(ap);
+    if (!ret) report_error(&err, failmsg);
+    return ret;
+}
+
+typedef struct {
+    dbus_pending_callback callback;
+    void *user_data;
+} MethodResponse;
+
+static const char*
+format_message_error(DBusError *err) {
+    static char buf[1024];
+    snprintf(buf, sizeof(buf), "[%s] %s", err->name ? err->name : "", err->message);
+    return buf;
+}
+
+static void
+method_reply_received(DBusPendingCall *pending, void *user_data) {
+    MethodResponse *res = (MethodResponse*)user_data;
+    DBusMessage *msg = dbus_pending_call_steal_reply(pending);
+    if (msg) {
+        DBusError err;
+        dbus_error_init(&err);
+        if (dbus_set_error_from_message(&err, msg)) res->callback(NULL, format_message_error(&err), res->user_data);
+        else res->callback(msg, NULL, res->user_data);
+        dbus_message_unref(msg);
+    }
+}
+
+bool
+call_method_with_msg(DBusConnection *conn, DBusMessage *msg, int timeout, dbus_pending_callback callback, void *user_data) {
+    bool retval = false;
+#define REPORT(errs) _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to call DBUS method: node=%s path=%s interface=%s method=%s, with error: %s", dbus_message_get_destination(msg), dbus_message_get_path(msg), dbus_message_get_interface(msg), dbus_message_get_member(msg), errs)
+    if (callback) {
+        DBusPendingCall *pending = NULL;
+        if (dbus_connection_send_with_reply(conn, msg, &pending, timeout)) {
+            MethodResponse *res = malloc(sizeof(MethodResponse));
+            if (!res) return false;
+            res->callback = callback;
+            res->user_data = user_data;
+            dbus_pending_call_set_notify(pending, method_reply_received, res, free);
+            retval = true;
+        } else {
+            REPORT("out of memory");
+        }
+    } else {
+        if (dbus_connection_send(conn, msg, NULL)) {
+            retval = true;
+        } else {
+            REPORT("out of memory");
+        }
+    }
+    return retval;
+#undef REPORT
+}
+
+static bool
+call_method(DBusConnection *conn, const char *node, const char *path, const char *interface, const char *method, int timeout, dbus_pending_callback callback, void *user_data, va_list ap) {
+    if (!conn) return false;
+    DBusMessage *msg = dbus_message_new_method_call(node, path, interface, method);
+    if (!msg) return false;
+    bool retval = false;
+
+    int firstarg = va_arg(ap, int);
+    if ((firstarg == DBUS_TYPE_INVALID) || dbus_message_append_args_valist(msg, firstarg, ap)) {
+        retval = call_method_with_msg(conn, msg, timeout, callback, user_data);
+    } else {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to call DBUS method: %s on node: %s and interface: %s could not add arguments", method, node, interface);
+    }
+    dbus_message_unref(msg);
+
+    return retval;
+}
+
+bool
+glfw_dbus_call_method_with_reply(DBusConnection *conn, const char *node, const char *path, const char *interface, const char *method, int timeout, dbus_pending_callback callback, void* user_data, ...) {
+    bool retval;
+    va_list ap;
+    va_start(ap, user_data);
+    retval = call_method(conn, node, path, interface, method, timeout, callback, user_data, ap);
+    va_end(ap);
+    return retval;
+}
+
+bool
+glfw_dbus_call_method_no_reply(DBusConnection *conn, const char *node, const char *path, const char *interface, const char *method, ...) {
+    bool retval;
+    va_list ap;
+    va_start(ap, method);
+    retval = call_method(conn, node, path, interface, method, DBUS_TIMEOUT_USE_DEFAULT, NULL, NULL, ap);
+    va_end(ap);
+    return retval;
+}
+
+int
+glfw_dbus_match_signal(DBusMessage *msg, const char *interface, ...) {
+    va_list ap;
+    va_start(ap, interface);
+    int ans = -1, num = -1;
+    while(1) {
+        num++;
+        const char *name = va_arg(ap, const char*);
+        if (!name) break;
+        if (dbus_message_is_signal(msg, interface, name)) { ans = num; break; }
+    }
+    va_end(ap);
+    return ans;
+}
+
+static void
+glfw_dbus_connect_to_session_bus(void) {
+    DBusError error;
+    dbus_error_init(&error);
+    if (session_bus) {
+        dbus_connection_unref(session_bus);
+    }
+    session_bus = dbus_bus_get(DBUS_BUS_SESSION, &error);
+    if (dbus_error_is_set(&error)) {
+        report_error(&error, "Failed to connect to DBUS session bus");
+        session_bus = NULL;
+        return;
+    }
+    static const char *name = "session-bus";
+    if (!dbus_connection_set_watch_functions(session_bus, add_dbus_watch, remove_dbus_watch, toggle_dbus_watch, (void*)name, NULL)) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to set DBUS watches on connection to: %s", name);
+        dbus_connection_close(session_bus);
+        dbus_connection_unref(session_bus);
+        return;
+    }
+    if (!dbus_connection_set_timeout_functions(session_bus, add_dbus_timeout, remove_dbus_timeout, toggle_dbus_timeout, (void*)name, NULL)) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to set DBUS timeout functions on connection to: %s", name);
+        dbus_connection_close(session_bus);
+        dbus_connection_unref(session_bus);
+        return;
+    }
+
+}
+
+DBusConnection *
+glfw_dbus_session_bus() {
+    if (!session_bus) glfw_dbus_connect_to_session_bus();
+    return session_bus;
+}

glfw/dbus_glfw.h

@@ -0,0 +1,54 @@
+//========================================================================
+// GLFW 3.4 XKB - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2018 Kovid Goyal <kovid@kovidgoyal.net>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+
+#pragma once
+
+#include <dbus/dbus.h>
+#include "backend_utils.h"
+
+typedef void(*dbus_pending_callback)(DBusMessage *msg, const char* err, void* data);
+
+typedef struct {
+    EventLoopData* eld;
+} _GLFWDBUSData;
+
+
+bool glfw_dbus_init(_GLFWDBUSData *dbus, EventLoopData *eld);
+void glfw_dbus_terminate(_GLFWDBUSData *dbus);
+DBusConnection* glfw_dbus_connect_to(const char *path, const char* err_msg, const char* name, bool register_on_bus);
+void glfw_dbus_close_connection(DBusConnection *conn);
+bool
+call_method_with_msg(DBusConnection *conn, DBusMessage *msg, int timeout, dbus_pending_callback callback, void *user_data);
+bool
+glfw_dbus_call_method_no_reply(DBusConnection *conn, const char *node, const char *path, const char *interface, const char *method, ...);
+bool
+glfw_dbus_call_method_with_reply(DBusConnection *conn, const char *node, const char *path, const char *interface, const char *method, int timeout_ms, dbus_pending_callback callback, void *user_data, ...);
+void glfw_dbus_dispatch(DBusConnection *);
+void glfw_dbus_session_bus_dispatch(void);
+bool glfw_dbus_get_args(DBusMessage *msg, const char *failmsg, ...);
+int glfw_dbus_match_signal(DBusMessage *msg, const char *interface, ...);
+DBusConnection* glfw_dbus_session_bus(void);

glfw/egl_context.c

@@ -0,0 +1,807 @@
+//========================================================================
+// GLFW 3.4 EGL - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2002-2006 Marcus Geelnard
+// Copyright (c) 2006-2019 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+// Please use C89 style variable declarations in this file because VS 2010
+//========================================================================
+
+#include "internal.h"
+
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+#include <assert.h>
+
+
+// Return a description of the specified EGL error
+//
+static const char* getEGLErrorString(EGLint error)
+{
+    switch (error)
+    {
+        case EGL_SUCCESS:
+            return "Success";
+        case EGL_NOT_INITIALIZED:
+            return "EGL is not or could not be initialized";
+        case EGL_BAD_ACCESS:
+            return "EGL cannot access a requested resource";
+        case EGL_BAD_ALLOC:
+            return "EGL failed to allocate resources for the requested operation";
+        case EGL_BAD_ATTRIBUTE:
+            return "An unrecognized attribute or attribute value was passed in the attribute list";
+        case EGL_BAD_CONTEXT:
+            return "An EGLContext argument does not name a valid EGL rendering context";
+        case EGL_BAD_CONFIG:
+            return "An EGLConfig argument does not name a valid EGL frame buffer configuration";
+        case EGL_BAD_CURRENT_SURFACE:
+            return "The current surface of the calling thread is a window, pixel buffer or pixmap that is no longer valid";
+        case EGL_BAD_DISPLAY:
+            return "An EGLDisplay argument does not name a valid EGL display connection";
+        case EGL_BAD_SURFACE:
+            return "An EGLSurface argument does not name a valid surface configured for GL rendering";
+        case EGL_BAD_MATCH:
+            return "Arguments are inconsistent";
+        case EGL_BAD_PARAMETER:
+            return "One or more argument values are invalid";
+        case EGL_BAD_NATIVE_PIXMAP:
+            return "A NativePixmapType argument does not refer to a valid native pixmap";
+        case EGL_BAD_NATIVE_WINDOW:
+            return "A NativeWindowType argument does not refer to a valid native window";
+        case EGL_CONTEXT_LOST:
+            return "The application must destroy all contexts and reinitialise";
+        default:
+            return "ERROR: UNKNOWN EGL ERROR";
+    }
+}
+
+#ifdef _GLFW_X11
+// Returns the specified attribute of the specified EGLConfig
+//
+static int getEGLConfigAttrib(EGLConfig config, int attrib)
+{
+    int value;
+    eglGetConfigAttrib(_glfw.egl.display, config, attrib, &value);
+    return value;
+}
+#endif
+
+// Return the EGLConfig most closely matching the specified hints
+//
+static bool chooseEGLConfig(const _GLFWctxconfig* ctxconfig,
+                                const _GLFWfbconfig* desired,
+                                EGLConfig* result)
+{
+    EGLConfig configs[512];
+    int i = 0, nativeCount = 0, ans_idx = 0;
+    EGLint attributes[64];
+#define ATTR(k, v) { attributes[i++] = k; attributes[i++] = v; }
+    ATTR(EGL_COLOR_BUFFER_TYPE, EGL_RGB_BUFFER);
+    ATTR(EGL_SURFACE_TYPE, EGL_WINDOW_BIT);
+    if (ctxconfig->client == GLFW_OPENGL_ES_API) {
+        if (ctxconfig->major == 1) ATTR(EGL_RENDERABLE_TYPE, EGL_OPENGL_ES_BIT)
+        else ATTR(EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT);
+    }
+    else if (ctxconfig->client == GLFW_OPENGL_API) ATTR(EGL_RENDERABLE_TYPE, EGL_OPENGL_BIT);
+    if (desired->samples > 0) ATTR(EGL_SAMPLES, desired->samples);
+    if (desired->depthBits > 0) ATTR(EGL_DEPTH_SIZE, desired->depthBits);
+    if (desired->stencilBits > 0) ATTR(EGL_STENCIL_SIZE, desired->stencilBits);
+    if (desired->redBits > 0) ATTR(EGL_RED_SIZE, desired->redBits);
+    if (desired->greenBits > 0) ATTR(EGL_GREEN_SIZE, desired->greenBits);
+    if (desired->blueBits > 0) ATTR(EGL_BLUE_SIZE, desired->blueBits);
+    if (desired->alphaBits > 0) ATTR(EGL_ALPHA_SIZE, desired->alphaBits);
+    ATTR(EGL_NONE, EGL_NONE);
+#undef ATTR
+    if (!eglChooseConfig(_glfw.egl.display, attributes, configs, sizeof(configs)/sizeof(configs[0]), &nativeCount)) {
+        _glfwInputError(GLFW_API_UNAVAILABLE, "EGL: eglChooseConfig failed");
+        return false;
+    }
+
+    if (!nativeCount)
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE, "EGL: No EGLConfigs returned");
+        return false;
+    }
+
+
+    for (i = 0;  i < nativeCount;  i++)
+    {
+
+#if defined(_GLFW_X11)
+        {
+            const EGLConfig n = configs[i];
+            XVisualInfo vi = {0};
+
+            // Only consider EGLConfigs with associated Visuals
+            vi.visualid = getEGLConfigAttrib(n, EGL_NATIVE_VISUAL_ID);
+            if (!vi.visualid)
+                continue;
+
+            if (desired->transparent)
+            {
+                int count;
+                XVisualInfo* vis =
+                    XGetVisualInfo(_glfw.x11.display, VisualIDMask, &vi, &count);
+                if (vis)
+                {
+                    bool transparent = _glfwIsVisualTransparentX11(vis[0].visual);
+                    XFree(vis);
+                    if (!transparent) continue;
+                }
+            }
+        }
+#endif // _GLFW_X11
+        ans_idx = i;
+        break;
+    }
+    *result = configs[ans_idx];
+    return true;
+}
+
+static void makeContextCurrentEGL(_GLFWwindow* window)
+{
+    if (window)
+    {
+        if (!eglMakeCurrent(_glfw.egl.display,
+                            window->context.egl.surface,
+                            window->context.egl.surface,
+                            window->context.egl.handle))
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "EGL: Failed to make context current: %s",
+                            getEGLErrorString(eglGetError()));
+            return;
+        }
+    }
+    else
+    {
+        if (!eglMakeCurrent(_glfw.egl.display,
+                            EGL_NO_SURFACE,
+                            EGL_NO_SURFACE,
+                            EGL_NO_CONTEXT))
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "EGL: Failed to clear current context: %s",
+                            getEGLErrorString(eglGetError()));
+            return;
+        }
+    }
+
+    _glfwPlatformSetTls(&_glfw.contextSlot, window);
+}
+
+static void swapBuffersEGL(_GLFWwindow* window)
+{
+    if (window != _glfwPlatformGetTls(&_glfw.contextSlot))
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "EGL: The context must be current on the calling thread when swapping buffers");
+        return;
+    }
+
+    eglSwapBuffers(_glfw.egl.display, window->context.egl.surface);
+}
+
+static void swapIntervalEGL(int interval)
+{
+    eglSwapInterval(_glfw.egl.display, interval);
+}
+
+static int extensionSupportedEGL(const char* extension)
+{
+    const char* extensions = eglQueryString(_glfw.egl.display, EGL_EXTENSIONS);
+    if (extensions)
+    {
+        if (_glfwStringInExtensionString(extension, extensions))
+            return true;
+    }
+
+    return false;
+}
+
+static GLFWglproc getProcAddressEGL(const char* procname)
+{
+    _GLFWwindow* window = _glfwPlatformGetTls(&_glfw.contextSlot);
+
+    if (window->context.egl.client)
+    {
+        GLFWglproc proc = NULL;
+        glfw_dlsym(proc, window->context.egl.client, procname);
+        if (proc)
+            return proc;
+    }
+
+    return eglGetProcAddress(procname);
+}
+
+static void destroyContextEGL(_GLFWwindow* window)
+{
+#if defined(_GLFW_X11)
+    // NOTE: Do not unload libGL.so.1 while the X11 display is still open,
+    //       as it will make XCloseDisplay segfault
+    if (window->context.client != GLFW_OPENGL_API)
+#endif // _GLFW_X11
+    {
+        if (window->context.egl.client)
+        {
+            _glfw_dlclose(window->context.egl.client);
+            window->context.egl.client = NULL;
+        }
+    }
+
+    if (window->context.egl.surface)
+    {
+        eglDestroySurface(_glfw.egl.display, window->context.egl.surface);
+        window->context.egl.surface = EGL_NO_SURFACE;
+    }
+
+    if (window->context.egl.handle)
+    {
+        eglDestroyContext(_glfw.egl.display, window->context.egl.handle);
+        window->context.egl.handle = EGL_NO_CONTEXT;
+    }
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW internal API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+// Initialize EGL
+//
+bool _glfwInitEGL(void)
+{
+    int i;
+    EGLint* attribs = NULL;
+    const char* extensions;
+    const char* sonames[] =
+    {
+#if defined(_GLFW_EGL_LIBRARY)
+        _GLFW_EGL_LIBRARY,
+#elif defined(_GLFW_WIN32)
+        "libEGL.dll",
+        "EGL.dll",
+#elif defined(_GLFW_COCOA)
+        "libEGL.dylib",
+#elif defined(__CYGWIN__)
+        "libEGL-1.so",
+#else
+        "libEGL.so.1",
+#endif
+        NULL
+    };
+
+    if (_glfw.egl.handle)
+        return true;
+
+    for (i = 0;  sonames[i];  i++)
+    {
+        _glfw.egl.handle = _glfw_dlopen(sonames[i]);
+        if (_glfw.egl.handle)
+            break;
+    }
+
+    if (!_glfw.egl.handle)
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE, "EGL: Library not found");
+        return false;
+    }
+
+    _glfw.egl.prefix = (strncmp(sonames[i], "lib", 3) == 0);
+
+    glfw_dlsym(_glfw.egl.GetConfigAttrib, _glfw.egl.handle, "eglGetConfigAttrib");
+    glfw_dlsym(_glfw.egl.GetConfigs, _glfw.egl.handle, "eglGetConfigs");
+    glfw_dlsym(_glfw.egl.ChooseConfig, _glfw.egl.handle, "eglChooseConfig");
+    glfw_dlsym(_glfw.egl.GetDisplay, _glfw.egl.handle, "eglGetDisplay");
+    glfw_dlsym(_glfw.egl.GetError, _glfw.egl.handle, "eglGetError");
+    glfw_dlsym(_glfw.egl.Initialize, _glfw.egl.handle, "eglInitialize");
+    glfw_dlsym(_glfw.egl.Terminate, _glfw.egl.handle, "eglTerminate");
+    glfw_dlsym(_glfw.egl.BindAPI, _glfw.egl.handle, "eglBindAPI");
+    glfw_dlsym(_glfw.egl.CreateContext, _glfw.egl.handle, "eglCreateContext");
+    glfw_dlsym(_glfw.egl.DestroySurface, _glfw.egl.handle, "eglDestroySurface");
+    glfw_dlsym(_glfw.egl.DestroyContext, _glfw.egl.handle, "eglDestroyContext");
+    glfw_dlsym(_glfw.egl.CreateWindowSurface, _glfw.egl.handle, "eglCreateWindowSurface");
+    glfw_dlsym(_glfw.egl.MakeCurrent, _glfw.egl.handle, "eglMakeCurrent");
+    glfw_dlsym(_glfw.egl.SwapBuffers, _glfw.egl.handle, "eglSwapBuffers");
+    glfw_dlsym(_glfw.egl.SwapInterval, _glfw.egl.handle, "eglSwapInterval");
+    glfw_dlsym(_glfw.egl.QueryString, _glfw.egl.handle, "eglQueryString");
+    glfw_dlsym(_glfw.egl.GetProcAddress, _glfw.egl.handle, "eglGetProcAddress");
+
+    if (!_glfw.egl.GetConfigAttrib ||
+        !_glfw.egl.GetConfigs ||
+        !_glfw.egl.ChooseConfig ||
+        !_glfw.egl.GetDisplay ||
+        !_glfw.egl.GetError ||
+        !_glfw.egl.Initialize ||
+        !_glfw.egl.Terminate ||
+        !_glfw.egl.BindAPI ||
+        !_glfw.egl.CreateContext ||
+        !_glfw.egl.DestroySurface ||
+        !_glfw.egl.DestroyContext ||
+        !_glfw.egl.CreateWindowSurface ||
+        !_glfw.egl.MakeCurrent ||
+        !_glfw.egl.SwapBuffers ||
+        !_glfw.egl.SwapInterval ||
+        !_glfw.egl.QueryString ||
+        !_glfw.egl.GetProcAddress)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "EGL: Failed to load required entry points");
+
+        _glfwTerminateEGL();
+        return false;
+    }
+
+    extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS);
+    if (extensions && eglGetError() == EGL_SUCCESS)
+        _glfw.egl.EXT_client_extensions = true;
+
+    if (_glfw.egl.EXT_client_extensions)
+    {
+        _glfw.egl.EXT_platform_base =
+            _glfwStringInExtensionString("EGL_EXT_platform_base", extensions);
+        _glfw.egl.EXT_platform_x11 =
+            _glfwStringInExtensionString("EGL_EXT_platform_x11", extensions);
+        _glfw.egl.EXT_platform_wayland =
+            _glfwStringInExtensionString("EGL_EXT_platform_wayland", extensions);
+        _glfw.egl.ANGLE_platform_angle =
+            _glfwStringInExtensionString("EGL_ANGLE_platform_angle", extensions);
+        _glfw.egl.ANGLE_platform_angle_opengl =
+            _glfwStringInExtensionString("EGL_ANGLE_platform_angle_opengl", extensions);
+        _glfw.egl.ANGLE_platform_angle_d3d =
+            _glfwStringInExtensionString("EGL_ANGLE_platform_angle_d3d", extensions);
+        _glfw.egl.ANGLE_platform_angle_vulkan =
+            _glfwStringInExtensionString("EGL_ANGLE_platform_angle_vulkan", extensions);
+        _glfw.egl.ANGLE_platform_angle_metal =
+            _glfwStringInExtensionString("EGL_ANGLE_platform_angle_metal", extensions);
+    }
+
+    if (_glfw.egl.EXT_platform_base)
+    {
+        _glfw.egl.GetPlatformDisplayEXT = (PFNEGLGETPLATFORMDISPLAYEXTPROC)
+            eglGetProcAddress("eglGetPlatformDisplayEXT");
+        _glfw.egl.CreatePlatformWindowSurfaceEXT = (PFNEGLCREATEPLATFORMWINDOWSURFACEEXTPROC)
+            eglGetProcAddress("eglCreatePlatformWindowSurfaceEXT");
+    }
+
+    _glfw.egl.platform = _glfwPlatformGetEGLPlatform(&attribs);
+    if (_glfw.egl.platform)
+    {
+        _glfw.egl.display =
+            eglGetPlatformDisplayEXT(_glfw.egl.platform,
+                                     _glfwPlatformGetEGLNativeDisplay(),
+                                     attribs);
+    }
+    else
+        _glfw.egl.display = eglGetDisplay(_glfwPlatformGetEGLNativeDisplay());
+
+    free(attribs);
+
+    if (_glfw.egl.display == EGL_NO_DISPLAY)
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE,
+                        "EGL: Failed to get EGL display: %s",
+                        getEGLErrorString(eglGetError()));
+
+        _glfwTerminateEGL();
+        return false;
+    }
+
+    if (!eglInitialize(_glfw.egl.display, &_glfw.egl.major, &_glfw.egl.minor))
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE,
+                        "EGL: Failed to initialize EGL: %s",
+                        getEGLErrorString(eglGetError()));
+
+        _glfwTerminateEGL();
+        return false;
+    }
+
+    _glfw.egl.KHR_create_context =
+        extensionSupportedEGL("EGL_KHR_create_context");
+    _glfw.egl.KHR_create_context_no_error =
+        extensionSupportedEGL("EGL_KHR_create_context_no_error");
+    _glfw.egl.KHR_gl_colorspace =
+        extensionSupportedEGL("EGL_KHR_gl_colorspace");
+    _glfw.egl.KHR_get_all_proc_addresses =
+        extensionSupportedEGL("EGL_KHR_get_all_proc_addresses");
+    _glfw.egl.KHR_context_flush_control =
+        extensionSupportedEGL("EGL_KHR_context_flush_control");
+
+    return true;
+}
+
+// Terminate EGL
+//
+void _glfwTerminateEGL(void)
+{
+    if (_glfw.egl.display)
+    {
+        eglTerminate(_glfw.egl.display);
+        _glfw.egl.display = EGL_NO_DISPLAY;
+    }
+
+    if (_glfw.egl.handle)
+    {
+        _glfw_dlclose(_glfw.egl.handle);
+        _glfw.egl.handle = NULL;
+    }
+}
+
+#define setAttrib(a, v) \
+{ \
+    assert(((size_t) index + 1) < sizeof(attribs) / sizeof(attribs[0])); \
+    attribs[index++] = a; \
+    attribs[index++] = v; \
+}
+
+// Create the OpenGL or OpenGL ES context
+//
+bool _glfwCreateContextEGL(_GLFWwindow* window,
+                               const _GLFWctxconfig* ctxconfig,
+                               const _GLFWfbconfig* fbconfig)
+{
+    EGLint attribs[40];
+    EGLConfig config;
+    EGLContext share = NULL;
+    EGLNativeWindowType native;
+    int index = 0;
+
+    if (!_glfw.egl.display)
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE, "EGL: API not available");
+        return false;
+    }
+
+    if (ctxconfig->share)
+        share = ctxconfig->share->context.egl.handle;
+
+    if (!chooseEGLConfig(ctxconfig, fbconfig, &config))
+    {
+        _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
+                        "EGL: Failed to find a suitable EGLConfig");
+        return false;
+    }
+
+    if (ctxconfig->client == GLFW_OPENGL_ES_API)
+    {
+        if (!eglBindAPI(EGL_OPENGL_ES_API))
+        {
+            _glfwInputError(GLFW_API_UNAVAILABLE,
+                            "EGL: Failed to bind OpenGL ES: %s",
+                            getEGLErrorString(eglGetError()));
+            return false;
+        }
+    }
+    else
+    {
+        if (!eglBindAPI(EGL_OPENGL_API))
+        {
+            _glfwInputError(GLFW_API_UNAVAILABLE,
+                            "EGL: Failed to bind OpenGL: %s",
+                            getEGLErrorString(eglGetError()));
+            return false;
+        }
+    }
+
+    if (_glfw.egl.KHR_create_context)
+    {
+        int mask = 0, flags = 0;
+
+        if (ctxconfig->client == GLFW_OPENGL_API)
+        {
+            if (ctxconfig->forward)
+                flags |= EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR;
+
+            if (ctxconfig->profile == GLFW_OPENGL_CORE_PROFILE)
+                mask |= EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR;
+            else if (ctxconfig->profile == GLFW_OPENGL_COMPAT_PROFILE)
+                mask |= EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR;
+        }
+
+        if (ctxconfig->debug)
+            flags |= EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR;
+
+        if (ctxconfig->robustness)
+        {
+            if (ctxconfig->robustness == GLFW_NO_RESET_NOTIFICATION)
+            {
+                setAttrib(EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR,
+                          EGL_NO_RESET_NOTIFICATION_KHR);
+            }
+            else if (ctxconfig->robustness == GLFW_LOSE_CONTEXT_ON_RESET)
+            {
+                setAttrib(EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR,
+                          EGL_LOSE_CONTEXT_ON_RESET_KHR);
+            }
+
+            flags |= EGL_CONTEXT_OPENGL_ROBUST_ACCESS_BIT_KHR;
+        }
+
+        if (ctxconfig->noerror)
+        {
+            if (_glfw.egl.KHR_create_context_no_error)
+                setAttrib(EGL_CONTEXT_OPENGL_NO_ERROR_KHR, true);
+        }
+
+        if (ctxconfig->major != 1 || ctxconfig->minor != 0)
+        {
+            setAttrib(EGL_CONTEXT_MAJOR_VERSION_KHR, ctxconfig->major);
+            setAttrib(EGL_CONTEXT_MINOR_VERSION_KHR, ctxconfig->minor);
+        }
+
+        if (mask)
+            setAttrib(EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR, mask);
+
+        if (flags)
+            setAttrib(EGL_CONTEXT_FLAGS_KHR, flags);
+    }
+    else
+    {
+        if (ctxconfig->client == GLFW_OPENGL_ES_API)
+            setAttrib(EGL_CONTEXT_CLIENT_VERSION, ctxconfig->major);
+    }
+
+    if (_glfw.egl.KHR_context_flush_control)
+    {
+        if (ctxconfig->release == GLFW_RELEASE_BEHAVIOR_NONE)
+        {
+            setAttrib(EGL_CONTEXT_RELEASE_BEHAVIOR_KHR,
+                      EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR);
+        }
+        else if (ctxconfig->release == GLFW_RELEASE_BEHAVIOR_FLUSH)
+        {
+            setAttrib(EGL_CONTEXT_RELEASE_BEHAVIOR_KHR,
+                      EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR);
+        }
+    }
+
+    setAttrib(EGL_NONE, EGL_NONE);
+
+    window->context.egl.handle = eglCreateContext(_glfw.egl.display,
+                                                  config, share, attribs);
+
+    if (window->context.egl.handle == EGL_NO_CONTEXT)
+    {
+        _glfwInputError(GLFW_VERSION_UNAVAILABLE,
+                        "EGL: Failed to create context: %s",
+                        getEGLErrorString(eglGetError()));
+        return false;
+    }
+
+    // Set up attributes for surface creation
+    index = 0;
+
+    if (fbconfig->sRGB)
+    {
+        if (_glfw.egl.KHR_gl_colorspace)
+            setAttrib(EGL_GL_COLORSPACE_KHR, EGL_GL_COLORSPACE_SRGB_KHR);
+    }
+
+    setAttrib(EGL_NONE, EGL_NONE);
+
+    native = _glfwPlatformGetEGLNativeWindow(window);
+    // HACK: ANGLE does not implement eglCreatePlatformWindowSurfaceEXT
+    //       despite reporting EGL_EXT_platform_base
+    if (_glfw.egl.platform && _glfw.egl.platform != EGL_PLATFORM_ANGLE_ANGLE)
+    {
+        window->context.egl.surface =
+            eglCreatePlatformWindowSurfaceEXT(_glfw.egl.display, config, native, attribs);
+    }
+    else
+    {
+        window->context.egl.surface =
+            eglCreateWindowSurface(_glfw.egl.display, config, native, attribs);
+    }
+
+    if (window->context.egl.surface == EGL_NO_SURFACE)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "EGL: Failed to create window surface: %s",
+                        getEGLErrorString(eglGetError()));
+        return false;
+    }
+
+    window->context.egl.config = config;
+
+    EGLint a = EGL_MIN_SWAP_INTERVAL;
+    if (!eglGetConfigAttrib(_glfw.egl.display, config, a, &a)) {
+        _glfwInputError(GLFW_VERSION_UNAVAILABLE, "EGL: could not check for non-blocking buffer swap with error: %s", getEGLErrorString(eglGetError()));
+    } else {
+        if (a > 0) {
+            _glfwInputError(GLFW_VERSION_UNAVAILABLE, "EGL: non-blocking swap buffers not available, minimum swap interval is: %d", a);
+        }
+    }
+
+    // Load the appropriate client library
+    if (!_glfw.egl.KHR_get_all_proc_addresses)
+    {
+        int i;
+        const char** sonames;
+        const char* es1sonames[] =
+        {
+#if defined(_GLFW_GLESV1_LIBRARY)
+            _GLFW_GLESV1_LIBRARY,
+#elif defined(_GLFW_WIN32)
+            "GLESv1_CM.dll",
+            "libGLES_CM.dll",
+#elif defined(_GLFW_COCOA)
+            "libGLESv1_CM.dylib",
+#else
+            "libGLESv1_CM.so.1",
+            "libGLES_CM.so.1",
+#endif
+            NULL
+        };
+        const char* es2sonames[] =
+        {
+#if defined(_GLFW_GLESV2_LIBRARY)
+            _GLFW_GLESV2_LIBRARY,
+#elif defined(_GLFW_WIN32)
+            "GLESv2.dll",
+            "libGLESv2.dll",
+#elif defined(_GLFW_COCOA)
+            "libGLESv2.dylib",
+#elif defined(__CYGWIN__)
+            "libGLESv2-2.so",
+#else
+            "libGLESv2.so.2",
+#endif
+            NULL
+        };
+        const char* glsonames[] =
+        {
+#if defined(_GLFW_OPENGL_LIBRARY)
+            _GLFW_OPENGL_LIBRARY,
+#elif defined(_GLFW_WIN32)
+#elif defined(_GLFW_COCOA)
+#else
+            "libGL.so.1",
+#endif
+            NULL
+        };
+
+        if (ctxconfig->client == GLFW_OPENGL_ES_API)
+        {
+            if (ctxconfig->major == 1)
+                sonames = es1sonames;
+            else
+                sonames = es2sonames;
+        }
+        else
+            sonames = glsonames;
+
+        for (i = 0;  sonames[i];  i++)
+        {
+            // HACK: Match presence of lib prefix to increase chance of finding
+            //       a matching pair in the jungle that is Win32 EGL/GLES
+            if (_glfw.egl.prefix != (strncmp(sonames[i], "lib", 3) == 0))
+                continue;
+
+            window->context.egl.client = _glfw_dlopen(sonames[i]);
+            if (window->context.egl.client)
+                break;
+        }
+
+        if (!window->context.egl.client)
+        {
+            _glfwInputError(GLFW_API_UNAVAILABLE,
+                            "EGL: Failed to load client library");
+            return false;
+        }
+    }
+
+    window->context.makeCurrent = makeContextCurrentEGL;
+    window->context.swapBuffers = swapBuffersEGL;
+    window->context.swapInterval = swapIntervalEGL;
+    window->context.extensionSupported = extensionSupportedEGL;
+    window->context.getProcAddress = getProcAddressEGL;
+    window->context.destroy = destroyContextEGL;
+
+    return true;
+}
+
+#undef setAttrib
+
+// Returns the Visual and depth of the chosen EGLConfig
+//
+#if defined(_GLFW_X11)
+bool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig UNUSED,
+                              const _GLFWctxconfig* ctxconfig,
+                              const _GLFWfbconfig* fbconfig,
+                              Visual** visual, int* depth)
+{
+    XVisualInfo* result;
+    XVisualInfo desired;
+    EGLConfig native;
+    EGLint visualID = 0, count = 0;
+    const long vimask = VisualScreenMask | VisualIDMask;
+
+    if (!chooseEGLConfig(ctxconfig, fbconfig, &native))
+    {
+        _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
+                        "EGL: Failed to find a suitable EGLConfig");
+        return false;
+    }
+
+    eglGetConfigAttrib(_glfw.egl.display, native,
+                       EGL_NATIVE_VISUAL_ID, &visualID);
+
+    desired.screen = _glfw.x11.screen;
+    desired.visualid = visualID;
+
+    result = XGetVisualInfo(_glfw.x11.display, vimask, &desired, &count);
+    if (!result)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "EGL: Failed to retrieve Visual for EGLConfig");
+        return false;
+    }
+
+    *visual = result->visual;
+    *depth = result->depth;
+
+    XFree(result);
+    return true;
+}
+#endif // _GLFW_X11
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                        GLFW native API                       //////
+//////////////////////////////////////////////////////////////////////////
+
+GLFWAPI EGLDisplay glfwGetEGLDisplay(void)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(EGL_NO_DISPLAY);
+    return _glfw.egl.display;
+}
+
+GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* handle)
+{
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    _GLFW_REQUIRE_INIT_OR_RETURN(EGL_NO_CONTEXT);
+
+    if (window->context.client == GLFW_NO_API)
+    {
+        _glfwInputError(GLFW_NO_WINDOW_CONTEXT, NULL);
+        return EGL_NO_CONTEXT;
+    }
+
+    return window->context.egl.handle;
+}
+
+GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* handle)
+{
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    _GLFW_REQUIRE_INIT_OR_RETURN(EGL_NO_SURFACE);
+
+    if (window->context.client == GLFW_NO_API)
+    {
+        _glfwInputError(GLFW_NO_WINDOW_CONTEXT, NULL);
+        return EGL_NO_SURFACE;
+    }
+
+    return window->context.egl.surface;
+}

glfw/egl_context.h

@@ -0,0 +1,231 @@
+//========================================================================
+// GLFW 3.4 EGL - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2002-2006 Marcus Geelnard
+// Copyright (c) 2006-2017 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+#if defined(_GLFW_WIN32)
+ #define EGLAPIENTRY __stdcall
+#else
+ #define EGLAPIENTRY
+#endif
+
+#define EGL_SUCCESS 0x3000
+#define EGL_NOT_INITIALIZED 0x3001
+#define EGL_BAD_ACCESS 0x3002
+#define EGL_BAD_ALLOC 0x3003
+#define EGL_BAD_ATTRIBUTE 0x3004
+#define EGL_BAD_CONFIG 0x3005
+#define EGL_BAD_CONTEXT 0x3006
+#define EGL_BAD_CURRENT_SURFACE 0x3007
+#define EGL_BAD_DISPLAY 0x3008
+#define EGL_BAD_MATCH 0x3009
+#define EGL_BAD_NATIVE_PIXMAP 0x300a
+#define EGL_BAD_NATIVE_WINDOW 0x300b
+#define EGL_BAD_PARAMETER 0x300c
+#define EGL_BAD_SURFACE 0x300d
+#define EGL_CONTEXT_LOST 0x300e
+#define EGL_COLOR_BUFFER_TYPE 0x303f
+#define EGL_RGB_BUFFER 0x308e
+#define EGL_SURFACE_TYPE 0x3033
+#define EGL_WINDOW_BIT 0x0004
+#define EGL_RENDERABLE_TYPE 0x3040
+#define EGL_OPENGL_ES_BIT 0x0001
+#define EGL_OPENGL_ES2_BIT 0x0004
+#define EGL_OPENGL_BIT 0x0008
+#define EGL_ALPHA_SIZE 0x3021
+#define EGL_BLUE_SIZE 0x3022
+#define EGL_GREEN_SIZE 0x3023
+#define EGL_RED_SIZE 0x3024
+#define EGL_DEPTH_SIZE 0x3025
+#define EGL_STENCIL_SIZE 0x3026
+#define EGL_SAMPLES 0x3031
+#define EGL_OPENGL_ES_API 0x30a0
+#define EGL_OPENGL_API 0x30a2
+#define EGL_NONE 0x3038
+#define EGL_EXTENSIONS 0x3055
+#define EGL_CONTEXT_CLIENT_VERSION 0x3098
+#define EGL_NATIVE_VISUAL_ID 0x302e
+#define EGL_NO_SURFACE ((EGLSurface) 0)
+#define EGL_NO_DISPLAY ((EGLDisplay) 0)
+#define EGL_NO_CONTEXT ((EGLContext) 0)
+#define EGL_DEFAULT_DISPLAY ((EGLNativeDisplayType) 0)
+#define EGL_MIN_SWAP_INTERVAL             0x303B
+#define EGL_MAX_SWAP_INTERVAL             0x303C
+
+#define EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR 0x00000002
+#define EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR 0x00000001
+#define EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR 0x00000002
+#define EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR 0x00000001
+#define EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR 0x31bd
+#define EGL_NO_RESET_NOTIFICATION_KHR 0x31be
+#define EGL_LOSE_CONTEXT_ON_RESET_KHR 0x31bf
+#define EGL_CONTEXT_OPENGL_ROBUST_ACCESS_BIT_KHR 0x00000004
+#define EGL_CONTEXT_MAJOR_VERSION_KHR 0x3098
+#define EGL_CONTEXT_MINOR_VERSION_KHR 0x30fb
+#define EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR 0x30fd
+#define EGL_CONTEXT_FLAGS_KHR 0x30fc
+#define EGL_CONTEXT_OPENGL_NO_ERROR_KHR 0x31b3
+#define EGL_GL_COLORSPACE_KHR 0x309d
+#define EGL_GL_COLORSPACE_SRGB_KHR 0x3089
+#define EGL_CONTEXT_RELEASE_BEHAVIOR_KHR 0x2097
+#define EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR 0
+#define EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR 0x2098
+#define EGL_PLATFORM_X11_EXT 0x31d5
+#define EGL_PLATFORM_WAYLAND_EXT 0x31d8
+#define EGL_PLATFORM_ANGLE_ANGLE 0x3202
+#define EGL_PLATFORM_ANGLE_TYPE_ANGLE 0x3203
+#define EGL_PLATFORM_ANGLE_TYPE_OPENGL_ANGLE 0x320d
+#define EGL_PLATFORM_ANGLE_TYPE_OPENGLES_ANGLE 0x320e
+#define EGL_PLATFORM_ANGLE_TYPE_D3D9_ANGLE 0x3207
+#define EGL_PLATFORM_ANGLE_TYPE_D3D11_ANGLE 0x3208
+#define EGL_PLATFORM_ANGLE_TYPE_VULKAN_ANGLE 0x3450
+#define EGL_PLATFORM_ANGLE_TYPE_METAL_ANGLE 0x3489
+#define EGL_PLATFORM_ANGLE_NATIVE_PLATFORM_TYPE_ANGLE 0x348f
+
+typedef int EGLint;
+typedef unsigned int EGLBoolean;
+typedef unsigned int EGLenum;
+typedef void* EGLConfig;
+typedef void* EGLContext;
+typedef void* EGLDisplay;
+typedef void* EGLSurface;
+
+typedef void* EGLNativeDisplayType;
+typedef void* EGLNativeWindowType;
+
+// EGL function pointer typedefs
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglGetConfigAttrib)(EGLDisplay,EGLConfig,EGLint,EGLint*);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglGetConfigs)(EGLDisplay,EGLConfig*,EGLint,EGLint*);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglChooseConfig)(EGLDisplay,EGLint const*,EGLConfig*,EGLint,EGLint*);
+typedef EGLDisplay (EGLAPIENTRY * PFN_eglGetDisplay)(EGLNativeDisplayType);
+typedef EGLint (EGLAPIENTRY * PFN_eglGetError)(void);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglInitialize)(EGLDisplay,EGLint*,EGLint*);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglTerminate)(EGLDisplay);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglBindAPI)(EGLenum);
+typedef EGLContext (EGLAPIENTRY * PFN_eglCreateContext)(EGLDisplay,EGLConfig,EGLContext,const EGLint*);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglDestroySurface)(EGLDisplay,EGLSurface);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglDestroyContext)(EGLDisplay,EGLContext);
+typedef EGLSurface (EGLAPIENTRY * PFN_eglCreateWindowSurface)(EGLDisplay,EGLConfig,EGLNativeWindowType,const EGLint*);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglMakeCurrent)(EGLDisplay,EGLSurface,EGLSurface,EGLContext);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglSwapBuffers)(EGLDisplay,EGLSurface);
+typedef EGLBoolean (EGLAPIENTRY * PFN_eglSwapInterval)(EGLDisplay,EGLint);
+typedef const char* (EGLAPIENTRY * PFN_eglQueryString)(EGLDisplay,EGLint);
+typedef GLFWglproc (EGLAPIENTRY * PFN_eglGetProcAddress)(const char*);
+#define eglGetConfigAttrib _glfw.egl.GetConfigAttrib
+#define eglGetConfigs _glfw.egl.GetConfigs
+#define eglChooseConfig _glfw.egl.ChooseConfig
+#define eglGetDisplay _glfw.egl.GetDisplay
+#define eglGetError _glfw.egl.GetError
+#define eglInitialize _glfw.egl.Initialize
+#define eglTerminate _glfw.egl.Terminate
+#define eglBindAPI _glfw.egl.BindAPI
+#define eglCreateContext _glfw.egl.CreateContext
+#define eglDestroySurface _glfw.egl.DestroySurface
+#define eglDestroyContext _glfw.egl.DestroyContext
+#define eglCreateWindowSurface _glfw.egl.CreateWindowSurface
+#define eglMakeCurrent _glfw.egl.MakeCurrent
+#define eglSwapBuffers _glfw.egl.SwapBuffers
+#define eglSwapInterval _glfw.egl.SwapInterval
+#define eglQueryString _glfw.egl.QueryString
+#define eglGetProcAddress _glfw.egl.GetProcAddress
+
+typedef EGLDisplay (EGLAPIENTRY * PFNEGLGETPLATFORMDISPLAYEXTPROC)(EGLenum,void*,const EGLint*);
+typedef EGLSurface (EGLAPIENTRY * PFNEGLCREATEPLATFORMWINDOWSURFACEEXTPROC)(EGLDisplay,EGLConfig,void*,const EGLint*);
+#define eglGetPlatformDisplayEXT _glfw.egl.GetPlatformDisplayEXT
+#define eglCreatePlatformWindowSurfaceEXT _glfw.egl.CreatePlatformWindowSurfaceEXT
+
+// EGL-specific per-context data
+//
+typedef struct _GLFWcontextEGL
+{
+   EGLConfig        config;
+   EGLContext       handle;
+   EGLSurface       surface;
+
+   void*            client;
+
+} _GLFWcontextEGL;
+
+// EGL-specific global data
+//
+typedef struct _GLFWlibraryEGL
+{
+    EGLenum         platform;
+    EGLDisplay      display;
+    EGLint          major, minor;
+    bool            prefix;
+
+    bool            KHR_create_context;
+    bool            KHR_create_context_no_error;
+    bool            KHR_gl_colorspace;
+    bool            KHR_get_all_proc_addresses;
+    bool            KHR_context_flush_control;
+    bool            EXT_client_extensions;
+    bool            EXT_platform_base;
+    bool            EXT_platform_x11;
+    bool            EXT_platform_wayland;
+    bool            ANGLE_platform_angle;
+    bool            ANGLE_platform_angle_opengl;
+    bool            ANGLE_platform_angle_d3d;
+    bool            ANGLE_platform_angle_vulkan;
+    bool            ANGLE_platform_angle_metal;
+
+    void*           handle;
+
+    PFN_eglGetConfigAttrib      GetConfigAttrib;
+    PFN_eglGetConfigs           GetConfigs;
+    PFN_eglChooseConfig         ChooseConfig;
+    PFN_eglGetDisplay           GetDisplay;
+    PFN_eglGetError             GetError;
+    PFN_eglInitialize           Initialize;
+    PFN_eglTerminate            Terminate;
+    PFN_eglBindAPI              BindAPI;
+    PFN_eglCreateContext        CreateContext;
+    PFN_eglDestroySurface       DestroySurface;
+    PFN_eglDestroyContext       DestroyContext;
+    PFN_eglCreateWindowSurface  CreateWindowSurface;
+    PFN_eglMakeCurrent          MakeCurrent;
+    PFN_eglSwapBuffers          SwapBuffers;
+    PFN_eglSwapInterval         SwapInterval;
+    PFN_eglQueryString          QueryString;
+    PFN_eglGetProcAddress       GetProcAddress;
+
+    PFNEGLGETPLATFORMDISPLAYEXTPROC GetPlatformDisplayEXT;
+    PFNEGLCREATEPLATFORMWINDOWSURFACEEXTPROC CreatePlatformWindowSurfaceEXT;
+
+} _GLFWlibraryEGL;
+
+
+bool _glfwInitEGL(void);
+void _glfwTerminateEGL(void);
+bool _glfwCreateContextEGL(_GLFWwindow* window,
+                               const _GLFWctxconfig* ctxconfig,
+                               const _GLFWfbconfig* fbconfig);
+#if defined(_GLFW_X11)
+bool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig,
+                              const _GLFWctxconfig* ctxconfig,
+                              const _GLFWfbconfig* fbconfig,
+                              Visual** visual, int* depth);
+#endif /*_GLFW_X11*/

glfw/glfw.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2017, Kovid Goyal <kovid at kovidgoyal.net>
+
+import json
+import os
+import re
+import sys
+from typing import Callable, Dict, List, Optional, Tuple
+
+_plat = sys.platform.lower()
+is_linux = 'linux' in _plat
+is_openbsd = 'openbsd' in _plat
+base = os.path.dirname(os.path.abspath(__file__))
+
+
+class Env:
+
+    cc: str = ''
+    cppflags: List[str] = []
+    cflags: List[str] = []
+    ldflags: List[str] = []
+    library_paths: Dict[str, List[str]] = {}
+    ldpaths: List[str] = []
+    ccver: Tuple[int, int]
+
+    # glfw stuff
+    all_headers: List[str] = []
+    sources: List[str] = []
+    wayland_packagedir: str = ''
+    wayland_scanner: str = ''
+    wayland_scanner_code: str = ''
+    wayland_protocols: Tuple[str, ...] = ()
+
+    def __init__(
+        self, cc: str = '', cppflags: List[str] = [], cflags: List[str] = [], ldflags: List[str] = [],
+        library_paths: Dict[str, List[str]] = {}, ldpaths: Optional[List[str]] = None, ccver: Tuple[int, int] = (0, 0)
+    ):
+        self.cc, self.cppflags, self.cflags, self.ldflags, self.library_paths = cc, cppflags, cflags, ldflags, library_paths
+        self.ldpaths, self.ccver = [] if ldpaths is None else ldpaths, ccver
+
+    def copy(self) -> 'Env':
+        ans = Env(self.cc, list(self.cppflags), list(self.cflags), list(self.ldflags), dict(self.library_paths), list(self.ldpaths), self.ccver)
+        ans.all_headers = list(self.all_headers)
+        ans.sources = list(self.sources)
+        ans.wayland_packagedir = self.wayland_packagedir
+        ans.wayland_scanner = self.wayland_scanner
+        ans.wayland_scanner_code = self.wayland_scanner_code
+        ans.wayland_protocols = self.wayland_protocols
+        return ans
+
+
+def wayland_protocol_file_name(base: str, ext: str = 'c') -> str:
+    base = os.path.basename(base).rpartition('.')[0]
+    return 'wayland-{}-client-protocol.{}'.format(base, ext)
+
+
+def init_env(env: Env, pkg_config: Callable, at_least_version: Callable, test_compile: Callable, module: str = 'x11') -> Env:
+    ans = env.copy()
+    ans.cflags.append('-fPIC')
+    ans.cppflags.append('-D_GLFW_' + module.upper())
+    ans.cppflags.append('-D_GLFW_BUILD_DLL')
+
+    with open(os.path.join(base, 'source-info.json')) as f:
+        sinfo = json.load(f)
+    module_sources = list(sinfo[module]['sources'])
+    if module in ('x11', 'wayland'):
+        remove = 'null_joystick.c' if is_linux else 'linux_joystick.c'
+        module_sources.remove(remove)
+
+    ans.sources = sinfo['common']['sources'] + module_sources
+    ans.all_headers = [x for x in os.listdir(base) if x.endswith('.h')]
+
+    if module in ('x11', 'wayland'):
+        ans.cflags.append('-pthread')
+        ans.ldpaths.extend('-pthread -lm'.split())
+        if not is_openbsd:
+            ans.ldpaths.extend('-lrt -ldl'.split())
+        at_least_version('xkbcommon', 0, 5)
+
+    if module == 'x11':
+        for dep in 'x11 xrandr xinerama xcursor xkbcommon xkbcommon-x11 x11-xcb dbus-1'.split():
+            ans.cflags.extend(pkg_config(dep, '--cflags-only-I'))
+            ans.ldpaths.extend(pkg_config(dep, '--libs'))
+
+    elif module == 'cocoa':
+        ans.cppflags.append('-DGL_SILENCE_DEPRECATION')
+        for f_ in 'Cocoa IOKit CoreFoundation CoreVideo'.split():
+            ans.ldpaths.extend(('-framework', f_))
+
+    elif module == 'wayland':
+        at_least_version('wayland-protocols', *sinfo['wayland_protocols'])
+        ans.wayland_packagedir = os.path.abspath(pkg_config('wayland-protocols', '--variable=pkgdatadir')[0])
+        ans.wayland_scanner = os.path.abspath(pkg_config('wayland-scanner', '--variable=wayland_scanner')[0])
+        scanner_version = tuple(map(int, pkg_config('wayland-scanner', '--modversion')[0].strip().split('.')))
+        ans.wayland_scanner_code = 'private-code' if scanner_version >= (1, 14, 91) else 'code'
+        ans.wayland_protocols = tuple(sinfo[module]['protocols'])
+        for p in ans.wayland_protocols:
+            ans.sources.append(wayland_protocol_file_name(p))
+            ans.all_headers.append(wayland_protocol_file_name(p, 'h'))
+        for dep in 'wayland-client wayland-cursor xkbcommon dbus-1'.split():
+            ans.cflags.extend(pkg_config(dep, '--cflags-only-I'))
+            ans.ldpaths.extend(pkg_config(dep, '--libs'))
+        has_memfd_create = test_compile(env.cc, '-Werror', src='''#define _GNU_SOURCE
+    #include <unistd.h>
+    #include <sys/syscall.h>
+    int main(void) {
+        return syscall(__NR_memfd_create, "test", 0);
+    }''')
+        if has_memfd_create:
+            ans.cppflags.append('-DHAS_MEMFD_CREATE')
+
+    return ans
+
+
+def build_wayland_protocols(env: Env, Command: Callable, parallel_run: Callable, emphasis: Callable, newer: Callable, dest_dir: str) -> None:
+    items = []
+    for protocol in env.wayland_protocols:
+        src = os.path.join(env.wayland_packagedir, protocol)
+        if not os.path.exists(src):
+            raise SystemExit('The wayland-protocols package on your system is missing the {} protocol definition file'.format(protocol))
+        for ext in 'hc':
+            dest = wayland_protocol_file_name(src, ext)
+            dest = os.path.join(dest_dir, dest)
+            if newer(dest, src):
+                q = 'client-header' if ext == 'h' else env.wayland_scanner_code
+                items.append(Command(
+                    'Generating {} ...'.format(emphasis(os.path.basename(dest))),
+                    [env.wayland_scanner, q, src, dest],
+                    lambda: True, None, None, None))
+    if items:
+        parallel_run(items)
+
+
+class Arg:
+
+    def __init__(self, decl: str):
+        self.type, self.name = decl.rsplit(' ', 1)
+        self.type = self.type.strip()
+        self.name = self.name.strip()
+        while self.name.startswith('*'):
+            self.name = self.name[1:]
+            self.type = self.type + '*'
+
+    def __repr__(self) -> str:
+        return 'Arg({}, {})'.format(self.type, self.name)
+
+
+class Function:
+
+    def __init__(self, declaration: str, check_fail: bool = True):
+        self.check_fail = check_fail
+        m = re.match(
+            r'(.+?)\s+(glfw[A-Z][a-zA-Z0-9]+)[(](.+)[)]$', declaration
+        )
+        if m is None:
+            raise SystemExit('Failed to parse ' + repr(declaration))
+        self.restype = m.group(1).strip()
+        self.name = m.group(2)
+        args = m.group(3).strip().split(',')
+        args = [x.strip() for x in args]
+        self.args = []
+        for a in args:
+            if a == 'void':
+                continue
+            self.args.append(Arg(a))
+        if not self.args:
+            self.args = [Arg('void v')]
+
+    def declaration(self) -> str:
+        return 'typedef {restype} (*{name}_func)({args});\nGFW_EXTERN {name}_func {name}_impl;\n#define {name} {name}_impl'.format(
+            restype=self.restype,
+            name=self.name,
+            args=', '.join(a.type for a in self.args)
+        )
+
+    def load(self) -> str:
+        ans = '*(void **) (&{name}_impl) = dlsym(handle, "{name}");'.format(
+            name=self.name
+        )
+        if self.check_fail:
+            ans += '\n    if ({name}_impl == NULL) fail("Failed to load glfw function {name} with error: %s", dlerror());'.format(
+                name=self.name
+            )
+        return ans
+
+
+def generate_wrappers(glfw_header: str) -> None:
+    with open(glfw_header) as f:
+        src = f.read()
+    functions = []
+    first = None
+    for m in re.finditer(r'^GLFWAPI\s+(.+[)]);\s*$', src, flags=re.MULTILINE):
+        if first is None:
+            first = m.start()
+        decl = m.group(1)
+        if 'VkInstance' in decl:
+            continue
+        functions.append(Function(decl))
+    for line in '''\
+    void* glfwGetCocoaWindow(GLFWwindow* window)
+    void* glfwGetNSGLContext(GLFWwindow *window)
+    uint32_t glfwGetCocoaMonitor(GLFWmonitor* monitor)
+    GLFWcocoatextinputfilterfun glfwSetCocoaTextInputFilter(GLFWwindow* window, GLFWcocoatextinputfilterfun callback)
+    GLFWcocoatogglefullscreenfun glfwSetCocoaToggleFullscreenIntercept(GLFWwindow *window, GLFWcocoatogglefullscreenfun callback)
+    GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback)
+    GLFWapplicationwillfinishlaunchingfun glfwSetApplicationWillFinishLaunching(GLFWapplicationwillfinishlaunchingfun callback)
+    void glfwGetCocoaKeyEquivalent(int glfw_key, int glfw_mods, char* cocoa_key, size_t key_sz, int* cocoa_mods)
+    void glfwCocoaRequestRenderFrame(GLFWwindow *w, GLFWcocoarenderframefun callback)
+    void* glfwGetX11Display(void)
+    int32_t glfwGetX11Window(GLFWwindow* window)
+    void glfwSetPrimarySelectionString(GLFWwindow* window, const char* string)
+    const char* glfwGetPrimarySelectionString(GLFWwindow* window, void)
+    int glfwGetNativeKeyForName(const char* key_name, int case_sensitive)
+    void glfwRequestWaylandFrameEvent(GLFWwindow *handle, unsigned long long id, GLFWwaylandframecallbackfunc callback)
+    unsigned long long glfwDBusUserNotify(const char *app_name, const char* icon, const char *summary, const char *body, \
+const char *action_text, int32_t timeout, GLFWDBusnotificationcreatedfun callback, void *data)
+    void glfwDBusSetUserNotificationHandler(GLFWDBusnotificationactivatedfun handler)
+'''.splitlines():
+        if line:
+            functions.append(Function(line.strip(), check_fail=False))
+
+    declarations = [f.declaration() for f in functions]
+    p = src.find(' * GLFW API tokens')
+    p = src.find('*/', p)
+    preamble = src[p + 2:first]
+    header = '''\
+//
+// THIS FILE IS GENERATED BY glfw.py
+//
+// SAVE YOURSELF SOME TIME, DO NOT MANUALLY EDIT
+//
+
+#pragma once
+#include <stddef.h>
+#include <stdint.h>
+#include "monotonic.h"
+
+#ifndef GFW_EXTERN
+#define GFW_EXTERN extern
+#endif
+{}
+
+typedef int (* GLFWcocoatextinputfilterfun)(int,int,unsigned int,unsigned long);
+typedef bool (* GLFWapplicationshouldhandlereopenfun)(int);
+typedef void (* GLFWapplicationwillfinishlaunchingfun)(void);
+typedef bool (* GLFWcocoatogglefullscreenfun)(GLFWwindow*);
+typedef void (* GLFWcocoarenderframefun)(GLFWwindow*);
+typedef void (*GLFWwaylandframecallbackfunc)(unsigned long long id);
+typedef void (*GLFWDBusnotificationcreatedfun)(unsigned long long, uint32_t, void*);
+typedef void (*GLFWDBusnotificationactivatedfun)(uint32_t, const char*);
+{}
+
+const char* load_glfw(const char* path);
+'''.format(preamble, '\n\n'.join(declarations))
+    with open('../kitty/glfw-wrapper.h', 'w') as f:
+        f.write(header)
+
+    code = '''
+#define GFW_EXTERN
+#include "data-types.h"
+#include "glfw-wrapper.h"
+#include <dlfcn.h>
+
+static void* handle = NULL;
+
+#define fail(msg, ...) { snprintf(buf, sizeof(buf), msg, __VA_ARGS__); return buf; }
+
+const char*
+load_glfw(const char* path) {
+    static char buf[2048];
+    handle = dlopen(path, RTLD_LAZY);
+    if (handle == NULL) fail("Failed to dlopen %s with error: %s", path, dlerror());
+    dlerror();
+
+    LOAD
+
+    return NULL;
+}
+
+void
+unload_glfw(void) {
+    if (handle) { dlclose(handle); handle = NULL; }
+}
+'''.replace('LOAD', '\n\n    '.join(f.load() for f in functions))
+    with open('../kitty/glfw-wrapper.c', 'w') as f:
+        f.write(code)
+
+
+def main() -> None:
+    os.chdir(os.path.dirname(os.path.abspath(__file__)))
+    generate_wrappers('glfw3.h')
+
+
+if __name__ == '__main__':
+    main()

glfw/glx_context.c

@@ -0,0 +1,674 @@
+//========================================================================
+// GLFW 3.4 GLX - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2002-2006 Marcus Geelnard
+// Copyright (c) 2006-2019 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+// It is fine to use C99 in this file because it will not be built with VS
+//========================================================================
+
+#include "internal.h"
+
+#include <string.h>
+#include <stdlib.h>
+#include <assert.h>
+
+#ifndef GLXBadProfileARB
+ #define GLXBadProfileARB 13
+#endif
+
+
+// Returns the specified attribute of the specified GLXFBConfig
+//
+static int getGLXFBConfigAttrib(GLXFBConfig fbconfig, int attrib)
+{
+    int value;
+    glXGetFBConfigAttrib(_glfw.x11.display, fbconfig, attrib, &value);
+    return value;
+}
+
+static GLXFBConfig*
+choose_fb_config(const _GLFWfbconfig* desired, bool trust_window_bit, int *nelements) {
+    int attrib_list[64];
+    int pos = 0;
+#define ATTR(x, y) { attrib_list[pos++] = x; attrib_list[pos++] = y; }
+
+    ATTR(GLX_DOUBLEBUFFER, desired->doublebuffer ? True : False);
+    if (desired->stereo > 0) ATTR(GLX_STEREO, desired->stereo ? True : False);
+    if (desired->auxBuffers > 0) ATTR(GLX_AUX_BUFFERS, desired->auxBuffers);
+    if (_glfw.glx.ARB_multisample && desired->samples > 0) ATTR(GLX_SAMPLES, desired->samples);
+    if (desired->depthBits != GLFW_DONT_CARE) ATTR(GLX_DEPTH_SIZE, desired->depthBits);
+    if (desired->stencilBits != GLFW_DONT_CARE) ATTR(GLX_STENCIL_SIZE, desired->stencilBits);
+    if (desired->redBits != GLFW_DONT_CARE) ATTR(GLX_RED_SIZE, desired->redBits);
+    if (desired->greenBits != GLFW_DONT_CARE) ATTR(GLX_GREEN_SIZE, desired->greenBits);
+    if (desired->blueBits != GLFW_DONT_CARE) ATTR(GLX_BLUE_SIZE, desired->blueBits);
+    if (desired->alphaBits != GLFW_DONT_CARE) ATTR(GLX_ALPHA_SIZE, desired->alphaBits);
+    if (desired->accumRedBits != GLFW_DONT_CARE) ATTR(GLX_ACCUM_RED_SIZE, desired->accumRedBits);
+    if (desired->accumGreenBits != GLFW_DONT_CARE) ATTR(GLX_ACCUM_GREEN_SIZE, desired->accumGreenBits);
+    if (desired->accumBlueBits != GLFW_DONT_CARE) ATTR(GLX_ACCUM_BLUE_SIZE, desired->accumBlueBits);
+    if (desired->accumAlphaBits != GLFW_DONT_CARE) ATTR(GLX_ACCUM_ALPHA_SIZE, desired->accumAlphaBits);
+    if (!trust_window_bit) ATTR(GLX_DRAWABLE_TYPE, 0);
+    ATTR(None, None);
+    return glXChooseFBConfig(_glfw.x11.display, _glfw.x11.screen, attrib_list, nelements);
+#undef ATTR
+}
+
+
+// Return the GLXFBConfig most closely matching the specified hints
+//
+static bool chooseGLXFBConfig(const _GLFWfbconfig* desired,
+                                  GLXFBConfig* result)
+{
+    GLXFBConfig* nativeConfigs;
+    int i, nativeCount, ans_idx = 0;
+    const char* vendor;
+    bool trustWindowBit = true;
+    static _GLFWfbconfig prev_desired  = {0};
+    static GLXFBConfig prev_result = 0;
+    if (prev_result != 0 && memcmp(&prev_desired, desired, sizeof(_GLFWfbconfig)) == 0) {
+        *result = prev_result;
+        return true;
+    }
+    prev_desired = *desired;
+
+    // HACK: This is a (hopefully temporary) workaround for Chromium
+    //       (VirtualBox GL) not setting the window bit on any GLXFBConfigs
+    vendor = glXGetClientString(_glfw.x11.display, GLX_VENDOR);
+    if (vendor && strcmp(vendor, "Chromium") == 0)
+        trustWindowBit = false;
+    nativeConfigs = choose_fb_config(desired, trustWindowBit, &nativeCount);
+    if (!nativeConfigs || !nativeCount)
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: No GLXFBConfigs returned");
+        return false;
+    }
+    for (i = 0;  i < nativeCount;  i++)
+    {
+        const GLXFBConfig n = nativeConfigs[i];
+        bool transparency_matches = true, srgb_matches = true;
+        if (desired->transparent) {
+            transparency_matches = false;
+            XVisualInfo* vi = glXGetVisualFromFBConfig(_glfw.x11.display, n);
+            if (vi && _glfwIsVisualTransparentX11(vi->visual)) transparency_matches = true;
+        }
+
+        if (desired->sRGB && (_glfw.glx.ARB_framebuffer_sRGB || _glfw.glx.EXT_framebuffer_sRGB)) {
+            srgb_matches = getGLXFBConfigAttrib(n, GLX_FRAMEBUFFER_SRGB_CAPABLE_ARB) ? true : false;
+        }
+
+        if (transparency_matches && srgb_matches) {
+            ans_idx = i; break;
+        }
+
+    }
+
+    *result = nativeConfigs[ans_idx];
+    prev_result = nativeConfigs[ans_idx];
+
+    XFree(nativeConfigs);
+
+    return true;
+}
+
+// Create the OpenGL context using legacy API
+//
+static GLXContext createLegacyContextGLX(_GLFWwindow* window UNUSED,
+                                         GLXFBConfig fbconfig,
+                                         GLXContext share)
+{
+    return glXCreateNewContext(_glfw.x11.display,
+                               fbconfig,
+                               GLX_RGBA_TYPE,
+                               share,
+                               True);
+}
+
+static void makeContextCurrentGLX(_GLFWwindow* window)
+{
+    if (window)
+    {
+        if (!glXMakeCurrent(_glfw.x11.display,
+                            window->context.glx.window,
+                            window->context.glx.handle))
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "GLX: Failed to make context current");
+            return;
+        }
+    }
+    else
+    {
+        if (!glXMakeCurrent(_glfw.x11.display, None, NULL))
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "GLX: Failed to clear current context");
+            return;
+        }
+    }
+
+    _glfwPlatformSetTls(&_glfw.contextSlot, window);
+}
+
+static void swapBuffersGLX(_GLFWwindow* window)
+{
+    glXSwapBuffers(_glfw.x11.display, window->context.glx.window);
+}
+
+static void swapIntervalGLX(int interval)
+{
+    _GLFWwindow* window = _glfwPlatformGetTls(&_glfw.contextSlot);
+
+    if (_glfw.glx.EXT_swap_control)
+    {
+        _glfw.glx.SwapIntervalEXT(_glfw.x11.display,
+                                  window->context.glx.window,
+                                  interval);
+    }
+    else if (_glfw.glx.MESA_swap_control)
+        _glfw.glx.SwapIntervalMESA(interval);
+    else if (_glfw.glx.SGI_swap_control)
+    {
+        if (interval > 0)
+            _glfw.glx.SwapIntervalSGI(interval);
+    }
+}
+
+static int extensionSupportedGLX(const char* extension)
+{
+    const char* extensions =
+        glXQueryExtensionsString(_glfw.x11.display, _glfw.x11.screen);
+    if (extensions)
+    {
+        if (_glfwStringInExtensionString(extension, extensions))
+            return true;
+    }
+
+    return false;
+}
+
+static GLFWglproc getProcAddressGLX(const char* procname)
+{
+    if (_glfw.glx.GetProcAddress)
+        return _glfw.glx.GetProcAddress((const GLubyte*) procname);
+    else if (_glfw.glx.GetProcAddressARB)
+        return _glfw.glx.GetProcAddressARB((const GLubyte*) procname);
+    else {
+        GLFWglproc ans = NULL;
+        glfw_dlsym(ans, _glfw.glx.handle, procname);
+        return ans;
+    }
+}
+
+static void destroyContextGLX(_GLFWwindow* window)
+{
+    if (window->context.glx.window)
+    {
+        glXDestroyWindow(_glfw.x11.display, window->context.glx.window);
+        window->context.glx.window = None;
+    }
+
+    if (window->context.glx.handle)
+    {
+        glXDestroyContext(_glfw.x11.display, window->context.glx.handle);
+        window->context.glx.handle = NULL;
+    }
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW internal API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+// Initialize GLX
+//
+bool _glfwInitGLX(void)
+{
+    int i;
+    const char* sonames[] =
+    {
+#if defined(_GLFW_GLX_LIBRARY)
+        _GLFW_GLX_LIBRARY,
+#elif defined(__CYGWIN__)
+        "libGL-1.so",
+#else
+        "libGL.so.1",
+        "libGL.so",
+#endif
+        NULL
+    };
+
+    if (_glfw.glx.handle)
+        return true;
+
+    for (i = 0;  sonames[i];  i++)
+    {
+        _glfw.glx.handle = _glfw_dlopen(sonames[i]);
+        if (_glfw.glx.handle)
+            break;
+    }
+
+    if (!_glfw.glx.handle)
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: Failed to load GLX");
+        return false;
+    }
+
+    glfw_dlsym(_glfw.glx.GetFBConfigs, _glfw.glx.handle, "glXGetFBConfigs");
+    glfw_dlsym(_glfw.glx.GetFBConfigAttrib, _glfw.glx.handle, "glXGetFBConfigAttrib");
+    glfw_dlsym(_glfw.glx.ChooseFBConfig, _glfw.glx.handle, "glXChooseFBConfig");
+    glfw_dlsym(_glfw.glx.GetClientString, _glfw.glx.handle, "glXGetClientString");
+    glfw_dlsym(_glfw.glx.QueryExtension, _glfw.glx.handle, "glXQueryExtension");
+    glfw_dlsym(_glfw.glx.QueryVersion, _glfw.glx.handle, "glXQueryVersion");
+    glfw_dlsym(_glfw.glx.DestroyContext, _glfw.glx.handle, "glXDestroyContext");
+    glfw_dlsym(_glfw.glx.MakeCurrent, _glfw.glx.handle, "glXMakeCurrent");
+    glfw_dlsym(_glfw.glx.SwapBuffers, _glfw.glx.handle, "glXSwapBuffers");
+    glfw_dlsym(_glfw.glx.QueryExtensionsString, _glfw.glx.handle, "glXQueryExtensionsString");
+    glfw_dlsym(_glfw.glx.CreateNewContext, _glfw.glx.handle, "glXCreateNewContext");
+    glfw_dlsym(_glfw.glx.CreateWindow, _glfw.glx.handle, "glXCreateWindow");
+    glfw_dlsym(_glfw.glx.DestroyWindow, _glfw.glx.handle, "glXDestroyWindow");
+    glfw_dlsym(_glfw.glx.GetProcAddress, _glfw.glx.handle, "glXGetProcAddress");
+    glfw_dlsym(_glfw.glx.GetProcAddressARB, _glfw.glx.handle, "glXGetProcAddressARB");
+    glfw_dlsym(_glfw.glx.GetVisualFromFBConfig, _glfw.glx.handle, "glXGetVisualFromFBConfig");
+
+    if (!_glfw.glx.GetFBConfigs ||
+        !_glfw.glx.GetFBConfigAttrib ||
+        !_glfw.glx.GetClientString ||
+        !_glfw.glx.QueryExtension ||
+        !_glfw.glx.QueryVersion ||
+        !_glfw.glx.DestroyContext ||
+        !_glfw.glx.MakeCurrent ||
+        !_glfw.glx.SwapBuffers ||
+        !_glfw.glx.QueryExtensionsString ||
+        !_glfw.glx.CreateNewContext ||
+        !_glfw.glx.CreateWindow ||
+        !_glfw.glx.DestroyWindow ||
+        !_glfw.glx.GetProcAddress ||
+        !_glfw.glx.GetProcAddressARB ||
+        !_glfw.glx.GetVisualFromFBConfig)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "GLX: Failed to load required entry points");
+        return false;
+    }
+
+    if (!glXQueryExtension(_glfw.x11.display,
+                           &_glfw.glx.errorBase,
+                           &_glfw.glx.eventBase))
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: GLX extension not found");
+        return false;
+    }
+
+    if (!glXQueryVersion(_glfw.x11.display, &_glfw.glx.major, &_glfw.glx.minor))
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE,
+                        "GLX: Failed to query GLX version");
+        return false;
+    }
+
+    if (_glfw.glx.major == 1 && _glfw.glx.minor < 3)
+    {
+        _glfwInputError(GLFW_API_UNAVAILABLE,
+                        "GLX: GLX version 1.3 is required");
+        return false;
+    }
+
+    if (extensionSupportedGLX("GLX_EXT_swap_control"))
+    {
+        _glfw.glx.SwapIntervalEXT = (PFNGLXSWAPINTERVALEXTPROC)
+            getProcAddressGLX("glXSwapIntervalEXT");
+
+        if (_glfw.glx.SwapIntervalEXT)
+            _glfw.glx.EXT_swap_control = true;
+    }
+
+    if (extensionSupportedGLX("GLX_SGI_swap_control"))
+    {
+        _glfw.glx.SwapIntervalSGI = (PFNGLXSWAPINTERVALSGIPROC)
+            getProcAddressGLX("glXSwapIntervalSGI");
+
+        if (_glfw.glx.SwapIntervalSGI)
+            _glfw.glx.SGI_swap_control = true;
+    }
+
+    if (extensionSupportedGLX("GLX_MESA_swap_control"))
+    {
+        _glfw.glx.SwapIntervalMESA = (PFNGLXSWAPINTERVALMESAPROC)
+            getProcAddressGLX("glXSwapIntervalMESA");
+
+        if (_glfw.glx.SwapIntervalMESA)
+            _glfw.glx.MESA_swap_control = true;
+    }
+
+    if (extensionSupportedGLX("GLX_ARB_multisample"))
+        _glfw.glx.ARB_multisample = true;
+
+    if (extensionSupportedGLX("GLX_ARB_framebuffer_sRGB"))
+        _glfw.glx.ARB_framebuffer_sRGB = true;
+
+    if (extensionSupportedGLX("GLX_EXT_framebuffer_sRGB"))
+        _glfw.glx.EXT_framebuffer_sRGB = true;
+
+    if (extensionSupportedGLX("GLX_ARB_create_context"))
+    {
+        _glfw.glx.CreateContextAttribsARB = (PFNGLXCREATECONTEXTATTRIBSARBPROC)
+            getProcAddressGLX("glXCreateContextAttribsARB");
+
+        if (_glfw.glx.CreateContextAttribsARB)
+            _glfw.glx.ARB_create_context = true;
+    }
+
+    if (extensionSupportedGLX("GLX_ARB_create_context_robustness"))
+        _glfw.glx.ARB_create_context_robustness = true;
+
+    if (extensionSupportedGLX("GLX_ARB_create_context_profile"))
+        _glfw.glx.ARB_create_context_profile = true;
+
+    if (extensionSupportedGLX("GLX_EXT_create_context_es2_profile"))
+        _glfw.glx.EXT_create_context_es2_profile = true;
+
+    if (extensionSupportedGLX("GLX_ARB_create_context_no_error"))
+        _glfw.glx.ARB_create_context_no_error = true;
+
+    if (extensionSupportedGLX("GLX_ARB_context_flush_control"))
+        _glfw.glx.ARB_context_flush_control = true;
+
+    return true;
+}
+
+// Terminate GLX
+//
+void _glfwTerminateGLX(void)
+{
+    // NOTE: This function must not call any X11 functions, as it is called
+    //       after XCloseDisplay (see _glfwPlatformTerminate for details)
+
+    if (_glfw.glx.handle)
+    {
+        _glfw_dlclose(_glfw.glx.handle);
+        _glfw.glx.handle = NULL;
+    }
+}
+
+#define setAttrib(a, v) \
+{ \
+    assert(((size_t) index + 1) < sizeof(attribs) / sizeof(attribs[0])); \
+    attribs[index++] = a; \
+    attribs[index++] = v; \
+}
+
+// Create the OpenGL or OpenGL ES context
+//
+bool _glfwCreateContextGLX(_GLFWwindow* window,
+                               const _GLFWctxconfig* ctxconfig,
+                               const _GLFWfbconfig* fbconfig)
+{
+    int attribs[40];
+    GLXFBConfig native = NULL;
+    GLXContext share = NULL;
+
+    if (ctxconfig->share)
+        share = ctxconfig->share->context.glx.handle;
+
+    if (!chooseGLXFBConfig(fbconfig, &native))
+    {
+        _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
+                        "GLX: Failed to find a suitable GLXFBConfig");
+        return false;
+    }
+
+    if (ctxconfig->client == GLFW_OPENGL_ES_API)
+    {
+        if (!_glfw.glx.ARB_create_context ||
+            !_glfw.glx.ARB_create_context_profile ||
+            !_glfw.glx.EXT_create_context_es2_profile)
+        {
+            _glfwInputError(GLFW_API_UNAVAILABLE,
+                            "GLX: OpenGL ES requested but GLX_EXT_create_context_es2_profile is unavailable");
+            return false;
+        }
+    }
+
+    if (ctxconfig->forward)
+    {
+        if (!_glfw.glx.ARB_create_context)
+        {
+            _glfwInputError(GLFW_VERSION_UNAVAILABLE,
+                            "GLX: Forward compatibility requested but GLX_ARB_create_context_profile is unavailable");
+            return false;
+        }
+    }
+
+    if (ctxconfig->profile)
+    {
+        if (!_glfw.glx.ARB_create_context ||
+            !_glfw.glx.ARB_create_context_profile)
+        {
+            _glfwInputError(GLFW_VERSION_UNAVAILABLE,
+                            "GLX: An OpenGL profile requested but GLX_ARB_create_context_profile is unavailable");
+            return false;
+        }
+    }
+
+    _glfwGrabErrorHandlerX11();
+
+    if (_glfw.glx.ARB_create_context)
+    {
+        int index = 0, mask = 0, flags = 0;
+
+        if (ctxconfig->client == GLFW_OPENGL_API)
+        {
+            if (ctxconfig->forward)
+                flags |= GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB;
+
+            if (ctxconfig->profile == GLFW_OPENGL_CORE_PROFILE)
+                mask |= GLX_CONTEXT_CORE_PROFILE_BIT_ARB;
+            else if (ctxconfig->profile == GLFW_OPENGL_COMPAT_PROFILE)
+                mask |= GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB;
+        }
+        else
+            mask |= GLX_CONTEXT_ES2_PROFILE_BIT_EXT;
+
+        if (ctxconfig->debug)
+            flags |= GLX_CONTEXT_DEBUG_BIT_ARB;
+
+        if (ctxconfig->robustness)
+        {
+            if (_glfw.glx.ARB_create_context_robustness)
+            {
+                if (ctxconfig->robustness == GLFW_NO_RESET_NOTIFICATION)
+                {
+                    setAttrib(GLX_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB,
+                              GLX_NO_RESET_NOTIFICATION_ARB);
+                }
+                else if (ctxconfig->robustness == GLFW_LOSE_CONTEXT_ON_RESET)
+                {
+                    setAttrib(GLX_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB,
+                              GLX_LOSE_CONTEXT_ON_RESET_ARB);
+                }
+
+                flags |= GLX_CONTEXT_ROBUST_ACCESS_BIT_ARB;
+            }
+        }
+
+        if (ctxconfig->release)
+        {
+            if (_glfw.glx.ARB_context_flush_control)
+            {
+                if (ctxconfig->release == GLFW_RELEASE_BEHAVIOR_NONE)
+                {
+                    setAttrib(GLX_CONTEXT_RELEASE_BEHAVIOR_ARB,
+                              GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB);
+                }
+                else if (ctxconfig->release == GLFW_RELEASE_BEHAVIOR_FLUSH)
+                {
+                    setAttrib(GLX_CONTEXT_RELEASE_BEHAVIOR_ARB,
+                              GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB);
+                }
+            }
+        }
+
+        if (ctxconfig->noerror)
+        {
+            if (_glfw.glx.ARB_create_context_no_error)
+                setAttrib(GLX_CONTEXT_OPENGL_NO_ERROR_ARB, true);
+        }
+
+        // NOTE: Only request an explicitly versioned context when necessary, as
+        //       explicitly requesting version 1.0 does not always return the
+        //       highest version supported by the driver
+        if (ctxconfig->major != 1 || ctxconfig->minor != 0)
+        {
+            setAttrib(GLX_CONTEXT_MAJOR_VERSION_ARB, ctxconfig->major);
+            setAttrib(GLX_CONTEXT_MINOR_VERSION_ARB, ctxconfig->minor);
+        }
+
+        if (mask)
+            setAttrib(GLX_CONTEXT_PROFILE_MASK_ARB, mask);
+
+        if (flags)
+            setAttrib(GLX_CONTEXT_FLAGS_ARB, flags);
+
+        setAttrib(None, None);
+
+        window->context.glx.handle =
+            _glfw.glx.CreateContextAttribsARB(_glfw.x11.display,
+                                              native,
+                                              share,
+                                              True,
+                                              attribs);
+
+        // HACK: This is a fallback for broken versions of the Mesa
+        //       implementation of GLX_ARB_create_context_profile that fail
+        //       default 1.0 context creation with a GLXBadProfileARB error in
+        //       violation of the extension spec
+        if (!window->context.glx.handle)
+        {
+            if (_glfw.x11.errorCode == _glfw.glx.errorBase + GLXBadProfileARB &&
+                ctxconfig->client == GLFW_OPENGL_API &&
+                ctxconfig->profile == GLFW_OPENGL_ANY_PROFILE &&
+                ctxconfig->forward == false)
+            {
+                window->context.glx.handle =
+                    createLegacyContextGLX(window, native, share);
+            }
+        }
+    }
+    else
+    {
+        window->context.glx.handle =
+            createLegacyContextGLX(window, native, share);
+    }
+
+    _glfwReleaseErrorHandlerX11();
+
+    if (!window->context.glx.handle)
+    {
+        _glfwInputErrorX11(GLFW_VERSION_UNAVAILABLE, "GLX: Failed to create context");
+        return false;
+    }
+
+    window->context.glx.window =
+        glXCreateWindow(_glfw.x11.display, native, window->x11.handle, NULL);
+    if (!window->context.glx.window)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "GLX: Failed to create window");
+        return false;
+    }
+
+    window->context.makeCurrent = makeContextCurrentGLX;
+    window->context.swapBuffers = swapBuffersGLX;
+    window->context.swapInterval = swapIntervalGLX;
+    window->context.extensionSupported = extensionSupportedGLX;
+    window->context.getProcAddress = getProcAddressGLX;
+    window->context.destroy = destroyContextGLX;
+
+    return true;
+}
+
+#undef setAttrib
+
+// Returns the Visual and depth of the chosen GLXFBConfig
+//
+bool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig UNUSED,
+                              const _GLFWctxconfig* ctxconfig UNUSED,
+                              const _GLFWfbconfig* fbconfig,
+                              Visual** visual, int* depth)
+{
+    GLXFBConfig native;
+    XVisualInfo* result;
+
+    if (!chooseGLXFBConfig(fbconfig, &native))
+    {
+        _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
+                        "GLX: Failed to find a suitable GLXFBConfig");
+        return false;
+    }
+
+    result = glXGetVisualFromFBConfig(_glfw.x11.display, native);
+    if (!result)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                        "GLX: Failed to retrieve Visual for GLXFBConfig");
+        return false;
+    }
+
+    *visual = result->visual;
+    *depth  = result->depth;
+
+    XFree(result);
+    return true;
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                        GLFW native API                       //////
+//////////////////////////////////////////////////////////////////////////
+
+GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* handle)
+{
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+
+    if (window->context.client == GLFW_NO_API)
+    {
+        _glfwInputError(GLFW_NO_WINDOW_CONTEXT, NULL);
+        return NULL;
+    }
+
+    return window->context.glx.handle;
+}
+
+GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* handle)
+{
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    _GLFW_REQUIRE_INIT_OR_RETURN(None);
+
+    if (window->context.client == GLFW_NO_API)
+    {
+        _glfwInputError(GLFW_NO_WINDOW_CONTEXT, NULL);
+        return None;
+    }
+
+    return window->context.glx.window;
+}

glfw/glx_context.h

@@ -0,0 +1,183 @@
+//========================================================================
+// GLFW 3.4 GLX - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2002-2006 Marcus Geelnard
+// Copyright (c) 2006-2017 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+#define GLX_VENDOR 1
+#define GLX_RGBA_BIT 0x00000001
+#define GLX_WINDOW_BIT 0x00000001
+#define GLX_DRAWABLE_TYPE 0x8010
+#define GLX_RENDER_TYPE 0x8011
+#define GLX_RGBA_TYPE 0x8014
+#define GLX_DOUBLEBUFFER 5
+#define GLX_STEREO 6
+#define GLX_AUX_BUFFERS 7
+#define GLX_RED_SIZE 8
+#define GLX_GREEN_SIZE 9
+#define GLX_BLUE_SIZE 10
+#define GLX_ALPHA_SIZE 11
+#define GLX_DEPTH_SIZE 12
+#define GLX_STENCIL_SIZE 13
+#define GLX_ACCUM_RED_SIZE 14
+#define GLX_ACCUM_GREEN_SIZE 15
+#define GLX_ACCUM_BLUE_SIZE 16
+#define GLX_ACCUM_ALPHA_SIZE 17
+#define GLX_SAMPLES 0x186a1
+#define GLX_VISUAL_ID 0x800b
+
+#define GLX_FRAMEBUFFER_SRGB_CAPABLE_ARB 0x20b2
+#define GLX_CONTEXT_DEBUG_BIT_ARB 0x00000001
+#define GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB 0x00000002
+#define GLX_CONTEXT_CORE_PROFILE_BIT_ARB 0x00000001
+#define GLX_CONTEXT_PROFILE_MASK_ARB 0x9126
+#define GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB 0x00000002
+#define GLX_CONTEXT_MAJOR_VERSION_ARB 0x2091
+#define GLX_CONTEXT_MINOR_VERSION_ARB 0x2092
+#define GLX_CONTEXT_FLAGS_ARB 0x2094
+#define GLX_CONTEXT_ES2_PROFILE_BIT_EXT 0x00000004
+#define GLX_CONTEXT_ROBUST_ACCESS_BIT_ARB 0x00000004
+#define GLX_LOSE_CONTEXT_ON_RESET_ARB 0x8252
+#define GLX_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB 0x8256
+#define GLX_NO_RESET_NOTIFICATION_ARB 0x8261
+#define GLX_CONTEXT_RELEASE_BEHAVIOR_ARB 0x2097
+#define GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB 0
+#define GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB 0x2098
+#define GLX_CONTEXT_OPENGL_NO_ERROR_ARB 0x31b3
+
+typedef XID GLXWindow;
+typedef XID GLXDrawable;
+typedef struct __GLXFBConfig* GLXFBConfig;
+typedef struct __GLXcontext* GLXContext;
+typedef void (*__GLXextproc)(void);
+
+typedef int (*PFNGLXGETFBCONFIGATTRIBPROC)(Display*,GLXFBConfig,int,int*);
+typedef GLXFBConfig* (*PFNGLXCHOOSEFBCONFIGPROC)(Display*,int,const int*,int*);
+typedef const char* (*PFNGLXGETCLIENTSTRINGPROC)(Display*,int);
+typedef Bool (*PFNGLXQUERYEXTENSIONPROC)(Display*,int*,int*);
+typedef Bool (*PFNGLXQUERYVERSIONPROC)(Display*,int*,int*);
+typedef void (*PFNGLXDESTROYCONTEXTPROC)(Display*,GLXContext);
+typedef Bool (*PFNGLXMAKECURRENTPROC)(Display*,GLXDrawable,GLXContext);
+typedef void (*PFNGLXSWAPBUFFERSPROC)(Display*,GLXDrawable);
+typedef const char* (*PFNGLXQUERYEXTENSIONSSTRINGPROC)(Display*,int);
+typedef GLXFBConfig* (*PFNGLXGETFBCONFIGSPROC)(Display*,int,int*);
+typedef GLXContext (*PFNGLXCREATENEWCONTEXTPROC)(Display*,GLXFBConfig,int,GLXContext,Bool);
+typedef __GLXextproc (* PFNGLXGETPROCADDRESSPROC)(const GLubyte *procName);
+typedef void (*PFNGLXSWAPINTERVALEXTPROC)(Display*,GLXDrawable,int);
+typedef XVisualInfo* (*PFNGLXGETVISUALFROMFBCONFIGPROC)(Display*,GLXFBConfig);
+typedef GLXWindow (*PFNGLXCREATEWINDOWPROC)(Display*,GLXFBConfig,Window,const int*);
+typedef void (*PFNGLXDESTROYWINDOWPROC)(Display*,GLXWindow);
+
+typedef int (*PFNGLXSWAPINTERVALMESAPROC)(int);
+typedef int (*PFNGLXSWAPINTERVALSGIPROC)(int);
+typedef GLXContext (*PFNGLXCREATECONTEXTATTRIBSARBPROC)(Display*,GLXFBConfig,GLXContext,Bool,const int*);
+
+// libGL.so function pointer typedefs
+#define glXGetFBConfigs _glfw.glx.GetFBConfigs
+#define glXGetFBConfigAttrib _glfw.glx.GetFBConfigAttrib
+#define glXChooseFBConfig _glfw.glx.ChooseFBConfig
+#define glXGetClientString _glfw.glx.GetClientString
+#define glXQueryExtension _glfw.glx.QueryExtension
+#define glXQueryVersion _glfw.glx.QueryVersion
+#define glXDestroyContext _glfw.glx.DestroyContext
+#define glXMakeCurrent _glfw.glx.MakeCurrent
+#define glXSwapBuffers _glfw.glx.SwapBuffers
+#define glXQueryExtensionsString _glfw.glx.QueryExtensionsString
+#define glXCreateNewContext _glfw.glx.CreateNewContext
+#define glXGetVisualFromFBConfig _glfw.glx.GetVisualFromFBConfig
+#define glXCreateWindow _glfw.glx.CreateWindow
+#define glXDestroyWindow _glfw.glx.DestroyWindow
+
+#define _GLFW_PLATFORM_CONTEXT_STATE            _GLFWcontextGLX glx;
+#define _GLFW_PLATFORM_LIBRARY_CONTEXT_STATE    _GLFWlibraryGLX glx;
+
+
+// GLX-specific per-context data
+//
+typedef struct _GLFWcontextGLX
+{
+    GLXContext      handle;
+    GLXWindow       window;
+
+} _GLFWcontextGLX;
+
+// GLX-specific global data
+//
+typedef struct _GLFWlibraryGLX
+{
+    int             major, minor;
+    int             eventBase;
+    int             errorBase;
+
+    // dlopen handle for libGL.so.1
+    void*           handle;
+
+    // GLX 1.3 functions
+    PFNGLXGETFBCONFIGSPROC              GetFBConfigs;
+    PFNGLXGETFBCONFIGATTRIBPROC         GetFBConfigAttrib;
+    PFNGLXCHOOSEFBCONFIGPROC            ChooseFBConfig;
+    PFNGLXGETCLIENTSTRINGPROC           GetClientString;
+    PFNGLXQUERYEXTENSIONPROC            QueryExtension;
+    PFNGLXQUERYVERSIONPROC              QueryVersion;
+    PFNGLXDESTROYCONTEXTPROC            DestroyContext;
+    PFNGLXMAKECURRENTPROC               MakeCurrent;
+    PFNGLXSWAPBUFFERSPROC               SwapBuffers;
+    PFNGLXQUERYEXTENSIONSSTRINGPROC     QueryExtensionsString;
+    PFNGLXCREATENEWCONTEXTPROC          CreateNewContext;
+    PFNGLXGETVISUALFROMFBCONFIGPROC     GetVisualFromFBConfig;
+    PFNGLXCREATEWINDOWPROC              CreateWindow;
+    PFNGLXDESTROYWINDOWPROC             DestroyWindow;
+
+    // GLX 1.4 and extension functions
+    PFNGLXGETPROCADDRESSPROC            GetProcAddress;
+    PFNGLXGETPROCADDRESSPROC            GetProcAddressARB;
+    PFNGLXSWAPINTERVALSGIPROC           SwapIntervalSGI;
+    PFNGLXSWAPINTERVALEXTPROC           SwapIntervalEXT;
+    PFNGLXSWAPINTERVALMESAPROC          SwapIntervalMESA;
+    PFNGLXCREATECONTEXTATTRIBSARBPROC   CreateContextAttribsARB;
+    bool            SGI_swap_control;
+    bool            EXT_swap_control;
+    bool            MESA_swap_control;
+    bool            ARB_multisample;
+    bool            ARB_framebuffer_sRGB;
+    bool            EXT_framebuffer_sRGB;
+    bool            ARB_create_context;
+    bool            ARB_create_context_profile;
+    bool            ARB_create_context_robustness;
+    bool            EXT_create_context_es2_profile;
+    bool            ARB_create_context_no_error;
+    bool            ARB_context_flush_control;
+
+} _GLFWlibraryGLX;
+
+bool _glfwInitGLX(void);
+void _glfwTerminateGLX(void);
+bool _glfwCreateContextGLX(_GLFWwindow* window,
+                               const _GLFWctxconfig* ctxconfig,
+                               const _GLFWfbconfig* fbconfig);
+void _glfwDestroyContextGLX(_GLFWwindow* window);
+bool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig,
+                              const _GLFWctxconfig* ctxconfig,
+                              const _GLFWfbconfig* fbconfig,
+                              Visual** visual, int* depth);

glfw/ibus_glfw.c

@@ -0,0 +1,435 @@
+//========================================================================
+// GLFW 3.4 XKB - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2018 Kovid Goyal <kovid@kovidgoyal.net>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <errno.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <limits.h>
+
+#include "internal.h"
+#include "ibus_glfw.h"
+
+#define debug(...) if (_glfw.hints.init.debugKeyboard) printf(__VA_ARGS__);
+static const char IBUS_SERVICE[]         = "org.freedesktop.IBus";
+static const char IBUS_PATH[]            = "/org/freedesktop/IBus";
+static const char IBUS_INTERFACE[]       = "org.freedesktop.IBus";
+static const char IBUS_INPUT_INTERFACE[] = "org.freedesktop.IBus.InputContext";
+enum Capabilities {
+    IBUS_CAP_PREEDIT_TEXT       = 1 << 0,
+    IBUS_CAP_AUXILIARY_TEXT     = 1 << 1,
+    IBUS_CAP_LOOKUP_TABLE       = 1 << 2,
+    IBUS_CAP_FOCUS              = 1 << 3,
+    IBUS_CAP_PROPERTY           = 1 << 4,
+    IBUS_CAP_SURROUNDING_TEXT   = 1 << 5
+};
+
+
+static inline bool
+test_env_var(const char *name, const char *val) {
+    const char *q = getenv(name);
+    return (q && strcmp(q, val) == 0) ? true : false;
+}
+
+static inline size_t
+GLFW_MIN(size_t a, size_t b) {
+    return a < b ? a : b;
+}
+
+static const char*
+get_ibus_text_from_message(DBusMessage *msg) {
+    /* The message structure is (from dbus-monitor)
+       variant       struct {
+         string "IBusText"
+         array [
+         ]
+         string "ash "
+         variant             struct {
+               string "IBusAttrList"
+               array [
+               ]
+               array [
+               ]
+            }
+      }
+    */
+    const char *text = NULL;
+    const char *struct_id = NULL;
+    DBusMessageIter iter, sub1, sub2;
+    dbus_message_iter_init(msg, &iter);
+
+    if (dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_VARIANT) return NULL;
+
+    dbus_message_iter_recurse(&iter, &sub1);
+
+    if (dbus_message_iter_get_arg_type(&sub1) != DBUS_TYPE_STRUCT) return NULL;
+
+    dbus_message_iter_recurse(&sub1, &sub2);
+
+    if (dbus_message_iter_get_arg_type(&sub2) != DBUS_TYPE_STRING) return NULL;
+
+    dbus_message_iter_get_basic(&sub2, &struct_id);
+    if (!struct_id || strncmp(struct_id, "IBusText", sizeof("IBusText")) != 0) return NULL;
+
+    dbus_message_iter_next(&sub2);
+    dbus_message_iter_next(&sub2);
+
+    if (dbus_message_iter_get_arg_type(&sub2) != DBUS_TYPE_STRING) return NULL;
+
+    dbus_message_iter_get_basic(&sub2, &text);
+
+    return text;
+}
+
+static inline void
+send_text(const char *text, int ime_state) {
+    _GLFWwindow *w = _glfwFocusedWindow();
+    if (w && w->callbacks.keyboard) {
+        GLFWkeyevent fake_ev;
+        _glfwInitializeKeyEvent(&fake_ev, GLFW_KEY_UNKNOWN, 0, GLFW_PRESS, 0);
+        fake_ev.text = text;
+        fake_ev.ime_state = ime_state;
+        w->callbacks.keyboard((GLFWwindow*) w, &fake_ev);
+    }
+}
+
+// Connection handling {{{
+
+static DBusHandlerResult
+message_handler(DBusConnection *conn UNUSED, DBusMessage *msg, void *user_data) {
+    // To monitor signals from IBUS, use
+    //  dbus-monitor --address `ibus address` "type='signal',interface='org.freedesktop.IBus.InputContext'"
+    _GLFWIBUSData *ibus = (_GLFWIBUSData*)user_data;
+    (void)ibus;
+    const char *text;
+    switch(glfw_dbus_match_signal(msg, IBUS_INPUT_INTERFACE, "CommitText", "UpdatePreeditText", "HidePreeditText", "ShowPreeditText", NULL)) {
+        case 0:
+            text = get_ibus_text_from_message(msg);
+            debug("IBUS: CommitText: '%s'\n", text ? text : "(nil)");
+            send_text(text, 2);
+            break;
+        case 1:
+            text = get_ibus_text_from_message(msg);
+            send_text(text, 1);
+            debug("IBUS: UpdatePreeditText: '%s'\n", text ? text : "(nil)");
+            break;
+        case 2:
+            debug("IBUS: HidePreeditText\n");
+            break;
+        case 3:
+            debug("IBUS: ShowPreeditText\n");
+            break;
+    }
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+}
+
+static inline const char*
+get_ibus_address_file_name(void) {
+    const char *addr;
+    static char ans[PATH_MAX];
+    addr = getenv("IBUS_ADDRESS");
+    int offset = 0;
+    if (addr && addr[0]) {
+        memcpy(ans, addr, GLFW_MIN(strlen(addr), sizeof(ans)));
+        return ans;
+    }
+
+    const char *de = getenv("DISPLAY");
+    if (!de || !de[0]) de = ":0.0";
+    char *display = _glfw_strdup(de);
+    const char *host = display;
+    char *disp_num  = strrchr(display, ':');
+    char *screen_num = strrchr(display, '.');
+
+    if (!disp_num) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Could not get IBUS address file name as DISPLAY env var has no colon");
+        free(display);
+        return NULL;
+    }
+    *disp_num = 0;
+    disp_num++;
+    if (screen_num) *screen_num = 0;
+    if (!*host) host = "unix";
+
+    memset(ans, 0, sizeof(ans));
+    const char *conf_env = getenv("XDG_CONFIG_HOME");
+    if (conf_env && conf_env[0]) {
+        offset = snprintf(ans, sizeof(ans), "%s", conf_env);
+    } else {
+        conf_env = getenv("HOME");
+        if (!conf_env || !conf_env[0]) {
+            _glfwInputError(GLFW_PLATFORM_ERROR, "Could not get IBUS address file name as no HOME env var is set");
+            free(display);
+            return NULL;
+        }
+        offset = snprintf(ans, sizeof(ans), "%s/.config", conf_env);
+    }
+    char *key = dbus_get_local_machine_id();
+    snprintf(ans + offset, sizeof(ans) - offset, "/ibus/bus/%s-%s-%s", key, host, disp_num);
+    dbus_free(key);
+    free(display);
+    return ans;
+}
+
+
+static inline bool
+read_ibus_address(_GLFWIBUSData *ibus) {
+    static char buf[1024];
+    struct stat s;
+    FILE *addr_file = fopen(ibus->address_file_name, "r");
+    if (!addr_file) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to open IBUS address file: %s with error: %s", ibus->address_file_name, strerror(errno));
+        return false;
+    }
+    int stat_result = fstat(fileno(addr_file), &s);
+    bool found = false;
+    while (fgets(buf, sizeof(buf), addr_file)) {
+        if (strncmp(buf, "IBUS_ADDRESS=", sizeof("IBUS_ADDRESS=")-1) == 0) {
+            size_t sz = strlen(buf);
+            if (buf[sz-1] == '\n') buf[sz-1] = 0;
+            if (buf[sz-2] == '\r') buf[sz-2] = 0;
+            found = true;
+            break;
+        }
+    }
+    fclose(addr_file); addr_file = NULL;
+    if (stat_result != 0) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to stat IBUS address file: %s with error: %s", ibus->address_file_name, strerror(errno));
+        return false;
+    }
+    ibus->address_file_mtime = s.st_mtime;
+    if (found) {
+        free((void*)ibus->address);
+        ibus->address = _glfw_strdup(buf + sizeof("IBUS_ADDRESS=") - 1);
+        return true;
+    }
+    _glfwInputError(GLFW_PLATFORM_ERROR, "Could not find IBUS_ADDRESS in %s", ibus->address_file_name);
+    return false;
+}
+
+void
+input_context_created(DBusMessage *msg, const char* errmsg, void *data) {
+    if (errmsg) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "IBUS: Failed to create input context with error: %s", errmsg);
+        return;
+    }
+    const char *path = NULL;
+    if (!glfw_dbus_get_args(msg, "Failed to get IBUS context path from reply", DBUS_TYPE_OBJECT_PATH, &path, DBUS_TYPE_INVALID)) return;
+    _GLFWIBUSData *ibus = (_GLFWIBUSData*)data;
+    free((void*)ibus->input_ctx_path);
+    ibus->input_ctx_path = _glfw_strdup(path);
+    if (!ibus->input_ctx_path) return;
+    dbus_bus_add_match(ibus->conn, "type='signal',interface='org.freedesktop.IBus.InputContext'", NULL);
+    DBusObjectPathVTable ibus_vtable = {.message_function = message_handler};
+    dbus_connection_try_register_object_path(ibus->conn, ibus->input_ctx_path, &ibus_vtable, ibus, NULL);
+    enum Capabilities caps = IBUS_CAP_FOCUS | IBUS_CAP_PREEDIT_TEXT;
+    if (!glfw_dbus_call_method_no_reply(ibus->conn, IBUS_SERVICE, ibus->input_ctx_path, IBUS_INPUT_INTERFACE, "SetCapabilities", DBUS_TYPE_UINT32, &caps, DBUS_TYPE_INVALID)) return;
+    ibus->ok = true;
+    glfw_ibus_set_focused(ibus, false);
+    glfw_ibus_set_cursor_geometry(ibus, 0, 0, 0, 0);
+    debug("Connected to IBUS daemon for IME input management\n");
+}
+
+bool
+setup_connection(_GLFWIBUSData *ibus) {
+    const char *client_name = "GLFW_Application";
+    const char *address_file_name = get_ibus_address_file_name();
+    ibus->ok = false;
+    if (!address_file_name) return false;
+    free((void*)ibus->address_file_name);
+    ibus->address_file_name = _glfw_strdup(address_file_name);
+    if (!read_ibus_address(ibus)) return false;
+    if (ibus->conn) {
+        glfw_dbus_close_connection(ibus->conn);
+        ibus->conn = NULL;
+    }
+    debug("Connecting to IBUS daemon @ %s for IME input management\n", ibus->address);
+    ibus->conn = glfw_dbus_connect_to(ibus->address, "Failed to connect to the IBUS daemon, with error", "ibus", true);
+    if (!ibus->conn) return false;
+    free((void*)ibus->input_ctx_path); ibus->input_ctx_path = NULL;
+    if (!glfw_dbus_call_method_with_reply(
+            ibus->conn, IBUS_SERVICE, IBUS_PATH, IBUS_INTERFACE, "CreateInputContext", DBUS_TIMEOUT_USE_DEFAULT, input_context_created, ibus,
+            DBUS_TYPE_STRING, &client_name, DBUS_TYPE_INVALID)) {
+        return false;
+    }
+    return true;
+}
+
+
+void
+glfw_connect_to_ibus(_GLFWIBUSData *ibus) {
+    if (ibus->inited) return;
+    if (!test_env_var("GLFW_IM_MODULE", "ibus")) return;
+    ibus->inited = true;
+    setup_connection(ibus);
+}
+
+void
+glfw_ibus_terminate(_GLFWIBUSData *ibus) {
+    if (ibus->conn) {
+        glfw_dbus_close_connection(ibus->conn);
+        ibus->conn = NULL;
+    }
+#define F(x) if (ibus->x) { free((void*)ibus->x); ibus->x = NULL; }
+    F(input_ctx_path);
+    F(address);
+    F(address_file_name);
+#undef F
+
+    ibus->ok = false;
+}
+
+static bool
+check_connection(_GLFWIBUSData *ibus) {
+    if (!ibus->inited) return false;
+    if (ibus->conn && dbus_connection_get_is_connected(ibus->conn)) {
+        return ibus->ok;
+    }
+    struct stat s;
+    if (stat(ibus->address_file_name, &s) != 0 || s.st_mtime != ibus->address_file_mtime) {
+        if (!read_ibus_address(ibus)) return false;
+        setup_connection(ibus);
+    }
+    return false;
+}
+
+
+void
+glfw_ibus_dispatch(_GLFWIBUSData *ibus) {
+    if (ibus->conn) glfw_dbus_dispatch(ibus->conn);
+}
+// }}}
+
+static void
+simple_message(_GLFWIBUSData *ibus, const char *method) {
+    if (check_connection(ibus)) {
+        glfw_dbus_call_method_no_reply(ibus->conn, IBUS_SERVICE, ibus->input_ctx_path, IBUS_INPUT_INTERFACE, method, DBUS_TYPE_INVALID);
+    }
+}
+
+void
+glfw_ibus_set_focused(_GLFWIBUSData *ibus, bool focused) {
+    simple_message(ibus, focused ? "FocusIn" : "FocusOut");
+}
+
+void
+glfw_ibus_set_cursor_geometry(_GLFWIBUSData *ibus, int x, int y, int w, int h) {
+    if (check_connection(ibus)) {
+        glfw_dbus_call_method_no_reply(ibus->conn, IBUS_SERVICE, ibus->input_ctx_path, IBUS_INPUT_INTERFACE, "SetCursorLocation",
+                DBUS_TYPE_INT32, &x, DBUS_TYPE_INT32, &y, DBUS_TYPE_INT32, &w, DBUS_TYPE_INT32, &h, DBUS_TYPE_INVALID);
+    }
+}
+
+typedef enum
+{
+    IBUS_SHIFT_MASK    = 1 << 0,
+    IBUS_LOCK_MASK     = 1 << 1,
+    IBUS_CONTROL_MASK  = 1 << 2,
+    IBUS_MOD1_MASK     = 1 << 3,
+    IBUS_MOD2_MASK     = 1 << 4,
+    IBUS_MOD3_MASK     = 1 << 5,
+    IBUS_MOD4_MASK     = 1 << 6,
+    IBUS_MOD5_MASK     = 1 << 7,
+    IBUS_BUTTON1_MASK  = 1 << 8,
+    IBUS_BUTTON2_MASK  = 1 << 9,
+    IBUS_BUTTON3_MASK  = 1 << 10,
+    IBUS_BUTTON4_MASK  = 1 << 11,
+    IBUS_BUTTON5_MASK  = 1 << 12,
+
+    /* The next few modifiers are used by XKB, so we skip to the end.
+     * Bits 15 - 23 are currently unused. Bit 29 is used internally.
+     */
+
+    /* ibus mask */
+    IBUS_HANDLED_MASK  = 1 << 24,
+    IBUS_FORWARD_MASK  = 1 << 25,
+    IBUS_IGNORED_MASK  = IBUS_FORWARD_MASK,
+
+    IBUS_SUPER_MASK    = 1 << 26,
+    IBUS_HYPER_MASK    = 1 << 27,
+    IBUS_META_MASK     = 1 << 28,
+
+    IBUS_RELEASE_MASK  = 1 << 30,
+
+    IBUS_MODIFIER_MASK = 0x5f001fff
+} IBusModifierType;
+
+
+static inline uint32_t
+ibus_key_state(unsigned int glfw_modifiers, int action) {
+    uint32_t ans = action == GLFW_RELEASE ? IBUS_RELEASE_MASK : 0;
+#define M(g, i) if(glfw_modifiers & GLFW_MOD_##g) ans |= i
+    M(SHIFT, IBUS_SHIFT_MASK);
+    M(CAPS_LOCK, IBUS_LOCK_MASK);
+    M(CONTROL, IBUS_CONTROL_MASK);
+    M(ALT, IBUS_MOD1_MASK);
+    M(NUM_LOCK, IBUS_MOD2_MASK);
+    M(SUPER, IBUS_MOD4_MASK);
+#undef M
+    return ans;
+}
+
+void
+key_event_processed(DBusMessage *msg, const char* errmsg, void *data) {
+    uint32_t handled = 0;
+    _GLFWIBUSKeyEvent *ev = (_GLFWIBUSKeyEvent*)data;
+    // Restore key's text from the text embedded in the structure.
+    ev->glfw_ev.text = ev->__embedded_text;
+    bool is_release = ev->glfw_ev.action == GLFW_RELEASE;
+    bool failed = false;
+    if (errmsg) {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "IBUS: Failed to process key with error: %s", errmsg);
+        failed = true;
+    } else {
+        glfw_dbus_get_args(msg, "Failed to get IBUS handled key from reply", DBUS_TYPE_BOOLEAN, &handled, DBUS_TYPE_INVALID);
+        debug("IBUS processed native_key: 0x%x release: %d handled: %u\n", ev->glfw_ev.native_key, is_release, handled);
+    }
+    glfw_xkb_key_from_ime(ev, handled ? true : false, failed);
+    free(ev);
+}
+
+bool
+ibus_process_key(const _GLFWIBUSKeyEvent *ev_, _GLFWIBUSData *ibus) {
+    if (!check_connection(ibus)) return false;
+    _GLFWIBUSKeyEvent *ev = calloc(1, sizeof(_GLFWIBUSKeyEvent));
+    if (!ev) return false;
+    memcpy(ev, ev_, sizeof(_GLFWIBUSKeyEvent));
+    // Put the key's text in a field IN the structure, for proper serialization.
+    if (ev->glfw_ev.text) strncpy(ev->__embedded_text, ev->glfw_ev.text, sizeof(ev->__embedded_text) - 1);
+    ev->glfw_ev.text = NULL;
+    uint32_t state = ibus_key_state(ev->glfw_ev.mods, ev->glfw_ev.action);
+    if (!glfw_dbus_call_method_with_reply(
+            ibus->conn, IBUS_SERVICE, ibus->input_ctx_path, IBUS_INPUT_INTERFACE, "ProcessKeyEvent",
+            3000, key_event_processed, ev,
+            DBUS_TYPE_UINT32, &ev->ibus_keysym, DBUS_TYPE_UINT32, &ev->ibus_keycode, DBUS_TYPE_UINT32,
+            &state, DBUS_TYPE_INVALID)) {
+        free(ev);
+        return false;
+    }
+    return true;
+}

glfw/ibus_glfw.h

@@ -0,0 +1,54 @@
+//========================================================================
+// GLFW 3.4 XKB - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2018 Kovid Goyal <kovid@kovidgoyal.net>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+
+#pragma once
+
+#include "internal.h"
+#include "dbus_glfw.h"
+#include <xkbcommon/xkbcommon.h>
+
+typedef struct {
+    bool ok, inited;
+    time_t address_file_mtime;
+    DBusConnection *conn;
+    const char *input_ctx_path, *address_file_name, *address;
+} _GLFWIBUSData;
+
+typedef struct {
+    xkb_keycode_t ibus_keycode;
+    xkb_keysym_t ibus_keysym;
+    GLFWid window_id;
+    GLFWkeyevent glfw_ev;
+    char __embedded_text[64];
+} _GLFWIBUSKeyEvent;
+
+void glfw_connect_to_ibus(_GLFWIBUSData *ibus);
+void glfw_ibus_terminate(_GLFWIBUSData *ibus);
+void glfw_ibus_set_focused(_GLFWIBUSData *ibus, bool focused);
+void glfw_ibus_dispatch(_GLFWIBUSData *ibus);
+bool ibus_process_key(const _GLFWIBUSKeyEvent *ev_, _GLFWIBUSData *ibus);
+void glfw_ibus_set_cursor_geometry(_GLFWIBUSData *ibus, int x, int y, int w, int h);

glfw/init.c

@@ -0,0 +1,377 @@
+//========================================================================
+// GLFW 3.4 - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2002-2006 Marcus Geelnard
+// Copyright (c) 2006-2018 Camilla Löwy <elmindreda@glfw.org>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+// Please use C89 style variable declarations in this file because VS 2010
+//========================================================================
+
+#include "internal.h"
+#include "mappings.h"
+
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <stdarg.h>
+#include <assert.h>
+
+
+// The global variables below comprise all mutable global data in GLFW
+//
+// Any other global variable is a bug
+
+// Global state shared between compilation units of GLFW
+//
+_GLFWlibrary _glfw = { false };
+
+// These are outside of _glfw so they can be used before initialization and
+// after termination
+//
+static _GLFWerror _glfwMainThreadError;
+static GLFWerrorfun _glfwErrorCallback;
+static _GLFWinitconfig _glfwInitHints =
+{
+    true,      // hat buttons
+    GLFW_ANGLE_PLATFORM_TYPE_NONE, // ANGLE backend
+    false,     // debug keyboard
+    {
+        true,  // macOS menu bar
+        true   // macOS bundle chdir
+    }
+};
+
+// Terminate the library
+//
+static void terminate(void)
+{
+    int i;
+
+    memset(&_glfw.callbacks, 0, sizeof(_glfw.callbacks));
+
+    while (_glfw.windowListHead)
+        glfwDestroyWindow((GLFWwindow*) _glfw.windowListHead);
+
+    while (_glfw.cursorListHead)
+        glfwDestroyCursor((GLFWcursor*) _glfw.cursorListHead);
+
+    for (i = 0;  i < _glfw.monitorCount;  i++)
+    {
+        _GLFWmonitor* monitor = _glfw.monitors[i];
+        if (monitor->originalRamp.size)
+            _glfwPlatformSetGammaRamp(monitor, &monitor->originalRamp);
+        _glfwFreeMonitor(monitor);
+    }
+
+    free(_glfw.monitors);
+    _glfw.monitors = NULL;
+    _glfw.monitorCount = 0;
+
+    free(_glfw.mappings);
+    _glfw.mappings = NULL;
+    _glfw.mappingCount = 0;
+
+    _glfwTerminateVulkan();
+    _glfwPlatformTerminateJoysticks();
+    _glfwPlatformTerminate();
+
+    _glfw.initialized = false;
+
+    while (_glfw.errorListHead)
+    {
+        _GLFWerror* error = _glfw.errorListHead;
+        _glfw.errorListHead = error->next;
+        free(error);
+    }
+
+    _glfwPlatformDestroyTls(&_glfw.contextSlot);
+    _glfwPlatformDestroyTls(&_glfw.errorSlot);
+    _glfwPlatformDestroyMutex(&_glfw.errorLock);
+
+    memset(&_glfw, 0, sizeof(_glfw));
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                       GLFW internal API                      //////
+//////////////////////////////////////////////////////////////////////////
+
+char* _glfw_strdup(const char* source)
+{
+    const size_t length = strlen(source);
+    char* result = malloc(length + 1);
+    memcpy(result, source, length);
+    result[length] = 0;
+    return result;
+}
+
+
+//////////////////////////////////////////////////////////////////////////
+//////                         GLFW event API                       //////
+//////////////////////////////////////////////////////////////////////////
+
+// Notifies shared code of an error
+//
+void _glfwInputError(int code, const char* format, ...)
+{
+    _GLFWerror* error;
+    char description[_GLFW_MESSAGE_SIZE];
+
+    if (format)
+    {
+        va_list vl;
+
+        va_start(vl, format);
+        vsnprintf(description, sizeof(description), format, vl);
+        va_end(vl);
+
+        description[sizeof(description) - 1] = '\0';
+    }
+    else
+    {
+        if (code == GLFW_NOT_INITIALIZED)
+            strcpy(description, "The GLFW library is not initialized");
+        else if (code == GLFW_NO_CURRENT_CONTEXT)
+            strcpy(description, "There is no current context");
+        else if (code == GLFW_INVALID_ENUM)
+            strcpy(description, "Invalid argument for enum parameter");
+        else if (code == GLFW_INVALID_VALUE)
+            strcpy(description, "Invalid value for parameter");
+        else if (code == GLFW_OUT_OF_MEMORY)
+            strcpy(description, "Out of memory");
+        else if (code == GLFW_API_UNAVAILABLE)
+            strcpy(description, "The requested API is unavailable");
+        else if (code == GLFW_VERSION_UNAVAILABLE)
+            strcpy(description, "The requested API version is unavailable");
+        else if (code == GLFW_PLATFORM_ERROR)
+            strcpy(description, "A platform-specific error occurred");
+        else if (code == GLFW_FORMAT_UNAVAILABLE)
+            strcpy(description, "The requested format is unavailable");
+        else if (code == GLFW_NO_WINDOW_CONTEXT)
+            strcpy(description, "The specified window has no context");
+        else if (code == GLFW_FEATURE_UNAVAILABLE)
+            strcpy(description, "The requested feature cannot be implemented for this platform");
+        else if (code == GLFW_FEATURE_UNIMPLEMENTED)
+            strcpy(description, "The requested feature has not yet been implemented for this platform");
+        else
+            strcpy(description, "ERROR: UNKNOWN GLFW ERROR");
+    }
+
+    if (_glfw.initialized)
+    {
+        error = _glfwPlatformGetTls(&_glfw.errorSlot);
+        if (!error)
+        {
+            error = calloc(1, sizeof(_GLFWerror));
+            _glfwPlatformSetTls(&_glfw.errorSlot, error);
+            _glfwPlatformLockMutex(&_glfw.errorLock);
+            error->next = _glfw.errorListHead;
+            _glfw.errorListHead = error;
+            _glfwPlatformUnlockMutex(&_glfw.errorLock);
+        }
+    }
+    else
+        error = &_glfwMainThreadError;
+
+    error->code = code;
+    strcpy(error->description, description);
+
+    if (_glfwErrorCallback)
+        _glfwErrorCallback(code, description);
+}
+
+void
+_glfwDebug(const char *format, ...) {
+    if (format)
+    {
+        va_list vl;
+
+        fprintf(stderr, "[%.4f] ", monotonic_t_to_s_double(glfwGetTime()));
+        va_start(vl, format);
+        vfprintf(stderr, format, vl);
+        va_end(vl);
+        fprintf(stderr, "\n");
+    }
+
+}
+
+//////////////////////////////////////////////////////////////////////////
+//////                        GLFW public API                       //////
+//////////////////////////////////////////////////////////////////////////
+
+GLFWAPI int glfwInit(monotonic_t start_time)
+{
+    if (_glfw.initialized)
+        return true;
+    monotonic_start_time = start_time;
+
+    memset(&_glfw, 0, sizeof(_glfw));
+    _glfw.hints.init = _glfwInitHints;
+
+    if (!_glfwPlatformInit())
+    {
+        terminate();
+        return false;
+    }
+
+    if (!_glfwPlatformCreateMutex(&_glfw.errorLock) ||
+        !_glfwPlatformCreateTls(&_glfw.errorSlot) ||
+        !_glfwPlatformCreateTls(&_glfw.contextSlot))
+    {
+        terminate();
+        return false;
+    }
+
+    _glfwPlatformSetTls(&_glfw.errorSlot, &_glfwMainThreadError);
+
+    _glfw.initialized = true;
+
+    glfwDefaultWindowHints();
+
+    {
+        int i;
+
+        for (i = 0;  _glfwDefaultMappings[i];  i++)
+        {
+            if (!glfwUpdateGamepadMappings(_glfwDefaultMappings[i]))
+            {
+                terminate();
+                return false;
+            }
+        }
+    }
+
+    return true;
+}
+
+GLFWAPI void glfwTerminate(void)
+{
+    if (!_glfw.initialized)
+        return;
+
+    terminate();
+}
+
+GLFWAPI void glfwInitHint(int hint, int value)
+{
+    switch (hint)
+    {
+        case GLFW_JOYSTICK_HAT_BUTTONS:
+            _glfwInitHints.hatButtons = value;
+            return;
+        case GLFW_ANGLE_PLATFORM_TYPE:
+            _glfwInitHints.angleType = value;
+            return;
+        case GLFW_DEBUG_KEYBOARD:
+            _glfwInitHints.debugKeyboard = value;
+            return;
+        case GLFW_COCOA_CHDIR_RESOURCES:
+            _glfwInitHints.ns.chdir = value;
+            return;
+        case GLFW_COCOA_MENUBAR:
+            _glfwInitHints.ns.menubar = value;
+            return;
+    }
+
+    _glfwInputError(GLFW_INVALID_ENUM,
+                    "Invalid init hint 0x%08X", hint);
+}
+
+GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev)
+{
+    if (major != NULL)
+        *major = GLFW_VERSION_MAJOR;
+    if (minor != NULL)
+        *minor = GLFW_VERSION_MINOR;
+    if (rev != NULL)
+        *rev = GLFW_VERSION_REVISION;
+}
+
+GLFWAPI const char* glfwGetVersionString(void)
+{
+    return _glfwPlatformGetVersionString();
+}
+
+GLFWAPI int glfwGetError(const char** description)
+{
+    _GLFWerror* error;
+    int code = GLFW_NO_ERROR;
+
+    if (description)
+        *description = NULL;
+
+    if (_glfw.initialized)
+        error = _glfwPlatformGetTls(&_glfw.errorSlot);
+    else
+        error = &_glfwMainThreadError;
+
+    if (error)
+    {
+        code = error->code;
+        error->code = GLFW_NO_ERROR;
+        if (description && code)
+            *description = error->description;
+    }
+
+    return code;
+}
+
+GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun)
+{
+    _GLFW_SWAP_POINTERS(_glfwErrorCallback, cbfun);
+    return cbfun;
+}
+
+
+GLFWAPI void glfwRunMainLoop(GLFWtickcallback callback, void *data)
+{
+    _GLFW_REQUIRE_INIT();
+    _glfwPlatformRunMainLoop(callback, data);
+}
+
+GLFWAPI void glfwStopMainLoop(void) {
+    _GLFW_REQUIRE_INIT();
+    _glfwPlatformStopMainLoop();
+}
+
+GLFWAPI unsigned long long glfwAddTimer(
+        monotonic_t interval, bool repeats, GLFWuserdatafun callback,
+        void *callback_data, GLFWuserdatafun free_callback)
+{
+    return _glfwPlatformAddTimer(interval, repeats, callback, callback_data, free_callback);
+}
+
+GLFWAPI void glfwUpdateTimer(unsigned long long timer_id, monotonic_t interval, bool enabled) {
+    _glfwPlatformUpdateTimer(timer_id, interval, enabled);
+}
+
+GLFWAPI void glfwRemoveTimer(unsigned long long timer_id) {
+    _glfwPlatformRemoveTimer(timer_id);
+}
+
+GLFWAPI GLFWapplicationclosefun glfwSetApplicationCloseCallback(GLFWapplicationclosefun cbfun)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+    _GLFW_SWAP_POINTERS(_glfw.callbacks.application_close, cbfun);
+    return cbfun;
+}