From: Richard Dodd Date: Sun, 1 Oct 2017 18:37:48 +0000 (+0100) Subject: Some moer docs X-Git-Tag: archive/raspbian/0.35.0-2+rpi1~3^2^2^2^2^2^2^2~22^2~6^2~24^2~2 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=624f9dbce91f08731636e3b81bd196d732cb9ff3;p=cargo.git Some moer docs --- diff --git a/Cargo.lock b/Cargo.lock index 2feeeafad..e6435473f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2,13 +2,13 @@ name = "cargo" version = "0.23.0" dependencies = [ - "advapi32-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", - "atty 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)", + "atty 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)", "bufstream 0.1.3 (registry+https://github.com/rust-lang/crates.io-index)", "cargotest 0.1.0", "core-foundation 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)", "crates-io 0.12.0", "crossbeam 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)", + "crypto-hash 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)", "curl 0.4.8 (registry+https://github.com/rust-lang/crates.io-index)", "docopt 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)", "env_logger 0.4.3 (registry+https://github.com/rust-lang/crates.io-index)", @@ -29,8 +29,7 @@ dependencies = [ "libgit2-sys 0.6.15 (registry+https://github.com/rust-lang/crates.io-index)", "log 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)", "miow 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)", - "num_cpus 1.6.2 (registry+https://github.com/rust-lang/crates.io-index)", - "openssl 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)", + "num_cpus 1.7.0 (registry+https://github.com/rust-lang/crates.io-index)", "psapi-sys 0.1.0 (registry+https://github.com/rust-lang/crates.io-index)", "same-file 0.1.3 (registry+https://github.com/rust-lang/crates.io-index)", "scoped-tls 0.1.0 (registry+https://github.com/rust-lang/crates.io-index)", @@ -75,11 +74,12 @@ dependencies = [ [[package]] name = "atty" -version = "0.2.2" +version = "0.2.3" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "kernel32-sys 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)", "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)", + "termion 1.5.1 (registry+https://github.com/rust-lang/crates.io-index)", "winapi 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -155,6 +155,22 @@ dependencies = [ "cc 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)", ] +[[package]] +name = "commoncrypto" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "commoncrypto-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "commoncrypto-sys" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "conv" version = "0.3.3" @@ -202,6 +218,18 @@ name = "crossbeam" version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" +[[package]] +name = "crypto-hash" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "advapi32-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", + "commoncrypto 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", + "hex 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", + "openssl 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)", + "winapi 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "curl" version = "0.4.8" @@ -248,7 +276,7 @@ name = "docopt" version = "0.8.1" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)", + "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)", "regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)", "serde 1.0.15 (registry+https://github.com/rust-lang/crates.io-index)", "serde_derive 1.0.15 (registry+https://github.com/rust-lang/crates.io-index)", @@ -399,7 +427,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "crossbeam 0.2.10 (registry+https://github.com/rust-lang/crates.io-index)", "globset 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", - "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)", + "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)", "log 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)", "memchr 1.0.1 (registry+https://github.com/rust-lang/crates.io-index)", "regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)", @@ -432,7 +460,7 @@ dependencies = [ [[package]] name = "lazy_static" -version = "0.2.8" +version = "0.2.9" source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] @@ -621,7 +649,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] name = "num_cpus" -version = "1.6.2" +version = "1.7.0" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)", @@ -634,7 +662,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "bitflags 0.9.1 (registry+https://github.com/rust-lang/crates.io-index)", "foreign-types 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", - "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)", + "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)", "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)", "openssl-sys 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -693,6 +721,14 @@ name = "redox_syscall" version = "0.1.31" source = "registry+https://github.com/rust-lang/crates.io-index" +[[package]] +name = "redox_termios" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "redox_syscall 0.1.31 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "regex" version = "0.1.80" @@ -878,6 +914,16 @@ dependencies = [ "wincolor 0.1.4 (registry+https://github.com/rust-lang/crates.io-index)", ] +[[package]] +name = "termion" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)", + "redox_syscall 0.1.31 (registry+https://github.com/rust-lang/crates.io-index)", + "redox_termios 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "thread-id" version = "2.0.0" @@ -900,7 +946,7 @@ name = "thread_local" version = "0.3.4" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)", + "lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)", "unreachable 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -1019,7 +1065,7 @@ dependencies = [ "checksum advapi32-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "e06588080cb19d0acb6739808aafa5f26bfb2ca015b2b6370028b44cf7cb8a9a" "checksum aho-corasick 0.5.3 (registry+https://github.com/rust-lang/crates.io-index)" = "ca972c2ea5f742bfce5687b9aef75506a764f61d37f8f649047846a9686ddb66" "checksum aho-corasick 0.6.3 (registry+https://github.com/rust-lang/crates.io-index)" = "500909c4f87a9e52355b26626d890833e9e1d53ac566db76c36faa984b889699" -"checksum atty 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "d912da0db7fa85514874458ca3651fe2cddace8d0b0505571dbdcd41ab490159" +"checksum atty 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "21e50800ec991574876040fff8ee46b136a53e985286fbe6a3bdfe6421b78860" "checksum backtrace 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)" = "99f2ce94e22b8e664d95c57fff45b98a966c2252b60691d0b7aeeccd88d70983" "checksum backtrace-sys 0.1.14 (registry+https://github.com/rust-lang/crates.io-index)" = "c63ea141ef8fdb10409d0f5daf30ac51f84ef43bff66f16627773d2a292cd189" "checksum bitflags 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "aad18937a628ec6abcd26d1489012cc0e18c21798210f491af69ded9b881106d" @@ -1028,11 +1074,14 @@ dependencies = [ "checksum cc 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "7db2f146208d7e0fbee761b09cd65a7f51ccc38705d4e7262dad4d73b12a76b1" "checksum cfg-if 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "d4c819a1287eb618df47cc647173c5c4c66ba19d888a6e50d605672aed3140de" "checksum cmake 0.1.26 (registry+https://github.com/rust-lang/crates.io-index)" = "357c07e7a1fc95732793c1edb5901e1a1f305cfcf63a90eb12dbd22bdb6b789d" +"checksum commoncrypto 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "d056a8586ba25a1e4d61cb090900e495952c7886786fc55f909ab2f819b69007" +"checksum commoncrypto-sys 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "1fed34f46747aa73dfaa578069fd8279d2818ade2b55f38f22a9401c7f4083e2" "checksum conv 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)" = "78ff10625fd0ac447827aa30ea8b861fead473bb60aeb73af6c1c58caf0d1299" "checksum core-foundation 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)" = "5909502e547762013619f4c4e01cc7393c20fe2d52d7fa471c1210adb2320dc7" "checksum core-foundation-sys 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)" = "bc9fb3d6cb663e6fd7cf1c63f9b144ee2b1e4a78595a0451dd34bff85b9a3387" "checksum crossbeam 0.2.10 (registry+https://github.com/rust-lang/crates.io-index)" = "0c5ea215664ca264da8a9d9c3be80d2eaf30923c259d03e870388eb927508f97" "checksum crossbeam 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "8837ab96533202c5b610ed44bc7f4183e7957c1c8f56e8cc78bb098593c8ba0a" +"checksum crypto-hash 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "34903878eec1694faf53cae8473a088df333181de421d4d3d48061d6559fe602" "checksum curl 0.4.8 (registry+https://github.com/rust-lang/crates.io-index)" = "7034c534a1d7d22f7971d6088aa9d281d219ef724026c3428092500f41ae9c2c" "checksum curl-sys 0.3.15 (registry+https://github.com/rust-lang/crates.io-index)" = "4bee31aa3a079d5f3ff9579ea4dcfb1b1a17a40886f5f467436d383e78134b55" "checksum custom_derive 0.1.7 (registry+https://github.com/rust-lang/crates.io-index)" = "ef8ae57c4978a2acd8b869ce6b9ca1dfe817bff704c220209fdef2c0b75a01b9" @@ -1058,7 +1107,7 @@ dependencies = [ "checksum itoa 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)" = "8324a32baf01e2ae060e9de58ed0bc2320c9a2833491ee36cd3b4c414de4db8c" "checksum jobserver 0.1.6 (registry+https://github.com/rust-lang/crates.io-index)" = "443ae8bc0af6c106e6e8b77e04684faecc1a5ce94e058f4c2b0a037b0ea1b133" "checksum kernel32-sys 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "7507624b29483431c0ba2d82aece8ca6cdba9382bff4ddd0f7490560c056098d" -"checksum lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)" = "3b37545ab726dd833ec6420aaba8231c5b320814b9029ad585555d2a03e94fbf" +"checksum lazy_static 0.2.9 (registry+https://github.com/rust-lang/crates.io-index)" = "c9e5e58fa1a4c3b915a561a78a22ee0cac6ab97dca2504428bc1cb074375f8d5" "checksum libc 0.2.31 (registry+https://github.com/rust-lang/crates.io-index)" = "d1419b2939a0bc44b77feb34661583c7546b532b192feab36249ab584b86856c" "checksum libgit2-sys 0.6.15 (registry+https://github.com/rust-lang/crates.io-index)" = "205fc37e829c5b36de63d14c8dc8b62c5a6a2519b16318ed0977079ca97256a9" "checksum libssh2-sys 0.2.6 (registry+https://github.com/rust-lang/crates.io-index)" = "0db4ec23611747ef772db1c4d650f8bd762f07b461727ec998f953c614024b75" @@ -1079,7 +1128,7 @@ dependencies = [ "checksum num-iter 0.1.34 (registry+https://github.com/rust-lang/crates.io-index)" = "7485fcc84f85b4ecd0ea527b14189281cf27d60e583ae65ebc9c088b13dffe01" "checksum num-rational 0.1.39 (registry+https://github.com/rust-lang/crates.io-index)" = "288629c76fac4b33556f4b7ab57ba21ae202da65ba8b77466e6d598e31990790" "checksum num-traits 0.1.40 (registry+https://github.com/rust-lang/crates.io-index)" = "99843c856d68d8b4313b03a17e33c4bb42ae8f6610ea81b28abe076ac721b9b0" -"checksum num_cpus 1.6.2 (registry+https://github.com/rust-lang/crates.io-index)" = "aec53c34f2d0247c5ca5d32cca1478762f301740468ee9ee6dcb7a0dd7a0c584" +"checksum num_cpus 1.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "514f0d73e64be53ff320680ca671b64fe3fb91da01e1ae2ddc99eb51d453b20d" "checksum openssl 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)" = "816914b22eb15671d62c73442a51978f311e911d6a6f6cbdafa6abce1b5038fc" "checksum openssl-probe 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)" = "d98df0270d404ccd3c050a41d579c52d1db15375168bb3471e04ec0f5f378daf" "checksum openssl-sys 0.9.19 (registry+https://github.com/rust-lang/crates.io-index)" = "1e4c63a7d559c1e5afa6d6a9e6fa34bbc5f800ffc9ae08b72c605420b0c4f5e8" @@ -1089,6 +1138,7 @@ dependencies = [ "checksum quote 0.3.15 (registry+https://github.com/rust-lang/crates.io-index)" = "7a6e920b65c65f10b2ae65c831a81a073a89edd28c7cce89475bff467ab4167a" "checksum rand 0.3.16 (registry+https://github.com/rust-lang/crates.io-index)" = "eb250fd207a4729c976794d03db689c9be1d634ab5a1c9da9492a13d8fecbcdf" "checksum redox_syscall 0.1.31 (registry+https://github.com/rust-lang/crates.io-index)" = "8dde11f18c108289bef24469638a04dce49da56084f2d50618b226e47eb04509" +"checksum redox_termios 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)" = "7e891cfe48e9100a70a3b6eb652fef28920c117d366339687bd5576160db0f76" "checksum regex 0.1.80 (registry+https://github.com/rust-lang/crates.io-index)" = "4fd4ace6a8cf7860714a2c2280d6c1f7e6a413486c13298bbc86fd3da019402f" "checksum regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "1731164734096285ec2a5ec7fea5248ae2f5485b3feeb0115af4fda2183b2d1b" "checksum regex-syntax 0.3.9 (registry+https://github.com/rust-lang/crates.io-index)" = "f9ec002c35e86791825ed294b50008eea9ddfc8def4420124fbc6b08db834957" @@ -1113,6 +1163,7 @@ dependencies = [ "checksum tar 0.4.13 (registry+https://github.com/rust-lang/crates.io-index)" = "281285b717926caa919ad905ef89c63d75805c7d89437fb873100925a53f2b1b" "checksum tempdir 0.3.5 (registry+https://github.com/rust-lang/crates.io-index)" = "87974a6f5c1dfb344d733055601650059a3363de2a6104819293baff662132d6" "checksum termcolor 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)" = "9065bced9c3e43453aa3d56f1e98590b8455b341d2fa191a1090c0dd0b242c75" +"checksum termion 1.5.1 (registry+https://github.com/rust-lang/crates.io-index)" = "689a3bdfaab439fd92bc87df5c4c78417d3cbe537487274e9b0b2dce76e92096" "checksum thread-id 2.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "a9539db560102d1cef46b8b78ce737ff0bb64e7e18d35b2a5688f7d097d0ff03" "checksum thread_local 0.2.7 (registry+https://github.com/rust-lang/crates.io-index)" = "8576dbbfcaef9641452d5cf0df9b0e7eeab7694956dd33bb61515fb8f18cfdd5" "checksum thread_local 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)" = "1697c4b57aeeb7a536b647165a2825faddffb1d3bad386d507709bd51a90bb14" diff --git a/src/cargo/core/package.rs b/src/cargo/core/package.rs index afc047f88..90e7c811f 100644 --- a/src/cargo/core/package.rs +++ b/src/cargo/core/package.rs @@ -20,12 +20,13 @@ use util::errors::{CargoResult, CargoResultExt}; // TODO: Is manifest_path a relic? #[derive(Clone, Debug)] pub struct Package { - // The package's manifest + /// The package's manifest manifest: Manifest, - // The root of the package + /// The root of the package manifest_path: PathBuf, } +/// A Package in a form where `Serialize` can be derived. #[derive(Serialize)] struct SerializedPackage<'a> { name: &'a str, @@ -69,6 +70,7 @@ impl ser::Serialize for Package { } impl Package { + /// Create a package from a manifest and its location pub fn new(manifest: Manifest, manifest_path: &Path) -> Package { Package { @@ -77,6 +79,7 @@ impl Package { } } + /// Calculate the Package from the manifest path (and cargo configuration). pub fn for_path(manifest_path: &Path, config: &Config) -> CargoResult { let path = manifest_path.parent().unwrap(); let source_id = SourceId::for_path(path)?; @@ -84,18 +87,30 @@ impl Package { Ok(pkg) } + /// Get the manifest dependencies pub fn dependencies(&self) -> &[Dependency] { self.manifest.dependencies() } + /// Get the manifest pub fn manifest(&self) -> &Manifest { &self.manifest } + /// Get the path to the manifest pub fn manifest_path(&self) -> &Path { &self.manifest_path } + /// Get the name of the package pub fn name(&self) -> &str { self.package_id().name() } + /// Get the PackageId object for the package (fully defines a packge) pub fn package_id(&self) -> &PackageId { self.manifest.package_id() } + /// Get the root folder of the package pub fn root(&self) -> &Path { self.manifest_path.parent().unwrap() } + /// Get the summary for the package pub fn summary(&self) -> &Summary { self.manifest.summary() } + /// Get the targets specified in the manifest pub fn targets(&self) -> &[Target] { self.manifest.targets() } + /// Get the current package version pub fn version(&self) -> &Version { self.package_id().version() } + /// Get the package authors pub fn authors(&self) -> &Vec { &self.manifest.metadata().authors } + /// Whether the package is set to publish pub fn publish(&self) -> bool { self.manifest.publish() } + /// Whether the package uses a custom build script for any target pub fn has_custom_build(&self) -> bool { self.targets().iter().any(|t| t.is_custom_build()) } diff --git a/src/cargo/core/source.rs b/src/cargo/core/source.rs index b9218bd5a..01d659919 100644 --- a/src/cargo/core/source.rs +++ b/src/cargo/core/source.rs @@ -21,6 +21,7 @@ use util::{Config, CargoResult, ToUrl}; /// A Source finds and downloads remote packages based on names and /// versions. pub trait Source: Registry { + /// Returns the `SourceId` corresponding to this source fn source_id(&self) -> &SourceId; /// The update method performs any network operations required to @@ -56,27 +57,34 @@ pub trait Source: Registry { } impl<'a, T: Source + ?Sized + 'a> Source for Box { + /// Forwards to `Source::source_id` fn source_id(&self) -> &SourceId { (**self).source_id() } + /// Forwards to `Source::update` fn update(&mut self) -> CargoResult<()> { (**self).update() } + /// Forwards to `Source::download` fn download(&mut self, id: &PackageId) -> CargoResult { (**self).download(id) } + /// Forwards to `Source::fingerprint` fn fingerprint(&self, pkg: &Package) -> CargoResult { (**self).fingerprint(pkg) } + /// Forwards to `Source::verify` fn verify(&self, pkg: &PackageId) -> CargoResult<()> { (**self).verify(pkg) } } +/// The possible kinds of code source. Along with a URL, this fully defines the +/// source #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] enum Kind { /// Kind::Git() represents a git repository @@ -91,10 +99,14 @@ enum Kind { Directory, } +/// Information to find a specific commit in a git repository #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum GitReference { + /// from a tag Tag(String), + /// from the HEAD of a branch Branch(String), + /// from a specific revision Rev(String), } @@ -104,16 +116,23 @@ pub struct SourceId { inner: Arc, } +/// Unique identifier for a source of packages. #[derive(Eq, Clone, Debug)] struct SourceIdInner { + /// The source URL url: Url, + /// `git::canonicalize_url(url)` for the url field canonical_url: Url, + /// The source kind kind: Kind, // e.g. the exact git revision of the specified branch for a Git Source precise: Option, } impl SourceId { + /// Create a SourceId object from the kind and url. + /// + /// The canonical url will be calculated, but the precise field will not fn new(kind: Kind, url: Url) -> CargoResult { let source_id = SourceId { inner: Arc::new(SourceIdInner { @@ -174,29 +193,36 @@ impl SourceId { } } + /// A view of the `SourceId` that can be `Display`ed as a URL pub fn to_url(&self) -> SourceIdToUrl { SourceIdToUrl { inner: &*self.inner } } - // Pass absolute path + /// Create a SourceId from a filesystem path. + /// + /// Pass absolute path pub fn for_path(path: &Path) -> CargoResult { let url = path.to_url()?; SourceId::new(Kind::Path, url) } + /// Crate a SourceId from a git reference pub fn for_git(url: &Url, reference: GitReference) -> CargoResult { SourceId::new(Kind::Git(reference), url.clone()) } + /// Create a SourceId from a registry url pub fn for_registry(url: &Url) -> CargoResult { SourceId::new(Kind::Registry, url.clone()) } + /// Create a SourceId from a local registry path pub fn for_local_registry(path: &Path) -> CargoResult { let url = path.to_url()?; SourceId::new(Kind::LocalRegistry, url) } + /// Create a SourceId from a directory path pub fn for_directory(path: &Path) -> CargoResult { let url = path.to_url()?; SourceId::new(Kind::Directory, url) @@ -212,9 +238,9 @@ impl SourceId { static WARNED: AtomicBool = ATOMIC_BOOL_INIT; if !WARNED.swap(true, SeqCst) { config.shell().warn("custom registry support via \ - the `registry.index` configuration is \ - being removed, this functionality \ - will not work in the future")?; + the `registry.index` configuration is \ + being removed, this functionality \ + will not work in the future")?; } &index[..] } else { @@ -224,16 +250,22 @@ impl SourceId { SourceId::for_registry(&url) } + /// Get this source URL pub fn url(&self) -> &Url { &self.inner.url } + + /// Is this source from a filesystem path pub fn is_path(&self) -> bool { self.inner.kind == Kind::Path } + + /// Is this source from a registry (either local or not) pub fn is_registry(&self) -> bool { self.inner.kind == Kind::Registry || self.inner.kind == Kind::LocalRegistry } + /// Is this source from a git repository pub fn is_git(&self) -> bool { match self.inner.kind { Kind::Git(_) => true, @@ -271,10 +303,12 @@ impl SourceId { } } + /// Get the value of the precise field pub fn precise(&self) -> Option<&str> { self.inner.precise.as_ref().map(|s| &s[..]) } + /// Get the git reference if this is a git source, otherwise None. pub fn git_reference(&self) -> Option<&GitReference> { match self.inner.kind { Kind::Git(ref s) => Some(s), @@ -282,6 +316,7 @@ impl SourceId { } } + /// Create a new SourceId from this source with the given `precise` pub fn with_precise(&self, v: Option) -> SourceId { SourceId { inner: Arc::new(SourceIdInner { @@ -291,6 +326,7 @@ impl SourceId { } } + /// Whether the remote registry is the standard https://crates.io pub fn is_default_registry(&self) -> bool { match self.inner.kind { Kind::Registry => {} @@ -299,6 +335,10 @@ impl SourceId { self.inner.url.to_string() == CRATES_IO } + /// Hash `self` + /// + /// For paths, remove the workspace prefix so the same source will give the + /// same hash in different locations. pub fn stable_hash(&self, workspace: &Path, into: &mut S) { if self.is_path() { if let Ok(p) = self.inner.url.to_file_path().unwrap().strip_prefix(workspace) { @@ -383,6 +423,9 @@ impl fmt::Display for SourceId { // This custom implementation handles situations such as when two git sources // point at *almost* the same URL, but not quite, even when they actually point // to the same repository. +/// This method tests for self and other values to be equal, and is used by ==. +/// +/// For git repositories, the canonical url is checked. impl PartialEq for SourceIdInner { fn eq(&self, other: &SourceIdInner) -> bool { if self.kind != other.kind { @@ -441,6 +484,7 @@ impl Hash for SourceId { } } +/// A `Display`able view into a SourceId that will write it as a url pub struct SourceIdToUrl<'a> { inner: &'a SourceIdInner, } @@ -477,6 +521,8 @@ impl<'a> fmt::Display for SourceIdToUrl<'a> { } impl GitReference { + /// Returns a `Display`able view of this git reference, or None if using + /// the head of the "master" branch pub fn pretty_ref(&self) -> Option { match *self { GitReference::Branch(ref s) if *s == "master" => None, @@ -485,6 +531,7 @@ impl GitReference { } } +/// A git reference that can be `Display`ed pub struct PrettyRef<'a> { inner: &'a GitReference, } @@ -499,26 +546,32 @@ impl<'a> fmt::Display for PrettyRef<'a> { } } +/// A `HashMap` of `SourceId` -> `Box` #[derive(Default)] pub struct SourceMap<'src> { map: HashMap>, } +/// A `std::collection::hash_map::Values` for `SourceMap` pub type Sources<'a, 'src> = Values<'a, SourceId, Box>; +/// A `std::collection::hash_map::IterMut` for `SourceMap` pub struct SourcesMut<'a, 'src: 'a> { inner: IterMut<'a, SourceId, Box>, } impl<'src> SourceMap<'src> { + /// Create an empty map pub fn new() -> SourceMap<'src> { SourceMap { map: HashMap::new() } } + /// Like `HashMap::contains_key` pub fn contains(&self, id: &SourceId) -> bool { self.map.contains_key(id) } + /// Like `HashMap::get` pub fn get(&self, id: &SourceId) -> Option<&(Source + 'src)> { let source = self.map.get(id); @@ -528,6 +581,7 @@ impl<'src> SourceMap<'src> { }) } + /// Like `HashMap::get_mut` pub fn get_mut(&mut self, id: &SourceId) -> Option<&mut (Source + 'src)> { self.map.get_mut(id).map(|s| { let s: &mut (Source + 'src) = &mut **s; @@ -535,27 +589,34 @@ impl<'src> SourceMap<'src> { }) } + /// Like `HashMap::get`, but first calculates the `SourceId` from a + /// `PackageId` pub fn get_by_package_id(&self, pkg_id: &PackageId) -> Option<&(Source + 'src)> { self.get(pkg_id.source_id()) } + /// Like `HashMap::insert`, but derives the SourceId key from the Source pub fn insert(&mut self, source: Box) { let id = source.source_id().clone(); self.map.insert(id, source); } + /// Like `HashMap::is_empty` pub fn is_empty(&self) -> bool { self.map.is_empty() } + /// Like `HashMap::len` pub fn len(&self) -> usize { self.map.len() } + /// Like `HashMap::values` pub fn sources<'a>(&'a self) -> Sources<'a, 'src> { self.map.values() } + /// Like `HashMap::iter_mut` pub fn sources_mut<'a>(&'a mut self) -> SourcesMut<'a, 'src> { SourcesMut { inner: self.map.iter_mut() } } diff --git a/src/cargo/ops/cargo_rustc/context.rs b/src/cargo/ops/cargo_rustc/context.rs index 192badff2..7e85c0d58 100755 --- a/src/cargo/ops/cargo_rustc/context.rs +++ b/src/cargo/ops/cargo_rustc/context.rs @@ -64,8 +64,11 @@ pub struct Unit<'a> { pub struct Context<'a, 'cfg: 'a> { /// The workspace the build is for pub ws: &'a Workspace<'cfg>, + /// The cargo configuration pub config: &'cfg Config, + /// The dependency graph for our build pub resolve: &'a Resolve, + /// Information on the compilation output pub compilation: Compilation<'cfg>, pub packages: &'a PackageSet<'cfg>, pub build_state: Arc, diff --git a/src/cargo/util/to_url.rs b/src/cargo/util/to_url.rs index 5508bb9aa..f6a4d23a5 100644 --- a/src/cargo/util/to_url.rs +++ b/src/cargo/util/to_url.rs @@ -4,7 +4,9 @@ use url::Url; use util::CargoResult; +/// A type that can be converted to a Url pub trait ToUrl { + /// Performs the conversion fn to_url(self) -> CargoResult; }