version 0.19.3

Also some misc code/docs cleanups for it.

.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

@@ -3,11 +3,14 @@ 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
+kitty/unicode-data.c linguist-generated=true
 kitty/rgb.py linguist-generated=true
 kitty/gl-wrapper.* linguist-generated=true
-kitty/khrplatform.h 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
+
+*.py  text diff=python
+*.m  text diff=objc

.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,129 @@
+#!/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:
+        if is_macos:
+            # needed for zlib for pillow, should not be needed after pillow 8.0
+            os.environ['PKG_CONFIG_PATH'] = '/usr/local/opt/zlib/lib/pkgconfig'
+        run('pip3 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,15 +1,21 @@
 *.so
 *.pyc
 *.pyo
-tags
-build
-linux-package
-kitty.app
-logo/*.iconset
-compile_commands.json
-glad/out
-asan-launcher
-kitty-profile
-dev
-__pycache__
-glfw/wayland-*-client-protocol.[ch]
+*_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,129 +0,0 @@
-matrix:
-    fast_finish: true
-    include:
-        - os: linux
-          dist: trusty
-          group: beta
-          sudo: false
-          env:
-            - CC=gcc SANITIZE_ARG=--sanitize
-          language: python
-          python: "3.5"
-          addons:
-            apt:
-              packages:
-                - libfontconfig1-dev
-                - libharfbuzz-dev
-                - libxi-dev
-                - libxrandr-dev
-                - libxinerama-dev
-                - libxcursor-dev
-                - libunistring-dev
-                - libxcb-xkb-dev
-                - libpng-dev
-                - python3-pil
-
-        - os: linux
-          dist: trusty
-          group: beta
-          sudo: false
-          env:
-            - CC=clang SANITIZE_ARG=--sanitize
-          language: python
-          python: "3.5"
-          addons:
-            apt:
-              packages:
-                - libfontconfig1-dev
-                - libharfbuzz-dev
-                - libxi-dev
-                - libxrandr-dev
-                - libxinerama-dev
-                - libxcursor-dev
-                - libunistring-dev
-                - libxcb-xkb-dev
-                - libpng-dev
-                - python3-pil
-
-        - os: linux
-          dist: trusty
-          group: beta
-          sudo: false
-          env:
-            - RUN_FLAKE=1 BUILD_PKG=1
-          language: python
-          python: "3.6"
-          addons:
-            apt:
-              packages:
-                - libfontconfig1-dev
-                - libharfbuzz-dev
-                - libxi-dev
-                - libxrandr-dev
-                - libxinerama-dev
-                - libxcursor-dev
-                - libunistring-dev
-                - libxcb-xkb-dev
-                - libpng-dev
-                - python3-pil
-                - 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
-
-env:
-    global:
-        - PYTHON=python3
-        - PKG_CONFIG_PATH=$HOME/harfbuzz/lib/pkgconfig:$PKG_CONFIG_PATH
-        - LD_LIBRARY_PATH=$HOME/harfbuzz/lib:$LD_LIBRARY_PATH
-        - ASAN_OPTIONS=leak_check_at_exit=0
-
-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 upgrade python;
-            brew install harfbuzz --without-glib --without-gobject-introspection --without-graphite2 --without-icu4c --without-freetype;
-        else
-            mkdir -p $SW;
-            curl https://download.calibre-ebook.com/travis/kitty/osx.tar.xz | tar xJ -C $SW;
-        fi
-    else
-        pushd /tmp
-        wget http://xkbcommon.org/download/libxkbcommon-0.6.1.tar.xz
-        tar xf libxkbcommon-0.6.1.tar.xz
-        cd libxkbcommon-0.6.1
-        ./configure --prefix=$HOME/harfbuzz --disable-dependency-tracking --disable-static
-        make -j2
-        make install
-        wget https://github.com/behdad/harfbuzz/releases/download/1.6.3/harfbuzz-1.6.3.tar.bz2
-        tar xf harfbuzz-1.6.3.tar.bz2
-        cd harfbuzz-1.6.3
-        ./configure --prefix=$HOME/harfbuzz --disable-dependency-tracking --disable-static --with-glib=no --with-gobject=no --with-cairo=no --with-fontconfig=no --with-icu=no --with-directwrite=no --with-freetype=yes
-        make -j2
-        make install
-        cd ..
-        popd
-    fi
-    pkg-config --cflags harfbuzz
-    if [[ "$TRAVIS_OS_NAME" != 'osx' ]]; then
-        PLIB=$(ldd `which python` | grep libpython | cut -d ' ' -f 3)
-        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`dirname $PLIB`
-    fi
-    set +e
-
-before_script:
-    - echo $LD_LIBRARY_PATH
-    - $PYTHON setup.py build --debug --verbose $SANITIZE_ARG;
-
-script:
-    - if grep -Inr '\s$' kitty kitty_tests *.py *.asciidoc .gitattributes .gitignore; then echo Trailing whitespace found, aborting.; exit 1; fi
-    - if [[ -z $SANITIZE_ARG ]]; then $PYTHON test.py; else ./asan-launcher test.py; fi
-    - 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,6 @@
+pkg-config
+zlib
+python
+imagemagick
+harfbuzz
+sphinx-doc

CHANGELOG.rst

@@ -1,418 +1 @@
-Changelog
-==============
-
-kitty is a feature full, cross-platform, *fast*, GPU based terminal emulator.
-
-version 0.9.0 [2018-04-15]
-------------------------------
-
-- A new kitty command shell to allow controlling kitty via commands. Press
-  `ctrl+shift+escape` to run the shell.
-
-- The hints kitten has become much more powerful. Now in addition to URLs you
-  can use it to select word, paths, filenames, lines, etc. from the screen.
-  These can be inserted into the terminal, copied to clipboard or sent to
-  external programs.
-
-- Linux: Switch to libxkbcommon for keyboard handling. It allows kitty to
-  support XCompose and dead keys and also react to keyboard remapping/layout
-  change without needing a restart.
-
-- Add support for multiple-key-sequence shortcuts
-
-- A new remote control command `set-colors` to change the current and/or
-  configured colors.
-
-- When double-clicking to select a word, select words that continue onto the
-  next/prev line as well.
-
-- Add an `include` directive for the config files to read multiple config files
-
-- Improve mouse selection for windows with padding. Moving the mouse into the
-  padding area now acts as if the mouse is over the nearest cell.
-
-- Allow setting all 256 terminal colors in the config file
-
-- Fix using `kitty --single-instance` to open a new window in a running kitty
-  instance, not respecting the `--directory` flag
-
-- URL hints: Exclude trailing punctuation from URLs
-
-- URL hints: Launch the browser from the kitty parent process rather than the
-  hints kitten. Fixes launching on some systems where xdg-open doesn't like
-  being run from a kitten.
-
-- Allow using rectangle select mode by pressing shift in addition to the
-  rectangle select modifiers even when the terminal program has grabbed the
-  mouse.
-
-
-version 0.8.4 [2018-03-31]
------------------------------
-
-- Fix presence of XDG_CONFIG_DIRS and absence of XDG_CONFIG_HOME preventing
-  kitty from starting
-
-- Revert change in last release to cell width calculation. Instead just clip
-  the right edges of characters that overflow the cell by at most two pixels
-
-
-version 0.8.3 [2018-03-29]
------------------------------
-
-- Fix a regression that broke the visual bell and invert screen colors escape
-  code
-
-- Allow double-click and triple-click + drag to extend selections word at a
-  time or line at a time
-
-- Add a keyboard shortcut to set the tab title
-
-- Fix setting window title to empty via OSC escape code not working correctly
-
-- Linux: Fix cell width calculation incorrect for some fonts (cell widths are
-  now calculated by actually rendering bitmaps, which is slower but more
-  accurate)
-
-- Allow specifying a system wide kitty config file, for all users
-
-- Add a --debug-config command line flag to output data about the system and
-  kitty configuration.
-
-- Wayland: Fix auto-repeat of keys not working
-
-
-version 0.8.2 [2018-03-17]
------------------------------
-
-- Allow extending existing selections by right clicking
-
-- Add a configurable keyboard shortcut and remote command to set the font size to a specific value
-
-- Add an option to have kitty close the window when the main processes running in it exits, even if there are still background processes writing to that terminal
-
-- Add configurable keyboard shortcuts to switch to a specific layout
-
-- Add a keyboard shortcut to edit the kitty config file easily 
-
-- macOS: Fix restoring of window size not correct on Retina screens
-
-- macOS: Add a facility to specify command line arguments when running kitty from the GUI 
-
-- Add a focus-tab remote command
-
-- Fix screen not being refreshed immediately after moving a window.
-
-- Fix a crash when getting the contents of the scrollback buffer as text
-
-version 0.8.1 [2018-03-09]
------------------------------
-
-- Extend kitty's remote control feature to work over both UNIX and TCP sockets,
-  so now you can control kitty from across the internet, if you want to.
-
-- Render private use unicode characters that are followed by a space as a two
-  character ligature. This fixes rendering for applications that misuse
-  private-use characters to display square symbols.
-
-- Fix Unicode emoji presentation variant selector causing new a fallback font
-  instance to be created
-
-- Fix a rare error that prevented the Unicode input kitten from working
-  sometimes
-
-- Allow using Ctrl+Alt+letter in legacy keyboard modes by outputting them as Ctrl+letter and Alt+letter.
-  This matches other terminals' behavior.
-
-- Fix cursor position off-by-one on horizontal axis when resizing the terminal
-
-- Wayland: Fix auto-repeat of keys not working
-
-- Wayland: Add support for window decorations provided by the Wayland shell
-
-- macOS: Fix URL hints not working 
-
-- macOS: Fix shell not starting in login mode on some computers
-
-- macOS: Output errors into console.app when running as a bundle
-
-
-version 0.8.0 [2018-02-24]
------------------------------
-
-- A framework for kittens, that is, small terminal programs designed to run
-  inside kitty and extend its capabilities. Examples include unicode input and
-  selecting URLs with the keyboard.
-
-- Input arbitrary unicode characters by pressing Ctrl+Shift+u. You can choose
-  characters by name, by hex code, by recently used, etc. There is even and
-  editable Favorites list.
-
-- Open URLs using only the keyboard. kitty has a new "hints mode". Press
-  Ctrl+Shift+e and all detected URLs on the screen are highlighted with a key
-  to press to open them. The facility is customizable so you can change
-  what is detected as a URL and which program is used to open it.
-
-- Add an option to change the titlebar color of kitty windows on macOS
-
-- Only consider Emoji characters with default Emoji presentation to be two
-  cells wide. This matches the standard. Also add support for the Unicode Emoji
-  variation presentation selector.
-
-- Prevent video tearing during high speed scrolling by syncing draws
-  to the monitor's refresh rate. There is a new configuration option to
-  control this ``sync_to_monitor``.
-
-- When displaying only a single window, use the default background color of the
-  window (which can be changed via escape codes) as the color for the margin
-  and padding of the window.
-
-- Add some non standard terminfo capabilities used by neovim and tmux.
-
-- Fix large drop in performance when using multiple top-level windows on macOS
-
-- Fix save/restore of window sizes not working correctly.
-
-- Remove option to use system wcwidth(). Now always use a wcwidth() based on
-  the Unicode standard. Only sane way.
-
-- Fix a regression that caused a few ligature glyphs to not render correctly in
-  rare circumstances.
-
-- Browsing the scrollback buffer now happens in an overlay window instead of a
-  new window/tab.
-
-version 0.7.1 [2018-01-31]
----------------------------
-
-- Add an option to adjust the width of character cells
-
-- Fix selecting text with the mouse in the scrollback buffer selecting text
-  from the line above the actually selected line
-
-- Fix some italic fonts having the right edge of characters cut-off,
-  unnecessarily
-
-
-version 0.7.0 [2018-01-24]
----------------------------
-
-- Allow controlling kitty from the shell prompt/scripts. You can
-  open/close/rename windows and tabs and even send input to specific windows.
-  See the README for details.
-
-- Add option to put tab bar at the top instead of the bottom
-
-- Add option to override the default shell
-
-- Add "Horizontal" and "Vertical" window layouts
-
-- Sessions: Allow setting titles and working directories for individual windows 
-
-- Option to copy to clipboard on mouse select
-
-- Fix incorrect reporting of mouse move events when using the SGR protocol
-
-- Make alt+backspace delete the previous word
-
-- Take the mouse wheel multiplier option in to account when generating fake key
-  scroll events
-
-- macOS: Fix closing top-level window does not transfer focus to other
-  top-level windows.
-
-- macOS: Fix alt+arrow keys not working when disabling the macos_option_as_alt
-  config option.
-
-- kitty icat: Workaround for bug in ImageMagick that would cause some images
-  to fail to display at certain sizes.
-
-- Fix rendering of text with ligature fonts that do not use dummy glyphs
-
-- Fix a regression that caused copying of the selection to clipboard to only
-  copy the visible part of the selection
-
-- Fix incorrect handling of some unicode combining marks that are not re-ordered
-
-- Fix handling on non-BMP combining characters
-
-- Drop the dependency on libunistring
-
-
-version 0.6.1 [2017-12-28]
----------------------------
-
-- Add an option to fade the text in inactive windows
-
-- Add new actions to open windows/tabs/etc. with the working directory set to 
-  the working directory of the current window.
-
-- Automatically adjust cell size when DPI changes, for example when kitty is
-  moved from one monitor to another with a different DPI
-
-- Ensure underlines are rendered even for fonts with very poor metrics
-
-- Fix some emoji glyphs not colored on Linux
-
-- Internal wcwidth() implementation is now auto-generated from the unicode
-  standard database
-
-- Allow configuring the modifiers to use for rectangular selection with the
-  mouse.
-
-- Fix incorrect minimum wayland version in the build script
-
-- Fix a crash when detecting a URL that ends at the end of the line
-
-- Fix regression that broke drawing of hollow cursor when window loses focus
-
-
-version 0.6.0 [2017-12-18]
----------------------------
-
-- Support background transparency via the background_opacity option. Provided
-  that your OS/window manager supports transparency, you can now have kitty
-  render pixels that have only the default background color as
-  semi-transparent.
-
-- Support multiple top level (OS) windows. These windows all share the sprite
-  texture cache on the GPU, further reducing overall resource usage. Use
-  the shortcut `ctrl+shift+n` to open a new top-level window.
-
-- Add support for a *daemon* mode using the `--single-instance` command line
-  option. With this option you can have only a single kitty instance running.
-  All future invocations simply open new top-level windows in the existing
-  instance.
-
-- Support colored emoji
-
-- Use CoreText instead of FreeType to render text on macOS
-
-- Support running on the "low power" GPU on dual GPU macOS machines
-
-- Add a new "grid" window layout
-
-- Drop the dependency on glfw (kitty now uses a modified, bundled copy of glfw)
-
-- Add an option to control the audio bell volume on X11 systems
-
-- Add a command line switch to set the name part of the WM_CLASS window
-  property independently.
-
-- Add a command line switch to set the window title.
-
-- Add more options to customize the tab-bar's appearance (font styles and
-  separator)
-
-- Allow drag and drop of files into kitty. On drop kitty will paste the
-  file path to the running program.
-
-- Add an option to control the underline style for URL highlighting on hover
-
-- X11: Set the WINDOWID environment variable 
-
-- Fix middle and right buttons swapped when sending mouse events to child
-  processes
-
-- Allow selecting in a rectangle by holding down Ctrl+Alt while dragging with
-  the mouse.
-
-
-version 0.5.1 [2017-12-01]
----------------------------
-
-- Add an option to control the thickness of lines in box drawing characters
-
-- Increase max. allowed ligature length to nine characters
-
-- Fix text not vertically centered when adjusting line height
-
-- Fix unicode block characters not being rendered properly
-
-- Fix shift+up/down not generating correct escape codes
-
-- Image display: Fix displaying images taller than two screen heights not
-  scrolling properly
-
-
-version 0.5.0 [2017-11-19]
----------------------------
-
-- Add support for ligature fonts such as Fira Code, Hasklig, etc. kitty now
-  uses harfbuzz for text shaping which allow it to support advanced OpenType
-  features such as contextual alternates/ligatures/combining glyphs/etc.
-
-- Make it easy to select fonts by allowing listing of monospace fonts using:
-  kitty list-fonts
-
-- Add an option to have window focus follow mouse
-
-- Add a keyboard shortcut (ctrl+shift+f11) to toggle fullscreen mode
-
-- macOS: Fix handling of option key. It now behaves just like the alt key on
-  Linux. There is an option to make it type unicode characters instead.
-
-- Linux: Add support for startup notification on X11 desktops. kitty will
-  now inform the window manager when its startup is complete.
-
-- Fix shell prompt being duplicated when window is resized
-
-- Fix crash when displaying more than 64 images in the same session
-
-- Add support for colons in SGR color codes. These are generated by some
-  applications such as neovim when they mistakenly identify kitty as a libvte
-  based terminal.
-
-- Fix mouse interaction not working in apps using obsolete mouse interaction
-  protocols
-
-- Linux: no longer require glew as a dependency
-
-
-version 0.4.2 [2017-10-23]
----------------------------
-
-- Fix a regression in 0.4.0 that broke custom key mappings
-
-- Fix a regression in 0.4.0 that broke support for non-QWERTY keyboard layouts 
-
-- Avoid using threads to reap zombie child processes. Also prevent kitty from
-  hanging if the open program hangs when clicking on a URL.
-
-
-version 0.4.0 [2017-10-22]
----------------------------
-
-- Support for drawing arbitrary raster graphics (images) in the terminal via a
-  new graphics protocol. kitty can draw images with full 32-bit color using both
-  ssh connections and files/shared memory (when available) for better
-  performance. The drawing primitives support alpha blending and z-index.
-  Images can be drawn both above and below text. See
-  https://github.com/kovidgoyal/kitty/blob/master/graphics-protocol.asciidoc
-  for details. 
-
-- Refactor kitty's internals to make it even faster and more efficient. The CPU
-  usage of kitty + X server while doing intensive tasks such as scrolling a
-  file continuously in less has been reduced by 50%. There are now two
-  configuration options ``repaint_delay`` and ``input_delay`` you can use to
-  fine tune kitty's performance vs CPU usage profile. The CPU usage of kitty +
-  X when scrolling in less is now significantly better than most (all?) other
-  terminals. See https://github.com/kovidgoyal/kitty#performance
-
-- Hovering over URLs with the mouse now underlines them to indicate they
-  can be clicked. Hold down Ctrl+Shift while clicking to open the URL.
-
-- Selection using the mouse is now more intelligent. It does not add
-  blank cells (i.e. cells that have no content) after the end of text in a
-  line to the selection.
-
-- The block cursor in now fully opaque but renders the character under it in
-  the background color, for enhanced visibility.
-
-- Allow combining multiple independent actions into a single shortcut
-
-- Add a new shortcut to pass the current selection to an external program
-
-- Allow creating shortcuts to open new windows running arbitrary commands. You
-  can also pass the current selection to the command as an arguments and the
-  contents of the screen + scrollback buffer as stdin to the command.
+See https://sw.kovidgoyal.net/kitty/changelog.html

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 ### Reporting bugs
 
 Please first search existing bug reports (especially closed ones) for a report
-that matches your issue. 
+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
@@ -10,9 +10,9 @@ config to reproduce the issue with).
 
 ### Contributing code
 
-Install [the dependencies](https://github.com/kovidgoyal/kitty#dependencies)
+Install [the dependencies](https://sw.kovidgoyal.net/kitty/build.html#dependencies)
 using your favorite package manager. Build and run kitty [from
-source](https://github.com/kovidgoyal/kitty#install-and-run-from-source).
+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

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,8 +1,8 @@
 ifdef V
-		VVAL=--verbose
+	VVAL=--verbose
 endif
 ifdef VERBOSE
-		VVAL=--verbose
+	VVAL=--verbose
 endif
 
 all:
@@ -18,6 +18,9 @@ clean:
 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
@@ -25,10 +28,16 @@ asan:
 profile:
 	python3 setup.py build $(VVAL) --profile
 
-logo/kitty.iconset/icon_256x256.png: logo/kitty.svg logo/make.py
-	logo/make.py
-
-rendered_logo: logo/kitty.iconset/icon_256x256.png
-
-app: rendered_logo
+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,568 +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_decrease_font_size: pass:quotes[`ctrl+shift+minus`]
-:sc_edit_config_file: pass:quotes[`ctrl+shift+f2`]
-: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_increase_font_size: pass:quotes[`ctrl+shift+equal`]
-:sc_input_unicode_character: pass:quotes[`ctrl+shift+u`]
-:sc_kitty_shell_window: pass:quotes[`ctrl+shift+escape`]
-: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_os_window: pass:quotes[`ctrl+shift+n`]
-: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_pass_selection_to_program: pass:quotes[`ctrl+shift+o`]
-: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_restore_font_size: pass:quotes[`ctrl+shift+backspace`]
-:sc_run_kitten_text_hints: pass:quotes[`ctrl+shift+e`]
-:sc_run_kitten_text_hints_type_line_program: pass:quotes[`ctrl+shift+p → l`]
-:sc_run_kitten_text_hints_type_path: pass:quotes[`ctrl+shift+p → shift+f`]
-:sc_run_kitten_text_hints_type_path_program: pass:quotes[`ctrl+shift+p → f`]
-:sc_run_kitten_text_hints_type_word_program: pass:quotes[`ctrl+shift+p → w`]
-: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_set_tab_title: pass:quotes[`ctrl+shift+alt+t`]
-: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`]
-:sc_toggle_fullscreen: pass:quotes[`ctrl+shift+f11`]
-// 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
-
-* Uses OpenGL for rendering, offloads rendering to the GPU for link:#performance[lower system
-load] and buttery smooth scrolling. Uses threaded rendering to minimize input
-latency.
-
-* Supports all modern terminal features: link:graphics-protocol.asciidoc[graphics (images)], unicode,
-true-color, OpenType ligatures, mouse protocol, focus tracking, bracketed paste and so on.
-
-* Supports tiling multiple terminal windows side by side in different
-link:#layouts[layouts] without needing to use an extra program like tmux
-
-* Can be link:remote-control.asciidoc[controlled from scripts or the shell prompt], even over SSH.
-
-* Has a framework for _kittens_, small terminal programs that can be used to extend kitty's functionality.
-For example, they are used for link:#unicode-input[Unicode input] and link:#url-hints[Hints].
-
-* Supports link:#startup-sessions[startup sessions] which allow you to specify the window/tab layout,
-working directories and programs to run on startup.
-
-* 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.
-
-* Allows you to open link:#the-scrollback-buffer[the scrollback buffer] in a separate
-window using arbitrary programs of your choice. This is useful for browsing
-the history comfortably in a pager or editor.
-
-
-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
-* harfbuzz >= 1.5.0
-* zlib
-* libpng
-* freetype (not needed on macOS)
-* fontconfig (not needed on macOS)
-* ImageMagick (optional, needed to use the `kitty icat` tool to display images in the terminal)
-* gcc or clang (required only for building)
-* pkg-config (required only for building)
-* For building on Linux in addition to the above dependencies you might also need to install the `-dev` packages for `xcursor`, `xrandr`, `xinerama`, `libgl1-mesa` and `xkbcommon-x11`, if they are not already installed by your distro.
-
-=== 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:
-
-....
-make
-....
-
-You can run kitty, as:
-
-....
-python3 .
-....
-
-=== Linux packages
-
-* Arch Linux: AUR git package https://aur.archlinux.org/packages/kitty-git/
-
-* Arch Linux: AUR stable package https://aur.archlinux.org/packages/kitty/
-
-* NixOS / nixpkgs: https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/kitty/default.nix
-
-* Gentoo: https://packages.gentoo.org/packages/x11-terms/kitty
-
-* openSUSE: https://build.opensuse.org/package/show/X11:terminals/kitty
-
-=== 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
-dependencies 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). Its configuration is a simple, human editable, single file for
-easy reproducibility (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}
-|Set tab title | {sc_set_tab_title}
-
-|===
-
-
-[options="header"]
-
-=== Windows
-
-|===
-|Action |Shortcut
-
-|New window   | {sc_new_window}
-|New OS window| {sc_new_os_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}
-
-|===
-
-=== Miscellaneous
-
-|===
-|Action |Shortcut
-
-|Increase font size   | {sc_increase_font_size}
-|Decrease font size   | {sc_decrease_font_size}
-|Restore font size    | {sc_restore_font_size}
-|Toggle fullscreen    | {sc_toggle_fullscreen}
-|Input unicode character | {sc_input_unicode_character}
-|Click URL using the keyboard | {sc_run_simple_kitten_text_url_hints}
-|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}
-|===
-
-
-== Controlling kitty from scripts
-
-You can control kitty from the command line/scripts by sending it messages.
-You can tell kitty to open/close/rename tabs and windows. You can even send
-arbitrary input/text to any specified window. Messages can be sent using `kitty
-@`. Note that you must set `allow_remote_control yes` in your
-link:kitty/kitty.conf[kitty.conf] to use this feature.  It even works over SSH
-connections.  This feature is best illustrated with a
-link:remote-control.asciidoc[tutorial].
-
-
-== 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 your favorite pager program (which is
-`less` by default). Colors and text formatting are preserved. You can explore
-the scrollback pager comfortably within the pager.
-
-
-== 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.
-
-image::unicode.png?raw=true[Unicode input widget, showing selection of unicode characters by name]
-
-In 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.
-
-In 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 dont like to use arrow
-keys.
-
-== 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_run_kitten_text_hints}
-to choose any URL visible on the screen and then open it using your system
-browser.
-
-image::hints_mode.png?raw=true[URL hints mode]
-
-Similarly, you can press {sc_run_kitten_text_hints_type_path_program} 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.
-
-The hints kitten is very powerful to see more detailed help on its various
-options and modes of operation, use: `kitty +kitten hints --help`.
-
-== Miscellaneous features
-
-* You can also hold down `ctrl+shift` and click on a URL to open it in a browser.
-* You can double click to select a word and triple click to select a line.
-* You can right click to extend a previous selection
-
-
-== Layouts
-
-Currently, there are five 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
-* Grid -- All windows are shown in a grid
-* Horizontal -- All windows are shown side-by-side
-* Vertical -- All windows are shown one below the other
-
-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 link:kitty/kitty.conf[kitty.conf] for examples.
-
-Writing a new layout only requires about fifty 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] for an overview of all customization possibilities.
-
-By default kitty looks for a config file in the OS config directories (usually
-`~/.config/kitty/kitty.conf` and additionally
-`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a specific
-path via the `--config` option or use the `KITTY_CONFIG_DIRECTORY` environment
-variable. See the help for the `--config` option in `kitty --help` for full
-details. You can also dump the current configuration using the `--debug-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 windows in the current tab
-cd ~
-# Create a window and run the specified command in it
-launch zsh
-launch 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
-# 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].
-
-== 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. ``repaint_delay``
-and ``input_delay``. These control the artificial delays introduced into the
-render loop to reduce CPU usage. See the link:kitty/kitty.conf[config file] for details.
-See also the ``sync_to_monitor`` option to further decrease latency at the cost
-of some link:https://en.wikipedia.org/wiki/Screen_tearing[tearing] while scrolling.
-
-You can generate detailed per-function performance data using
-link:https://github.com/gperftools/gperftools[gperftools]. Build kitty with
-`make profile` which will create an executable called `kitty-profile`.  Run
-that 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).
-
-== 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.
-
-You also need `tic` to compile the terminfo files, it is usually found in the development package of `ncurses`
-
-This applies to creating packages for kitty for macOS package managers such as
-brew or MacPorts as well.
-
-
-== Frequently Asked Questions
-
-=== 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.
-
-=== How do I build kitty.app on macOS?
-
-Install `imagemagick`, `optipng` and `librsvg` using `brew` or similar (needed for the logo generation step).
-
-And run:
-```
-make app
-```
-
-This `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 that the released kitty.dmg includes all dependencies, unlike the
-`kitty.app` built above and is built automatically by using the `kitty` branch of
-link:https://github.com/kovidgoyal/build-calibre[build-calibre] however, that
-is designed to run on Linux and is not for the faint of heart.
-
-
-=== 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 link:https://github.com/kovidgoyal/kitty/blob/master/protocol-extensions.asciidoc#setting-text-styles-colors-in-arbitrary-regions-of-the-screen[here]
-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.
-Either install kitty on the server, or simply copy over the terminfo files,
-using:
-
-....
-infocmp xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
-....
-
-Really, the correct solution for this is to convince the OpenSSH maintainers to
-have ssh do this automatically when connecting to a server, so that all
-terminals work transparently.
-
-
-=== How do I change the colors in a running kitty instance?
-
-You can either use the
-link:http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands[OSC
-terminal escape codes] to set colors or you can enable link:remote-control.asciidoc[remote control]
-for kitty and use `kitty @ set-colors --help`.
-
-
-=== 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
-`<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:
-`/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.
-
-== Resources on terminal behavior
-
-http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
-
-https://en.wikipedia.org/wiki/C0_and_C1_control_codes
-
-https://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,44 +1,76 @@
-#!/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
 
 
-def icat(args):
-    from kitty.icat import main
-    main(args)
+def icat(args: List[str]) -> None:
+    from kittens.runner import run_kitten as rk
+    sys.argv = args
+    rk('icat')
 
 
-def list_fonts(args):
-    from kitty.fonts.list import main
-    main(args)
+def list_fonts(args: List[str]) -> None:
+    from kitty.fonts.list import main as list_main
+    list_main(args)
 
 
-def remote_control(args):
-    from kitty.remote_control import main
-    main(args)
+def remote_control(args: List[str]) -> None:
+    from kitty.remote_control import main as rc_main
+    rc_main(args)
 
 
-def runpy(args):
+def runpy(args: List[str]) -> None:
     sys.argv = ['kitty'] + args[2:]
     exec(args[1])
 
 
-def launch(args):
+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:]
-    runpy.run_path(args[1], run_name='__main__')
+    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):
-    kitten = args[1]
+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
-    run_kitten(kitten)
+    from kittens.runner import run_kitten as rk
+    rk(kitten)
 
 
-def namespaced(args):
+def edit_config_file(args: List[str]) -> None:
+    from kitty.utils import edit_config_file as f
+    f()
+
+
+def namespaced(args: List[str]) -> None:
     func = namespaced_entry_points[args[1]]
     func(args[1:])
 
@@ -50,14 +82,33 @@ entry_points = {
     'runpy': runpy,
     'launch': launch,
     'kitten': run_kitten,
+    'edit-config': edit_config_file,
 
     '@': 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 main():
+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:
@@ -66,8 +117,8 @@ def main():
         elif first_arg.startswith('+'):
             namespaced(['+', first_arg[1:]] + sys.argv[2:])
         else:
-            from kitty.main import main
-            main()
+            from kitty.main import main as kitty_main
+            kitty_main()
     else:
         func(sys.argv[1:])
 

asan-launcher.c

@@ -1,19 +0,0 @@
-/*
- * linux-launcher.c
- * Copyright (C) 2017 Kovid Goyal <kovid at kovidgoyal.net>
- *
- * Distributed under terms of the GPL3 license.
- */
-
-#include <Python.h>
-
-#define MAX_ARGC 1024
-
-int main(int argc, char *argv[]) {
-    wchar_t *argvw[MAX_ARGC + 1] = {0};
-    argvw[0] = L"kitty";
-    for (int i = 1; i < argc; i++) argvw[i] = Py_DecodeLocale(argv[i], NULL);
-    int ret = Py_Main(argc, argvw);
-    for (int i = 1; i < argc; i++) PyMem_RawFree(argvw[i]);
-    return ret;
-}

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', '-x', '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/wcwidth-std.h\nkitty/glfw.c\nkitty/keys.h\nkitty/charsets.c\nkitty/unicode-data.c\nkitty/key_encoding.py\nkitty/rgb.py\nkitty/gl.h\nkitty/gl-wrapper.h\nkitty/gl-wrapper.c\nkitty/khrplatform.h\nkitty/glfw-wrapper.h\nkitty/glfw-wrapper.c\nkitty/emoji.h\nkittens/unicode_input/names.h') kitty kittens
+#!/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,126 @@
+/*
+ * 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;
+}
+
+div.body {
+    min-width: 200px;
+}
+
+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,135 @@
+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 ``libpython3-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>`_.
+
+Build and run from source with Nix
+-------------------------------------------
+
+On NixOS or any other Linux or macOS system with the Nix package manager
+installed, execute `nix-shell
+<https://nixos.org/guides/nix-pills/developing-with-nix-shell.html>`_ to create
+the correct environment to build kitty or use ``nix-shell --pure`` instead to
+eliminate most of the influence of the outside system, e.g. globally installed
+packages. ``nix-shell`` will automatically fetch all required dependencies and
+make them available in the newly spawned shell.
+
+Then proceed with ``make`` or ``make app`` according to the platform specific instructions above.
+
+
+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, version_info  # 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() if version_info[0] < 3 else 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() if version_info[0] < 3 else 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,280 @@
+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
+
+This ssh kitten takes all the same command line arguments
+as ssh, you can alias it to ssh in your shell's rc files to avoid having to
+type it each time.
+
+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.
+Furthermore, it needs fonts to be freely resizable, so it does not support
+bitmapped fonts.
+
+If your font is not listed in ``kitty list-fonts`` it means that it is not
+monospace or is a bitmapped font. 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="scan">
+        <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``
+
+How do I open a new window or tab with the same working directory as the current window?
+--------------------------------------------------------------------------------------------
+
+In :file:`kitty.conf` add the following::
+
+    map f1 launch --cwd=current
+    map f2  launch --cwd=current --type=tab
+
+Pressing :kbd:`F1` will open a new kitty window with the same working directory
+as the current window. The :doc:`launch command <launch>` is very powerful,
+explore :doc:`its documentation <launch>`.
+
+
+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,565 @@
+: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
+ * `viu <https://github.com/atanunq/viu>`_ - a terminal image viewer
+ * `glkitty <https://github.com/michaeljclark/glkitty>`_ - C library to draw OpenGL shaders in the terminal with a glgears demo
+
+
+.. 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;AAAA<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. Each such display of an image is called a *placement*.  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
+to the placement request 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.
+
+Since there can be many placements per image, you can also give placements an
+id. To do so add the ``p`` key with a number between ``1`` and ``4294967295``.
+When you specify a placement id, it will be added to the acknowledgement code
+above. Every placement is uniquely identified by the pair of the ``image id``
+and the ``placement id``. If you specify a placement id for an image that does
+not have an id, it will be ignored. An example response::
+
+    <ESC>_Gi=<image id>,p=<placement id>;OK<ESC>\
+
+If you send two placements with the same ``image id`` and ``placement id`` the
+second one will replace the first. This can be used to resize or move
+placements around the screen, without flicker.
+
+
+.. versionadded:: 0.19.3
+   Support for specifying placement ids (see :doc:`kittens/query_terminal` to query kitty version)
+
+
+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.
+
+.. note:: After placing an image on the screen the cursor must be moved to the
+   right by the number of cols in the image placement rectangle and down by the
+   number of rows in the image placement rectangle. If either of these cause
+   the cursor to leave either the screen or the scroll area, the exact
+   positioning of the cursor is undefined, and up to implementations.
+
+
+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 placements visible on screen
+``i`` or ``I``       Delete all images with the specified id, specified using the ``i`` key. If you specify a ``p`` key for the placement                      id as well, then only the placement with the specified image id and placement id will be deleted.
+``n`` or ``N``       Delete newest image with the specified number, specified using the ``I`` key. If you specify a ``p`` key for the
+                     placement id as well, then only the placement with the specified number and placement id will be deleted.
+``c`` or ``C``       Delete all placements that intersect with the current cursor position.
+``c`` or ``C``       Delete all placements that intersect with the current cursor position.
+``p`` or ``P``       Delete all placements that intersect a specific cell, the cell is specified using the ``x`` and ``y`` keys
+``q`` or ``Q``       Delete all placements 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 placements that intersect the specified column, specified using the ``x`` key.
+``y`` or ``Y``       Delete all placements that intersect the specified row, specified using the ``y`` key.
+``z`` or ``Z``       Delete all placements that have the specified z-index, specified using the ``z`` key.
+=================    ============
+
+
+Note when all placements for an image have been deleted, the image is also
+deleted, if the capital letter form above is specified. Also, when the terminal
+is running out of quota space for image, images without placements will be
+preferentially deleted.
+
+Some examples::
+
+    <ESC>_Ga=d<ESC>\              # delete all visible placements
+    <ESC>_Ga=d,d=i,i=10<ESC>\     # delete the image with id=10, without freeing data
+    <ESC>_Ga=d,d=i,i=10,p=7<ESC>\ # delete the image with id=10 and placement id=7, without freeing data
+    <ESC>_Ga=d,d=Z,z=-1<ESC>\     # delete the placements with z-index -1, also freeing up image data
+    <ESC>_Ga=d,d=p,x=3,y=4<ESC>\  # delete all placements that intersect the cell at (3, 4), without freeing data
+
+
+Suppressing responses from the terminal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are using the graphics protocol from a limited client, such as a shell
+script, it might be useful to avoid having to process responses from the
+terminal. For this, you can use the ``q`` key. Set it to ``1`` to suppress
+``OK`` responses and to ``2`` to suppress failure responses.
+
+.. versionadded:: 0.19.3
+   The ability to suppress responses (see :doc:`kittens/query_terminal` to query kitty version)
+
+
+Requesting image ids from the terminal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are writing a program that is going to share the screen with other
+programs and you still want to use image ids, it is not possible to know
+what image ids are free to use. In this case, instead of using the ``i``
+key to specify and image id use the ``I`` key to specify and image number
+instead. These numbers are not unique.
+When creating a new image, even if an existing image has the same number a new
+one is created. And the terminal will reply with the id of the newly created
+image. For example, when creating an image with ``I=13``, the terminal will
+send the response::
+
+    <ESC>_Gi=99,I=13;OK<ESC>\
+
+Here, the value of ``i`` is the id for the newly created image and the value of
+``I`` is the same as was sent in the creation command.
+
+All future commands that refer to images using the image number, such as
+creating placements or deleting images, will act on only the newest image with
+that number. This allows the client program to send a bunch of commands dealing
+with an image by image number without waiting for a response from the terminal
+with the image id. Once such a response is received, the client program should
+use the ``i`` key with the image id for all future communication.
+
+.. note:: Specifying both ``i`` and ``I`` keys in any command is an error. The
+   terminal must reply with an EINVAL error message, unless silenced.
+
+.. versionadded:: 0.19.3
+   The ability to use image numbers (see :doc:`kittens/query_terminal` to query kitty version)
+
+
+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)``
+
+``q``    ``0, 1, 2``           ``0``      Suppress responses from the terminal to this graphics command.
+
+**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
+``p``    Positive integer.
+         ``(0 - 4294967295)``  ``0``      The placement 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, n, N,
+         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,131 @@
+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
+
+`viu <https://github.com/atanunq/viu>`_
+    view images in the terminal, similar to kitty's icat, however also supports
+    displaying animated GIFs
+
+
+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)'
+
+`onefetch <https://github.com/o2sh/onefetch>`_
+    a tool to fetch information about your git repositories
+
+`wttr <https://github.com/chubin/wttr.in>`_
+    a tool to display weather information in your terminal with curl
+
+
+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.
+
+`glkitty <https://github.com/michaeljclark/glkitty>`_
+    C library to draw OpenGL shaders in the terminal with a glgears demo

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/broadcast.rst

@@ -0,0 +1,23 @@
+broadcast - type text in all kitty windows
+==================================================
+
+The ``broadcast`` kitten can be used to type text simultaneously in
+all kitty windows (or a subset as desired).
+
+To use it, simply create a mapping in :file:`kitty.conf` such as::
+
+    map F1 launch --allow-remote-control kitty +kitten broadcast
+
+Then press the :kbd:`F1` key and whatever you type in the newly created widow
+will be sent to all kitty windows.
+
+You can use the options described below to control which windows
+are selected.
+
+.. program:: kitty +kitten broadcast
+
+
+Command Line Interface
+--------------------------
+
+.. include:: /generated/cli-kitten-broadcast.rst

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,205 @@
+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
+
+    from typing import List
+    from kitty.boss import Boss
+
+    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: 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,95 @@
+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`.
+
+Pressing :sc:`open_selected_hyperlink` will open hyperlinks, i.e. a URL
+that has been marked as such by the program running in the terminal,
+for example, by ``ls --hyperlink=auto``. You can also :doc:`customize what actions are
+taken for different types of URLs <../open_actions>`.
+
+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,68 @@
+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 hyperlinked_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 that, instead of using an alias create a simple wrapper script named
+:file:`hg` somewhere in your ``PATH``:
+
+.. code-block:: sh
+
+    #!/bin/sh
+    exec kitty +kitten hyperlinked_grep "$@"
+
+Then, for example, for ZSH, add the following to :file:`.zshrc`::
+
+    compdef _rg hg
+
+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/query_terminal.rst

@@ -0,0 +1,21 @@
+Query terminal
+=================
+
+Used to query kitty from terminal programs about version, values of various
+runtime options controlling its features, etc.
+
+The querying is done using the (*semi*) standard XTGETTCAP escape sequence
+pioneered by XTerm, so it works over SSH as well. The downside is that it
+is slow, since it requires a roundtrip to the terminal emulator and back.
+
+If you want to do some of the same querying in your terminal program without
+depending on the kitten, you can do so, by processing the same escape codes.
+Search `this page <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>`_
+for *XTGETTCAP* to see the syntax for the escape code and read the source
+of this kitten to find the values of the keys for the various queries.
+
+
+Command Line Interface
+-------------------------
+
+.. include:: ../generated/cli-kitten-query_terminal.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,95 @@
+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``. You can add MIME types to kitty by creating the
+    :file:`mime.types` in the kitty configuration directory. Useful if your
+    system MIME database does not have definitions you need. This file is
+    in the standard format of one definition per line, like: ``text/plain rst
+    md``.
+
+``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,354 @@
+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 word consisting of characters 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
+returned 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 as 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,181 @@
+: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).
+
+.. note:: 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.
+
+.. note:: You dont need ``allow_remote_control`` to make this work as it is
+   limited to only programs running in that specific window. Be careful with
+   what programs you run in such windows, since they can effectively control
+   kitty, as if you were running with ``allow_remote_control`` turned on.
+
+
+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.
+
+.. note:: You do not need ``allow_remote_control`` to use these mappings,
+   as they are not actual remote programs, but are simply a way to resuse
+   the remote control infrastructure via keybings.
+
+
+Broadcasting what you type to all kitty windows
+--------------------------------------------------
+
+As a simple illustration of the power of remote control, lets
+have what we type sent to all open kitty windows. To do that define the
+following mapping in :file:`kitty.conf`::
+
+    map F1 launch --allow-remote-control kitty +kitten broadcast
+
+Now press, F1 and start typing, what you type will be sent to all windows,
+live, as you type it.
+
+
+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,281 @@
+#!/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('aAiIcCnNpPqQxXyYzZ')),
+        't': ('transmission_type', flag('dfts')),
+        'o': ('compressed', flag('z')),
+        'f': ('format', 'uint'),
+        'm': ('more', 'uint'),
+        'i': ('id', 'uint'),
+        'I': ('image_number', 'uint'),
+        'p': ('placement_id', 'uint'),
+        'q': ('quiet', '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

@@ -3,6 +3,7 @@
 # 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
@@ -11,20 +12,33 @@ 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, folder='UCD'):
+
+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):
-        data = open(local, 'rb').read()
+        with open(local, 'rb') as f:
+            data = f.read()
     else:
         data = urlopen(url).read()
-        open(local, 'wb').write(data)
+        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('#'):
@@ -32,21 +46,25 @@ def get_data(fname, folder='UCD'):
 
 
 # Map of class names to set of codepoints in class
-class_maps = {}
-name_map = {}
-word_search_map = defaultdict(set)
-marks = set()
+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():
+def parse_ucd() -> None:
 
-    def add_word(w, c):
+    def add_word(w: str, c: int) -> None:
         if c <= 32 or c == 127 or 128 <= c <= 159:
             return
-        word_search_map[w.lower()].add(c)
+        if len(w) > 1:
+            word_search_map[w.lower()].add(c)
 
-    first = None
+    first: Optional[int] = None
     for word, c in html5.items():
         if len(c) == 1:
             add_word(word.rstrip(';'), ord(c))
@@ -54,7 +72,9 @@ def parse_ucd():
     for line in get_data('ucd/UnicodeData.txt'):
         parts = [x.strip() for x in line.split(';')]
         codepoint = int(parts[0], 16)
-        name = parts[1]
+        name = parts[1] or parts[10]
+        if name == '<control>':
+            name = parts[10]
         if name:
             name_map[codepoint] = name
             for word in name.lower().split():
@@ -62,7 +82,7 @@ def parse_ucd():
         category = parts[2]
         s = class_maps.setdefault(category, set())
         desc = parts[1]
-        codepoints = (codepoint,)
+        codepoints: Union[Tuple[int, ...], Iterable[int]] = (codepoint,)
         if first is None:
             if desc.endswith(', First>'):
                 first = codepoint
@@ -75,45 +95,118 @@ def parse_ucd():
             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 split_two(line):
-    spec, rest = line.split(';', 1)
-    spec, rest = spec.strip(), rest.strip().split(' ', 1)[0].strip()
+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))
+        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, rest
+    return chars
 
 
-all_emoji = set()
-emoji_categories = {}
-emoji_presentation_bases = set()
+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
 
 
-def parse_emoji():
-    for line in get_data('emoji-data.txt', 'emoji'):
-        chars, rest = split_two(line)
-        s = emoji_categories.setdefault(rest, set())
-        s.update(chars)
-        all_emoji.update(chars)
-    for line in get_data('emoji-variation-sequences.txt', 'emoji'):
-        base, var, *rest = line.split()
-        if base.startswith('#'):
+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
-        base = int(base, 16)
-        if var.upper() == 'FE0F':
-            emoji_presentation_bases.add(base)
+        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, ambiguous = set(), set()
+doublewidth: Set[int] = set()
+ambiguous: Set[int] = set()
 
 
-def parse_eaw():
+def parse_eaw() -> None:
     global doublewidth, ambiguous
-    seen = set()
+    seen: Set[int] = set()
     for line in get_data('ucd/EastAsianWidth.txt'):
         chars, eaw = split_two(line)
         if eaw == 'A':
@@ -129,7 +222,7 @@ def parse_eaw():
     doublewidth |= set(range(0x30000, 0x3FFFD + 1)) - seen
 
 
-def get_ranges(items):
+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))
@@ -140,7 +233,7 @@ def get_ranges(items):
             yield a, b
 
 
-def write_case(spec, p):
+def write_case(spec: Union[Tuple, int], p: Callable) -> None:
     if isinstance(spec, tuple):
         p('\t\tcase 0x{:x} ... 0x{:x}:'.format(*spec))
     else:
@@ -148,25 +241,24 @@ def write_case(spec, p):
 
 
 @contextmanager
-def create_header(path, include_data_types=True):
-    f = open(path, 'w')
-    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')
-    f.close()
+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():
+def gen_emoji() -> None:
     with create_header('kitty/emoji.h') as p:
         p('static inline bool\nis_emoji(char_type code) {')
         p('\tswitch(code) {')
@@ -176,9 +268,10 @@ def gen_emoji():
         p('\t\tdefault: return false;')
         p('\t}')
         p('\treturn false;\n}')
-        p('static inline bool\nis_emoji_modifier(char_type code) {')
+
+        p('static inline bool\nis_symbol(char_type code) {')
         p('\tswitch(code) {')
-        for spec in get_ranges(list(emoji_categories['Emoji_Modifier'])):
+        for spec in get_ranges(list(all_symbols)):
             write_case(spec, p)
             p('\t\t\treturn true;')
         p('\t\tdefault: return false;')
@@ -186,28 +279,46 @@ def gen_emoji():
         p('\treturn false;\n}')
 
 
-def category_test(name, p, classes, comment, static=False):
-    static = 'static inline ' if static else ''
-    chars = set()
+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(f'\t\t\treturn true;')
+        p('\t\t\treturn true;')
     p('\t} // }}}\n')
     p('\treturn false;\n}\n')
 
 
-def codepoint_to_mark_map(p, mark_map):
+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]]
-            p(f'\t\tcase {spec[0]} ... {spec[1]}: return {s} + c - {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;')
@@ -215,12 +326,14 @@ def codepoint_to_mark_map(p, mark_map):
     return rmap
 
 
-def classes_to_regex(classes):
-    chars = set()
+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):
+    def as_string(codepoint: int) -> str:
         if codepoint < 256:
             return r'\x{:02x}'.format(codepoint)
         if codepoint <= 0xffff:
@@ -234,12 +347,24 @@ def classes_to_regex(classes):
             yield as_string(spec)
 
 
-def gen_ucd():
+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)')
-        category_test('is_ignored_char', p, 'Cc Cf Cs'.split(), 'Control characters (Cc Cf Cs)')
+        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)')
@@ -252,62 +377,124 @@ def gen_ucd():
         p('combining_type mark_for_codepoint(char_type c) {')
         rmap = codepoint_to_mark_map(p, mark_map)
         p('}\n')
-        if rmap[0xfe0e] != 1275:
+        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/url_hints/url_regex.py', 'w') as f:
-        f.write("url_delimiters = '{}'  # noqa".format(''.join(classes_to_regex(cz))))
+    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():
-    words = tuple(sorted(word_search_map))
-
+def gen_names() -> None:
     with create_header('kittens/unicode_input/names.h') as p:
-        cp_map = list(sorted(name_map))
-        p(f'static const char* name_map[{len(cp_map)}] = {{' ' // {{{')
-        for cp in cp_map:
+        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")
 
-        p(f'static const char* idx_to_word[{len(words)}] = ' '{ // {{{')
-        for s in words:
-            s = s.replace('"', '\\"')
-            p(f'\t"{s}",')
-        p("}; // }}}\n")
-
-        first_letters = {ord(w[0]) for w in words if ord(w[0]) < 256}
-        wmap = {w: i for i, w in enumerate(words)}
-        p(f'static const unsigned short* words_for_first_letter[256] = ' '{ // {{{')
-        for fl in range(0, 256):
-            if fl in first_letters:
-                winds = [str(wmap[w]) for w in words if w.startswith(chr(fl))]
-                p(f'\t(const unsigned short[{len(winds) + 1}]){{{len(winds)}, ', ', '.join(winds), '},')
-            else:
-                p('NULL,')
-        p("}; // }}}\n")
-
-        p(f'static const char_type* codepoints_for_word_idx[{len(words)}] = ' '{ // {{{')
-        for s in words:
-            cps = word_search_map[s]
-            a = ', '.join(map(str, cps))
-            p(f'\t(const char_type[{len(cps) + 1}]){{{len(cps)}, ', a, '},')
-        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, cp_map)
+        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')
 
-def gen_wcwidth():
-    seen = set()
+        # 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')
 
-    def add(p, comment, chars_, ret):
+        # 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)' + ' {{' '{')
@@ -318,24 +505,26 @@ def gen_wcwidth():
 
     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', emoji_categories['Emoji'] - emoji_categories['Emoji_Presentation'], 1)
+        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', emoji_categories['Emoji_Presentation'], 2)
+        add(p, 'Emoji Presentation', wide_emoji, 2)
 
-        add(p, 'Not assigned in the unicode character database', not_assigned, -1)
+        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 bool\nis_emoji_presentation_base(uint32_t code) {')
+        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)

glad/generate.py

@@ -8,9 +8,11 @@ import shlex
 import shutil
 import subprocess
 
+
 cmdline = (
-    'glad --profile core --out-path {dest} --api gl=3.3 --generator {generator} --spec gl'
-    ' --extensions GL_ARB_texture_storage,GL_ARB_copy_image,GL_ARB_multisample,GL_ARB_robustness,GL_KHR_debug'
+    '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'
 )
 
 
@@ -23,37 +25,21 @@ def regenerate():
     clean('out')
 
     subprocess.check_call(
-        shlex.split(cmdline.format(dest='out', generator='c-debug'))
+        shlex.split(cmdline.format(dest='out'))
     )
 
 
+def strip_trailing_whitespace(c):
+    return re.sub(r'\s+$', '', c, flags=re.MULTILINE) + '\n'
+
+
 def export():
-    c = open('out/src/glad.c', 'rb').read().decode('utf-8')
-    functions = []
+    with open('out/include/glad/gl.h', 'r', encoding='utf-8') as source:
+        data = source.read()
+        data = strip_trailing_whitespace(data)
 
-    def sub(m):
-        functions.append(m.group(2))
-        return m.group()
-
-    c = re.sub(r'^([A-Z0-9]+) glad_debug_([a-zA-Z0-9]+) = glad_debug_impl_\2;$', sub, c, flags=re.M)
-    switch = ['glad_debug_{0} = glad_{0}'.format(f) for f in functions]
-    c = c.replace('<glad/glad.h>', '"gl-wrapper.h"', 1)
-    c = '#pragma GCC diagnostic ignored "-Wpedantic"\n' + c
-    c += '''
-int
-init_glad(GLADloadproc load, int debug) {
-    int ret = gladLoadGLLoader(load);
-    if (ret && !debug) {
-        SUB;
-    }
-    return ret;
-}'''.replace('SUB', ';\n        '.join(switch), 1)
-    open('../kitty/gl-wrapper.c', 'w').write(c)
-    raw = open('out/include/glad/glad.h').read()
-    raw = raw.replace('<KHR/khrplatform.h>', '"khrplatform.h"')
-    raw += '\nint init_glad(GLADloadproc, int);\n'
-    open('../kitty/gl-wrapper.h', 'w').write(raw)
-    shutil.copy2('out/include/KHR/khrplatform.h', '../kitty')
+        with open('../kitty/gl-wrapper.h', 'w', encoding='utf-8') as dest:
+            dest.write(data)
 
 
 if __name__ == '__main__':

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

@@ -1,7 +1,7 @@
 //========================================================================
-// GLFW 3.3 macOS - www.glfw.org
+// GLFW 3.4 macOS - www.glfw.org
 //------------------------------------------------------------------------
-// Copyright (c) 2009-2016 Camilla Löwy <elmindreda@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
@@ -23,10 +23,16 @@
 //    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
 //
@@ -64,15 +70,119 @@ static void changeToResourcesDirectory(void)
     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 scancode;
-    _glfw.ns.debug_keyboard = getenv("GLFW_DEBUG_KEYBOARD") != NULL;
+    int keycode;
 
     memset(_glfw.ns.keycodes, -1, sizeof(_glfw.ns.keycodes));
-    memset(_glfw.ns.scancodes, -1, sizeof(_glfw.ns.scancodes));
+    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;
@@ -189,17 +299,17 @@ static void createKeyTables(void)
     _glfw.ns.keycodes[0x43] = GLFW_KEY_KP_MULTIPLY;
     _glfw.ns.keycodes[0x4E] = GLFW_KEY_KP_SUBTRACT;
 
-    for (scancode = 0;  scancode < 256;  scancode++)
+    for (keycode = 0; keycode < 256; keycode++)
     {
         // Store the reverse translation for faster key name lookup
-        if (_glfw.ns.keycodes[scancode] >= 0)
-            _glfw.ns.scancodes[_glfw.ns.keycodes[scancode]] = scancode;
+        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 GLFWbool updateUnicodeDataNS(void)
+static bool updateUnicodeDataNS(void)
 {
     if (_glfw.ns.inputSource)
     {
@@ -208,12 +318,15 @@ static GLFWbool updateUnicodeDataNS(void)
         _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 GLFW_FALSE;
+        return false;
     }
 
     _glfw.ns.unicodeData =
@@ -223,15 +336,15 @@ static GLFWbool updateUnicodeDataNS(void)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
                         "Cocoa: Failed to retrieve keyboard layout Unicode data");
-        return GLFW_FALSE;
+        return false;
     }
 
-    return GLFW_TRUE;
+    return true;
 }
 
 // Load HIToolbox.framework and the TIS symbols we need from it
 //
-static GLFWbool initializeTIS(void)
+static bool initializeTIS(void)
 {
     // This works only because Cocoa has already loaded it properly
     _glfw.ns.tis.bundle =
@@ -240,19 +353,19 @@ static GLFWbool initializeTIS(void)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
                         "Cocoa: Failed to load HIToolbox.framework");
-        return GLFW_FALSE;
+        return false;
     }
 
     CFStringRef* kPropertyUnicodeKeyLayoutData =
         CFBundleGetDataPointerForName(_glfw.ns.tis.bundle,
                                       CFSTR("kTISPropertyUnicodeKeyLayoutData"));
-    _glfw.ns.tis.CopyCurrentKeyboardLayoutInputSource =
+    *(void **)&_glfw.ns.tis.CopyCurrentKeyboardLayoutInputSource =
         CFBundleGetFunctionPointerForName(_glfw.ns.tis.bundle,
                                           CFSTR("TISCopyCurrentKeyboardLayoutInputSource"));
-    _glfw.ns.tis.GetInputSourceProperty =
+    *(void **)&_glfw.ns.tis.GetInputSourceProperty =
         CFBundleGetFunctionPointerForName(_glfw.ns.tis.bundle,
                                           CFSTR("TISGetInputSourceProperty"));
-    _glfw.ns.tis.GetKbdType =
+    *(void **)&_glfw.ns.tis.GetKbdType =
         CFBundleGetFunctionPointerForName(_glfw.ns.tis.bundle,
                                           CFSTR("LMGetKbdType"));
 
@@ -263,7 +376,7 @@ static GLFWbool initializeTIS(void)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
                         "Cocoa: Failed to load TIS API symbols");
-        return GLFW_FALSE;
+        return false;
     }
 
     _glfw.ns.tis.kPropertyUnicodeKeyLayoutData =
@@ -272,33 +385,275 @@ static GLFWbool initializeTIS(void)
     return updateUnicodeDataNS();
 }
 
-@interface GLFWLayoutListener : NSObject
+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 GLFWLayoutListener
+@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)
 {
-    _glfw.ns.autoreleasePool = [[NSAutoreleasePool alloc] init];
+    @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();
 
-    _glfw.ns.listener = [[GLFWLayoutListener alloc] init];
+    // Press and Hold prevents some keys from emitting repeated characters
+    NSDictionary* defaults = @{@"ApplePressAndHoldEnabled":@NO};
+    [[NSUserDefaults standardUserDefaults] registerDefaults:defaults];
+
     [[NSNotificationCenter defaultCenter]
-        addObserver:_glfw.ns.listener
+        addObserver:_glfw.ns.helper
            selector:@selector(selectedKeyboardInputSourceChanged:)
                name:NSTextInputContextKeyboardSelectionDidChangeNotification
              object:nil];
@@ -307,22 +662,25 @@ int _glfwPlatformInit(void)
 
     _glfw.ns.eventSource = CGEventSourceCreate(kCGEventSourceStateHIDSystemState);
     if (!_glfw.ns.eventSource)
-        return GLFW_FALSE;
+        return false;
 
     CGEventSourceSetLocalEventsSuppressionInterval(_glfw.ns.eventSource, 0.0);
 
     if (!initializeTIS())
-        return GLFW_FALSE;
-
-    _glfwInitTimerNS();
-    _glfwInitJoysticksNS();
+        return false;
 
     _glfwPollMonitorsNS();
-    return GLFW_TRUE;
+    return true;
+
+    } // autoreleasepool
 }
 
 void _glfwPlatformTerminate(void)
 {
+    @autoreleasepool {
+
+    _glfwClearDisplayLinks();
+
     if (_glfw.ns.inputSource)
     {
         CFRelease(_glfw.ns.inputSource);
@@ -343,32 +701,164 @@ void _glfwPlatformTerminate(void)
         _glfw.ns.delegate = nil;
     }
 
-    if (_glfw.ns.listener)
+    if (_glfw.ns.helper)
     {
         [[NSNotificationCenter defaultCenter]
-            removeObserver:_glfw.ns.listener
+            removeObserver:_glfw.ns.helper
                       name:NSTextInputContextKeyboardSelectionDidChangeNotification
                     object:nil];
         [[NSNotificationCenter defaultCenter]
-            removeObserver:_glfw.ns.listener];
-        [_glfw.ns.listener release];
-        _glfw.ns.listener = nil;
+            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();
-    _glfwTerminateJoysticksNS();
 
-    [_glfw.ns.autoreleasePool release];
-    _glfw.ns.autoreleasePool = nil;
+    } // autoreleasepool
 }
 
 const char* _glfwPlatformGetVersionString(void)
 {
-    return _GLFW_VERSION_NUMBER " Cocoa NSGL"
+    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

@@ -1,7 +1,7 @@
 //========================================================================
-// GLFW 3.3 Cocoa - www.glfw.org
+// GLFW 3.4 Cocoa - www.glfw.org
 //------------------------------------------------------------------------
-// Copyright (c) 2006-2016 Camilla Löwy <elmindreda@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
@@ -44,7 +44,3 @@ typedef struct _GLFWjoystickNS
     CFMutableArrayRef   hats;
 } _GLFWjoystickNS;
 
-
-void _glfwInitJoysticksNS(void);
-void _glfwTerminateJoysticksNS(void);
-

glfw/cocoa_joystick.m

@@ -1,7 +1,7 @@
 //========================================================================
-// GLFW 3.3 Cocoa - www.glfw.org
+// GLFW 3.4 Cocoa - www.glfw.org
 //------------------------------------------------------------------------
-// Copyright (c) 2009-2016 Camilla Löwy <elmindreda@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
@@ -24,6 +24,8 @@
 //    distribution.
 //
 //========================================================================
+// It is fine to use C99 in this file because it will not be built with VS
+//========================================================================
 
 #include "internal.h"
 
@@ -75,7 +77,7 @@ static long getElementValue(_GLFWjoystick* js, _GLFWjoyelementNS* element)
 //
 static CFComparisonResult compareElements(const void* fp,
                                           const void* sp,
-                                          void* user)
+                                          void* user UNUSED)
 {
     const _GLFWjoyelementNS* fe = fp;
     const _GLFWjoyelementNS* se = sp;
@@ -117,9 +119,9 @@ static void closeJoystick(_GLFWjoystick* js)
 
 // Callback for user-initiated joystick addition
 //
-static void matchCallback(void* context,
-                          IOReturn result,
-                          void* sender,
+static void matchCallback(void* context UNUSED,
+                          IOReturn result UNUSED,
+                          void* sender UNUSED,
                           IOHIDDeviceRef device)
 {
     int jid;
@@ -220,9 +222,31 @@ static void matchCallback(void* context,
                 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_Button)
+        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)
@@ -261,9 +285,9 @@ static void matchCallback(void* context,
 
 // Callback for user-initiated joystick removal
 //
-static void removeCallback(void* context,
-                           IOReturn result,
-                           void* sender,
+static void removeCallback(void* context UNUSED,
+                           IOReturn result UNUSED,
+                           void* sender UNUSED,
                            IOHIDDeviceRef device)
 {
     int jid;
@@ -280,12 +304,10 @@ static void removeCallback(void* context,
 
 
 //////////////////////////////////////////////////////////////////////////
-//////                       GLFW internal API                      //////
+//////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
 
-// Initialize joystick interface
-//
-void _glfwInitJoysticksNS(void)
+bool _glfwPlatformInitJoysticks(void)
 {
     CFMutableArrayRef matching;
     const long usages[] =
@@ -304,10 +326,10 @@ void _glfwInitJoysticksNS(void)
     if (!matching)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR, "Cocoa: Failed to create array");
-        return;
+        return false;
     }
 
-    for (int i = 0;  i < sizeof(usages) / sizeof(long);  i++)
+    for (size_t i = 0;  i < sizeof(usages) / sizeof(long);  i++)
     {
         const long page = kHIDPage_GenericDesktop;
 
@@ -359,26 +381,24 @@ void _glfwInitJoysticksNS(void)
     // Execute the run loop once in order to register any initially-attached
     // joysticks
     CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0, false);
+    return true;
 }
 
-// Close all opened joystick handles
-//
-void _glfwTerminateJoysticksNS(void)
+void _glfwPlatformTerminateJoysticks(void)
 {
     int jid;
 
     for (jid = 0;  jid <= GLFW_JOYSTICK_LAST;  jid++)
         closeJoystick(_glfw.joysticks + jid);
 
-    CFRelease(_glfw.ns.hidManager);
-    _glfw.ns.hidManager = NULL;
+    if (_glfw.ns.hidManager)
+    {
+        CFRelease(_glfw.ns.hidManager);
+        _glfw.ns.hidManager = NULL;
+    }
 }
 
 
-//////////////////////////////////////////////////////////////////////////
-//////                       GLFW platform API                      //////
-//////////////////////////////////////////////////////////////////////////
-
 int _glfwPlatformPollJoystick(_GLFWjoystick* js, int mode)
 {
     if (mode & _GLFW_POLL_AXES)
@@ -397,12 +417,12 @@ int _glfwPlatformPollJoystick(_GLFWjoystick* js, int mode)
             if (raw > axis->maximum)
                 axis->maximum = raw;
 
-            const long delta = axis->maximum - axis->minimum;
-            if (delta == 0)
+            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) / delta) - 1.f;
+                const float value = (2.f * (raw - axis->minimum) / size) - 1.f;
                 _glfwInputJoystickAxis(js, (int) i, value);
             }
         }
@@ -417,7 +437,8 @@ int _glfwPlatformPollJoystick(_GLFWjoystick* js, int mode)
             _GLFWjoyelementNS* button = (_GLFWjoyelementNS*)
                 CFArrayGetValueAtIndex(js->ns.buttons, i);
             const char value = getElementValue(js, button) - button->minimum;
-            _glfwInputJoystickButton(js, (int) i, value);
+            const int state = (value > 0) ? GLFW_PRESS : GLFW_RELEASE;
+            _glfwInputJoystickButton(js, (int) i, state);
         }
 
         for (i = 0;  i < CFArrayGetCount(js->ns.hats);  i++)
@@ -454,9 +475,8 @@ void _glfwPlatformUpdateGamepadGUID(char* guid)
         (strncmp(guid + 20, "000000000000", 12) == 0))
     {
         char original[33];
-        strcpy(original, guid);
+        strncpy(original, guid, sizeof(original) - 1);
         sprintf(guid, "03000000%.4s0000%.4s000000000000",
                 original, original + 16);
     }
 }
-

glfw/cocoa_monitor.m

@@ -1,8 +1,8 @@
 //========================================================================
-// GLFW 3.3 macOS - www.glfw.org
+// GLFW 3.4 macOS - www.glfw.org
 //------------------------------------------------------------------------
 // Copyright (c) 2002-2006 Marcus Geelnard
-// Copyright (c) 2006-2016 Camilla Löwy <elmindreda@glfw.org>
+// 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
@@ -24,11 +24,14 @@
 //    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>
@@ -115,16 +118,16 @@ static char* getDisplayName(CGDirectDisplayID displayID)
 
 // Check whether the display mode should be included in enumeration
 //
-static GLFWbool modeIsGood(CGDisplayModeRef mode)
+static bool modeIsGood(CGDisplayModeRef mode)
 {
     uint32_t flags = CGDisplayModeGetIOFlags(mode);
 
     if (!(flags & kDisplayModeValidFlag) || !(flags & kDisplayModeSafeFlag))
-        return GLFW_FALSE;
+        return false;
     if (flags & kDisplayModeInterlacedFlag)
-        return GLFW_FALSE;
+        return false;
     if (flags & kDisplayModeStretchedFlag)
-        return GLFW_FALSE;
+        return false;
 
 #if MAC_OS_X_VERSION_MAX_ALLOWED <= 101100
     CFStringRef format = CGDisplayModeCopyPixelEncoding(mode);
@@ -132,30 +135,26 @@ static GLFWbool modeIsGood(CGDisplayModeRef mode)
         CFStringCompare(format, CFSTR(IO32BitDirectPixels), 0))
     {
         CFRelease(format);
-        return GLFW_FALSE;
+        return false;
     }
 
     CFRelease(format);
 #endif /* MAC_OS_X_VERSION_MAX_ALLOWED */
-    return GLFW_TRUE;
+    return true;
 }
 
 // Convert Core Graphics display mode to GLFW video mode
 //
 static GLFWvidmode vidmodeFromCGDisplayMode(CGDisplayModeRef mode,
-                                            CVDisplayLinkRef link)
+                                            double fallbackRefreshRate)
 {
     GLFWvidmode result;
     result.width = (int) CGDisplayModeGetWidth(mode);
     result.height = (int) CGDisplayModeGetHeight(mode);
-    result.refreshRate = (int) CGDisplayModeGetRefreshRate(mode);
+    result.refreshRate = (int) round(CGDisplayModeGetRefreshRate(mode));
 
     if (result.refreshRate == 0)
-    {
-        const CVTime time = CVDisplayLinkGetNominalOutputVideoRefreshPeriod(link);
-        if (!(time.flags & kCVTimeIsIndefinite))
-            result.refreshRate = (int) (time.timeScale / (double) time.timeValue);
-    }
+        result.refreshRate = (int) round(fallbackRefreshRate);
 
 #if MAC_OS_X_VERSION_MAX_ALLOWED <= 101100
     CFStringRef format = CGDisplayModeCopyPixelEncoding(mode);
@@ -212,27 +211,156 @@ static void endFadeReservation(CGDisplayFadeReservationToken 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 i, j, displayCount, disconnectedCount;
-    CGDirectDisplayID* displays;
-    _GLFWmonitor** disconnected = NULL;
+    uint32_t displayCount;
 
     CGGetOnlineDisplayList(0, NULL, &displayCount);
-    displays = calloc(displayCount, sizeof(CGDirectDisplayID));
+    CGDirectDisplayID* displays = calloc(displayCount, sizeof(CGDirectDisplayID));
     CGGetOnlineDisplayList(displayCount, displays, &displayCount);
+    _glfwClearDisplayLinks();
 
-    for (i = 0;  i < _glfw.monitorCount;  i++)
+    for (int i = 0;  i < _glfw.monitorCount;  i++)
         _glfw.monitors[i]->ns.screen = nil;
 
-    disconnectedCount = _glfw.monitorCount;
+    _GLFWmonitor** disconnected = NULL;
+    uint32_t disconnectedCount = _glfw.monitorCount;
     if (disconnectedCount)
     {
         disconnected = calloc(_glfw.monitorCount, sizeof(_GLFWmonitor*));
@@ -241,19 +369,18 @@ void _glfwPollMonitorsNS(void)
                _glfw.monitorCount * sizeof(_GLFWmonitor*));
     }
 
-    for (i = 0;  i < displayCount;  i++)
+    for (uint32_t i = 0;  i < displayCount;  i++)
     {
-        _GLFWmonitor* monitor;
-        const uint32_t unitNumber = CGDisplayUnitNumber(displays[i]);
-
         if (CGDisplayIsAsleep(displays[i]))
             continue;
 
-        for (j = 0;  j < disconnectedCount;  j++)
+        // 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++)
         {
-            // HACK: Compare unit numbers instead of display IDs to work around
-            //       display replacement on machines with automatic graphics
-            //       switching
             if (disconnected[j] && disconnected[j]->ns.unitNumber == unitNumber)
             {
                 disconnected[j] = NULL;
@@ -266,16 +393,22 @@ void _glfwPollMonitorsNS(void)
         if (!name)
             name = _glfw_strdup("Unknown");
 
-        monitor = _glfwAllocMonitor(name, size.width, size.height);
+        _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 (i = 0;  i < disconnectedCount;  i++)
+    for (uint32_t i = 0;  i < disconnectedCount;  i++)
     {
         if (disconnected[i])
             _glfwInputMonitor(disconnected[i], GLFW_DISCONNECTED, 0);
@@ -283,36 +416,32 @@ void _glfwPollMonitorsNS(void)
 
     free(disconnected);
     free(displays);
+    _glfwRestartDisplayLinks();
 }
 
 // Change the current video mode
 //
 void _glfwSetVideoModeNS(_GLFWmonitor* monitor, const GLFWvidmode* desired)
 {
-    CFArrayRef modes;
-    CFIndex count, i;
-    CVDisplayLinkRef link;
-    CGDisplayModeRef native = NULL;
     GLFWvidmode current;
-    const GLFWvidmode* best;
-
-    best = _glfwChooseVideoMode(monitor, desired);
     _glfwPlatformGetVideoMode(monitor, &current);
+
+    const GLFWvidmode* best = _glfwChooseVideoMode(monitor, desired);
     if (_glfwCompareVideoModes(&current, best) == 0)
         return;
 
-    CVDisplayLinkCreateWithCGDisplay(monitor->ns.displayID, &link);
+    CFArrayRef modes = CGDisplayCopyAllDisplayModes(monitor->ns.displayID, NULL);
+    const CFIndex count = CFArrayGetCount(modes);
+    CGDisplayModeRef native = NULL;
 
-    modes = CGDisplayCopyAllDisplayModes(monitor->ns.displayID, NULL);
-    count = CFArrayGetCount(modes);
-
-    for (i = 0;  i < count;  i++)
+    for (CFIndex i = 0;  i < count;  i++)
     {
         CGDisplayModeRef dm = (CGDisplayModeRef) CFArrayGetValueAtIndex(modes, i);
         if (!modeIsGood(dm))
             continue;
 
-        const GLFWvidmode mode = vidmodeFromCGDisplayMode(dm, link);
+        const GLFWvidmode mode =
+            vidmodeFromCGDisplayMode(dm, monitor->ns.fallbackRefreshRate);
         if (_glfwCompareVideoModes(best, &mode) == 0)
         {
             native = dm;
@@ -331,7 +460,6 @@ void _glfwSetVideoModeNS(_GLFWmonitor* monitor, const GLFWvidmode* desired)
     }
 
     CFRelease(modes);
-    CVDisplayLinkRelease(link);
 }
 
 // Restore the previously saved (original) video mode
@@ -355,7 +483,7 @@ void _glfwRestoreVideoModeNS(_GLFWmonitor* monitor)
 //////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
 
-void _glfwPlatformFreeMonitor(_GLFWmonitor* monitor)
+void _glfwPlatformFreeMonitor(_GLFWmonitor* monitor UNUSED)
 {
 }
 
@@ -372,35 +500,8 @@ void _glfwPlatformGetMonitorPos(_GLFWmonitor* monitor, int* xpos, int* ypos)
 void _glfwPlatformGetMonitorContentScale(_GLFWmonitor* monitor,
                                          float* xscale, float* yscale)
 {
-    if (!monitor->ns.screen)
-    {
-        NSUInteger i;
-        NSArray* screens = [NSScreen screens];
-
-        for (i = 0;  i < [screens count];  i++)
-        {
-            NSScreen* screen = [screens objectAtIndex:i];
-            NSNumber* displayID =
-                [[screen deviceDescription] objectForKey:@"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;
-                break;
-            }
-        }
-
-        if (i == [screens count])
-        {
-            _glfwInputError(GLFW_PLATFORM_ERROR,
-                            "Cocoa: Failed to find a screen for monitor");
-            return;
-        }
-    }
+    if (!refreshMonitorScreen(monitor))
+        return;
 
     const NSRect points = [monitor->ns.screen frame];
     const NSRect pixels = [monitor->ns.screen convertRectToBacking:points];
@@ -411,30 +512,43 @@ void _glfwPlatformGetMonitorContentScale(_GLFWmonitor* monitor,
         *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)
 {
-    CFArrayRef modes;
-    CFIndex found, i, j;
-    GLFWvidmode* result;
-    CVDisplayLinkRef link;
-
     *count = 0;
 
-    CVDisplayLinkCreateWithCGDisplay(monitor->ns.displayID, &link);
+    CFArrayRef modes = CGDisplayCopyAllDisplayModes(monitor->ns.displayID, NULL);
+    const CFIndex found = CFArrayGetCount(modes);
+    GLFWvidmode* result = calloc(found, sizeof(GLFWvidmode));
 
-    modes = CGDisplayCopyAllDisplayModes(monitor->ns.displayID, NULL);
-    found = CFArrayGetCount(modes);
-    result = calloc(found, sizeof(GLFWvidmode));
-
-    for (i = 0;  i < found;  i++)
+    for (CFIndex i = 0;  i < found;  i++)
     {
         CGDisplayModeRef dm = (CGDisplayModeRef) CFArrayGetValueAtIndex(modes, i);
         if (!modeIsGood(dm))
             continue;
 
-        const GLFWvidmode mode = vidmodeFromCGDisplayMode(dm, link);
+        const GLFWvidmode mode =
+            vidmodeFromCGDisplayMode(dm, monitor->ns.fallbackRefreshRate);
 
-        for (j = 0;  j < *count;  j++)
+        for (CFIndex j = 0;  j < *count;  j++)
         {
             if (_glfwCompareVideoModes(result + j, &mode) == 0)
                 break;
@@ -449,27 +563,19 @@ GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count)
     }
 
     CFRelease(modes);
-    CVDisplayLinkRelease(link);
     return result;
 }
 
 void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode *mode)
 {
-    CGDisplayModeRef displayMode;
-    CVDisplayLinkRef link;
-
-    CVDisplayLinkCreateWithCGDisplay(monitor->ns.displayID, &link);
-
-    displayMode = CGDisplayCopyDisplayMode(monitor->ns.displayID);
-    *mode = vidmodeFromCGDisplayMode(displayMode, link);
-    CGDisplayModeRelease(displayMode);
-
-    CVDisplayLinkRelease(link);
+    CGDisplayModeRef native = CGDisplayCopyDisplayMode(monitor->ns.displayID);
+    *mode = vidmodeFromCGDisplayMode(native, monitor->ns.fallbackRefreshRate);
+    CGDisplayModeRelease(native);
 }
 
-void _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp)
+bool _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp)
 {
-    uint32_t i, size = CGDisplayGammaTableCapacity(monitor->ns.displayID);
+    uint32_t size = CGDisplayGammaTableCapacity(monitor->ns.displayID);
     CGGammaValue* values = calloc(size * 3, sizeof(CGGammaValue));
 
     CGGetDisplayTransferByTable(monitor->ns.displayID,
@@ -481,7 +587,7 @@ void _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp)
 
     _glfwAllocGammaArrays(ramp, size);
 
-    for (i = 0; i < size; i++)
+    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);
@@ -489,14 +595,14 @@ void _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp)
     }
 
     free(values);
+    return true;
 }
 
 void _glfwPlatformSetGammaRamp(_GLFWmonitor* monitor, const GLFWgammaramp* ramp)
 {
-    int i;
     CGGammaValue* values = calloc(ramp->size * 3, sizeof(CGGammaValue));
 
-    for (i = 0;  i < ramp->size;  i++)
+    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;
@@ -523,4 +629,3 @@ GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* handle)
     _GLFW_REQUIRE_INIT_OR_RETURN(kCGNullDirectDisplay);
     return monitor->ns.displayID;
 }
