Examples cannot have separate sets of dependencies

[brendanzab]

gfx-rs has examples which have different dependency requirements. It would be great not to have to litter the Cargo.toml with them.

At the moment we have a Makefile to build them, but it results in a huge amount of recompilation.

This could be also useful for external API tests and benchmarks that need to test themselves against different libraries.

[huonw]

Do you know about dev_dependencies?

The [dev-dependencies.*] Sections

The format of this section is equivalent to [dependencies.*]. Dev-dependencies are not used when compiling a package for building, but are used for compiling tests and benchmarks.

These dependencies are not propagated to other packages which depend on this package.

[brendanzab]

No I didn't know about that.

Still, it would be kinda hard to work out what dependency is used where.

Are the examples required to be in the root of the examples folder? because that would be a tad restrictive :/

[brendanzab]

Here are the dependencies of each example. If we use dev-dependencies, then they would be all smooshed together in the top level Cargo.toml. The more and more examples we add, the harder it would be to keep track of what example relies on what.

[[bin]]
name = "cube"
path = "main.rs"

[dependencies.gfx]
path = "../../"

[dependencies.glfw]
git = "https://github.com/bjz/glfw-rs.git"

[dependencies.cgmath]
git = "http://github.com/bjz/cgmath-rs"

[[bin]]
name = "gl-init"
path = "main.rs"

[dependencies.gfx]
path = "../../"

[dependencies.gl_init]
git = "https://github.com/tomaka/gl-init-rs.git"

[[bin]]
name = "gfx-perf"
path = "main.rs"

[dependencies.gfx]
path = "../../"

[dependencies.glfw]
git = "https://github.com/bjz/glfw-rs.git"

[dependencies.gfx_gl]
git = "https://github.com/gfx-rs/gfx_gl.git"

[dependencies.cgmath]
git = "http://github.com/bjz/cgmath-rs"

[[bin]]
name = "terrain"
path = "main.rs"

[dependencies.gfx]
path = "../../"

[dependencies.glfw]
git = "https://github.com/bjz/glfw-rs.git"

[dependencies.cgmath]
git = "http://github.com/bjz/cgmath-rs"

[dependencies.genmesh]
git = "https://github.com/csherratt/genmesh.git"

[dependencies.noise-rs]
git = "https://github.com/bjz/noise-rs.git"

[[bin]]
name = "triangle"
path = "main.rs"

[dependencies.gfx]
path = "../../"

[dependencies.glfw]
git = "https://github.com/bjz/glfw-rs.git"

[huonw]

I believe you can put things in whatever order you like, and you can also define examples explicitly via the example heading, so you could possibly do

[[example]]
name = "foo"

[dev_dependencies.x]
...
[dev_dependencies.y]
...

[[example]]
name = "bar"

[dev_dependencies.x]
...
[dev_dependencies.z]
...

I'm not 100% sure that cargo handles duplicated deps like that, so you may just have to write them once, and I guess you'll need paths for things that aren't examples/$name.rs.

Lastly, each example needs an extern crate ...; for any deps so people looking at a specific one can easily work out exactly what they need.

[brendanzab]

Ah yep,

# ...

[[example]]
name = "triangle"
path = "examples/triangle/main.rs"

[dev_dependencies.glfw]
git = "https://github.com/bjz/glfw-rs.git"


[[example]]
name = "cube"
path = "examples/cube/main.rs"

[dev_dependencies.glfw]
git = "https://github.com/bjz/glfw-rs.git"

Gives:

gfx-rs ➤ cargo update                                                                    git:master*
could not parse input TOML
Cargo.toml:38:1-38:22 redefinition of table `dev_dependencies.glfw`

[brendanzab]

It would be cool if [[example]] would look for a Cargo.toml in that directory.

[alexcrichton]

@bjz, it sounds like you've learned some new things in this issue, which is great! I've got a few follow-up questions at this point.

1. Given the documentation at http://crates.io/, do you think that any of this is missing? How can we improve it to make sure that everything is signaled?
2. It looks like the main umbrage leftover is "too many dev-dependencies in Cargo.toml", does that seem right?
3. Are the any other lingering concerns you'd like to see for improvements?

[brendanzab]

Our Cargo.toml is now pretty overwhelming. It might be hard for contributors and users of our library to understand what's going on. A Cargo.toml is a nice summary of the external dependencies of a unit of code (a crate) - now it is all mixed in together. I just worry about the scalability of the current system as projects grow.

The navigation on http://crates.io/ is right down the bottom. It might be nicer if it was easier to find.

It might be cool to a hierarchical index of the [[blah]], [ooh], and foo = "..." things with one line summaries, then a link to the details. That way you can do a quick scan of the manifest format before diving in closer.

[alexcrichton]

There's a proposal for toml to add "inline table" syntax, which would transform your Cargo.toml to:

[package]

name = "gfx"
version = "0.1.0"
authors = [
    "Brendan Zabarauskas <bjzaba@yahoo.com.au>",
    "Corey Richardson <corey@octayn.net>",
    "kvark",
]


[lib]
name = "gfx"
path = "src/gfx/lib.rs"

[dependencies]

gfx_macros = { path = "src/gfx_macros" }
device = { path = "src/device" }
render = { path = "src/render" }

[[example]]
name = "triangle"
path = "examples/triangle/main.rs"

[[example]]
name = "cube"
path = "examples/cube/main.rs"

[[example]]
name = "terrain"
path = "examples/terrain/main.rs"

[[example]]
name = "gl-init"
path = "examples/gl-init/main.rs"


[[example]]
name = "performance"
path = "examples/performance/main.rs"

[dev-dependencies]

glfw = { git = "https://github.com/bjz/glfw-rs.git" }
gfx_gl = { git = "https://github.com/gfx-rs/gfx_gl.git" }
gl_init = { git = "https://github.com/tomaka/gl-init-rs.git" }
genmesh = { git = "https://github.com/csherratt/genmesh.git" }
noise-rs = { git = "https://github.com/bjz/noise-rs.git" }
cgmath = { git = "http://github.com/bjz/cgmath-rs" }

Out of curiosity, how does that look to you?

[brendanzab]

That looks nicer, but I would still really prefer per-example dependency specification. Or a recursive Cargo.toml solution. Like:

[[example]]
name = "performance"
path = "examples/performance/" # looks for cargo.toml

The latter would make it more self-explanatory for the gfx-rs users about how to set up their projects locally. (Just go to the respective Cargo.toml, and see how it is put together)

[alexcrichton]

I don't believe that we're planning on supporting sub-Cargo.toml to "append to the configuration". At that point it's considered a sub-package. You could always have each of your examples have their own Cargo.toml with a path dependency on the upper level.

From what it sounds like, however, this issue doesn't seem particularly actionable. The issue as-is is solved by dev-dependencies, the prettiness issue is dependent on the PR to TOML, and the sub-testing all packages feature is covered by #483, #482 and #436. In light of this, I'm going to close this for now. If more issues arise though, please feel free to open them!

[brendanzab]

Yeah, the issue with the path (which is what we had previously) is that it leads to redundant recompilations. Anyway, at least we have got a little closer.

[alexcrichton]

The solution for #483 will definitely solve the problem of redundant compilations for sub-packages, as it's basically the same problem there. I hope to have a fix soon-ish!

[ModProg]

maybe the proposed syntax for cargo-script could be used for something like this as well: #12207, rust-lang/rfcs#3424

//! ```cargo
//! [dependencies]
//! clap = { version = "4.2", features = ["derive"] }
//! ```