feat(install-path): add install-path config

book/src/config.md

@@ -192,7 +192,7 @@ If no scope is specified the package will be global.
 
 > since 0.1.0
 
-Example `checksum = "sha512"`
+Example: `checksum = "sha512"`
 
 Specifies how to checksum [executable-zips][]. Supported values:
 
@@ -209,7 +209,7 @@ Future work is planned to [support more robust signed checksums][issue-sigstore]
 
 > since 0.1.0
 
-Example `precise-builds = true`
+Example: `precise-builds = true`
 
 **This can only be set globally**
 
@@ -232,7 +232,7 @@ If that downside is big enough for you, this setting is a good idea.
 
 > since 0.1.0
 
-Example `merge-tasks = true`
+Example: `merge-tasks = true`
 
 **This can only be set globally**
 
@@ -242,11 +242,12 @@ For example, if you build for x64 macos and arm64 macos, by default we will gene
 
 The default is `false`. Before 0.1.0 it was always `true` and couldn't be changed, making releases annoyingly slow (and technically less fault-isolated). This config was added to allow you to restore the old behaviour, if you really want.
 
+
 ### fail-fast
 
 > since 0.1.0
 
-Example `fail-fast = true`
+Example: `fail-fast = true`
 
 **This can only be set globally**
 
@@ -267,6 +268,28 @@ Prior to 0.1.0 we didn't set the correct flags in our CI scripts to do this, but
 This flag was introduced to allow you to restore the old behaviour if you prefer.
 
 