-

glfw/cocoa_platform.h

@@ -1,7 +1,7 @@
 //========================================================================
-// GLFW 3.3 macOS - www.glfw.org
+// GLFW 3.4 macOS - www.glfw.org
 //------------------------------------------------------------------------
-// Copyright (c) 2009-2016 Camilla Löwy <elmindreda@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
@@ -27,16 +27,52 @@
 #include <stdint.h>
 #include <dlfcn.h>
 
-#if defined(__OBJC__)
-#import <Carbon/Carbon.h>
-#import <Cocoa/Cocoa.h>
-#else
 #include <Carbon/Carbon.h>
-#include <ApplicationServices/ApplicationServices.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
 {
@@ -46,21 +82,25 @@ typedef struct VkMacOSSurfaceCreateInfoMVK
     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"
-#include "egl_context.h"
-#include "osmesa_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_EGL_NATIVE_WINDOW  ((EGLNativeWindowType) window->ns.view)
-#define _GLFW_EGL_NATIVE_DISPLAY EGL_DEFAULT_DISPLAY
-
 #define _GLFW_PLATFORM_WINDOW_STATE         _GLFWwindowNS  ns
 #define _GLFW_PLATFORM_LIBRARY_WINDOW_STATE _GLFWlibraryNS ns
 #define _GLFW_PLATFORM_LIBRARY_TIMER_STATE  _GLFWtimerNS   ns
@@ -86,7 +126,11 @@ typedef struct _GLFWwindowNS
     id              view;
     id              layer;
 
-    GLFWbool        maximized;
+    bool            maximized;
+    bool            retina;
+    bool            in_traditional_fullscreen;
+    bool            titlebar_hidden;
+    unsigned long   pre_full_screen_style_mask;
 
     // Cached window properties to filter out duplicate events
     int             width, height;
@@ -98,26 +142,44 @@ typedef struct _GLFWwindowNS
     // 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;
-    id                  autoreleasePool;
-    GLFWbool            cursorHidden;
+    bool                finishedLaunching;
+    bool                cursorHidden;
     TISInputSourceRef   inputSource;
     IOHIDManagerRef     hidManager;
     id                  unicodeData;
-    id                  listener;
+    id                  helper;
+    id                  keyUpMonitor;
+    id                  keyDownMonitor;
+    id                  nibObjects;
 
     char                keyName[64];
     char                text[256];
-    GLFWbool            debug_keyboard;
     short int           keycodes[256];
-    short int           scancodes[GLFW_KEY_LAST + 1];
+    short int           key_to_keycode[GLFW_KEY_LAST + 1];
     char*               clipboardString;
     CGPoint             cascadePoint;
     // Where to place the cursor when re-enabled
@@ -133,6 +195,11 @@ typedef struct _GLFWlibraryNS
         CFStringRef     kPropertyUnicodeKeyLayoutData;
     } tis;
 
