Improve CONTRIBUTING documentation about crates.io override

[ajanvrin]

Hello, I'm trying to diagnose a problem I'm encountering, I tried to build himalaya from source.
It compiled without error, and the locally compiled version seemed to work just as well as the released version.
I was able to replicate my issue with the locally-compiled version.

However, as the issue seems to be in email-lib, I also needed to clone this repo and rebuild himalaya, making it point at my local email-lib copy, and it's where things started to go south.

Here are the steps I've taken:

git clone https://github.com/pimalaya/himalaya.git
git clone https://github.com/pimalaya/core pimalaya_core
cd pimalaya_core
# Seems to be the commit corresponding to the specific version used by himalaya
git checkout 1f0534c15c6684a1c68e3dc52bb9e859defa88db
cd ../himalaya
# I tried without removing Cargo.lock too, just in case
rm Cargo.lock
# in Cargo.toml, replaced
# email-lib = { version = "0.26", default-features = false, features = ["tokio-rustls", "derive", "thread"] }
# with
# email-lib = { version = "0.26", path = "../pimalaya_core/email", default-features = false, features = ["tokio-rustls", "derive", "thread"] }
cargo check

I've been greeted with a large error trace:

   Compiling himalaya v1.0.0 (home\gits\himalaya)
error[E0277]: the trait bound `email::config::Config: std::convert::From<HimalayaTomlConfig>` is not satisfied
   --> src\account\command\doctor.rs:64:14
    |
