From 04d69e3c2902bca56605ad59e60b2ae1e5ce91a3 Mon Sep 17 00:00:00 2001 From: Joe Wilm Date: Mon, 2 Jan 2017 09:07:50 -0800 Subject: [PATCH] Write README.md --- README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/README.md b/README.md index 74e67238..22aab2a1 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,129 @@ Alacritty ========= [![Build Status](https://travis-ci.org/jwilm/alacritty.svg?branch=master)](https://travis-ci.org/jwilm/alacritty) + +Alacritty the fastest terminal emulator in existence. Using the GPU for +rendering enables optimizations that simply aren't possible in other emulators. +Alacritty currently supports macOS and Linux, and Windows support is planned +before the 1.0 release. + +

+ Alacritty running vim inside tmux +

+ +## About + +Alacritty is focused on simplicity and performance. The performance goal means +it should be faster than any other terminal emulator available. The simplicity +goal means that it doesn't have many features like tabs or scroll back as in +other terminals. Instead, it is expected that users of Alacritty make use of a +terminal multiplexer such as [`tmux`](https://github.com/tmux/tmux). + +## Installation + +The only supported installation method at this time is from source. Proper +installers will be added prior to the 1.0 release of Alacritty. This section +will walk you through how to build from source on both macOS and Ubuntu. + +### Prerequisites + +1. Install [`rustup.rs`](https://rustup.rs/) + +2. Clone the source code: + + ```sh + git clone https://github.com/jwilm/alacritty + cd alacritty + ``` + +3. Make sure you have the right Rust compiler installed. Alacritty is currently + pinned to a certain Rust nightly, and the compiler/nightly dependencies are + updated as needed. To install the correct compiler, run: + + ```sh + rustup override set $(cat rustc-version) + ``` + +#### Additional Linux Prerequisites + +##### Ubuntu + +On Ubuntu, you need a few extra libraries to build Alacritty. Here's an `apt` +command that should install all of them. If something is still found to be +missing, please open an issue. + +```sh +apt-get install cmake libfreetype6-dev libfontconfig1-dev xclip +``` + +##### Other + +If you build Alacritty on another Linux distribution, we would love some help +filling in this section of the README. + +#### Additional macOS Prerequisites + +It's possible `cmake` is needed on macOS to build Alacritty. If someone can +verify this and make a PR clarifying either way, it would be greatly +appreciated! + +### Building + +Once all the prerequisites are installed, compiling Alacritty should be easy: + +```sh +cargo build --release +``` + +If all goes well, this should place a binary at `target/release/alacritty`. +**BEFORE YOU RUN IT:** Install the config file as described below; otherwise, +many things (such as arrow keys) would not work. + +### Configuration + +Although it's possible the default configuration would work on your system, +you'll probably end up wanting to customize it anyhow. There is an +`alacritty.yml` at the git repository root. Copy this to either +`$HOME/.alacritty.yml` or `$HOME/.config/alacritty.yml` and run Alacritty. + +Many configuration options will take effect immediately upon saving changes to +the config file. The only exception is the `font` and `dpi` section which +requires Alacritty to be restarted. For further explanation of the config file, +please consult the comments in the default config file. + +## Issues (known, unknown, feature requests, etc) + +If you run into a problem with Alacritty, please file an issue. If you've got a +feature request, feel free to ask about it. Keep in mind that Alacritty is very +much not looking to be a feature-rich terminal emulator with all sorts of bells +and widgets. It's primarily a cross-platform, blazing fast `tmux` renderer that +Just Works. + +## FAQ + +- _Is it really the fastest terminal emulator?_ In the terminals I've + benchmarked against, alacritty is either faster, WAY faster, or at least + neutral. There are no benchmarks in which I've found Alacritty to be slower. +- _It's not fast! Why?_ There's a known bug affecting some versions of + Mesa/libxcb where calls to glClear take an insanely long time. If it's not + that, there's probably another bug. I'd be happy to look at the issue if you + can provide some profiling information (wall time and otherwise). +- _macOS + tmux + vim is slow! I thought this was supposed to be fast!_ This + appears to be an issue outside of terminal emulators; either macOS has an IPC + performance issue, or either tmux or vim (or both) have a bug. This same issue + can be seen in `iTerm2` and `Terminal.app`. I've found that if tmux is running + on another machine which is connected to Alacritty via SSH, this issue + disappears. Actual throughput and rendering performance are still better in + Alacritty. +- _Is wayland supported?_ Not yet. Alacritty is currently on a fork of glutin + that needs some updates to work with Wayland. +- _When will Windows support be available?_ When someone has time to work on it. + Contributors would be welcomed :). +- _My arrow keys don't work_ Did you install the default config file? + + +## License + +Alacritty is released under the [Apache License, Version 2.0]. + +[Apache License, Version 2.0]: https://github.com/jwilm/alacritty/blob/readme/LICENSE-APACHE