+    struct {
+        _GLFWDisplayLinkNS entries[256];
+        size_t count;
+    } displayLinks;
+
 } _GLFWlibraryNS;
 
 // Cocoa-specific per-monitor data
@@ -143,6 +210,7 @@ typedef struct _GLFWmonitorNS
     CGDisplayModeRef    previousMode;
     uint32_t            unitNumber;
     id                  screen;
+    double              fallbackRefreshRate;
 
 } _GLFWmonitorNS;
 
@@ -163,8 +231,17 @@ typedef struct _GLFWtimerNS
 } _GLFWtimerNS;
 
 
-void _glfwInitTimerNS(void);
-
 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/cocoa_time.c

@@ -1,60 +0,0 @@
-//========================================================================
-// GLFW 3.3 macOS - www.glfw.org
-//------------------------------------------------------------------------
-// Copyright (c) 2009-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.
-//
-//========================================================================
-
-#include "internal.h"
-
-#include <mach/mach_time.h>
-
-
-//////////////////////////////////////////////////////////////////////////
-//////                       GLFW internal API                      //////
-//////////////////////////////////////////////////////////////////////////
-
-// Initialise timer
-//
-void _glfwInitTimerNS(void)
-{
-    mach_timebase_info_data_t info;
-    mach_timebase_info(&info);
-
-    _glfw.timer.ns.frequency = (info.denom * 1e9) / info.numer;
-}
-
-
-//////////////////////////////////////////////////////////////////////////
-//////                       GLFW platform API                      //////
-//////////////////////////////////////////////////////////////////////////
-
-uint64_t _glfwPlatformGetTimerValue(void)
-{
-    return mach_absolute_time();
-}
-
-uint64_t _glfwPlatformGetTimerFrequency(void)
-{
-    return _glfw.timer.ns.frequency;
-}
-

