Building and Customizing the new Windows Terminal
Tags: beginners, opensource, productivity, bash
Published: 2019-05-14 16:02:03

---
title: Building and Customizing the new Windows Terminal
published: true
description: There is a new Windows Terminal!  While early in development, this post walks through how to get it, build it, and the settings to customize.  Run bash, zsh, cmd, PowerShell all in one place!
tags: beginners,opensource,productivity,bash
canonical_url: https://timheuer.com/blog/archive/2019/05/13/building-windows-terminal-navigating-source-and-profile-settings.aspx
---
<p>I don’t like C++.&nbsp; There I said it…got it out of the way.&nbsp; It’s not a fair statement, as I know many people who do and think I’m crazy for not only writing code in C++.&nbsp; As someone who didn’t come from a traditional computer science background, I just never ‘grew up’ on C or C++ as fundamentals.&nbsp; </p><blockquote><p>NOTE: You can hear more about my journey (and others) to tech on the awesome <strong><a href="https://www.codenewbie.org">CodeNewbie</a></strong> podcast.&nbsp; Here’s my episode right here: <a href="https://www.codenewbie.org/podcast/from-police-recruit-to-developer">From police recruit to developer</a>.</p></blockquote><p>Go ahead, insert ‘you’re not a real programmer’ comments below.&nbsp; I’ve established enough thick skin over the years to hear that feedback.&nbsp; Anyhow, I digress.&nbsp; While I’m not a fan of C++ it really isn’t about the language but the iteration dev loop.&nbsp; I’ve often found it slower than what I’d like and the mix/match of toolsets, settings, etc. has left a lot to be desired to me.&nbsp; HOWEVER, all this said, looking at C++ code is an excellent way to learn and to actually appreciate more the language and code that others write.&nbsp; No better source of learning development exists than code.</p><p>Last week at the Microsoft Build conference a fun new project was unleashed to the developer community…a new <strong><a href="https://github.com/microsoft/Terminal/">Windows Terminal</a></strong>.&nbsp; AND it is Open Source!&nbsp; </p><p><img width="1083" height="640" style="margin-right: auto; margin-left: auto; float: none; display: block;" src="https://storage2.timheuer.com/terminal1.png"></p><p>I’ve never seen as much excitement about a terminal app in this ecosystem as I have the past 10 days.&nbsp; So much fun.&nbsp; First, here’s the team that brings you the Windows Terminal project:</p><p><blockquote class="twitter-tweet"><p lang="en" dir="ltr">Dear <a href="https://twitter.com/hashtag/Build2019?src=hash&amp;ref_src=twsrc%5Etfw">#Build2019</a> physical and virtual attendees &amp; tweeps - thank you for attending our talks, visiting our booth, and asking/posting tons of great questions &amp; comments. We appreciate you all.<br><br>With love from the <a href="https://twitter.com/hashtag/WSL?src=hash&amp;ref_src=twsrc%5Etfw">#WSL</a> and <a href="https://twitter.com/hashtag/Terminal?src=hash&amp;ref_src=twsrc%5Etfw">#Terminal</a> teams<br><br>Until next year 😜 <a href="https://t.co/VayHovDnNJ">pic.twitter.com/VayHovDnNJ</a></p>— Rich Tur-minal-ner-d (@richturn_ms) <a href="https://twitter.com/richturn_ms/status/1126264083043328002?ref_src=twsrc%5Etfw">May 8, 2019</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script><p>Great people, passionate about making Windows a great development environment for no matter what you are developing.&nbsp; This is also the team bringing you WSL and the new capabilities there!&nbsp; So you want to try out the terminal…your first question is <em>Where can I get it?</em></p><h2>Building Windows Terminal</h2><p>Well, for now it is source only.&nbsp; This will likely change over the course of the next few months, but for now if you really want to try it out, you need to build it yourself.&nbsp; The <a href="https://github.com/microsoft/Terminal/">repository on GitHub</a> has all the bits and instructions for you to do so.&nbsp; I jumped on this right away like others but ran into a few bumps because I was using Visual Studio 2019.&nbsp; Luckily this has been solved by <a href="https://github.com/microsoft/Terminal/commit/af7316c130059ba15fe16ff0d13608d956a2b449">this PR</a> to help make the scavenger hunt for dependencies less painful.&nbsp; </p><blockquote><p>SIDE NOTE: If you have an open source or team-based project, do yourself a favor and add a .vsconfig file now.&nbsp; Details: <a href="https://devblogs.microsoft.com/setup/configure-visual-studio-across-your-organization-with-vsconfig/?WT.mc_id=blog-blog-timheuer">Configure Visual Studio across your organization with .vsconfig</a></p></blockquote><p>Basically the steps are:</p><ul><li><a href="https://docs.microsoft.com/windows/uwp/get-started/enable-your-device-for-development?WT.mc_id=docs-blog-timheuer">put your machine in developer mode</a></li><li>ensure you have some Git tools</li><li>ensure you have the C++ tools (compilers, etc.) (<a href="https://visualstudio.microsoft.com/?WT.mc_id=visualstudio-blog-timheuer">Visual Studio Community Edition</a> is free to download/install and works)</li><li>clone the repository</li><li><a href="https://github.com/microsoft/Terminal#building-the-code">update the submodules</a></li><li>build the repo (using VS or the tools\bcz script)</li></ul><p>If you use Visual Studio 2019 (recommended by me) opening the OpenConsole.sln file should prompt you with a screen that will give you a note to ‘install’ the missing dependencies in the Solution Explorer:</p><p><img style="margin-right: auto; margin-left: auto; float: none; display: block;" src="https://storage2.timheuer.com/vsconfig-screenshot00.png"></p><p>If you click Install it will run you through the missing components you may not have enabled for completing the build.&nbsp; Finish that process.&nbsp; Once done, you will have all the bits and can go back to the OpenConsole.sln project and choose ‘Build Solution’ and start the process.&nbsp; Lots of stuff building for the first time so it will take a bit.&nbsp; Now what?</p><h2>Deploying/Running Windows Terminal</h2><p>Building is step 1, now you want to run it.&nbsp; Windows Terminal is a Universal Windows Platform (UWP) application and must be deployed first.&nbsp; The <em>easiest</em> way for doing this is from Visual Studio, but you may want to know what project!?&nbsp; The <strong>Terminal\CascadiaPackage</strong> project is the one you want and just right-click on that and choose Deploy.&nbsp; This will deploy it to your machine (assuming you enabled developer mode).&nbsp; And this will now be in your start menu:</p><p><img style="margin-right: auto; margin-left: auto; float: none; display: block;" src="https://storage2.timheuer.com/startmenuterminal.png"></p><p>Click/tap/whatever on that and you will launch Terminal for the first time!</p><h2>Wait, where are the tabs I saw?</h2><p>Ah, now that you have it running, let’s take a tour.&nbsp; The settings right now are a JSON file that you can access via the settings menu.&nbsp; How do you get the settings menu?&nbsp; Hit CTRL + T to bring up the tab view and then you should have a drop-down menu in the upper right area:</p><p><img style="margin-right: auto; margin-left: auto; float: none; display: block;" src="https://storage2.timheuer.com/terminalmenupic.png"></p><p>If you click Settings it will open up the profile.json file in the default editor on your machine configured for editing JSON files.&nbsp; For me this was Visual Studio, but you can use Code or other editor as well.&nbsp; This is editing your own profile for your terminal environment.&nbsp; By default this JSON is void of white-space so you may want to format it to make it more readable.&nbsp; In Visual Studio that is CTRL + K, CTRL + D and it will prettify it for you.&nbsp; You’ll then see some initial settings in the top of the file:</p><p><pre class="brush: css; toolbar: false; highlight: [5];">{
  "defaultProfile": "{a933a071-2a32-42c9-b03a-550845793252}",
  "initialRows": 30,
  "initialCols": 120,
  "alwaysShowTabs": true,
  "showTerminalTitleInTitlebar": true,
  "experimental_showTabsInTitlebar": false,
