feat: upgrade installer and add docs (#2551)

cli/flags.rs

@@ -350,7 +350,21 @@ Demonstrates breaking the input up by space delimiter instead of by lines:
         .long_about(
 "Automatically downloads deno_installer dependencies on first run.
 
-  deno install file_server https://deno.land/std/http/file_server.ts --allow-net --allow-read",
+Default installation directory is $HOME/.deno/bin and it must be added to the path manually.
+
+  deno install file_server https://deno.land/std/http/file_server.ts --allow-net --allow-read
+
+  deno install colors https://deno.land/std/examples/colors.ts
+
+To change installation directory use -d/--dir flag
+
+  deno install -d /usr/local/bin file_server https://deno.land/std/http/file_server.ts --allow-net --allow-read",
+        ).arg(
+          Arg::with_name("dir")
+            .long("dir")
+            .short("d")
+            .help("Installation directory (defaults to $HOME/.deno/bin)")
+            .takes_value(true)
         ).arg(
           Arg::with_name("exe_name")
             .help("Executable name")
@@ -509,7 +523,7 @@ fn parse_run_args(mut flags: DenoFlags, matches: &ArgMatches) -> DenoFlags {
 /// Used for `deno fmt <files>...` subcommand
 const PRETTIER_URL: &str = "https://deno.land/std@v0.7.0/prettier/main.ts";
 /// Used for `deno install...` subcommand
-const INSTALLER_URL: &str = "https://deno.land/std@1679ba/installer/mod.ts";
+const INSTALLER_URL: &str = "https://deno.land/std@b13441f/installer/mod.ts";
 
 /// These are currently handled subcommands.
 /// There is no "Help" subcommand because it's handled by `clap::App` itself.
@@ -617,10 +631,18 @@ pub fn flags_from_vec(
       flags.allow_run = true;
       argv.push(INSTALLER_URL.to_string());
 
+      if install_match.is_present("dir") {
+        let install_dir = install_match.value_of("dir").unwrap();
+        argv.push("--dir".to_string());
+        argv.push(install_dir.to_string());
+      }
+
       let exe_name: &str = install_match.value_of("exe_name").unwrap();
+      argv.push(exe_name.to_string());
+
       match install_match.subcommand() {
         (script_url, Some(script_match)) => {
-          argv.extend(vec![exe_name.to_string(), script_url.to_string()]);
+          argv.push(script_url.to_string());
           if script_match.is_present("") {
             let flags: Vec<String> = script_match
               .values_of("")
@@ -1322,5 +1344,41 @@ mod tests {
         "--allow-read"
       ]
     );
+
+    let (flags, subcommand, argv) = flags_from_vec(svec![
+      "deno",
+      "install",
+      "-d",
+      "/usr/local/bin",
+      "file_server",
+      "https://deno.land/std/http/file_server.ts",
+      "--allow-net",
+      "--allow-read"
+    ]);
+    assert_eq!(
+      flags,
+      DenoFlags {
+        allow_write: true,
+        allow_net: true,
+        allow_read: true,
+        allow_env: true,
+        allow_run: true,
+        ..DenoFlags::default()
+      }
+    );
+    assert_eq!(subcommand, DenoSubcommand::Install);
+    assert_eq!(
+      argv,
+      svec![
+        "deno",
+        INSTALLER_URL,
+        "--dir",
+        "/usr/local/bin",
+        "file_server",
+        "https://deno.land/std/http/file_server.ts",
+        "--allow-net",
+        "--allow-read"
+      ]
+    );
   }
 }

website/manual.md

@@ -698,6 +698,82 @@ export main() {
 }
 ```
 
+### Installing executable scripts
+
+Deno provides ability to easily install and distribute executable code via
+`deno install` command.
+
+`deno install [EXE_NAME] [URL] [FLAGS...]` will install script available at
+`URL` with name `EXE_NAME`.
+
+This command is a thin wrapper that creates executable shell scripts which
+invoke `deno` with specified permissions and CLI flags.
+
+Example:
+
+```
+$ deno install file_server https://deno.land/std/http/file_server.ts --allow-net --allow-read
+[1/1] Compiling https://deno.land/std/http/file_server.ts
+
+✅ Successfully installed file_server.
+/Users/deno/.deno/bin/file_server
+```
+
+By default scripts are installed at `$HOME/.deno/bin` and that directory must be
+added to the path manually.
+
+```
+$ echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
+```
+
+Installation directory can be changed using `-d/--dir` flag:
+
+```
+deno install --dir /usr/local/bin prettier https://deno.land/std/prettier/main.ts --allow-write --allow-read
+```
+
+When installing a script you can specify permissions that will be used to run
+the script. They are placed after the script URL and can be mixed with any
+additional CLI flags you want to pass to the script.
+
+Example:
+
+```
+deno install format_check https://deno.land/std/prettier/main.ts --allow-write --allow-read --check --print-width 88 --tab-width 2
+```
+
+Above command creates an executable called `format_check` that runs `prettier`
+with write and read permissions. When you run `format_check` deno will run
+prettier in `check` mode and configured to use `88` column width with `2` column
+tabs.
+
+It is a good practice to use `import.meta.main` idiom for an entry point for
+executable file. See
+[Testing if current file is the main program](#testing-if-current-file-is-the-main-program)
+section.
+
+Example:
+
+```ts
+// https://example.com/awesome/cli.ts
+async function myAwesomeCli(): Promise<void> {
+  -- snip --
+}
+
+if (import.meta.main) {
+  myAwesomeCli();
+}
+```
+
+When you create executable script make sure to let users know by adding example
+installation command to your repository:
+
+```
+# Install using deno install
+
+$ deno install awesome_cli https://example.com/awesome/cli.ts
+```
+
 ## Import maps
 
 Deno supports [import maps](https://github.com/WICG/import-maps).