glfw/context.c

@@ -1,5 +1,5 @@
 //========================================================================
-// GLFW 3.3 - www.glfw.org
+// GLFW 3.4 - www.glfw.org
 //------------------------------------------------------------------------
 // Copyright (c) 2002-2006 Marcus Geelnard
 // Copyright (c) 2006-2016 Camilla Löwy <elmindreda@glfw.org>
@@ -24,6 +24,8 @@
 //    distribution.
 //
 //========================================================================
+// Please use C89 style variable declarations in this file because VS 2010
+//========================================================================
 
 #include "internal.h"
 
@@ -44,7 +46,7 @@
 // exists and whether all relevant options have supported and non-conflicting
 // values
 //
-GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
+bool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
 {
     if (ctxconfig->share)
     {
@@ -52,7 +54,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
             ctxconfig->share->context.client == GLFW_NO_API)
         {
             _glfwInputError(GLFW_NO_WINDOW_CONTEXT, NULL);
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -63,7 +65,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
         _glfwInputError(GLFW_INVALID_ENUM,
                         "Invalid context creation API 0x%08X",
                         ctxconfig->source);
-        return GLFW_FALSE;
+        return false;
     }
 
     if (ctxconfig->client != GLFW_NO_API &&
@@ -73,7 +75,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
         _glfwInputError(GLFW_INVALID_ENUM,
                         "Invalid client API 0x%08X",
                         ctxconfig->client);
-        return GLFW_FALSE;
+        return false;
     }
 
     if (ctxconfig->client == GLFW_OPENGL_API)
@@ -92,7 +94,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
             _glfwInputError(GLFW_INVALID_VALUE,
                             "Invalid OpenGL version %i.%i",
                             ctxconfig->major, ctxconfig->minor);
-            return GLFW_FALSE;
+            return false;
         }
 
         if (ctxconfig->profile)