64  |             .into_account_configs(self.account.name.as_deref(), |c: &Config, name| {
    |              ^^^^^^^^^^^^^^^^^^^^ the trait `std::convert::From<HimalayaTomlConfig>` is not implemented for `email::config::Config`, which is required by `HimalayaTomlConfig: Into<_>`
    |
    = note: required for `HimalayaTomlConfig` to implement `Into<email::config::Config>`
note: required by a bound in `into_account_configs`
   --> home\.cargo\registry\src\index.crates.io-6f17d22bba15001f\pimalaya-tui-0.2.1\src\terminal\config.rs:221:15
    |
215 |     fn into_account_configs<C, A>(
    |        -------------------- required by a bound in this associated function
...
221 |         Self: Into<C>,
    |               ^^^^^^^ required by this bound in `TomlConfig::into_account_configs`

error[E0308]: mismatched types
   --> src\account\command\doctor.rs:149:87
    |
149 |                 let ctx = MaildirContextBuilder::new(account_config.clone(), Arc::new(mdir_config));
    |                                                                              -------- ^^^^^^^^^^^ expected `MaildirConfig`, found a different `MaildirConfig`
    |                                                                              |
    |                                                                              arguments to this function are incorrect
    |
    = note: `MaildirConfig` and `MaildirConfig` have similar names, but are actually distinct types
note: `MaildirConfig` is defined in crate `email`
   --> home\.cargo\registry\src\index.crates.io-6f17d22bba15001f\email-lib-0.26.2\src\maildir\config.rs:15:1
    |
15  | pub struct MaildirConfig {
    | ^^^^^^^^^^^^^^^^^^^^^^^^
note: `MaildirConfig` is defined in crate `email`
   --> home\gits\pimalaya_core\email\src\maildir\config.rs:15:1
    |
15  | pub struct MaildirConfig {
    | ^^^^^^^^^^^^^^^^^^^^^^^^
    = note: perhaps two different versions of crate `email` are being used?
note: associated function defined here
   --> home\.rustup\toolchains\1.82.0-x86_64-pc-windows-msvc\lib/rustlib/src/rust\library\alloc\src\sync.rs:384:12
    |
[2866 lines removed for brevity]

warning: unused import: `folder::delete::DeleteFolder`
 --> src\folder\command\delete.rs:7:46
  |
7 |     {backend::feature::BackendFeatureSource, folder::delete::DeleteFolder},
  |                                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

warning: unused import: `folder::add::AddFolder`
 --> src\folder\command\add.rs:7:46
  |
7 |     {backend::feature::BackendFeatureSource, folder::add::AddFolder},
  |                                              ^^^^^^^^^^^^^^^^^^^^^^

Some errors have detailed explanations: E0277, E0308, E0599.
For more information about an error, try `rustc --explain E0277`.
warning: `himalaya` (lib) generated 5 warnings
error: could not compile `himalaya` (lib) due to 128 previous errors; 5 warnings emitted

Now, I realize that it certainly stems from my poor cargo skills, and more proficient Rust developers would keenly identify the cause and fix it.
And also that helping me setup my build environment may not be a great use of your time.

Still, can you please give me some pointers?

[ajanvrin]

Ok, I found the issue.
I noticed the note: perhaps two different versions of crate email are being used?
Which gave me the hunch that something was pulling email-lib from crates.io instead of my local source.
It was the case, pimalaya-tui does that.
So I pulled that too and made additional edits to various Cargo.toml files:

git clone https://github.com/pimalaya/himalaya.git
git clone https://github.com/pimalaya/core pimalaya_core
git clone https://github.com/pimalaya/tui pimalaya_tui

cd pimalaya_core
# Seems to be the commit corresponding to the specific version used by himalaya
git checkout 1f0534c15c6684a1c68e3dc52bb9e859defa88db

cd ..
# Made the following edits to himalaya_tui/Cargo.toml
diff --git a/Cargo.toml b/Cargo.toml
index 6fc6f1f..14d9c00 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -92,21 +92,21 @@ color-eyre = { version = "0.6", optional = true }
 comfy-table = { version = "7.1", optional = true }
 crossterm = { version = "0.27", features = ["serde"] }
 dirs = { version = "4", optional = true }
-email-lib = { version = "0.26", optional = true, default-features = false, features = ["tokio-rustls"] }
+email-lib = { version = "0.26", path = "../pimalaya_core/email", optional = true, default-features = false, features = ["tokio-rustls"] }
 email_address = { version = "0.2", optional = true, default-features = false }
 git2 = { version = "0.19", optional = true, default-features = false }
 inquire = "0.7"
 md5 = "0.7"
-mml-lib = { version = "1", optional = true, default-features = false, features = ["tokio", "rustls", "compiler", "interpreter", "derive"] }
-oauth-lib = { version = "2", optional = true, default-features = false, features = ["tokio", "rustls"] }
+mml-lib = { version = "1", path = "../pimalaya_core/mml", optional = true, default-features = false, features = ["tokio", "rustls", "compiler", "interpreter", "derive"] }
+oauth-lib = { version = "2", path = "../pimalaya_core/oauth", optional = true, default-features = false, features = ["tokio", "rustls"] }
 once_cell = { version = "1.20", optional = true }
 petgraph = { version = "0.6", optional = true }
-process-lib = { version = "1", optional = true, features = ["tokio", "derive"] }
-secret-lib = { version = "1", optional = true, default-features = false, features = ["tokio", "rustls", "command"] }
+process-lib = { version = "1", path = "../pimalaya_core/process", optional = true, features = ["tokio", "derive"] }
+secret-lib = { version = "1", path = "../pimalaya_core/secret", optional = true, default-features = false, features = ["tokio", "rustls", "command"] }
 serde = { version = "1", features = ["derive"], optional = true }
 serde-toml-merge = { version = "0.3", optional = true }
 serde_json = { version = "1", optional = true }
-shellexpand-utils = { version = "=0.2.1", optional = true }
+shellexpand-utils = { version = "=0.2.1", path = "../pimalaya_core/shellexpand-utils", optional = true }
 sled = { version = "=0.34.7", optional = true }
 thiserror = "2"
 tokio = { version = "1.40", optional = true, default-features = false, features = ["process"] }

# Made the following edits to himalaya/Cargo.toml
diff --git a/Cargo.toml b/Cargo.toml
index 818f116..e9e72ec 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -30,7 +30,7 @@ pgp-gpg = ["email-lib/pgp-gpg", "mml-lib/pgp-gpg", "pimalaya-tui/pgp-gpg"]
 pgp-native = ["email-lib/pgp-native", "mml-lib/pgp-native", "pimalaya-tui/pgp-native"]

 [build-dependencies]
-pimalaya-tui = { version = "0.2", default-features = false, features = ["build-envs"] }
+pimalaya-tui = { version = "0.2", path = "../pimalaya_tui", default-features = false, features = ["build-envs"] }

 [dev-dependencies]
 himalaya = { path = ".", features = ["notmuch", "keyring", "oauth2", "pgp-gpg", "pgp-native"] }
@@ -41,15 +41,15 @@ clap = { version = "4.4", features = ["derive", "env", "wrap_help"] }
 clap_complete = "4.4"
 clap_mangen = "0.2"
 color-eyre = "0.6"
-email-lib = { version = "0.26", default-features = false, features = ["tokio-rustls", "derive", "thread"] }
-mml-lib = { version = "1", default-features = false, features = ["compiler", "interpreter", "derive"]  }
+email-lib = { version = "0.26", path = "../pimalaya_core/email", default-features = false, features = ["tokio-rustls", "derive", "thread"] }
+mml-lib = { version = "1", path = "../pimalaya_core/mml", default-features = false, features = ["compiler", "interpreter", "derive"]  }
 once_cell = "1.16"
 open = "5.3"
-pimalaya-tui = { version = "0.2", default-features = false, features = ["rustls", "email", "path", "cli", "himalaya", "tracing", "sled"] }
-secret-lib = { version = "1", default-features = false, features = ["tokio", "rustls", "command", "derive"] }
+pimalaya-tui = { version = "0.2", path = "../pimalaya_tui", default-features = false, features = ["rustls", "email", "path", "cli", "himalaya", "tracing", "sled"] }
+secret-lib = { version = "1", path = "../pimalaya_core/secret", default-features = false, features = ["tokio", "rustls", "command", "derive"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-shellexpand-utils = "=0.2.1"
+shellexpand-utils = { version = "=0.2.1", path = "../pimalaya_core/shellexpand-utils" }
 tokio = { version = "1.23", default-features = false, features = ["macros", "rt-multi-thread"] }
 toml = "0.8"
 tracing = "0.1"

cd himalaya
rm Cargo.lock
cargo check

And it compiled without errors or warnings, w00t: Finished dev profile [unoptimized + debuginfo] target(s) in 49.96s

Now, I can't help but wonder: Isn't this a bit convoluted?
You seem to make heavy use of Nix in your workflow, so I'm sure your build environment is very different from mine.
Could I do it in a more simple way?

In the meantime, maybe this issue can remain open in order to help the next person who'd like to compile himalaya, pimalaya-tui and email-lib locally?
I don't think spending time on a proper build setup guide would be worthwhile, as there seem to be refactoring efforts ongoing, and users in my situation (not very proficient in rust, but motivated to get to the bottom of a specific issue) are probably not very common.

[ajanvrin]

Nevermind, I found
https://github.com/pimalaya/himalaya/blob/master/CONTRIBUTING.md

I'm not sure it would have fixed my problem (haven't checked whether it pulls pimalaya-core from github or from crates.io)

But anyway, it's based on Nix, and Nix does not exist on Windows (man I wish, being stuck with winget and chocolatey is no fun).
I've been able to compile on Windows so I'm going to keep going that way, I'll move to a WSL+Nix setup if i hit a wall.

[soywod]

Let me re-open this issue for improving the CONTRIBUTING documentation.
Your case has nothing to deal with Nix, you just need to override crates.io dependencies:

[patch.crates-io]
email-lib = { path = "../pimalaya_core/email" }

This should be enough, but you may encounter version mismatch with other crates that also use email-lib, like pimalaya-tui. In this case you will need to override them as well:

[patch.crates-io]
email-lib = { path = "../pimalaya_core/email" }
pimalaya-tui = { path = "../pimalaya/tui" }
# …