Adopting a flat crate hierarchy

[ebkalderon]

I was wondering whether restructuring the file hierarchy of our crates to be flat rather than nested might be of any benefit. That is, transitioning from our current setup of:

* book/
* examples/
* src/
  * config/
    * src/
    * Cargo.toml
  * context/
    * src/
    * Cargo.toml
  * ecs/
    * src/
    * Cargo.toml
  * engine/
  * processors/
  * renderer/
    * src/
    * Cargo.toml
* Cargo.toml

over to something like:

* amethyst/
  * examples/
  * src/
  * Cargo.toml
* amethyst_config/
  * examples/
  * src/
  * Cargo.toml
* amethyst_context/
  * examples/
  * src/
  * Cargo.toml
* amethyst_ecs/
  * examples/
  * src/
  * Cargo.toml
* amethyst_renderer/
  * examples/
  * src/
  * Cargo.toml
* book/

Nested Hierarchy

Pros:

1. Conveys crate dependencies clearly through folder hierarchy.
2. A simple cargo build at the top level is enough to build the whole thing.

Cons:

1. Can get convoluted the more crates we add.
2. No easy distinction between modules and sub-crates.

Flat Hierarchy

Pros:

1. Easier to locate each crate in the entire project.
2. Good distinctions between modules and sub-crates.

Cons:

1. Crate dependencies are not obvious if there is no hierarchy.
2. What is the difference between README in top-level engine repo and README in amethyst/ directory?

[wendivoid]

Hey, First let me say nice project!
I'm currently using amethyst to build a Pokemon clone as a learning project. If i may offer my two cents, i would like to see it organized this way. I've had some issues when trying to use each crate separately (I quite trying and just use the main crate now). I cant remember the exact error's i was receiving but next time i come across one i could post an issue.

PS. Amethyst has some of the nicest looking code I've seen. It's been easy for me as a newbie to dig though and understand exactly what is happening under the hood, and i very much appreciate that!

[Julianobsg]

Hi, new to this project and rust.

I'm using some rust projects to learn the language and yours got my attention, not sure if my opinion can be useful for you, but I would like to suggest you, to split the code in separated project, as the code base and contributors grow, splitting projects helps out.

[LucioFranco]

@ByteBuddha @Julianobsg Welcome to the project! We appreciate the feedback. If you guys need any help feel free to join us on gitter.

@ebkalderon I think we should keep it as the nested structure because of the ability to easily compile the project. Maybe we can create a WIKI page to describe the structure of the project. I think adding a ton of folders to the root of the project just makes it harder to understand whats going on.

[CooCooCaCha]

I recently moved one of my personal projects to a monorepo layout and I like it a lot. Not a fan of splitting into separate projects since coordinating changes between projects becomes increasingly painful. Unreal Engine is a single repo for example.

[Aceeri]

While we are talking about this, I've been thinking that maybe making each portion of the engine to be separate crates instead of modules might not be the best idea. You can see the problems it causes with amethyst_context only being able to get other crates through importing it by its Cargo.toml:

[dependencies.amethyst_renderer]
path = "../renderer/"
version = "0.3.0"

Which means that any bit of modularity it might have is diminished (since it now depends on getting another crate locally). The only current benefit I see of splitting into separate crates is shorter compile times (which will eventually be swapped when incremental compilation comes along).

[yeliknewo]

I am working on my own game engine with similar design. I switched to multiple crates from modules. Compile time was much faster. It made it inconvenient to change dependencies such as gfx versions. It was also more hierarchical and less interconnected so it was easier to switch out parts of the engine.

[msiglreith]

I personally would prefer a flat hierarchy as it's easier to distinguish the different components or layers of the engine. The top-level README could contain a quick overview, which directory contains the actual engine/entrypoint.

[Aceeri]

Crate dependencies are not obvious if there is no hierarchy.

I'm not sure the current set up is too obvious with the dependencies (since some crates may depend on other sub-crates). So I think moving them to the top-level might make it easier to read anyways.

A simple cargo build at the top level is enough to build the whole thing.

Wouldn't it be easy to do this by doing

cd amethyst/
cargo build

from the top-level?

[lschmierer]

Having modules and crates mixed in src is pretty confusing for me.

When #152 is merged, amethyst_renderer is going to be the only "feature" that is implemented as seperate crate (at that moment).

I would encourage for a flat hierarchy that would currently look like

* amethyst/
  * examples/
  * src/
  * Cargo.toml
* amethyst_renderer/
  * examples/
  * src/
  * Cargo.toml

For new features that are integrated, it should be individually determined if it makes sense to mantain these as seperate crates.
This could be, for example, if the crate would be useful outside of the amethyst project.
(Therefore seperate crates may avoid dependency of the main amethyst crate.)

[ebkalderon]

I like @lschmierer's hierarchy. I would also recommend that the book reside in the amethyst crate because the book describes the use of the top-level crate in particular, not necessarily all of the sub-crates. Where should we put README.md, CONTRIBUTING.md, etc?

Actually, looking at the workspace section of the Cargo Manifest Format and the linked RFC 1525, it appears that this is the idiomatic way:

* amethyst_config/
  * examples/
  * src/
  * Cargo.toml
* amethyst_renderer/
  * examples/
  * src/
  * Cargo.toml
* book/
* examples/
* src/
* Cargo.toml
* CONTRIBUTING.md
* README.md

I like that the amethyst_* crates stay nicely towards the top since it's all in alphabetical order, and also there is no question of where to place the book and Markdown files. Therefore, I think we should use this method.

[ebkalderon]

Heads up, this will actually be landing as part of #233!

[Xaeroxe]

Implemented, so I'm closing this.