@@ -103,7 +105,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
                 _glfwInputError(GLFW_INVALID_ENUM,
                                 "Invalid OpenGL profile 0x%08X",
                                 ctxconfig->profile);
-                return GLFW_FALSE;
+                return false;
             }
 
             if (ctxconfig->major <= 2 ||
@@ -114,7 +116,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
 
                 _glfwInputError(GLFW_INVALID_VALUE,
                                 "Context profiles are only defined for OpenGL version 3.2 and above");
-                return GLFW_FALSE;
+                return false;
             }
         }
 
@@ -123,7 +125,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
             // 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 GLFW_FALSE;
+            return false;
         }
     }
     else if (ctxconfig->client == GLFW_OPENGL_ES_API)
@@ -140,7 +142,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
             _glfwInputError(GLFW_INVALID_VALUE,
                             "Invalid OpenGL ES version %i.%i",
                             ctxconfig->major, ctxconfig->minor);
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -152,7 +154,7 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
             _glfwInputError(GLFW_INVALID_ENUM,
                             "Invalid context robustness mode 0x%08X",
                             ctxconfig->robustness);
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -164,184 +166,16 @@ GLFWbool _glfwIsValidContextConfig(const _GLFWctxconfig* ctxconfig)
             _glfwInputError(GLFW_INVALID_ENUM,
                             "Invalid context release behavior 0x%08X",
                             ctxconfig->release);
-            return GLFW_FALSE;
+            return false;
         }
     }
 
-    return GLFW_TRUE;
-}
-
-// Chooses the framebuffer config that best matches the desired one
-//
-const _GLFWfbconfig* _glfwChooseFBConfig(const _GLFWfbconfig* desired,
-                                         const _GLFWfbconfig* alternatives,
-                                         unsigned int count)
-{
-    unsigned int i;
-    unsigned int missing, leastMissing = UINT_MAX;
-    unsigned int colorDiff, leastColorDiff = UINT_MAX;
-    unsigned int extraDiff, leastExtraDiff = UINT_MAX;
-    const _GLFWfbconfig* current;
-    const _GLFWfbconfig* closest = NULL;
-
-    for (i = 0;  i < count;  i++)
-    {
-        current = alternatives + i;
-
-        if (desired->stereo > 0 && current->stereo == 0)
-        {
-            // Stereo is a hard constraint
-            continue;
-        }
-
-        if (desired->doublebuffer != current->doublebuffer)
-        {
-            // Double buffering is a hard constraint
-            continue;
-        }
-
-        // Count number of missing buffers
-        {
-            missing = 0;
-
-            if (desired->alphaBits > 0 && current->alphaBits == 0)
-                missing++;
-
-            if (desired->depthBits > 0 && current->depthBits == 0)
-                missing++;
-
-            if (desired->stencilBits > 0 && current->stencilBits == 0)
-                missing++;
-
-            if (desired->auxBuffers > 0 &&
-                current->auxBuffers < desired->auxBuffers)
-            {
-                missing += desired->auxBuffers - current->auxBuffers;
-            }
-
-            if (desired->samples > 0 && current->samples == 0)
-            {
-                // Technically, several multisampling buffers could be
-                // involved, but that's a lower level implementation detail and
-                // not important to us here, so we count them as one
-                missing++;
-            }
-
-            if (desired->transparent != current->transparent)
-                missing++;
-        }
-
-        // These polynomials make many small channel size differences matter
-        // less than one large channel size difference
-
-        // Calculate color channel size difference value
-        {
-            colorDiff = 0;
-
-            if (desired->redBits != GLFW_DONT_CARE)
-            {
-                colorDiff += (desired->redBits - current->redBits) *
-                             (desired->redBits - current->redBits);
-            }
-
-            if (desired->greenBits != GLFW_DONT_CARE)
-            {
-                colorDiff += (desired->greenBits - current->greenBits) *
-                             (desired->greenBits - current->greenBits);
-            }
-
-            if (desired->blueBits != GLFW_DONT_CARE)
-            {
-                colorDiff += (desired->blueBits - current->blueBits) *
-                             (desired->blueBits - current->blueBits);
-            }
-        }
-
-        // Calculate non-color channel size difference value
-        {
-            extraDiff = 0;
-
-            if (desired->alphaBits != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->alphaBits - current->alphaBits) *
-                             (desired->alphaBits - current->alphaBits);
-            }
-
-            if (desired->depthBits != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->depthBits - current->depthBits) *
-                             (desired->depthBits - current->depthBits);
-            }
-
-            if (desired->stencilBits != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->stencilBits - current->stencilBits) *
-                             (desired->stencilBits - current->stencilBits);
-            }
-
-            if (desired->accumRedBits != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->accumRedBits - current->accumRedBits) *
-                             (desired->accumRedBits - current->accumRedBits);
-            }
-
-            if (desired->accumGreenBits != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->accumGreenBits - current->accumGreenBits) *
-                             (desired->accumGreenBits - current->accumGreenBits);
-            }
-
-            if (desired->accumBlueBits != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->accumBlueBits - current->accumBlueBits) *
-                             (desired->accumBlueBits - current->accumBlueBits);
-            }
-
-            if (desired->accumAlphaBits != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->accumAlphaBits - current->accumAlphaBits) *
-                             (desired->accumAlphaBits - current->accumAlphaBits);
-            }
-
-            if (desired->samples != GLFW_DONT_CARE)
-            {
-                extraDiff += (desired->samples - current->samples) *
-                             (desired->samples - current->samples);
-            }
-
-            if (desired->sRGB && !current->sRGB)
-                extraDiff++;
-        }
-
-        // Figure out if the current one is better than the best one found so far
-        // Least number of missing buffers is the most important heuristic,
-        // then color buffer size match and lastly size match for other buffers
-
-        if (missing < leastMissing)
-            closest = current;
-        else if (missing == leastMissing)
-        {
-            if ((colorDiff < leastColorDiff) ||
-                (colorDiff == leastColorDiff && extraDiff < leastExtraDiff))
-            {
-                closest = current;
-            }
-        }
-
-        if (current == closest)
-        {
-            leastMissing = missing;
-            leastColorDiff = colorDiff;
-            leastExtraDiff = extraDiff;
-        }
-    }
-
-    return closest;
+    return true;
 }
 
 // Retrieves the attributes of the current context
 //
-GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
+bool _glfwRefreshContextAttribs(_GLFWwindow* window,
                                     const _GLFWctxconfig* ctxconfig)
 {
     int i;
@@ -358,7 +192,7 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
     window->context.source = ctxconfig->source;
     window->context.client = GLFW_OPENGL_API;
 
-    previous = _glfwPlatformGetTls(&_glfw.contextSlot);;
+    previous = _glfwPlatformGetTls(&_glfw.contextSlot);
     glfwMakeContextCurrent((GLFWwindow*) window);
 
     window->context.GetIntegerv = (PFNGLGETINTEGERVPROC)
@@ -369,7 +203,7 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
     {
         _glfwInputError(GLFW_PLATFORM_ERROR, "Entry point retrieval is broken");
         glfwMakeContextCurrent((GLFWwindow*) previous);
-        return GLFW_FALSE;
+        return false;
     }
 
     version = (const char*) window->context.GetString(GL_VERSION);
@@ -387,7 +221,7 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
         }
 
         glfwMakeContextCurrent((GLFWwindow*) previous);
-        return GLFW_FALSE;
+        return false;
     }
 
     for (i = 0;  prefixes[i];  i++)
@@ -419,7 +253,7 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
         }
 
         glfwMakeContextCurrent((GLFWwindow*) previous);
-        return GLFW_FALSE;
+        return false;
     }
 
     if (window->context.major < ctxconfig->major ||
@@ -449,7 +283,7 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
         }
 
         glfwMakeContextCurrent((GLFWwindow*) previous);
-        return GLFW_FALSE;
+        return false;
     }
 
     if (window->context.major >= 3)
@@ -465,7 +299,7 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
             _glfwInputError(GLFW_PLATFORM_ERROR,
                             "Entry point retrieval is broken");
             glfwMakeContextCurrent((GLFWwindow*) previous);
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -478,21 +312,21 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
             window->context.GetIntegerv(GL_CONTEXT_FLAGS, &flags);
 
             if (flags & GL_CONTEXT_FLAG_FORWARD_COMPATIBLE_BIT)
-                window->context.forward = GLFW_TRUE;
+                window->context.forward = true;
 
             if (flags & GL_CONTEXT_FLAG_DEBUG_BIT)
-                window->context.debug = GLFW_TRUE;
+                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 = GLFW_TRUE;
+                window->context.debug = true;
             }
 
             if (flags & GL_CONTEXT_FLAG_NO_ERROR_BIT_KHR)
-                window->context.noerror = GLFW_TRUE;
+                window->context.noerror = true;
         }
 
         // Read back OpenGL context profile (OpenGL 3.2 and above)
@@ -572,12 +406,12 @@ GLFWbool _glfwRefreshContextAttribs(_GLFWwindow* window,
     }
 
     glfwMakeContextCurrent((GLFWwindow*) previous);
-    return GLFW_TRUE;
+    return true;
 }
 
 // Searches an extension string for the specified extension
 //
-GLFWbool _glfwStringInExtensionString(const char* string, const char* extensions)
+bool _glfwStringInExtensionString(const char* string, const char* extensions)
 {
     const char* start = extensions;
 
@@ -588,7 +422,7 @@ GLFWbool _glfwStringInExtensionString(const char* string, const char* extensions
 
         where = strstr(start, string);
         if (!where)
-            return GLFW_FALSE;
+            return false;
 
         terminator = where + strlen(string);
         if (where == start || *(where - 1) == ' ')
@@ -600,7 +434,7 @@ GLFWbool _glfwStringInExtensionString(const char* string, const char* extensions
         start = terminator;
     }
 
-    return GLFW_TRUE;
+    return true;
 }
 
 
@@ -677,20 +511,20 @@ GLFWAPI int glfwExtensionSupported(const char* extension)
     _GLFWwindow* window;
     assert(extension != NULL);
 
-    _GLFW_REQUIRE_INIT_OR_RETURN(GLFW_FALSE);
+    _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 GLFW_FALSE;
+        return false;
     }
 
     if (*extension == '\0')
     {
         _glfwInputError(GLFW_INVALID_VALUE, "Extension name cannot be an empty string");
-        return GLFW_FALSE;
+        return false;
     }
 
     if (window->context.major >= 3)
@@ -710,11 +544,11 @@ GLFWAPI int glfwExtensionSupported(const char* extension)
             {
                 _glfwInputError(GLFW_PLATFORM_ERROR,
                                 "Extension string retrieval is broken");
-                return GLFW_FALSE;
+                return false;
             }
 
             if (strcmp(en, extension) == 0)
-                return GLFW_TRUE;
+                return true;
         }
     }
     else
@@ -727,11 +561,11 @@ GLFWAPI int glfwExtensionSupported(const char* extension)
         {
             _glfwInputError(GLFW_PLATFORM_ERROR,
                             "Extension string retrieval is broken");
-            return GLFW_FALSE;
+            return false;
         }
 
         if (_glfwStringInExtensionString(extension, extensions))
-            return GLFW_TRUE;
+            return true;
     }
 
     // Check if extension is in the platform-specific string
@@ -755,4 +589,3 @@ GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname)
 
     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

@@ -1,8 +1,8 @@
 //========================================================================
-// GLFW 3.3 EGL - www.glfw.org
+// GLFW 3.4 EGL - www.glfw.org
 //------------------------------------------------------------------------
 // Copyright (c) 2002-2006 Marcus Geelnard
-// Copyright (c) 2006-2016 Camilla Löwy <elmindreda@glfw.org>
+// 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
@@ -24,6 +24,8 @@
 //    distribution.
 //
 //========================================================================
+// Please use C89 style variable declarations in this file because VS 2010
+//========================================================================
 
 #include "internal.h"
 
@@ -74,6 +76,7 @@ static const char* getEGLErrorString(EGLint error)
     }
 }
 
+#ifdef _GLFW_X11
 // Returns the specified attribute of the specified EGLConfig
 //
 static int getEGLConfigAttrib(EGLConfig config, int attrib)
@@ -82,108 +85,78 @@ static int getEGLConfigAttrib(EGLConfig config, int attrib)
     eglGetConfigAttrib(_glfw.egl.display, config, attrib, &value);
     return value;
 }
+#endif
 
 // Return the EGLConfig most closely matching the specified hints
 //
-static GLFWbool chooseEGLConfig(const _GLFWctxconfig* ctxconfig,
+static bool chooseEGLConfig(const _GLFWctxconfig* ctxconfig,
                                 const _GLFWfbconfig* desired,
                                 EGLConfig* result)
 {
-    EGLConfig* nativeConfigs;
-    _GLFWfbconfig* usableConfigs;
-    const _GLFWfbconfig* closest;
-    int i, nativeCount, usableCount;
+    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;
+    }
 
-    eglGetConfigs(_glfw.egl.display, NULL, 0, &nativeCount);
     if (!nativeCount)
     {
         _glfwInputError(GLFW_API_UNAVAILABLE, "EGL: No EGLConfigs returned");
-        return GLFW_FALSE;
+        return false;
     }
 
-    nativeConfigs = calloc(nativeCount, sizeof(EGLConfig));
-    eglGetConfigs(_glfw.egl.display, nativeConfigs, nativeCount, &nativeCount);
-
-    usableConfigs = calloc(nativeCount, sizeof(_GLFWfbconfig));
-    usableCount = 0;
 
     for (i = 0;  i < nativeCount;  i++)
     {
-        const EGLConfig n = nativeConfigs[i];
-        _GLFWfbconfig* u = usableConfigs + usableCount;
-
-        // Only consider RGB(A) EGLConfigs
-        if (getEGLConfigAttrib(n, EGL_COLOR_BUFFER_TYPE) != EGL_RGB_BUFFER)
-            continue;
-
-        // Only consider window EGLConfigs
-        if (!(getEGLConfigAttrib(n, EGL_SURFACE_TYPE) & EGL_WINDOW_BIT))
-            continue;
 
 #if defined(_GLFW_X11)
-        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)
+            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)
             {
-                u->transparent = _glfwIsVisualTransparentX11(vis[0].visual);
-                XFree(vis);
+                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
-
-        if (ctxconfig->client == GLFW_OPENGL_ES_API)
-        {
-            if (ctxconfig->major == 1)
-            {
-                if (!(getEGLConfigAttrib(n, EGL_RENDERABLE_TYPE) & EGL_OPENGL_ES_BIT))
-                    continue;
-            }
-            else
-            {
-                if (!(getEGLConfigAttrib(n, EGL_RENDERABLE_TYPE) & EGL_OPENGL_ES2_BIT))
-                    continue;
-            }
-        }
-        else if (ctxconfig->client == GLFW_OPENGL_API)
-        {
-            if (!(getEGLConfigAttrib(n, EGL_RENDERABLE_TYPE) & EGL_OPENGL_BIT))
-                continue;
-        }
-
-        u->redBits = getEGLConfigAttrib(n, EGL_RED_SIZE);
-        u->greenBits = getEGLConfigAttrib(n, EGL_GREEN_SIZE);
-        u->blueBits = getEGLConfigAttrib(n, EGL_BLUE_SIZE);
-
-        u->alphaBits = getEGLConfigAttrib(n, EGL_ALPHA_SIZE);
-        u->depthBits = getEGLConfigAttrib(n, EGL_DEPTH_SIZE);
-        u->stencilBits = getEGLConfigAttrib(n, EGL_STENCIL_SIZE);
-
-        u->samples = getEGLConfigAttrib(n, EGL_SAMPLES);
-        u->doublebuffer = GLFW_TRUE;
-
-        u->handle = (uintptr_t) n;
-        usableCount++;
+        ans_idx = i;
+        break;
     }
-
-    closest = _glfwChooseFBConfig(desired, usableConfigs, usableCount);
-    if (closest)
-        *result = (EGLConfig) closest->handle;
-
-    free(nativeConfigs);
-    free(usableConfigs);
-
-    return closest != NULL;
+    *result = configs[ans_idx];
+    return true;
 }
 
 static void makeContextCurrentEGL(_GLFWwindow* window)
@@ -241,10 +214,10 @@ static int extensionSupportedEGL(const char* extension)
     if (extensions)
     {
         if (_glfwStringInExtensionString(extension, extensions))
-            return GLFW_TRUE;
+            return true;
     }
 
-    return GLFW_FALSE;
+    return false;
 }
 
 static GLFWglproc getProcAddressEGL(const char* procname)
@@ -253,8 +226,8 @@ static GLFWglproc getProcAddressEGL(const char* procname)
 
     if (window->context.egl.client)
     {
-        GLFWglproc proc = (GLFWglproc) _glfw_dlsym(window->context.egl.client,
-                                                   procname);
+        GLFWglproc proc = NULL;
+        glfw_dlsym(proc, window->context.egl.client, procname);
         if (proc)
             return proc;
     }
@@ -297,9 +270,11 @@ static void destroyContextEGL(_GLFWwindow* window)
 
 // Initialize EGL
 //
-GLFWbool _glfwInitEGL(void)
+bool _glfwInitEGL(void)
 {
     int i;
+    EGLint* attribs = NULL;
+    const char* extensions;
     const char* sonames[] =
     {
 #if defined(_GLFW_EGL_LIBRARY)
@@ -318,7 +293,7 @@ GLFWbool _glfwInitEGL(void)
     };
 
     if (_glfw.egl.handle)
-        return GLFW_TRUE;
+        return true;
 
     for (i = 0;  sonames[i];  i++)
     {
@@ -330,46 +305,32 @@ GLFWbool _glfwInitEGL(void)
     if (!_glfw.egl.handle)
     {
         _glfwInputError(GLFW_API_UNAVAILABLE, "EGL: Library not found");
-        return GLFW_FALSE;
+        return false;
     }
 
     _glfw.egl.prefix = (strncmp(sonames[i], "lib", 3) == 0);
 
-    _glfw.egl.GetConfigAttrib = (PFN_eglGetConfigAttrib)
-        _glfw_dlsym(_glfw.egl.handle, "eglGetConfigAttrib");
-    _glfw.egl.GetConfigs = (PFN_eglGetConfigs)
-        _glfw_dlsym(_glfw.egl.handle, "eglGetConfigs");
-    _glfw.egl.GetDisplay = (PFN_eglGetDisplay)
-        _glfw_dlsym(_glfw.egl.handle, "eglGetDisplay");
-    _glfw.egl.GetError = (PFN_eglGetError)
-        _glfw_dlsym(_glfw.egl.handle, "eglGetError");
-    _glfw.egl.Initialize = (PFN_eglInitialize)
-        _glfw_dlsym(_glfw.egl.handle, "eglInitialize");
-    _glfw.egl.Terminate = (PFN_eglTerminate)
-        _glfw_dlsym(_glfw.egl.handle, "eglTerminate");
-    _glfw.egl.BindAPI = (PFN_eglBindAPI)
-        _glfw_dlsym(_glfw.egl.handle, "eglBindAPI");
-    _glfw.egl.CreateContext = (PFN_eglCreateContext)
-        _glfw_dlsym(_glfw.egl.handle, "eglCreateContext");
-    _glfw.egl.DestroySurface = (PFN_eglDestroySurface)
-        _glfw_dlsym(_glfw.egl.handle, "eglDestroySurface");
-    _glfw.egl.DestroyContext = (PFN_eglDestroyContext)
-        _glfw_dlsym(_glfw.egl.handle, "eglDestroyContext");
-    _glfw.egl.CreateWindowSurface = (PFN_eglCreateWindowSurface)
-        _glfw_dlsym(_glfw.egl.handle, "eglCreateWindowSurface");
-    _glfw.egl.MakeCurrent = (PFN_eglMakeCurrent)
-        _glfw_dlsym(_glfw.egl.handle, "eglMakeCurrent");
-    _glfw.egl.SwapBuffers = (PFN_eglSwapBuffers)
-        _glfw_dlsym(_glfw.egl.handle, "eglSwapBuffers");
-    _glfw.egl.SwapInterval = (PFN_eglSwapInterval)
-        _glfw_dlsym(_glfw.egl.handle, "eglSwapInterval");
-    _glfw.egl.QueryString = (PFN_eglQueryString)
-        _glfw_dlsym(_glfw.egl.handle, "eglQueryString");
-    _glfw.egl.GetProcAddress = (PFN_eglGetProcAddress)
-        _glfw_dlsym(_glfw.egl.handle, "eglGetProcAddress");
+    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 ||
@@ -389,10 +350,54 @@ GLFWbool _glfwInitEGL(void)
                         "EGL: Failed to load required entry points");
 
         _glfwTerminateEGL();
-        return GLFW_FALSE;
+        return false;
     }
 
-    _glfw.egl.display = eglGetDisplay(_GLFW_EGL_NATIVE_DISPLAY);
+    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,
@@ -400,7 +405,7 @@ GLFWbool _glfwInitEGL(void)
                         getEGLErrorString(eglGetError()));
 
         _glfwTerminateEGL();
-        return GLFW_FALSE;
+        return false;
     }
 
     if (!eglInitialize(_glfw.egl.display, &_glfw.egl.major, &_glfw.egl.minor))
@@ -410,7 +415,7 @@ GLFWbool _glfwInitEGL(void)
                         getEGLErrorString(eglGetError()));
 
         _glfwTerminateEGL();
-        return GLFW_FALSE;
+        return false;
     }
 
     _glfw.egl.KHR_create_context =
@@ -424,7 +429,7 @@ GLFWbool _glfwInitEGL(void)
     _glfw.egl.KHR_context_flush_control =
         extensionSupportedEGL("EGL_KHR_context_flush_control");
 
-    return GLFW_TRUE;
+    return true;
 }
 
 // Terminate EGL
@@ -446,26 +451,27 @@ void _glfwTerminateEGL(void)
 
 #define setAttrib(a, v) \
 { \
-    assert((size_t) (index + 1) < sizeof(attribs) / sizeof(attribs[0])); \
+    assert(((size_t) index + 1) < sizeof(attribs) / sizeof(attribs[0])); \
     attribs[index++] = a; \
     attribs[index++] = v; \
 }
 
 // Create the OpenGL or OpenGL ES context
 //
-GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
+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 GLFW_FALSE;
+        return false;
     }
 
     if (ctxconfig->share)
@@ -475,7 +481,7 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
     {
         _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
                         "EGL: Failed to find a suitable EGLConfig");
-        return GLFW_FALSE;
+        return false;
     }
 
     if (ctxconfig->client == GLFW_OPENGL_ES_API)
@@ -485,7 +491,7 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
             _glfwInputError(GLFW_API_UNAVAILABLE,
                             "EGL: Failed to bind OpenGL ES: %s",
                             getEGLErrorString(eglGetError()));
-            return GLFW_FALSE;
+            return false;
         }
     }
     else
@@ -495,7 +501,7 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
             _glfwInputError(GLFW_API_UNAVAILABLE,
                             "EGL: Failed to bind OpenGL: %s",
                             getEGLErrorString(eglGetError()));
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -536,7 +542,7 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
         if (ctxconfig->noerror)
         {
             if (_glfw.egl.KHR_create_context_no_error)
-                setAttrib(EGL_CONTEXT_OPENGL_NO_ERROR_KHR, GLFW_TRUE);
+                setAttrib(EGL_CONTEXT_OPENGL_NO_ERROR_KHR, true);
         }
 
         if (ctxconfig->major != 1 || ctxconfig->minor != 0)
@@ -581,37 +587,53 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
         _glfwInputError(GLFW_VERSION_UNAVAILABLE,
                         "EGL: Failed to create context: %s",
                         getEGLErrorString(eglGetError()));
-        return GLFW_FALSE;
+        return false;
     }
 
     // Set up attributes for surface creation
+    index = 0;
+
+    if (fbconfig->sRGB)
     {
-        int 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);
+        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);
     }
 
-    window->context.egl.surface =
-        eglCreateWindowSurface(_glfw.egl.display,
-                               config,
-                               _GLFW_EGL_NATIVE_WINDOW,
-                               attribs);
     if (window->context.egl.surface == EGL_NO_SURFACE)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
                         "EGL: Failed to create window surface: %s",
                         getEGLErrorString(eglGetError()));
-        return GLFW_FALSE;
+        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)
     {
@@ -686,7 +708,7 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
         {
             _glfwInputError(GLFW_API_UNAVAILABLE,
                             "EGL: Failed to load client library");
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -697,7 +719,7 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
     window->context.getProcAddress = getProcAddressEGL;
     window->context.destroy = destroyContextEGL;
 
-    return GLFW_TRUE;
+    return true;
 }
 
 #undef setAttrib
@@ -705,7 +727,7 @@ GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
 // Returns the Visual and depth of the chosen EGLConfig
 //
 #if defined(_GLFW_X11)
-GLFWbool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig,
+bool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig UNUSED,
                               const _GLFWctxconfig* ctxconfig,
                               const _GLFWfbconfig* fbconfig,
                               Visual** visual, int* depth)
