add launch_menu section to the configuration

refs: https://github.com/wez/wezterm/issues/159

docs/SUMMARY.md

@@ -3,6 +3,7 @@
 - [Features](features.markdown)
 - [Change Log](changelog.markdown)
 - [Configuration](config/files.markdown)
+  - [Launching Programs](config/launch.markdown)
   - [Fonts](config/fonts.markdown)
   - [Font Shaping](config/font-shaping.markdown)
   - [Misc](config/misc.markdown)

docs/changelog.markdown

@@ -10,7 +10,8 @@ daily) from the master branch.  It may not be usable and
 the feature set may change.  As features stabilize some
 brief notes about them may accumulate here.
 
-* Not yet!
+* Added the `launch_menu` configuration for the launcher menu
+  as described in [Launching Programs](config/launch.html).
 
 ### 20200406-151651-5b700e4
 

docs/config/launch.markdown

@@ -0,0 +1,105 @@
+## Launching Programs
+
+By default, when opening new tabs or windows, your shell will be spawned.
+
+Your shell is determined by the following rules:
+
+### On Posix Systems
+
+1. The value of the `$SHELL` environment variable is used if it is set
+2. Otherwise, it will resolve your current uid and try to look up your
+   home directory from the password database.
+
+`wezterm` will spawn the shell and pass `-l` as an argument to request
+a login shell.  A login shell generally loads additional startup files
+and sets up more environment than a non-login shell.
+
+Note: if you have recently changed your shell using `chsh` and you
+have `$SHELL` set in the environment, you will need to sign out and
+sign back in again for the environment to pick up your new `$SHELL`
+value.
+
+### On Windows Systems
+
+1. The value of the `%COMSPEC%` environment variable is used if it is set.
+2. Otherwise, `cmd.exe`
+
+## Changing the default program
+
+If you'd like `wezterm` to run a different program than the shell as
+described above, you can use the `default_prog` config setting to specify
+the argument array; the array allows specifying the program and arguments
+portably:
+
+```lua
+return {
+  -- Spawn a fish shell in login mode
+  default_prog = {"/usr/local/bin/fish", "-l"},
+}
+```
+
+## Passing Environment variables to the spawned program
+
+The `set_environment_variables` configuration setting can be used to
+add environment variables to the environment of the spawned program.
+
+The behavior is to take the environment of the `wezterm` process
+and then set the specified variables for the spawned process.
+
+```lua
+return {
+  set_environment_variables = {
+    -- This changes the default prompt for cmd.exe to report the
+    -- current directory using OSC 7, show the current time and
+    -- the current directory colored in the prompt.
+    prompt = "$E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m "
+  },
+}
+```
+
+# The Launcher Menu
+
+The launcher menu is accessed from the new tab button in the tab bar UI; the
+`+` button to the right of the tabs.  Left clicking on the button will spawn
+a new tab, but right clicking on it will open the launcher menu.  You may also
+bind a key to the `ShowLauncher` action to trigger the menu.
+
+The launcher menu by default lists the various multiplexer domains and offers
+the option of connecting and spawning tabs/windows in those domains.
+
+*(New in the most recent nightly!)* You can define you own entries using the
+`launch_menu` configuration setting.  The snippet below adds two new entries to
+the menu; one that runs the `top` program to monitor process activity and a
+second one that explicitly launches the `bash` shell.
+
+```lua
+return {
+  launch_menu = {
+    {
+      args = {"top"},
+    },
+    {
+      -- Optional label to show in the launcher. If omitted, a label
+      -- is derived from the `args`
+      label = "Bash",
+      -- The argument array to spawn.  If omitted the default program
+      -- will be used as described in the documentation above
+      args = {"bash", "-l"},
+
+      -- You can specify an alternative current workding directory;
+      -- if you don't specify one then a default based on the OSC 7
+      -- escape sequence will be used (see the Shell Integration
+      -- docs), falling back to the home directory.
+      -- cwd = "/some/path"
+
+      -- You can override environment variables just for this command
+      -- by setting this here.  It has the same semantics as the main
+      -- set_environment_variables configuration option described above
+      -- set_environment_variables = { FOO = "bar" },
+    },
+  }
+}
+```
+
+<img src="../screenshots/launch-menu.png" alt="Screenshot">
+

docs/config/misc.markdown

@@ -11,15 +11,6 @@ return {
   -- to a single cell width
   enable_scroll_bar = true,
 
-  -- If no `prog` is specified on the command line, use this
-  -- instead of running the user's shell.
-  -- The value is the argument array, with the 0th element being
-  -- the executable to run.  The path will be searched to locate
-  -- this if needed.
-  -- For example, to have `wezterm` always run `top` by default,
-  -- you'd use this:
-  default_prog = {"top"},
-
   -- What to set the TERM variable to
   term = "xterm-256color",
 

src/config/mod.rs

@@ -5,7 +5,7 @@ use crate::font::locator::FontLocatorSelection;
 use crate::font::rasterizer::FontRasterizerSelection;
 use crate::font::shaper::FontShaperSelection;
 use crate::frontend::FrontEndSelection;
-use crate::keyassignment::KeyAssignment;
+use crate::keyassignment::{KeyAssignment, SpawnCommand};
 use anyhow::{anyhow, bail, Context, Error};
 use lazy_static::lazy_static;
 use portable_pty::{CommandBuilder, PtySize};
@@ -490,6 +490,9 @@ pub struct Config {
 
     #[serde(default)]
     pub use_local_build_for_proxy: bool,
+
+    #[serde(default)]
+    pub launch_menu: Vec<SpawnCommand>,
 }
 
 #[derive(Deserialize, Serialize, Clone, Copy, Debug)]

src/frontend/gui/overlay/launcher.rs

@@ -5,6 +5,7 @@
 //! be rendered as a popup/context menu if the system supports it; at the
 //! time of writing our window layer doesn't provide an API for context
 //! menus.
+use crate::config::configuration;
 use crate::frontend::gui::termwindow::{ClipboardHelper, TermWindow};
 use crate::keyassignment::{SpawnCommand, SpawnTabDomain};
 use crate::mux::domain::{DomainId, DomainState};
@@ -54,6 +55,22 @@ pub fn launcher(
     let mut active_idx = 0;
     let mut entries = vec![];
 
+    // Pull in the user defined entries from the launch_menu
+    // section of the configuration.
+    for item in &configuration().launch_menu {
+        entries.push(Entry::Spawn {
+            label: match item.label.as_ref() {
+                Some(label) => label.to_string(),
+                None => match item.args.as_ref() {
+                    Some(args) => args.join(" "),
+                    None => "(default shell)".to_string(),
+                },
+            },
+            command: item.clone(),
+            new_window: false,
+        });
+    }
+
     for (domain_id, domain_state, domain_name) in &domains {
         let entry = if *domain_state == DomainState::Attached {
             Entry::Spawn {

src/keyassignment.rs

@@ -27,6 +27,9 @@ impl Default for SpawnTabDomain {
 
 #[derive(Default, Debug, Clone, Deserialize, Serialize)]
 pub struct SpawnCommand {
+    /// Optional descriptive label
+    pub label: Option<String>,
+
     /// The command line to use.
     /// If omitted, the default command associated with the
     /// domain will be used instead, which is typically the