doc: expand on "the build script’s current directory is the source directory of the build script’s package."

[ghost]

This doc says:

In addition to environment variables, the build script’s current directory is the source directory of the build script’s package.

I would like it* to somehow expand upon that and say that for example, every file in the CARGO_MANIFEST_DIR (ie. same dir as build.rs) is now a dependency for build.rs which means that if any of them change (timestamp-wise), then build.rs and thus src/main.rs will be rebuilt! EDIT I misinterpreted this! see my next comment. (I used strikeout above)

More specifically, if you have a symlink to the resulting binary(ie. to ./target/debug/yourprojectname ) in the same dir that build.rs resides, then cargo build will always rebuild, because, due to the symlink, it detects a new timestamp(of the exe that was previously built!), thus requiring a new build every time.

* but I'm no doc guru, so if someone could take up the task of encapsulating the above into concise,readable words for the doc, that would be greatly appreciated.

To reproduce:

cargo new --bin someproj
cd someproj
echo "fn main(){}" > build.rs
ln -rs ./target/debug/someproj thesymlink
env RUST_LOG=warn cargo build -vv

then keep re-running the last command as many times as you want to see it rebuild, and you can meanwhile notice the "WARN" lines listing all the files that it depends on, including the symlink, preceeded with their timestamps (initially 0s for the symlink, but no matter)

WARN:cargo::sources::path: 1515212525.336571543s /tmp/1/someproj/Cargo.toml
WARN:cargo::sources::path: 1515212525.367571153s /tmp/1/someproj/build.rs
WARN:cargo::sources::path: 1515212525.336571543s /tmp/1/someproj/src/main.rs
WARN:cargo::sources::path: 1515212849.926490895s /tmp/1/someproj/thesymlink

Remove the symlink (ie. file named thesymlink) if you want to see it stop re-building.
Or, alternatively, you can remove/rename build.rs for the same effect. (but in this latter case, the WARN lines are not shown anymore)

Tested with:

cargo 0.25.0-nightly (a88fbac 2017-12-29)
release: 0.25.0
commit-hash: a88fbac
commit-date: 2017-12-29

rustc 1.24.0-nightly (8e7a609e6 2018-01-04)
binary: rustc
commit-hash: 8e7a609e635b728eba65d471c985ab462dc4cfc7
commit-date: 2018-01-04
host: x86_64-unknown-linux-gnu
release: 1.24.0-nightly
LLVM version: 4.0

[ghost]

Note: the above is thwarted by #4001 (comment)
and by thwarted I mean that, in the context above, always rebuild becomes never rebuild.

And a correction, for OP:
Looks like build.rs is not rebuilt due to the symlink existing, but only src/main.rs is the one being rebuilt!
Thus then I misinterpreted the doc when it said:

the build script’s current directory is the source directory of the build script’s package.

and I took it to mean that the symlink timestamp changing would rebuild build.rs(and because of that src/main.rs too, as a consequence), but it does not! it only rebuilds src/main.rs !!
So maybe there is something else happening here?

[ghost]

Workaround:
Added the following to Cargo.toml:

exclude = [ "thesymlink" ]

There are no more rebuilds now and I can keep the symlink:)

[alexcrichton]

@xftroxgpx hm so this isn't necessarily documentation about the current directory per se but rather about the behavior of rebuilding build scripts, is that right?

[ghost]

I'm closing this because it's such a mess. And I don't know how else to explain it to make any sense ( I've been trying to phrase it and write in this post for at least 30mins :D was still a mess, so deleted all, out of respect for people's time :) and i don't know how to answer your question )