@@ -720,7 +742,7 @@ GLFWbool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig,
     {
         _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
                         "EGL: Failed to find a suitable EGLConfig");
-        return GLFW_FALSE;
+        return false;
     }
 
     eglGetConfigAttrib(_glfw.egl.display, native,
@@ -734,14 +756,14 @@ GLFWbool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig,
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
                         "EGL: Failed to retrieve Visual for EGLConfig");
-        return GLFW_FALSE;
+        return false;
     }
 
     *visual = result->visual;
     *depth = result->depth;
 
     XFree(result);
-    return GLFW_TRUE;
+    return true;
 }
 #endif // _GLFW_X11
 
@@ -783,4 +805,3 @@ GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* handle)
 
     return window->context.egl.surface;
 }
-

glfw/egl_context.h

@@ -1,8 +1,8 @@
 //========================================================================
-// GLFW 3.3 EGL - www.glfw.org
+// GLFW 3.4 EGL - www.glfw.org
 //------------------------------------------------------------------------
 // Copyright (c) 2002-2006 Marcus Geelnard
-// Copyright (c) 2006-2016 Camilla Löwy <elmindreda@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
@@ -25,52 +25,32 @@
 //
 //========================================================================
 
-#if defined(_GLFW_USE_EGLPLATFORM_H)
- #include <EGL/eglplatform.h>
-#elif defined(_GLFW_WIN32)
+#if defined(_GLFW_WIN32)
  #define EGLAPIENTRY __stdcall
-typedef HDC EGLNativeDisplayType;
-typedef HWND EGLNativeWindowType;
-#elif defined(_GLFW_COCOA)
- #define EGLAPIENTRY
-typedef void* EGLNativeDisplayType;
-typedef id EGLNativeWindowType;
-#elif defined(_GLFW_X11)
- #define EGLAPIENTRY
-typedef Display* EGLNativeDisplayType;
-typedef Window EGLNativeWindowType;
-#elif defined(_GLFW_WAYLAND)
- #define EGLAPIENTRY
-typedef struct wl_display* EGLNativeDisplayType;
-typedef struct wl_egl_window* EGLNativeWindowType;
-#elif defined(_GLFW_MIR)
- #define EGLAPIENTRY
-typedef MirEGLNativeDisplayType EGLNativeDisplayType;
-typedef MirEGLNativeWindowType EGLNativeWindowType;
 #else
- #error "No supported EGL platform selected"
+ #define EGLAPIENTRY
 #endif
 
-#define EGL_SUCCESS	0x3000
-#define EGL_NOT_INITIALIZED	0x3001
+#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_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_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_RENDERABLE_TYPE 0x3040
 #define EGL_OPENGL_ES_BIT 0x0001
 #define EGL_OPENGL_ES2_BIT 0x0004
 #define EGL_OPENGL_BIT 0x0008
@@ -80,7 +60,7 @@ typedef MirEGLNativeWindowType EGLNativeWindowType;
 #define EGL_RED_SIZE 0x3024
 #define EGL_DEPTH_SIZE 0x3025
 #define EGL_STENCIL_SIZE 0x3026
-#define EGL_SAMPLES	0x3031
+#define EGL_SAMPLES 0x3031
 #define EGL_OPENGL_ES_API 0x30a0
 #define EGL_OPENGL_API 0x30a2
 #define EGL_NONE 0x3038
@@ -91,6 +71,8 @@ typedef MirEGLNativeWindowType EGLNativeWindowType;
 #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
@@ -110,6 +92,17 @@ typedef MirEGLNativeWindowType EGLNativeWindowType;
 #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;
@@ -119,9 +112,13 @@ 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*);
@@ -138,6 +135,7 @@ 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
@@ -153,9 +151,10 @@ typedef GLFWglproc (EGLAPIENTRY * PFN_eglGetProcAddress)(const char*);
 #define eglQueryString _glfw.egl.QueryString
 #define eglGetProcAddress _glfw.egl.GetProcAddress
 
-#define _GLFW_EGL_CONTEXT_STATE            _GLFWcontextEGL egl
-#define _GLFW_EGL_LIBRARY_CONTEXT_STATE    _GLFWlibraryEGL egl
-
+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
 //
@@ -173,20 +172,31 @@ typedef struct _GLFWcontextEGL
 //
 typedef struct _GLFWlibraryEGL
 {
+    EGLenum         platform;
     EGLDisplay      display;
     EGLint          major, minor;
-    GLFWbool        prefix;
+    bool            prefix;
 
-    GLFWbool        KHR_create_context;
-    GLFWbool        KHR_create_context_no_error;
-    GLFWbool        KHR_gl_colorspace;
-    GLFWbool        KHR_get_all_proc_addresses;
-    GLFWbool        KHR_context_flush_control;
+    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;
@@ -202,18 +212,20 @@ typedef struct _GLFWlibraryEGL
     PFN_eglQueryString          QueryString;
     PFN_eglGetProcAddress       GetProcAddress;
 
+    PFNEGLGETPLATFORMDISPLAYEXTPROC GetPlatformDisplayEXT;
+    PFNEGLCREATEPLATFORMWINDOWSURFACEEXTPROC CreatePlatformWindowSurfaceEXT;
+
 } _GLFWlibraryEGL;
 
 
-GLFWbool _glfwInitEGL(void);
+bool _glfwInitEGL(void);
 void _glfwTerminateEGL(void);
-GLFWbool _glfwCreateContextEGL(_GLFWwindow* window,
+bool _glfwCreateContextEGL(_GLFWwindow* window,
                                const _GLFWctxconfig* ctxconfig,
                                const _GLFWfbconfig* fbconfig);
 #if defined(_GLFW_X11)
-GLFWbool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig,
+bool _glfwChooseVisualEGL(const _GLFWwndconfig* wndconfig,
                               const _GLFWctxconfig* ctxconfig,
                               const _GLFWfbconfig* fbconfig,
                               Visual** visual, int* depth);
 #endif /*_GLFW_X11*/
-

glfw/glfw.py

@@ -1,79 +1,120 @@
-#!/usr/bin/env python
+#!/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 shutil
 import sys
+from typing import Callable, Dict, List, Optional, Tuple
 
 _plat = sys.platform.lower()
-is_macos = 'darwin' in _plat
-is_freebsd = 'freebsd' in _plat
-is_netbsd = 'netbsd' in _plat
-is_dragonflybsd = 'dragonfly' in _plat
-is_bsd = is_freebsd or is_netbsd or is_dragonflybsd
+is_linux = 'linux' in _plat
+is_openbsd = 'openbsd' in _plat
 base = os.path.dirname(os.path.abspath(__file__))
 
 
-def wayland_protocol_file_name(base, ext='c'):
+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, pkg_config, at_least_version, module='x11'):
+def init_env(env: Env, pkg_config: Callable, at_least_version: Callable, test_compile: Callable, module: str = 'x11') -> Env:
     ans = env.copy()
-    ans.cflags = [
-        x for x in ans.cflags
-        if x not in '-Wpedantic -Wextra -pedantic-errors'.split()
-    ]
-    if not is_macos:
-        ans.cflags.append('-pthread')
-        ans.ldpaths.append('-pthread')
-    ans.cflags.append('-fpic')
-    ans.cflags.append('-D_GLFW_' + module.upper())
-    ans.cflags.append('-D_GLFW_BUILD_DLL')
+    ans.cflags.append('-fPIC')
+    ans.cppflags.append('-D_GLFW_' + module.upper())
+    ans.cppflags.append('-D_GLFW_BUILD_DLL')
 
-    if is_macos:
-        ans.ldpaths.extend(
-            "-framework Cocoa -framework IOKit -framework CoreFoundation -framework CoreVideo".
-            split()
-        )
-    else:
-        ans.ldpaths.extend('-lrt -lm -ldl'.split())
-    sinfo = json.load(open(os.path.join(base, 'source-info.json')))
-    ans.sources = sinfo['common']['sources'] + sinfo[module]['sources']
+    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'.split():
+        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':
-        for f in 'Cocoa IOKit CoreFoundation CoreVideo'.split():
-            ans.ldpaths.extend(('-framework', f))
+        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-egl wayland-client wayland-cursor xkbcommon'.split():
+        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, run_tool, emphasis, newer, dest_dir):
+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):
@@ -82,58 +123,18 @@ def build_wayland_protocols(env, run_tool, emphasis, newer, dest_dir):
             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 'code'
-                run_tool([env.wayland_scanner, q, src, dest],
-                         desc='Generating {} ...'.format(emphasis(os.path.basename(dest))))
-
-
-def collect_source_information():
-    raw = open('src/CMakeLists.txt').read()
-    mraw = open('CMakeLists.txt').read()
-
-    def extract_sources(group, start_pos=0):
-        for which in 'HEADERS SOURCES'.split():
-            yield which.lower(), filter(
-                lambda x: x[0] not in '"$',
-                re.search(
-                    r'{0}_{1}\s+([^)]+?)[)]'.format(group, which),
-                    raw[start_pos:]
-                ).group(1).strip().split()
-            )
-
-    wayland_protocols = re.search('WaylandProtocols\s+(\S+)\s+', mraw).group(1)
-    wayland_protocols = list(map(int, wayland_protocols.split('.')))
-    ans = {
-        'common': dict(extract_sources('common')),
-        'wayland_protocols': wayland_protocols,
-    }
-    joystick = 'null' if is_bsd else 'linux'
-    for group in 'cocoa win32 x11 wayland osmesa'.split():
-        m = re.search('_GLFW_' + group.upper(), raw)
-        ans[group] = dict(extract_sources('glfw', m.start()))
-        if group in ('x11', 'wayland'):
-            ans[group]['headers'].append('{}_joystick.h'.format(joystick))
-            ans[group]['sources'].append('{}_joystick.c'.format(joystick))
-        if group == 'wayland':
-            ans[group]['protocols'] = p = []
-            for m in re.finditer(r'WAYLAND_PROTOCOLS_PKGDATADIR\}/(.+?)"?$', raw, flags=re.M):
-                p.append(m.group(1))
-    return ans
-
-
-def patch_in_file(path, pfunc):
-    with open(path, 'r+') as f:
-        raw = f.read()
-        nraw = pfunc(raw)
-        if raw == nraw:
-            raise SystemExit('Patching of {} failed'.format(path))
-        f.seek(0), f.truncate()
-        f.write(nraw)
+                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):
+    def __init__(self, decl: str):
         self.type, self.name = decl.rsplit(' ', 1)
         self.type = self.type.strip()
         self.name = self.name.strip()
@@ -141,13 +142,13 @@ class Arg:
             self.name = self.name[1:]
             self.type = self.type + '*'
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'Arg({}, {})'.format(self.type, self.name)
 
 
 class Function:
 
-    def __init__(self, declaration, check_fail=True):
+    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
@@ -163,15 +164,17 @@ class Function:
             if a == 'void':
                 continue
             self.args.append(Arg(a))
+        if not self.args:
+            self.args = [Arg('void v')]
 
-    def declaration(self):
-        return 'typedef {restype} (*{name}_func)({args});\n{name}_func {name}_impl;\n#define {name} {name}_impl'.format(
+    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):
+    def load(self) -> str:
         ans = '*(void **) (&{name}_impl) = dlsym(handle, "{name}");'.format(
             name=self.name
         )
@@ -182,8 +185,9 @@ class Function:
         return ans
 
 
-def generate_wrappers(glfw_header, glfw_native_header):
-    src = open(glfw_header).read()
+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):
@@ -195,11 +199,24 @@ def generate_wrappers(glfw_header, glfw_native_header):
         functions.append(Function(decl))
     for line in '''\
     void* glfwGetCocoaWindow(GLFWwindow* window)
+    void glfwHideCocoaTitlebar(GLFWwindow* window, bool yes)
+    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 glfwSetX11SelectionString(const char* string)
-    const char* glfwGetX11SelectionString(void)
+    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))
@@ -209,11 +226,30 @@ def generate_wrappers(glfw_header, glfw_native_header):
     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);
@@ -222,9 +258,10 @@ const char* load_glfw(const char* path);
         f.write(header)
 
     code = '''
-#include <dlfcn.h>
+#define GFW_EXTERN
 #include "data-types.h"
 #include "glfw-wrapper.h"
+#include <dlfcn.h>
 
 static void* handle = NULL;
 
@@ -243,7 +280,7 @@ load_glfw(const char* path) {
 }
 
 void
