doc: add section about RUSTFLAGS and CARGO_ENCODED_RUSTFLAGS to README

README.md

@@ -193,6 +193,44 @@ This forwards to [reproducible-wasm](#reproducible-wasm) variant of `build` comm
 2. has been pushed to remote repository, identified by 
    [`package.repository`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L9).
 
+## Special `cargo` environment variables
+
+Both of the following are mentioned on https://doc.rust-lang.org/cargo/reference/config.html#buildrustflags
+
+### `RUSTFLAGS`  
+
+running e.g.
+
+```bash
+RUSTFLAGS="your_custom_value" cargo near build non-reproducible-wasm
+```
+won't result in `"your_custom_value"` affecting the build.
+
+`RUSTFLAGS="-Awarnings"` is always used for abi build stage, and `RUSTFLAGS="-C link-arg=-s"` for wasm build stage.
+
+Logic for concatenating default values of this variable with values from env was removed in `cargo-near-0.13.3`/`cargo-near-build-0.4.3`, as it was seen as
+an unnecessary complication.
+
+There's still a way to override this parameter for wasm build stage, e.g.:
+
+```lang
+cargo near build non-reproducible-wasm --env 'RUSTFLAGS=--verbose'
+RUST_LOG=info cargo near build non-reproducible-wasm --env 'RUSTFLAGS=--verbose -C link-arg=-s'
+```
+
+### `CARGO_ENCODED_RUSTFLAGS`
+
+This variable is always unset during build, so
+
+```bash
+CARGO_ENCODED_RUSTFLAGS="your_custom_value" cargo near build non-reproducible-wasm
+```
+won't result in `"your_custom_value"` affecting the build.
+
+This is so to avoid weird issues like [#287](https://github.com/near/cargo-near/issues/287) when composing multiple builds via build scripts.
+
+
+
 
 ## Contribution
 

cargo-near-build/src/cargo_native/compile.rs

@@ -25,15 +25,12 @@ where
     let final_env = {
         let mut env: BTreeMap<_, _> = env.into_iter().collect();
         if hide_warnings {
-            env.insert("RUSTFLAGS", "-Awarnings");
+            env.insert(crate::env_keys::RUSTFLAGS, "-Awarnings");
         }
         env
     };
-    // removing env, which may be implicitly passed when bulding from within a build-script
-    // see https://github.com/near/cargo-near/issues/287
-    // CARGO_ENCODED_RUSTFLAGS="-Awarnings" and RUSTFLAGS="-Awarnings" both result
-    // in mysterious failures of `cargo build --target wasm32-unknown-unknown` (**cargo** bug)
-    let removed_env = ["CARGO_ENCODED_RUSTFLAGS"];
+
+    let removed_env = [crate::env_keys::CARGO_ENCODED_RUSTFLAGS];
 
     let artifacts = invoke_cargo(
         "build",

cargo-near-build/src/env_keys.rs

@@ -3,6 +3,19 @@ pub const CARGO_TARGET_DIR: &str = "CARGO_TARGET_DIR";
 /// this variable is set to `"true"` during ABI generation operation  
 pub const BUILD_RS_ABI_STEP_HINT: &str = "CARGO_NEAR_ABI_GENERATION";
 
+/// this behaviour that
+/// (1) default value for RUSTFLAGS for wasm build is "-C link-arg=-s"
+/// (2) it can be overriden with values from --env arguments
+/// (3) default RUSTFLAGS for abi gen are "-Awarnings"
+/// (4) RUSTFLAGS aren't concatenated (implicitly) with values from environment
+/// is documented in RUSTFLAGS section of README.md
+pub const RUSTFLAGS: &str = "RUSTFLAGS";
+
+/// this behaviour that
+/// (1) CARGO_ENCODED_RUSTFLAGS gets unset by default
+/// is documented in CARGO_ENCODED_RUSTFLAGS section of README.md
+pub const CARGO_ENCODED_RUSTFLAGS: &str = "CARGO_ENCODED_RUSTFLAGS";
+
 pub(crate) const CARGO_NEAR_ABI_PATH: &str = "CARGO_NEAR_ABI_PATH";
 
 pub(crate) const CARGO_NEAR_VERSION: &str = "CARGO_NEAR_VERSION";

cargo-near-build/src/near/build/mod.rs

@@ -142,7 +142,7 @@ pub fn run(args: Opts) -> eyre::Result<CompilationArtifact> {
     let abi_path_env = buildtime_env::AbiPath::new(args.no_embed_abi, &min_abi_path);
 
     let build_env = {
-        let mut build_env = vec![("RUSTFLAGS", "-C link-arg=-s")];
+        let mut build_env = vec![(env_keys::RUSTFLAGS, "-C link-arg=-s")];
         build_env.extend(
             args.env
                 .iter()

cargo-near-build/src/types/near/docker_build/metadata.rs

@@ -109,7 +109,7 @@ impl ReproducibleBuild {
         for command_token in build_command {
             if command_token
                 .chars()
-                .any(|c| !c.is_ascii() || c.is_ascii_control() || c.is_ascii_whitespace())
+                .any(|c| !c.is_ascii() || c.is_ascii_control())
             {
                 return Err(eyre::eyre!(
                     "{}: `{}`\n{}",