+### install-path
+
+> since 0.1.0
+
+Example: `install-path = "~/.my-app/"`
+
+The strategy to use for selecting a path to install things at, with 3 possible syntaxes:
+
+* `CARGO_HOME`: (default) installs as if `cargo install` did it (tries `$CARGO_HOME/bin/`, but if `$CARGO_HOME` isn't set uses `$HOME/.cargo/bin/`). Note that we do not (yet) properly update some of the extra metadata files Cargo maintains, so Cargo may be confused if you ask it to manage the binary.
+
+* `~/some/subdir/`: installs to the given subdir of the user's `$HOME`
+
+* `$SOME_VAR/some/subdir`: installs to the given subdir of the dir defined by `$SOME_VAR`
+
+> NOTE: `$HOME/some/subdir` is technically valid syntax but it won't behave the way you want on Windows, because `$HOME` isn't a proper environment variable. Let us handle those details for you and just use `~/subdir/`.
+
+All of these error out if none of the required env-vars are set to a non-empty value. In the future we may expand this setting to allow you to pass an array of options that are tried in sequence until one succeeds.
+
+We do not currently sanitize/escape the path components (it's not really a security concern when the user is about to download+run an opaque binary anyway). In the future validation/escaping of this input will become more strict. We do appear to correctly handle spaces in paths on both windows and unix (i.e. `~/My cargo-dist Documents/bin/` works), but we won't be surprised if things misbehave on Interesting Inputs.
+
+
+
 ## Subsetting CI Flags
 
 Several `metadata.dist` configs have globally available CLI equivalents. These can be used to select a subset of `metadata.dist` list for that run. If you don't pass any, it will be as-if you passed all the values in `metadata.dist`. You can pass these flags multiple times to provide a list. This includes:

cargo-dist/Cargo.toml

@@ -50,6 +50,7 @@ axoproject = { version = "0.3.0", default-features = false, features = ["cargo-p
 dialoguer = "0.10.4"
 axoasset = { version = "0.4.0", features = ["json-serde", "toml-serde", "toml-edit"] }
 sha2 = "0.10.6"
+minijinja = { version = "1.0.5", features = ["debug"] }
 
 [dev-dependencies]
 insta = { version = "1.26.0", features = ["filters"] }

cargo-dist/src/ci.rs

@@ -2,6 +2,8 @@
 //!
 //! In the future this may get split up into submodules.
 
+// FIXME(#283): migrate this to minijinja (steal logic from oranda to load a whole dir)
+
 use std::fs::File;
 
 use miette::{IntoDiagnostic, WrapErr};

cargo-dist/src/errors.rs

@@ -7,6 +7,7 @@
 //! If we ever change this decision, this will be a lot more important!
 
 use axoproject::errors::AxoprojectError;
+use camino::Utf8PathBuf;
 use miette::Diagnostic;
 use thiserror::Error;
 
@@ -27,6 +28,31 @@ pub enum DistError {
     #[diagnostic(transparent)]
     Asset(#[from] axoasset::AxoassetError),
 
+    /// A problem with a jinja template, which is always a cargo-dist bug
+    #[error("Failed to render template")]
+    #[diagnostic(help("this is a bug in cargo-dist, let us know and we'll fix it: https://github.com/axodotdev/cargo-dist/issues/new"))]
+    Jinja {
+        /// The SourceFile we were try to parse
+        #[source_code]
+        source: String,
+        /// The range the error was found on
+        #[label]
+        span: Option<miette::SourceSpan>,
+        /// Details of the error
+        #[source]
+        details: minijinja::Error,
+    },
+
+    /// Error parsing metadata in Cargo.toml (json because it's from cargo-metadata)
+    #[error("Malformed metadata.dist in {manifest_path}")]
+    CargoTomlParse {
+        /// path to file
+        manifest_path: Utf8PathBuf,
+        /// Inner error
+        #[source]
+        cause: serde_json::Error,
+    },
+
     /// User declined to update cargo-dist, refuse to make progress
     #[error(
         "to update your cargo-dist config you must use the version your project is configured for"
@@ -55,4 +81,46 @@ pub enum DistError {
     /// User declined to force tar.gz with npm
     #[error("Cannot enable npm support without forcing artifacts to be .tar.gz")]
     MustEnableTarGz,
+
+    /// Completely unknown format to install-path
+    ///
+    /// NOTE: we can't use `diagnostic(help)` here because this will get crammed into
+    /// a serde_json error, reducing it to a String. So we inline the help!
+    #[error(r#"install-path = "{path}" has an unknown format (it can either be "CARGO_HOME", "~/subdir/", or "$ENV_VAR/subdir/")"#)]
+    InstallPathInvalid {
+        /// The full value passed to install-path
+        path: String,
+    },
+
+    /// Being pedantic about the env-var mode of install-path to be consistent
+    ///
+    /// NOTE: we can't use `diagnostic(help)` here because this will get crammed into
+    /// a serde_json error, reducing it to a String. So we inline the help!
+    #[error(r#"install-path = "{path}" is missing a subdirectory (add a trailing slash if you want no subdirectory)"#)]
+    InstallPathEnvSlash {
+        /// The full value passed to install-path
+        path: String,
+    },
+
+    /// Being pedantic about the home mode of install-path to be consistent
+    ///
+    /// NOTE: we can't use `diagnostic(help)` here because this will get crammed into
+    /// a serde_json error, reducing it to a String. So we inline the help!
+    #[error(r#"install-path = "{path}" is missing a subdirectory (installing directly to home isn't allowed)"#)]
+    InstallPathHomeSubdir {
+        /// The full value passed to install-path
+        path: String,
+    },
+}
+
+impl From<minijinja::Error> for DistError {
+    fn from(details: minijinja::Error) -> Self {
+        let source: String = details.template_source().unwrap_or_default().to_owned();
+        let span = details.range().map(|r| r.into());
+        DistError::Jinja {
+            source,
+            span,
+            details,
+        }
+    }
 }

cargo-dist/src/init.rs

@@ -171,7 +171,10 @@ fn get_new_dist_metadata(
         .map(|t| t.contains_key(METADATA_DIST))
         .unwrap_or(false);
     let mut meta = if has_config {
-        tasks::parse_metadata_table(workspace_info.cargo_metadata_table.as_ref())
+        tasks::parse_metadata_table(
+            &workspace_info.manifest_path,
+            workspace_info.cargo_metadata_table.as_ref(),
+        )?
     } else {
         DistMetadata {
             // If they init with this version we're gonna try to stick to it!
@@ -191,6 +194,7 @@ fn get_new_dist_metadata(
             precise_builds: None,
             merge_tasks: None,
             fail_fast: None,
+            install_path: None,
         }
     };
 
@@ -554,6 +558,7 @@ fn update_toml_metadata(
         precise_builds,
         merge_tasks,
         fail_fast,
+        install_path,
     } = &meta;
 
     apply_optional_value(
@@ -661,6 +666,13 @@ fn update_toml_metadata(
         *fail_fast,
     );
 
+    apply_optional_value(
+        table,
+        "install-path",
+        "# Path that installers should place binaries in\n",
+        install_path.as_ref().map(|p| p.to_string()),
+    );
+
     // Finalize the table
     table
         .decor_mut()