-unload_glfw() {
+unload_glfw(void) {
     if (handle) { dlclose(handle); handle = NULL; }
 }
 '''.replace('LOAD', '\n\n    '.join(f.load() for f in functions))
@@ -251,35 +288,9 @@ unload_glfw() {
         f.write(code)
 
 
-def main():
-    os.chdir(sys.argv[-1])
-    sinfo = collect_source_information()
-    files_to_copy = set()
-    for x in sinfo.values():
-        if isinstance(x, dict):
-            headers, sources = x['headers'], x['sources']
-            for name in headers + sources:
-                files_to_copy.add(os.path.abspath(os.path.join('src', name)))
-    glfw_header = os.path.abspath('include/GLFW/glfw3.h')
-    glfw_native_header = os.path.abspath('include/GLFW/glfw3native.h')
-    os.chdir(base)
-    for x in os.listdir('.'):
-        if x.rpartition('.') in ('c', 'h'):
-            os.unlink(x)
-    for src in files_to_copy:
-        shutil.copy2(src, '.')
-    shutil.copy2(glfw_header, '.')
-    patch_in_file('internal.h', lambda x: x.replace('../include/GLFW/', ''))
-    patch_in_file('cocoa_window.m', lambda x: re.sub(
-        r'[(]void[)]loadMainMenu.+?}', '(void)loadMainMenu\n{ // removed by Kovid as it generated compiler warnings \n}\n', x, flags=re.DOTALL))
-    json.dump(
-        sinfo,
-        open('source-info.json', 'w'),
-        indent=2,
-        ensure_ascii=False,
-        sort_keys=True
-    )
-    generate_wrappers(glfw_header, glfw_native_header)
+def main() -> None:
+    os.chdir(os.path.dirname(os.path.abspath(__file__)))
+    generate_wrappers('glfw3.h')
 
 
 if __name__ == '__main__':

glfw/glx_context.c

@@ -1,8 +1,8 @@
 //========================================================================
-// GLFW 3.3 GLX - www.glfw.org
+// GLFW 3.4 GLX - www.glfw.org
 //------------------------------------------------------------------------
 // Copyright (c) 2002-2006 Marcus Geelnard
-// Copyright (c) 2006-2016 Camilla Löwy <elmindreda@glfw.org>
+// 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
@@ -24,6 +24,8 @@
 //    distribution.
 //
 //========================================================================
+// It is fine to use C99 in this file because it will not be built with VS
+//========================================================================
 
 #include "internal.h"
 
@@ -45,104 +47,92 @@ static int getGLXFBConfigAttrib(GLXFBConfig fbconfig, int attrib)
     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 GLFWbool chooseGLXFBConfig(const _GLFWfbconfig* desired,
+static bool chooseGLXFBConfig(const _GLFWfbconfig* desired,
                                   GLXFBConfig* result)
 {
     GLXFBConfig* nativeConfigs;
-    _GLFWfbconfig* usableConfigs;
-    const _GLFWfbconfig* closest;
-    int i, nativeCount, usableCount;
+    int i, nativeCount, ans_idx = 0;
     const char* vendor;
-    GLFWbool trustWindowBit = GLFW_TRUE;
+    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 = GLFW_FALSE;
-
-    nativeConfigs =
-        glXGetFBConfigs(_glfw.x11.display, _glfw.x11.screen, &nativeCount);
+        trustWindowBit = false;
+    nativeConfigs = choose_fb_config(desired, trustWindowBit, &nativeCount);
     if (!nativeConfigs || !nativeCount)
     {
         _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: No GLXFBConfigs returned");
-        return GLFW_FALSE;
+        return false;
     }
-
-    usableConfigs = calloc(nativeCount, sizeof(_GLFWfbconfig));
-    usableCount = 0;
-
     for (i = 0;  i < nativeCount;  i++)
     {
         const GLXFBConfig n = nativeConfigs[i];
-        _GLFWfbconfig* u = usableConfigs + usableCount;
-
-        // Only consider RGBA GLXFBConfigs
-        if (!(getGLXFBConfigAttrib(n, GLX_RENDER_TYPE) & GLX_RGBA_BIT))
-            continue;
-
-        // Only consider window GLXFBConfigs
-        if (!(getGLXFBConfigAttrib(n, GLX_DRAWABLE_TYPE) & GLX_WINDOW_BIT))
-        {
-            if (trustWindowBit)
-                continue;
-        }
-
-        if (desired->transparent)
-        {
+        bool transparency_matches = true, srgb_matches = true;
+        if (desired->transparent) {
+            transparency_matches = false;
             XVisualInfo* vi = glXGetVisualFromFBConfig(_glfw.x11.display, n);
-            if (vi)
-            {
-                u->transparent = _glfwIsVisualTransparentX11(vi->visual);
-                XFree(vi);
-            }
+            if (vi && _glfwIsVisualTransparentX11(vi->visual)) transparency_matches = true;
         }
 
-        u->redBits = getGLXFBConfigAttrib(n, GLX_RED_SIZE);
-        u->greenBits = getGLXFBConfigAttrib(n, GLX_GREEN_SIZE);
-        u->blueBits = getGLXFBConfigAttrib(n, GLX_BLUE_SIZE);
+        if (desired->sRGB && (_glfw.glx.ARB_framebuffer_sRGB || _glfw.glx.EXT_framebuffer_sRGB)) {
+            srgb_matches = getGLXFBConfigAttrib(n, GLX_FRAMEBUFFER_SRGB_CAPABLE_ARB) ? true : false;
+        }
 
-        u->alphaBits = getGLXFBConfigAttrib(n, GLX_ALPHA_SIZE);
-        u->depthBits = getGLXFBConfigAttrib(n, GLX_DEPTH_SIZE);
-        u->stencilBits = getGLXFBConfigAttrib(n, GLX_STENCIL_SIZE);
+        if (transparency_matches && srgb_matches) {
+            ans_idx = i; break;
+        }
 
-        u->accumRedBits = getGLXFBConfigAttrib(n, GLX_ACCUM_RED_SIZE);
-        u->accumGreenBits = getGLXFBConfigAttrib(n, GLX_ACCUM_GREEN_SIZE);
-        u->accumBlueBits = getGLXFBConfigAttrib(n, GLX_ACCUM_BLUE_SIZE);
-        u->accumAlphaBits = getGLXFBConfigAttrib(n, GLX_ACCUM_ALPHA_SIZE);
-
-        u->auxBuffers = getGLXFBConfigAttrib(n, GLX_AUX_BUFFERS);
-
-        if (getGLXFBConfigAttrib(n, GLX_STEREO))
-            u->stereo = GLFW_TRUE;
-        if (getGLXFBConfigAttrib(n, GLX_DOUBLEBUFFER))
-            u->doublebuffer = GLFW_TRUE;
-
-        if (_glfw.glx.ARB_multisample)
-            u->samples = getGLXFBConfigAttrib(n, GLX_SAMPLES);
-
-        if (_glfw.glx.ARB_framebuffer_sRGB || _glfw.glx.EXT_framebuffer_sRGB)
-            u->sRGB = getGLXFBConfigAttrib(n, GLX_FRAMEBUFFER_SRGB_CAPABLE_ARB);
-
-        u->handle = (uintptr_t) n;
-        usableCount++;
     }
 
-    closest = _glfwChooseFBConfig(desired, usableConfigs, usableCount);
-    if (closest)
-        *result = (GLXFBConfig) closest->handle;
+    *result = nativeConfigs[ans_idx];
+    prev_result = nativeConfigs[ans_idx];
 
     XFree(nativeConfigs);
-    free(usableConfigs);
 
-    return closest != NULL;
+    return true;
 }
 
 // Create the OpenGL context using legacy API
 //
-static GLXContext createLegacyContextGLX(_GLFWwindow* window,
+static GLXContext createLegacyContextGLX(_GLFWwindow* window UNUSED,
                                          GLXFBConfig fbconfig,
                                          GLXContext share)
 {
@@ -210,10 +200,10 @@ static int extensionSupportedGLX(const char* extension)
     if (extensions)
     {
         if (_glfwStringInExtensionString(extension, extensions))
-            return GLFW_TRUE;
+            return true;
     }
 
-    return GLFW_FALSE;
+    return false;
 }
 
 static GLFWglproc getProcAddressGLX(const char* procname)
@@ -222,12 +212,13 @@ static GLFWglproc getProcAddressGLX(const char* procname)
         return _glfw.glx.GetProcAddress((const GLubyte*) procname);
     else if (_glfw.glx.GetProcAddressARB)
         return _glfw.glx.GetProcAddressARB((const GLubyte*) procname);
-    else
-        return _glfw_dlsym(_glfw.glx.handle, procname);
+    else {
+        GLFWglproc ans = NULL;
+        glfw_dlsym(ans, _glfw.glx.handle, procname);
+        return ans;
+    }
 }
 
-// Destroy the OpenGL context
-//
 static void destroyContextGLX(_GLFWwindow* window)
 {
     if (window->context.glx.window)
@@ -250,7 +241,7 @@ static void destroyContextGLX(_GLFWwindow* window)
 
 // Initialize GLX
 //
-GLFWbool _glfwInitGLX(void)
+bool _glfwInitGLX(void)
 {
     int i;
     const char* sonames[] =
@@ -267,7 +258,7 @@ GLFWbool _glfwInitGLX(void)
     };
 
     if (_glfw.glx.handle)
-        return GLFW_TRUE;
+        return true;
 
     for (i = 0;  sonames[i];  i++)
     {
@@ -279,39 +270,25 @@ GLFWbool _glfwInitGLX(void)
     if (!_glfw.glx.handle)
     {
         _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: Failed to load GLX");
-        return GLFW_FALSE;
+        return false;
     }
 
-    _glfw.glx.GetFBConfigs =
-        _glfw_dlsym(_glfw.glx.handle, "glXGetFBConfigs");
-    _glfw.glx.GetFBConfigAttrib =
-        _glfw_dlsym(_glfw.glx.handle, "glXGetFBConfigAttrib");
-    _glfw.glx.GetClientString =
-        _glfw_dlsym(_glfw.glx.handle, "glXGetClientString");
-    _glfw.glx.QueryExtension =
-        _glfw_dlsym(_glfw.glx.handle, "glXQueryExtension");
-    _glfw.glx.QueryVersion =
-        _glfw_dlsym(_glfw.glx.handle, "glXQueryVersion");
-    _glfw.glx.DestroyContext =
-        _glfw_dlsym(_glfw.glx.handle, "glXDestroyContext");
-    _glfw.glx.MakeCurrent =
-        _glfw_dlsym(_glfw.glx.handle, "glXMakeCurrent");
-    _glfw.glx.SwapBuffers =
-        _glfw_dlsym(_glfw.glx.handle, "glXSwapBuffers");
-    _glfw.glx.QueryExtensionsString =
-        _glfw_dlsym(_glfw.glx.handle, "glXQueryExtensionsString");
-    _glfw.glx.CreateNewContext =
-        _glfw_dlsym(_glfw.glx.handle, "glXCreateNewContext");
-    _glfw.glx.CreateWindow =
-        _glfw_dlsym(_glfw.glx.handle, "glXCreateWindow");
-    _glfw.glx.DestroyWindow =
-        _glfw_dlsym(_glfw.glx.handle, "glXDestroyWindow");
-    _glfw.glx.GetProcAddress =
-        _glfw_dlsym(_glfw.glx.handle, "glXGetProcAddress");
-    _glfw.glx.GetProcAddressARB =
-        _glfw_dlsym(_glfw.glx.handle, "glXGetProcAddressARB");
-    _glfw.glx.GetVisualFromFBConfig =
-        _glfw_dlsym(_glfw.glx.handle, "glXGetVisualFromFBConfig");
+    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 ||
@@ -331,7 +308,7 @@ GLFWbool _glfwInitGLX(void)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
                         "GLX: Failed to load required entry points");
-        return GLFW_FALSE;
+        return false;
     }
 
     if (!glXQueryExtension(_glfw.x11.display,
@@ -339,21 +316,21 @@ GLFWbool _glfwInitGLX(void)
                            &_glfw.glx.eventBase))
     {
         _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: GLX extension not found");
-        return GLFW_FALSE;
+        return false;
     }
 
     if (!glXQueryVersion(_glfw.x11.display, &_glfw.glx.major, &_glfw.glx.minor))
     {
         _glfwInputError(GLFW_API_UNAVAILABLE,
                         "GLX: Failed to query GLX version");
-        return GLFW_FALSE;
+        return false;
     }
 
     if (_glfw.glx.major == 1 && _glfw.glx.minor < 3)
     {
         _glfwInputError(GLFW_API_UNAVAILABLE,
                         "GLX: GLX version 1.3 is required");
-        return GLFW_FALSE;
+        return false;
     }
 
     if (extensionSupportedGLX("GLX_EXT_swap_control"))
@@ -362,7 +339,7 @@ GLFWbool _glfwInitGLX(void)
             getProcAddressGLX("glXSwapIntervalEXT");
 
         if (_glfw.glx.SwapIntervalEXT)
-            _glfw.glx.EXT_swap_control = GLFW_TRUE;
+            _glfw.glx.EXT_swap_control = true;
     }
 
     if (extensionSupportedGLX("GLX_SGI_swap_control"))
@@ -371,7 +348,7 @@ GLFWbool _glfwInitGLX(void)
             getProcAddressGLX("glXSwapIntervalSGI");
 
         if (_glfw.glx.SwapIntervalSGI)
-            _glfw.glx.SGI_swap_control = GLFW_TRUE;
+            _glfw.glx.SGI_swap_control = true;
     }
 
     if (extensionSupportedGLX("GLX_MESA_swap_control"))
@@ -380,17 +357,17 @@ GLFWbool _glfwInitGLX(void)
             getProcAddressGLX("glXSwapIntervalMESA");
 
         if (_glfw.glx.SwapIntervalMESA)
-            _glfw.glx.MESA_swap_control = GLFW_TRUE;
+            _glfw.glx.MESA_swap_control = true;
     }
 
     if (extensionSupportedGLX("GLX_ARB_multisample"))
-        _glfw.glx.ARB_multisample = GLFW_TRUE;
+        _glfw.glx.ARB_multisample = true;
 
     if (extensionSupportedGLX("GLX_ARB_framebuffer_sRGB"))
-        _glfw.glx.ARB_framebuffer_sRGB = GLFW_TRUE;
+        _glfw.glx.ARB_framebuffer_sRGB = true;
 
     if (extensionSupportedGLX("GLX_EXT_framebuffer_sRGB"))
-        _glfw.glx.EXT_framebuffer_sRGB = GLFW_TRUE;
+        _glfw.glx.EXT_framebuffer_sRGB = true;
 
     if (extensionSupportedGLX("GLX_ARB_create_context"))
     {
@@ -398,25 +375,25 @@ GLFWbool _glfwInitGLX(void)
             getProcAddressGLX("glXCreateContextAttribsARB");
 
         if (_glfw.glx.CreateContextAttribsARB)
-            _glfw.glx.ARB_create_context = GLFW_TRUE;
+            _glfw.glx.ARB_create_context = true;
     }
 
     if (extensionSupportedGLX("GLX_ARB_create_context_robustness"))
-        _glfw.glx.ARB_create_context_robustness = GLFW_TRUE;
+        _glfw.glx.ARB_create_context_robustness = true;
 
     if (extensionSupportedGLX("GLX_ARB_create_context_profile"))
-        _glfw.glx.ARB_create_context_profile = GLFW_TRUE;
+        _glfw.glx.ARB_create_context_profile = true;
 
     if (extensionSupportedGLX("GLX_EXT_create_context_es2_profile"))
-        _glfw.glx.EXT_create_context_es2_profile = GLFW_TRUE;
+        _glfw.glx.EXT_create_context_es2_profile = true;
 
     if (extensionSupportedGLX("GLX_ARB_create_context_no_error"))
-        _glfw.glx.ARB_create_context_no_error = GLFW_TRUE;
+        _glfw.glx.ARB_create_context_no_error = true;
 
     if (extensionSupportedGLX("GLX_ARB_context_flush_control"))
-        _glfw.glx.ARB_context_flush_control = GLFW_TRUE;
+        _glfw.glx.ARB_context_flush_control = true;
 
-    return GLFW_TRUE;
+    return true;
 }
 
 // Terminate GLX
@@ -435,14 +412,14 @@ void _glfwTerminateGLX(void)
 
 #define setAttrib(a, v) \
 { \
-    assert((size_t) (index + 1) < sizeof(attribs) / sizeof(attribs[0])); \
+    assert(((size_t) index + 1) < sizeof(attribs) / sizeof(attribs[0])); \
     attribs[index++] = a; \
     attribs[index++] = v; \
 }
 
 // Create the OpenGL or OpenGL ES context
 //
-GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
+bool _glfwCreateContextGLX(_GLFWwindow* window,
                                const _GLFWctxconfig* ctxconfig,
                                const _GLFWfbconfig* fbconfig)
 {
@@ -457,7 +434,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
     {
         _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
                         "GLX: Failed to find a suitable GLXFBConfig");
-        return GLFW_FALSE;
+        return false;
     }
 
     if (ctxconfig->client == GLFW_OPENGL_ES_API)
@@ -468,7 +445,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
         {
             _glfwInputError(GLFW_API_UNAVAILABLE,
                             "GLX: OpenGL ES requested but GLX_EXT_create_context_es2_profile is unavailable");
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -478,7 +455,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
         {
             _glfwInputError(GLFW_VERSION_UNAVAILABLE,
                             "GLX: Forward compatibility requested but GLX_ARB_create_context_profile is unavailable");
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -489,7 +466,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
         {
             _glfwInputError(GLFW_VERSION_UNAVAILABLE,
                             "GLX: An OpenGL profile requested but GLX_ARB_create_context_profile is unavailable");
-            return GLFW_FALSE;
+            return false;
         }
     }
 
@@ -554,7 +531,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
         if (ctxconfig->noerror)
         {
             if (_glfw.glx.ARB_create_context_no_error)
-                setAttrib(GLX_CONTEXT_OPENGL_NO_ERROR_ARB, GLFW_TRUE);
+                setAttrib(GLX_CONTEXT_OPENGL_NO_ERROR_ARB, true);
         }
 
         // NOTE: Only request an explicitly versioned context when necessary, as
@@ -590,7 +567,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
             if (_glfw.x11.errorCode == _glfw.glx.errorBase + GLXBadProfileARB &&
                 ctxconfig->client == GLFW_OPENGL_API &&
                 ctxconfig->profile == GLFW_OPENGL_ANY_PROFILE &&
-                ctxconfig->forward == GLFW_FALSE)
+                ctxconfig->forward == false)
             {
                 window->context.glx.handle =
                     createLegacyContextGLX(window, native, share);
@@ -608,7 +585,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
     if (!window->context.glx.handle)
     {
         _glfwInputErrorX11(GLFW_VERSION_UNAVAILABLE, "GLX: Failed to create context");
-        return GLFW_FALSE;
+        return false;
     }
 
     window->context.glx.window =
@@ -616,7 +593,7 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
     if (!window->context.glx.window)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR, "GLX: Failed to create window");
-        return GLFW_FALSE;
+        return false;
     }
 
     window->context.makeCurrent = makeContextCurrentGLX;
@@ -626,15 +603,15 @@ GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
     window->context.getProcAddress = getProcAddressGLX;
     window->context.destroy = destroyContextGLX;
 
-    return GLFW_TRUE;
+    return true;
 }
 
 #undef setAttrib
 
 // Returns the Visual and depth of the chosen GLXFBConfig
 //
-GLFWbool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig,
-                              const _GLFWctxconfig* ctxconfig,
+bool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig UNUSED,
+                              const _GLFWctxconfig* ctxconfig UNUSED,
                               const _GLFWfbconfig* fbconfig,
                               Visual** visual, int* depth)
 {
@@ -645,7 +622,7 @@ GLFWbool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig,
     {
         _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
                         "GLX: Failed to find a suitable GLXFBConfig");
-        return GLFW_FALSE;
+        return false;
     }
 
     result = glXGetVisualFromFBConfig(_glfw.x11.display, native);
@@ -653,14 +630,14 @@ GLFWbool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig,
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
                         "GLX: Failed to retrieve Visual for GLXFBConfig");
-        return GLFW_FALSE;
+        return false;
     }
 
     *visual = result->visual;
     *depth  = result->depth;
 
     XFree(result);
-    return GLFW_TRUE;
+    return true;
 }
 
 
@@ -695,4 +672,3 @@ GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* handle)
 
     return window->context.glx.window;
 }
-

glfw/glx_context.h

@@ -1,8 +1,8 @@
 //========================================================================
-// GLFW 3.3 GLX - www.glfw.org
+// GLFW 3.4 GLX - www.glfw.org
 //------------------------------------------------------------------------
 // Copyright (c) 2002-2006 Marcus Geelnard
-// Copyright (c) 2006-2016 Camilla Löwy <elmindreda@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
@@ -29,11 +29,11 @@
 #define GLX_RGBA_BIT 0x00000001
 #define GLX_WINDOW_BIT 0x00000001
 #define GLX_DRAWABLE_TYPE 0x8010
-#define GLX_RENDER_TYPE	0x8011
+#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_AUX_BUFFERS 7
 #define GLX_RED_SIZE 8
 #define GLX_GREEN_SIZE 9
 #define GLX_BLUE_SIZE 10
@@ -42,7 +42,7 @@
 #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_BLUE_SIZE 16
 #define GLX_ACCUM_ALPHA_SIZE 17
 #define GLX_SAMPLES 0x186a1
 #define GLX_VISUAL_ID 0x800b
@@ -73,6 +73,7 @@ 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*);
@@ -95,6 +96,7 @@ typedef GLXContext (*PFNGLXCREATECONTEXTATTRIBSARBPROC)(Display*,GLXFBConfig,GLX
 // 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
@@ -107,8 +109,8 @@ typedef GLXContext (*PFNGLXCREATECONTEXTATTRIBSARBPROC)(Display*,GLXFBConfig,GLX
 #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
+#define _GLFW_PLATFORM_CONTEXT_STATE            _GLFWcontextGLX glx;
+#define _GLFW_PLATFORM_LIBRARY_CONTEXT_STATE    _GLFWlibraryGLX glx;
 
 
 // GLX-specific per-context data
@@ -134,6 +136,7 @@ typedef struct _GLFWlibraryGLX
     // GLX 1.3 functions
     PFNGLXGETFBCONFIGSPROC              GetFBConfigs;
     PFNGLXGETFBCONFIGATTRIBPROC         GetFBConfigAttrib;
+    PFNGLXCHOOSEFBCONFIGPROC            ChooseFBConfig;
     PFNGLXGETCLIENTSTRINGPROC           GetClientString;
     PFNGLXQUERYEXTENSIONPROC            QueryExtension;
     PFNGLXQUERYVERSIONPROC              QueryVersion;
@@ -153,29 +156,28 @@ typedef struct _GLFWlibraryGLX
     PFNGLXSWAPINTERVALEXTPROC           SwapIntervalEXT;
     PFNGLXSWAPINTERVALMESAPROC          SwapIntervalMESA;
     PFNGLXCREATECONTEXTATTRIBSARBPROC   CreateContextAttribsARB;
-    GLFWbool        SGI_swap_control;
-    GLFWbool        EXT_swap_control;
-    GLFWbool        MESA_swap_control;
-    GLFWbool        ARB_multisample;
-    GLFWbool        ARB_framebuffer_sRGB;
-    GLFWbool        EXT_framebuffer_sRGB;
-    GLFWbool        ARB_create_context;
-    GLFWbool        ARB_create_context_profile;
-    GLFWbool        ARB_create_context_robustness;
-    GLFWbool        EXT_create_context_es2_profile;
-    GLFWbool        ARB_create_context_no_error;
-    GLFWbool        ARB_context_flush_control;
+    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;
 
-GLFWbool _glfwInitGLX(void);
+bool _glfwInitGLX(void);
 void _glfwTerminateGLX(void);
-GLFWbool _glfwCreateContextGLX(_GLFWwindow* window,
+bool _glfwCreateContextGLX(_GLFWwindow* window,
                                const _GLFWctxconfig* ctxconfig,
                                const _GLFWfbconfig* fbconfig);
 void _glfwDestroyContextGLX(_GLFWwindow* window);
-GLFWbool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig,
+bool _glfwChooseVisualGLX(const _GLFWwndconfig* wndconfig,
                               const _GLFWctxconfig* ctxconfig,
                               const _GLFWfbconfig* fbconfig,
                               Visual** visual, int* depth);
-