@@ -49,6 +49,70 @@ pub fn alt_api_url() -> Url {
4949 Url :: from_file_path ( & * alt_api_path ( ) ) . ok ( ) . unwrap ( )
5050}
5151
52+ /// A builder for creating a new package in a registry.
53+ ///
54+ /// This uses "source replacement" using an automatically generated
55+ /// `.cargo/config` file to ensure that dependencies will use these packages
56+ /// instead of contacting crates.io. See `source-replacement.md` for more
57+ /// details on how source replacement works.
58+ ///
59+ /// Call `publish` to finalize and create the package.
60+ ///
61+ /// If no files are specified, an empty `lib.rs` file is automatically created.
62+ ///
63+ /// The `Cargo.toml` file is automatically generated based on the methods
64+ /// called on `Package` (for example, calling `dep()` will add to the
65+ /// `[dependencies]` automatically). You may also specify a `Cargo.toml` file
66+ /// to override the generated one.
67+ ///
68+ /// This supports different registry types:
69+ /// - Regular source replacement that replaces `crates.io` (the default).
70+ /// - A "local registry" which is a subset for vendoring (see
71+ /// `Package::local`).
72+ /// - An "alternative registry" which requires specifying the registry name
73+ /// (see `Package::alternative`).
74+ ///
75+ /// This does not support "directory sources". See `directory.rs` for
76+ /// `VendorPackage` which implements directory sources.
77+ ///
78+ /// # Example
79+ /// ```
80+ /// // Publish package "a" depending on "b".
81+ /// Package::new("a", "1.0.0")
82+ /// .dep("b", "1.0.0")
83+ /// .file("src/lib.rs", r#"
84+ /// extern crate b;
85+ /// pub fn f() -> i32 { b::f() * 2 }
86+ /// "#)
87+ /// .publish();
88+ ///
89+ /// // Publish package "b".
90+ /// Package::new("b", "1.0.0")
91+ /// .file("src/lib.rs", r#"
92+ /// pub fn f() -> i32 { 12 }
93+ /// "#)
94+ /// .publish();
95+ ///
96+ /// // Create a project that uses package "a".
97+ /// let p = project()
98+ /// .file("Cargo.toml", r#"
99+ /// [package]
100+ /// name = "foo"
101+ /// version = "0.0.1"
102+ ///
103+ /// [dependencies]
104+ /// a = "1.0"
105+ /// "#)
106+ /// .file("src/main.rs", r#"
107+ /// extern crate a;
108+ /// fn main() { println!("{}", a::f()); }
109+ /// "#)
110+ /// .build();
111+ ///
112+ /// assert_that(
113+ /// p.cargo("run"),
114+ /// execs().with_stdout("24"));
115+ /// ```
52116pub struct Package {
53117 name : String ,
54118 vers : String ,
@@ -128,6 +192,8 @@ pub fn init() {
128192}
129193
130194impl Package {
195+ /// Create a new package builder.
196+ /// Call `publish()` to finalize and build the package.
131197pub fn new ( name : & str , vers : & str ) -> Package {
132198 init ( ) ;
133199 Package {
@@ -143,47 +209,92 @@ impl Package {
143209 }
144210 }
145211
212+ /// Call with `true` to publish in a "local registry".
213+ ///
214+ /// See `source-replacement.html#local-registry-sources` for more details
215+ /// on local registries. See `local_registry.rs` for the tests that use
216+ /// this.
146217pub fn local ( & mut self , local : bool ) -> & mut Package {
147218 self . local = local;
148219 self
149220 }
150221
222+ /// Call with `true` to publish in an "alternative registry".
223+ ///
224+ /// The name of the alternative registry is called "alternative".
225+ ///
226+ /// See `unstable.html#alternate-registries` for more details on
227+ /// alternative registries. See `alt_registry.rs` for the tests that use
228+ /// this.
151229pub fn alternative ( & mut self , alternative : bool ) -> & mut Package {
152230 self . alternative = alternative;
153231 self
154232 }
155233
234+ /// Add a file to the package.
156235pub fn file ( & mut self , name : & str , contents : & str ) -> & mut Package {
157236 self . files . push ( ( name. to_string ( ) , contents. to_string ( ) ) ) ;
158237 self
159238 }
160239
240+ /// Add an "extra" file that is not rooted within the package.
241+ ///
242+ /// Normal files are automatically placed within a directory named
243+ /// `$PACKAGE-$VERSION`. This allows you to override that behavior,
244+ /// typically for testing invalid behavior.
161245pub fn extra_file ( & mut self , name : & str , contents : & str ) -> & mut Package {
162246 self . extra_files
163247 . push ( ( name. to_string ( ) , contents. to_string ( ) ) ) ;
164248 self
165249 }
166250
251+ /// Add a normal dependency. Example:
252+ /// ```
253+ /// [dependencies]
254+ /// foo = {version = "1.0"}
255+ /// ```
167256pub fn dep ( & mut self , name : & str , vers : & str ) -> & mut Package {
168257 self . full_dep ( name, vers, None , "normal" , & [ ] , None )
169258 }
170259
260+ /// Add a dependency with the given feature. Example:
261+ /// ```
262+ /// [dependencies]
263+ /// foo = {version = "1.0", "features": ["feat1", "feat2"]}
264+ /// ```
171265pub fn feature_dep ( & mut self , name : & str , vers : & str , features : & [ & str ] ) -> & mut Package {
172266 self . full_dep ( name, vers, None , "normal" , features, None )
173267 }
174268
269+ /// Add a platform-specific dependency. Example:
270+ /// ```
271+ /// [target.'cfg(windows)'.dependencies]
272+ /// foo = {version = "1.0"}
273+ /// ```
175274pub fn target_dep ( & mut self , name : & str , vers : & str , target : & str ) -> & mut Package {
176275 self . full_dep ( name, vers, Some ( target) , "normal" , & [ ] , None )
177276 }
178277
278+ /// Add a dependency to an alternative registry.
279+ /// The given registry should be a URI to the alternative registry.
179280pub fn registry_dep ( & mut self , name : & str , vers : & str , registry : & str ) -> & mut Package {
180281 self . full_dep ( name, vers, None , "normal" , & [ ] , Some ( registry) )
181282 }
182283
284+ /// Add a dev-dependency. Example:
285+ /// ```
286+ /// [dev-dependencies]
287+ /// foo = {version = "1.0"}
288+ /// ```
183289pub fn dev_dep ( & mut self , name : & str , vers : & str ) -> & mut Package {
184290 self . full_dep ( name, vers, None , "dev" , & [ ] , None )
185291 }
186292
293+ /// Add a build-dependency. Example:
294+ /// ```
295+ /// [build-dependencies]
296+ /// foo = {version = "1.0"}
297+ /// ```
187298pub fn build_dep ( & mut self , name : & str , vers : & str ) -> & mut Package {
188299 self . full_dep ( name, vers, None , "build" , & [ ] , None )
189300 }
@@ -208,11 +319,18 @@ impl Package {
208319 self
209320 }
210321
322+ /// Specify whether or not the package is "yanked".
211323pub fn yanked ( & mut self , yanked : bool ) -> & mut Package {
212324 self . yanked = yanked;
213325 self
214326 }
215327
328+ /// Create the package and place it in the registry.
329+ ///
330+ /// This does not actually use Cargo's publishing system, but instead
331+ /// manually creates the entry in the registry on the filesystem.
332+ ///
333+ /// Returns the checksum for the package.
216334pub fn publish ( & self ) -> String {
217335 self . make_archive ( ) ;
218336
@@ -358,6 +476,7 @@ impl Package {
358476 t ! ( ar. append( & header, contents. as_bytes( ) ) ) ;
359477 }
360478
479+ /// Returns the path to the compressed package file.
361480pub fn archive_dst ( & self ) -> PathBuf {
362481 if self . local {
363482 registry_path ( ) . join ( format ! ( "{}-{}.crate" , self . name, self . vers) )
0 commit comments