</pre><p>If you change line 5 here like I did to true then you will always start with tabs even if only one console host is running.&nbsp; When you save the profile.json file it will re-format to no whitespace FYI (there is a watcher on the file in the code) but the settings will become immediate.</p><h2>Navigating the profile.json options</h2><p>The profile file main meat is in the profiles themselves.&nbsp; These drive what shells/consoles you can launch and their configuration.&nbsp; For example here is a snippet of what mine looks like right now a bit:</p><p><pre class="brush: css; toolbar: false;">{
  "defaultProfile": "{a933a071-2a32-42c9-b03a-550845793252}",
  "initialRows": 30,
  "initialCols": 120,
  "alwaysShowTabs": true,
  "showTerminalTitleInTitlebar": true,
  "experimental_showTabsInTitlebar": false,
  "profiles": [
    {
      "startingDirectory": "c:\\users\\timheuer\\documents\\github",
      "guid": "{b056b6a8-89ba-4868-86c6-2ea078cd4fdd}",
      "name": "cmd",
      "colorscheme": "UbuntuLegit",
      "historySize": 9001,
      "snapOnInput": true,
      "cursorColor": "#FFFFFF",
      "cursorHeight": 25,
      "cursorShape": "vintage",
      "commandline": "cmd.exe",
      "fontFace": "Cascadia Code",
      "fontSize": 12,
      "acrylicOpacity": 0.75,
      "useAcrylic": true,
      "closeOnExit": true,
      "padding": "0, 0, 0, 0",
      "icon": "ms-appdata:///roaming/cmd-icon.png"
    },
    {
      "startingDirectory": "c:\\users\\timheuer\\documents\\github",
      "guid": "{a933a071-2a32-42c9-b03a-550845793252}",
      "name": "PowerShell",
      "background": "#0C0C0C",
      "colorscheme": "UbuntuLegit",
      "historySize": 9001,
      "snapOnInput": true,
      "cursorColor": "#FFFFFF",
      "cursorHeight": 25,
      "cursorShape": "vintage",
      "commandline": "powershell.exe",
      "fontFace": "Meslo LG M for Powerline",
      "fontSize": 12,
      "acrylicOpacity": 0.75,
      "useAcrylic": true,
      "closeOnExit": true,
      "padding": "0, 0, 0, 0",
      "icon": "ms-appdata:///roaming/powershell_64.png"
    },
</pre><p>While I don’t have all options enabled a <a href="https://github.com/microsoft/Terminal/blob/master/src/cascadia/TerminalApp/Profile.cpp">little spelunking the source code</a> helps you know what other options exist:</p><ul><li>name: the name of the particular profile.&nbsp; Right now this is what shows in the drop-down menu shown previously.&nbsp; There is an issue logged to perhaps make this the name of the tab as well.</li><li>guid: the unique identifier of this profile.&nbsp; Incidentally if you didn’t know and wanted to create your own profiles and need a GUID, VIsual Studio has a “Create GUID” tool available from the tools menu…choose registry format and then copy/paste</li><li>colorscheme: this maps to the color scheme for this area…which is an array of colors that maps to the various foreground/background/text/highlight/etc. settings that are also configurable.&nbsp; You can see in your profile file that Campbell and a few others (Solarized Dark/Light) are pre-configured.&nbsp; You can use iterm2colors values to create a new scheme.</li><li>foreground: the foreground, duh (overwriting colortable/scheme)</li><li>background: the background, duh (overwriting colortable/scheme)</li><li>colortable: an in-line version of the color array that would be within a scheme</li><li>historySize: I honestly haven’t looked at this one yet in the code to know</li><li>snapOnInput: I honestly haven’t looked at this one either</li><li>cursorColor: color of the cursor style you chose</li><li>cursorShape: different options to show the cursor: vintage (thick underscore), bar (vertial bar), underscore (thin underscore), filledBox, emptyBox</li><li>cursorHeight: height for the cursor</li><li>commandline: the command to run for the profile (full path or something that will be found in PATH)</li><li>fontFace: the fond to use for this profile.&nbsp; You may see in mine that I am using ‘Meslo LG M for Powerline’ to get the cool customizations of the prompt.&nbsp; <a href="https://gist.github.com/jchandra74/5b0c94385175c7a8d1cb39bc5157365e">Find more on how to do that here</a> and it works in Windows Terminal</li><ul><li>Note: the team will also be open sourcing a new font that will be used for the terminal, but is not yet available as of this post</li></ul><li>fontSize: size of the font</li><li>acrylicOpacity: the opacity of the window if you choose to use the acrylic (transparency) feature.&nbsp; value from 0-1</li><li>useAcrylic: true/false if you want to use the transparency</li><li>scrollbarState: hidden/visible are the options</li><li>closeOnExit: true/false if you want the tab to close when you initiate the exit command for your host</li><li>padding: this affects some of the output but honestly not working well right now, recommend leaving at 0,0,0,0</li><li>startingDirectory: the startup directory for this profile.&nbsp; I have mine configured with my github directory where all my code is instead of $home (which is default)</li><li>icon: an icon that will show in the menu and the tab.&nbsp; These live in your RoamingState directory (C:\Users\&lt;yourusername&gt;AppData\Local\Packages\WindowsTerminalDev_8wekyb3d8bbwe\RoamingState) and the format for the value is “ms-appdata:///roaming/&lt;yourfilename&gt;”</li></ul><p>For now these are the available options that you should fitz around with to customize what you need to change.&nbsp; I’ve messed around with these enough and got to where I want them to be for me right now.</p><h2>Navigating the source and contributing</h2><p>As I started this post about how I didn’t like C++, it is a good place to learn a lot.&nbsp; The Windows Terminal source is a maze of someone else’s code and right now without a clear map.&nbsp; So the best way is to really just dig in and follow a particular flow.&nbsp; I find this is the best way to navigate any project source code: find one feature and try to find and follow it in the code.&nbsp; For me, I was messing with the settings file so much and I hated using the menu with my mouse I wanted a keyboard shortcut.&nbsp; I knew that CTRL + T launched a new tab, so hey I could implement a keyboard shortcut to launch the settings file quickly.&nbsp; I first logged that feature as an issue on the project: <a href="https://github.com/microsoft/Terminal/issues/683">Add keybinding for access to Settings</a> and then went to work.&nbsp; I knew that the new tab shortcut existed so I took my own advice: <em>follow the code!</em>&nbsp; After a few tries and navigating all the headers and various code files I submitted a PR to the project for my own issue: <a href="https://github.com/microsoft/Terminal/pull/684/commits/c5cadf7b004ab4c380dabfe52c3458935df7383e">PR#684</a>.&nbsp; There were 6 files changed to add this key binding and if you look at the change I proposed, there was already a function I could call (same one the menu uses) and I really just needed to map the key binding and have it call the existing function.&nbsp; Simple, but I learned a bit of how the current code is structured in the repository.</p><p>So my recommendation would be to find something that you are seeing as a piece of existing functionality or something you want to add yourself and start looking at searching for where you think it might be.&nbsp; You’ll quickly find out some of the structure around TerminalSettings, TerminalCore, TerminalControl, etc. and play around with making some changes.&nbsp; Keep in mind this is active development and things will change around quite frequently.&nbsp; The team even indicates much:</p><blockquote><p>⚠ <strong>Note</strong>: The Command-Line Team is actively working out of this repository and will be periodically re-structuring the code to make it easier to comprehend, navigate, build, test, and contribute to, so <strong>DO expect significant changes to code layout on a regular basis</strong>.</p></blockquote><p>I have already been bitten a bit by a merge, but no big deal just fix up a few things and move along again!</p><h2>What’s Next?</h2><p>The team has a good aspiration of what they want to accomplish and just getting started.&nbsp; Quality will improve, bugs will get fixed, consumption of the terminal will be better, etc.&nbsp; Read the README file in the repository and engage with the team on Twitter (their contact info in the README).</p><p>Hope this helps!</p><p><br></p><p><br/><br/>(this article <a href="https://timheuer.com/blog/archive/2019/05/13/building-windows-terminal-navigating-source-and-profile-settings.aspx">cross-posted from timheuer.com</a>)</p>