diff --git a/README.md b/README.md index 350f3f2f024..45f6f768ea6 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,86 @@ -# Welcome\! -#### This repository contains the source code for: - - * [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701) - * The Windows console host (`conhost.exe`) - * Components shared between the two projects - * [ColorTool](https://github.com/Microsoft/Terminal/tree/master/src/tools/ColorTool) - * [Sample projects](https://github.com/Microsoft/Terminal/tree/master/samples) that show how to consume the Windows Console APIs +# Welcome + +This repository contains the source code for: + +* [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701) +* The Windows console host (`conhost.exe`) +* Components shared between the two projects +* [ColorTool](https://github.com/Microsoft/Terminal/tree/master/src/tools/ColorTool) +* [Sample projects](https://github.com/Microsoft/Terminal/tree/master/samples) that show how to consume the Windows Console APIs -#### Other related repositories include: - * [Console API Documentation](https://github.com/MicrosoftDocs/Console-Docs) +Other related repositories include: + +* [Console API Documentation](https://github.com/MicrosoftDocs/Console-Docs) -## Installation +## Installing & running Windows Terminal -_(Note: in order to run the Windows Terminal, you'll need to be running at least Windows build 18362 or higher.)_ +> 👉 Note: To run the Windows Terminal you'll need to be running Windows 10 1903 (build 18362) or later -### Microsoft Store +### From the Microsoft Store -Download the Microsoft Terminal free from the Microsoft Store and it'll be continuously updated. Or, feel free to side-load [releases](https://github.com/microsoft/terminal/releases) from GitHub, but note they won't auto-update. +Download the Microsoft Terminal free from the Microsoft Store and it'll be continuously updated: English badge -### Chocolatey (Unofficial) +### From this repository +Every public release of Windows Terminal is avaiable for manual download from [this repo's Releases page](https://github.com/microsoft/terminal/releases) + +> ⚠ Note: If you manually install Terminal from [releases](https://github.com/microsoft/terminal/releases) they won't auto-update so be sure to regularly install the latest Terminal release to receive all the latest fixes and improvements! + +### Via Chocolatey (unofficial) -Download and upgrade the Windows Terminal from [Chocolatey](https://chocolatey.org). +[Chocolatey](https://chocolatey.org) users can download and install the latest Terminal release by installing the `microsoft-windows-terminal` package: -To install Windows Terminal, run the following command from the command line or from PowerShell: ```powershell choco install microsoft-windows-terminal ``` -To upgrade Windows Terminal, run the following command from the command line or from PowerShell: +To upgrade Windows Terminal using Chocolatey, run the following: + ```powershell choco upgrade microsoft-windows-terminal ``` If you have any issues when installing/upgrading the package please go to the [package page](https://chocolatey.org/packages/microsoft-windows-terminal) and follow the [Chocolatey triage process](https://chocolatey.org/docs/package-triage-process) -### Build Status +--- + +## Project Build Status Project|Build Status ---|--- Terminal|[![Build Status](https://dev.azure.com/ms/Terminal/_apis/build/status/Terminal%20CI?branchName=master)](https://dev.azure.com/ms/Terminal/_build?definitionId=136) ColorTool|![](https://microsoft.visualstudio.com/_apis/public/build/definitions/c93e867a-8815-43c1-92c4-e7dd5404f1e1/17023/badge) -# Windows Terminal Project's Timeline +--- + +## Windows Terminal v1.0 Roadmap -The plan for delivering Windows Terminal v1.0 [is described here](/doc/terminal-v1-timeline.md), and will be updated as the project proceeds. +The plan for delivering Windows Terminal v1.0 [is described here](/doc/terminal-v1-roadmap.md), and will be updated as the project proceeds. -# Terminal & Console Overview +--- + +## Terminal & Console Overview Please take a few minutes to review the overview below before diving into the code: -## Windows Terminal +### Windows Terminal Windows Terminal is a new, modern, feature-rich, productive terminal application for command-line users. It includes many of the features most frequently requested by the Windows command-line community including support for tabs, rich text, globalization, configurability, theming & styling, and more. The Terminal will also need to meet our goals and measures to ensure it remains fast, and efficient, and doesn't consume vast amounts of memory or power. -## The Windows console host - -The Windows console host, `conhost.exe`, is Windows' original command-line user experience. It implements Windows' command-line infrastructure, and is responsible for hosting the Windows Console API, input engine, rendering engine, and user preferences. The console host code in this repository is the actual source from which the `conhost.exe` in Windows itself is built. +### The Windows Console host -Console's primary goal is to remain backwards-compatible with existing console subsystem applications. +The Windows Console host, `conhost.exe`, is Windows' original command-line user experience. It implements Windows' command-line infrastructure, and is responsible for hosting the Windows Console API, input engine, rendering engine, and user preferences. The console host code in this repository is the actual source from which the `conhost.exe` in Windows itself is built. Since assuming ownership of the Windows command-line in 2014, the team has added several new features to the Console, including window transparency, line-based selection, support for [ANSI / Virtual Terminal sequences](https://en.wikipedia.org/wiki/ANSI_escape_code), [24-bit color](https://devblogs.microsoft.com/commandline/24-bit-color-in-the-windows-console/), a [Pseudoconsole ("ConPTY")](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/), and more. -However, because the Console's primary goal is to maintain backward compatibility, we've been unable to add many of the features the community has been asking for, and which we've been wanting to add for the last several years--like tabs! +However, because Windows Console's primary goal is to maintain backward compatibility, we've been unable to add many of the features the community has been asking for (and which we've been wanting to add) for the last several years including tabs, unicode text, emoji, etc. These limitations led us to create the new Windows Terminal. -## Shared Components +### Shared Components While overhauling the Console, we've modernized its codebase considerably. We've cleanly separated logical entities into modules and classes, introduced some key extensibility points, replaced several old, home-grown collections and containers with safer, more efficient [STL containers](https://docs.microsoft.com/en-us/cpp/standard-library/stl-containers?view=vs-2019), and made the code simpler and safer by using Microsoft's [WIL](https://github.com/Microsoft/wil) header library. @@ -81,33 +92,27 @@ When we started building the new terminal application, we explored and evaluated Further, we realized that this would allow us to build the terminal's renderer and input stack as a reusable Windows UI control that others can incorporate into their applications. -# FAQ +--- -## Where can I download Windows Terminal? - -The latest release of Windows Terminal can be downloaded from [this repo's Releases](https://github.com/microsoft/terminal/releases) page or [from the Microsoft Store](https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701) +## FAQ ## I built and ran the new Terminal, but I just get a blank window app! Make sure you are building for your computer's architecture. If your box has a 64-bit Windows, change your Solution Platform to x64. To check your OS architecture go to Settings -> System -> About (or Win+X -> System) and under `Device specifications` check for the `System type`. -## I built and ran the new Terminal, but it looks just like the old console! What gives? +## I built and ran the new Terminal, but it looks just like the old console Firstly, make sure you're building & deploying `CascadiaPackage` in Visual Studio, _NOT_ `Host.EXE`. `OpenConsole.exe` is just `conhost.exe`, the same old console you know and love. `opencon.cmd` will launch `openconsole.exe`, and unfortunately, `openterm.cmd` is currently broken. Secondly, try pressing Ctrl + T. The tabs are hidden when you only have one tab by default. In the future, the UI will be dramatically different, but for now, the defaults are _supposed_ to look like the console defaults. -## I tried running WindowsTerminal.exe and it crashes! +## I tried running WindowsTerminal.exe and it crashes * Don't try to run it unpackaged. Make sure to build & deploy `CascadiaPackage` from Visual Studio, and run the Windows Terminal (Dev Build) app. * Make sure you're on the right version of Windows. You'll need to be on Insider's builds, or wait for the 1903 release, as the Windows Terminal **REQUIRES** features from the latest Windows release. -# Getting Started - -## Debugging - -* To debug in VS, right click on CascadiaPackage (from VS Solution Explorer) and go to properties, in the Debug menu, change "Application process" and "Background task process" to "Native Only". +--- ## Contributing @@ -139,7 +144,8 @@ If you would like to ask a question that you feel doesn't warrant an issue (yet) * Kayla Cinnamon, Program Manager (especially for UX issues): [@cinnamon\_msft](https://twitter.com/cinnamon_msft) -# Developer Guidance + +## Developer Guidance ## Build Prerequisites @@ -154,7 +160,6 @@ If you would like to ask a question that you feel doesn't warrant an issue (yet) * You must also [enable Developer Mode in the Windows Settings app](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development) to locally install and run the Terminal app. - ## Building the Code This repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for some of its dependencies. To make sure submodules are restored or updated, be sure to run the following prior to building: @@ -182,7 +187,11 @@ bcz We've provided a set of convenience scripts as well as [README](./tools/README.md) in the **/tools** directory to help automate the process of building and running tests. -## Coding Guidance +### Debugging + +* To debug in VS, right click on CascadiaPackage (from VS Solution Explorer) and go to properties, in the Debug menu, change "Application process" and "Background task process" to "Native Only". + +### Coding Guidance Please review these brief docs below relating to our coding standards etc. @@ -195,6 +204,8 @@ This is a work in progress as we learn what we'll need to provide people in orde - [Exceptions in our legacy codebase](https://github.com/Microsoft/Terminal/blob/master/doc/EXCEPTIONS.md) - [Helpful smart pointers and macros for interfacing with Windows in WIL](https://github.com/Microsoft/Terminal/blob/master/doc/WIL.md) +--- + # Code of Conduct This project has adopted the [Microsoft Open Source Code of Conduct][conduct-code].