Updated docs with instructions for project source overriding.

Signed-off-by: victor.linroth.sensmetry <victor.linroth@sensmetry.com>

Author: victor-linroth-sensmetry

docs/src/commands/add.md

@@ -14,6 +14,14 @@ Adds IRI and optional version constraint to list of usages in the project
 information file `.project.json`. By default this will also update the lockfile
 and sync the local environment (creating one if not already present).
 
+When adding a usage with a path or URL the configuration file will be
+automatically updated with the appropriate project source override as described
+in [Dependencies](../config/dependencies.md). The configuration file updated
+will either be the one given with `--config-file` or (if `--no-config` is not
+present) the `sysand.toml` at the root of the project. If no configuration file
+is given and `--no-config` is set the usage will be added to the project but no
+source will be configured so future syncing will not take this into account.
+
 ## Arguments
 
 - `<IRI>`: IRI identifying the project to be used
@@ -25,6 +33,10 @@ and sync the local environment (creating one if not already present).
 
 - `--no-lock`: Do not automatically resolve usages (and generate lockfile)
 - `--no-sync`: Do not automatically install dependencies
+- `--local-src <LOCAL_SRC>`: Path to local interchange project
+- `--local-kpar <LOCAL_KPAR>`: Path to local interchange project archive (KPAR)
+- `--remote-src <REMOTE_SRC>`: URL to remote interchange project
+- `--remote-kpar <REMOTE_KPAR>`: URL to remote interchange project archive (KPAR)
 
 {{#include ./partials/dependency_opts.md}}
 

docs/src/commands/remove.md

@@ -2,6 +2,8 @@
 
 Remove usage from project information
 
+Will also remove project source overrides from configuration file if available.
+
 ## Usage
 
 ```sh

docs/src/config.md

@@ -23,3 +23,4 @@ can be used to specify the path to an additional config file.
 ## Configurable options
 
 - [Indexes](config/indexes.md)
+- [Dependencies](config/dependencies.md)

docs/src/config/dependencies.md

@@ -0,0 +1,80 @@
+# Dependencies
+
+Sometimes you may wish to use a project that isn't resolvable through an
+available index or you want to override the dependency resolution for other
+reasons. In any case you can do this by adding the appropriate IRI and `Source`
+to a `project` entry in the `sysand.toml` configuration file at the root of
+your project. This follows the same structure as found in the lockfile, where
+`identifiers` are given as a list of IRI:s and `sources` are a list of sources.
+A project may have multiple identifiers in case it is referred to differently
+by different projects, and multiple sources where the additional ones after the
+first serve as backups in case the previous ones fail to resolve. Note that
+these should be sources of the exact same project as determined by it's
+checksum, as otherwise you are likely to run into problems when syncing against
+a lockfile.
+
+Below we describe we describe how add overriding sources directly to the
+configuration file, but it is also possible to do through the command line
+interface with the [`sysand add`](../commands/add.md) command.
+
+## Local projects
+
+To specify the source of a project that you have locally in a directory
+`./path/to/project` by the identifier `urn:kpar:my-project`, is done by adding
+the following entry to your `sysand.toml`.
+
+```toml
+[[project]]
+identifiers = [
+    "urn:kpar:my-project",
+]
+sources = [
+    { src_path = "path/to/project" },
+]
+```
+
+Note that the path to the project is given by path that is relative to the root
+of your project.
+
+## Local KPARs
+
+If you have a project locally available as a compressed KPAR this can be identified
+by `urn:kpar:my-kpar-project` by adding
+
+```toml
+[[project]]
+identifiers = [
+    "urn:kpar:my-kpar-project",
+]
+sources = [
+    { kpar_path = "path/to/project.kpar" },
+]
+```
+
+to your `sysand.toml`.
+
+## Remote projects and KPARs
+
+To specify a remote project as a source, add
+
+```toml
+[[project]]
+identifiers = [
+    "urn:kpar:remote-project",
+]
+sources = [
+    { remote_src = "https://www.example.com/path/to/project" },
+]
+```
+
+to your `sysand.toml`, or for a remote KPAR you add
+
+```toml
+[[project]]
+identifiers = [
+    "urn:kpar:remote-kpar-project",
+]
+sources = [
+    { remote_kpar = "https://www.example.com/path/to/project.kpar" },
+]
+```

sysand/src/cli.rs

@@ -1274,16 +1274,16 @@ pub struct ResolutionOptions {
 #[derive(clap::Args, Debug, Clone)]
 pub struct ProjectSourceOptions {
     /// Path to local interchange project
-    #[arg(long, group = "source", help_heading = "Source options")]
+    #[arg(long, group = "source")]
     pub local_src: Option<String>,
     /// Path to local interchange project archive (KPAR)
-    #[arg(long, group = "source", help_heading = "Source options")]
+    #[arg(long, group = "source")]
     pub local_kpar: Option<String>,
     /// URL to remote interchange project
-    #[arg(long, group = "source", help_heading = "Source options")]
+    #[arg(long, group = "source")]
     pub remote_src: Option<String>,
     /// URL to remote interchange project archive (KPAR)
-    #[arg(long, group = "source", help_heading = "Source options")]
+    #[arg(long, group = "source")]
     pub remote_kpar: Option<String>,
 }