From d50286a5d65baeaaebcb1046474fe2ef9329c413 Mon Sep 17 00:00:00 2001 From: "J.W" Date: Thu, 23 Nov 2017 01:39:59 +0800 Subject: [PATCH 1/4] cargo publish with internal path dependencies --- text/0000-internal-path-dependencies.md | 127 ++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 text/0000-internal-path-dependencies.md diff --git a/text/0000-internal-path-dependencies.md b/text/0000-internal-path-dependencies.md new file mode 100644 index 00000000000..ee691295ff5 --- /dev/null +++ b/text/0000-internal-path-dependencies.md @@ -0,0 +1,127 @@ +- Feature Name: internal-path-dependencies +- Start Date: 2017-11-22 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +This RFC proposes the support for publishing a crate with path dependencies. + +# Motivation +[motivation]: #motivation + +Cargo currently does not allow uploading a crate with path dependencies to the +registry, which means developers cannot utilize path dependencies to better +organize the code. + +Path dependencies can serve as sub-crates of the root crate. This structure can +help to avoid clustering the specs of all external dependencies in a single +top-level manifest file. This also ease the work if later we decide to publish +a standalone path dependency. + +With this feature, we don't have to publish path dependencies before the root +crate is allowed to be published. So path dependencies can be kept internal to +the project, and all the source code can be bundled into a single crate for +downloading. + +As a result of this, the workspace information will be kept along with the +published crate, thus large projects can benefit more from it. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +The manifest value of `package.publish` is `true` by default, which means +a path dependency is allowed to be published. By setting this value to `false`, +we can on one hand forbid a standalone crate from being published to the +registry (by accident), and on the other hand allow its content to be included +when `cargo package` or `cargo publish` is run. + +Say our project "foo" has these files: + +``` +foo/Cargo.toml +foo/src/main.rs +foo/bar/Cargo.toml +foo/bar/src/lib.rs +``` + +The root crate "foo" depends on the path dependency "bar" in the subdirectory +`bar/`: + +```toml +# foo/Cargo.toml +[package] +name = "foo" +version = "0.1.0" +... +[dependencies.bar] +path = "bar" +version = "*" +``` + +And we set `package.publish` to `false` in bar's manifest: + +```toml +[package] +publish = false +name = "bar" +version = "1.0.0" +... +``` + +Then we can run `cargo package --list` to see what is included for publishing: + +``` +Cargo.toml +bar/Cargo.toml +bar/src/lib.rs +src/main.rs +``` + +After `cargo publish --dry-run` we can find these files: + +``` +target/package/foo-0.1.0/Cargo.toml +target/package/foo-0.1.0/Cargo.toml.orig +target/package/foo-0.1.0/bar/Cargo.toml +target/package/foo-0.1.0/bar/Cargo.toml.orig +target/package/foo-0.1.0/bar/src/lib.rs +target/package/foo-0.1.0/src/main.rs +``` + +All manifest files are sanitized and reside with their original files `*.orig`. + +If you specify the workspace in the manifest, they would be kept as is. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +N/A + +# Drawbacks +[drawbacks]: #drawbacks + +This feature does not affect any existing projects or other functionality of +cargo. Only the published contents of the package will be changed, i.e. adding +source files of path dependencies, recursively. + +# Rationale and alternatives +[alternatives]: #alternatives + +There is still no other proposals related to publishing with path dependencies. + +Without this feature, a project with path dependencies cannot be uploaded, +unless the path dependencies are registed at the registry. If developers insist +publishing internal crates to the registry, then the namespace would get +polluted. In addition, these separated dependencies lose support of shared +workspace and thus make it harder to keep the same versions of dependencies. + +# Unresolved questions +[unresolved]: #unresolved-questions + +- Use another manifest key to specify whether path dependencies are included? + - Some people think `package.publish=false` means the source code should + not be published or "public" in any way. + - `package.internal=true`? + - `dependencies.foo.internal=true`? From 2dd71e273e120ca595037b406088928231df92b8 Mon Sep 17 00:00:00 2001 From: "J.W" Date: Thu, 23 Nov 2017 01:56:37 +0800 Subject: [PATCH 2/4] Include the .crate tarball in the file list --- text/0000-internal-path-dependencies.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-internal-path-dependencies.md b/text/0000-internal-path-dependencies.md index ee691295ff5..b3785c7f089 100644 --- a/text/0000-internal-path-dependencies.md +++ b/text/0000-internal-path-dependencies.md @@ -88,6 +88,7 @@ target/package/foo-0.1.0/bar/Cargo.toml target/package/foo-0.1.0/bar/Cargo.toml.orig target/package/foo-0.1.0/bar/src/lib.rs target/package/foo-0.1.0/src/main.rs +target/package/foo-0.1.0.crate ``` All manifest files are sanitized and reside with their original files `*.orig`. From eca4828b2e5ec534ee25f5f0a7f5af5c81b3e1b2 Mon Sep 17 00:00:00 2001 From: "J.W" Date: Thu, 23 Nov 2017 02:12:11 +0800 Subject: [PATCH 3/4] More questions --- text/0000-internal-path-dependencies.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0000-internal-path-dependencies.md b/text/0000-internal-path-dependencies.md index b3785c7f089..c67edd01882 100644 --- a/text/0000-internal-path-dependencies.md +++ b/text/0000-internal-path-dependencies.md @@ -126,3 +126,5 @@ workspace and thus make it harder to keep the same versions of dependencies. not be published or "public" in any way. - `package.internal=true`? - `dependencies.foo.internal=true`? +- No restriction for the versions of internal path dependencies? +- How should the manifest files be further sanitized? From ec3f0752b57bc9882de7db481113f6f72d74ac50 Mon Sep 17 00:00:00 2001 From: "J.W" Date: Sun, 26 Nov 2017 07:48:32 +0800 Subject: [PATCH 4/4] More questions --- text/0000-internal-path-dependencies.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/text/0000-internal-path-dependencies.md b/text/0000-internal-path-dependencies.md index c67edd01882..6ee3a6f62ff 100644 --- a/text/0000-internal-path-dependencies.md +++ b/text/0000-internal-path-dependencies.md @@ -103,9 +103,9 @@ N/A # Drawbacks [drawbacks]: #drawbacks -This feature does not affect any existing projects or other functionality of -cargo. Only the published contents of the package will be changed, i.e. adding -source files of path dependencies, recursively. +This feature (in theory) should not affect any existing projects or other +functionality of cargo. Only the published contents of the package will be +changed, i.e. adding source files of path dependencies, recursively. # Rationale and alternatives [alternatives]: #alternatives @@ -125,6 +125,7 @@ workspace and thus make it harder to keep the same versions of dependencies. - Some people think `package.publish=false` means the source code should not be published or "public" in any way. - `package.internal=true`? - - `dependencies.foo.internal=true`? - No restriction for the versions of internal path dependencies? - How should the manifest files be further sanitized? +- Exclude path dependencies from Cargo.lock (except their external deps)? +- How to organize the generated content of `cargo doc`?