# Make project layout evoke-compatible?

**URL:** <https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457>\
**Category:** Beman Libraries\
**Tags:** guidelines, packaging\
**Created:** [June 23, 2025, 8:20pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457 "2025-06-23T20:20:17Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![dascandy](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/dascandy/32/282_2.png) [@dascandy](https://discourse.bemanproject.org/u/dascandy)\
**Post date:** [June 23, 2025, 8:20pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/1 "2025-06-23T20:20:17Z")

</div>

The goal behind Evoke is to rely solely on the code itself, and the directory structure around the code, to determine what makes up which components, and which components are which type.

The Beman project setup is _almost_ perfect for it - including cloning a bunch of Beman projects into separate folders including cross-dependencies - except for the examples folder containing multiple examples, presumably with separate main() functions.

If each of the examples are just a function to be triggered through a main entry point for the examples, then it will work as is. However, if they are supposed to be separate executables, then it would (according to Evoke’s logic) need each of them to be its own folder.

Would this be an acceptable change?

There’s a teensy thing too - the test folder it expects is “test”, not “tests” - but that’s one that I think Evoke should just fix instead.

---

<div class="post-metadata">

**Author:** ![Jeff-Garland](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/jeff-garland/32/23_2.png) [@Jeff-Garland](https://discourse.bemanproject.org/u/Jeff-Garland)\
**Post date:** [June 23, 2025, 11:56pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/2 "2025-06-23T23:56:41Z")

</div>

Welcome @dascandy! So I assume Evoke is this? [GitHub - dascandy/evoke: Magic build tool](https://github.com/dascandy/evoke)

So to be clear are you suggesting evoke for the role of taking say 3 ranges repos and combining them into a single ranges repo?

Note that if you stare carefully at the Beman standard we’re doing are best to say cmake and python are about the extent of the tool chain (outside of compilers, coverage, documentation, and package managers optionally). So w.r.t adding another thing we’ll want some really compelling use cases.

---

<div class="post-metadata">

**Author:** ![dascandy](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/dascandy/32/282_2.png) [@dascandy](https://discourse.bemanproject.org/u/dascandy)\
**Post date:** [June 24, 2025, 6:12am UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/3 "2025-06-24T06:12:12Z")

</div>

I’m suggesting that by making a minor tweak to the guidance for one folder, that the whole thing already does everything evoke needs/requires, and wouldn’t need a single byte of build configuration anywhere.

I’m not trying to add any work, only trying to tune one rule, which would make that work.

If that’s not possible, then that’s okay too - I’ll just have to work around it locally.

---

<div class="post-metadata">

**Author:** ![Jeff-Garland](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/jeff-garland/32/23_2.png) [@Jeff-Garland](https://discourse.bemanproject.org/u/Jeff-Garland)\
**Post date:** [June 24, 2025, 11:45am UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/4 "2025-06-24T11:45:53Z")

</div>

I have no issues renaming the folder to tests.

---

<div class="post-metadata">

**Author:** ![dascandy](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/dascandy/32/282_2.png) [@dascandy](https://discourse.bemanproject.org/u/dascandy)\
**Post date:** [June 29, 2025, 5:13pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/5 "2025-06-29T17:13:55Z")

</div>

The action would be to either have the examples/ folder compile to one executable, or to have each example in its own folder. Both would work.

---

<div class="post-metadata">

**Author:** ![Jeff-Garland](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/jeff-garland/32/23_2.png) [@Jeff-Garland](https://discourse.bemanproject.org/u/Jeff-Garland)\
**Post date:** [June 29, 2025, 6:07pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/6 "2025-06-29T18:07:58Z")

</div>

> [@dascandy](#):
>
> he action would be to either have the examples/ folder compile to one executable, or to have each example in its own folder. Both would work.

Well for that I think evoke should be adapted and not Beman. Having many small stand alone example files is a pretty common pattern in open source and I wouldn’t want to prevent authors from using that pattern. Forcing a subdirectory per file doesn’t seem right – to pick one, in boost date-time there’s subdirectories in examples all with several files…

---

<div class="post-metadata">

**Author:** ![dsankel](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/dsankel/32/5_2.png) [@dsankel](https://discourse.bemanproject.org/u/dsankel)\
**Post date:** [July 7, 2025, 3:26pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/7 "2025-07-07T15:26:11Z")

</div>

> [@dascandy](#):
>
> The goal behind Evoke is to rely solely on the code itself, and the directory structure around the code, to determine what makes up which components, and which components are which type.

If I understand correctly, when looking at a folder with `.cpp` files, without more information, you cannot determine the type (e.g., library, executable) or quantity of build artifacts they produce. Evoke wants you to be able to determine this based on directory structure.

I like the theory behind that, but where tests predominantly consist of a single file, it’s tedious to maintain an extra containing directory. Rust’s cargo build system seems to share Evoke’s goals and gets around this tedium (in the case of examples) by treating `examples/foo.rs` as a single-file executable and `examples/bar/*.rs` as a multi-file executable (bar). What are your thoughts on that @dascandy / @Jeff-Garland ?

---

<div class="post-metadata">

**Author:** ![Jeff-Garland](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/jeff-garland/32/23_2.png) [@Jeff-Garland](https://discourse.bemanproject.org/u/Jeff-Garland)\
**Post date:** [July 7, 2025, 3:56pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/8 "2025-07-07T15:56:04Z")

</div>

> [@dsankel](#):
>
> I like the theory behind that, but where tests predominantly consist of a single file, it’s tedious to maintain an extra containing directory.

I’d note that the vast majority if not all Beman libraries currently have multiple .cpp files for tests - each with their own main. In my experience with this with most libraries this is done to split tests into logical groups for maintenance and parallel compilation. Building a library in the test directory to support tests is super rare…

> [@dsankel](#):
>
> Rust’s cargo build system seems to share Evoke’s goals and gets around this tedium (in the case of examples) by treating `examples/foo.rs` as a single-file executable and `examples/bar/*.rs` as a multi-file executable (bar). What are your thoughts on that @dascandy / @Jeff-Garland ?

I think the Rust assumption is more in line with what I’d expect. Still a bigger (see also execution) library could easily have example subdirectories with single file examples.

In the case of Beman we’re 100% standard on cmake which allows for the generation of compile\_commands.json – shouldn’t a tool like evoke consider using the actual generated commands instead of just a directory?

---

<div class="post-metadata">

**Author:** ![dascandy](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.bemanproject.org/dascandy/32/282_2.png) [@dascandy](https://discourse.bemanproject.org/u/dascandy)\
**Post date:** [October 4, 2025, 4:06pm UTC](https://discourse.bemanproject.org/t/make-project-layout-evoke-compatible/457/9 "2025-10-04T16:06:16Z")

</div>

> [@dsankel](#):
>
> Rust’s cargo build system seems to share Evoke’s goals and gets around this tedium (in the case of examples) by treating `examples/foo.rs` as a single-file executable and `examples/bar/*.rs` as a multi-file executable (bar). What are your thoughts on that @dascandy / @Jeff-Garland ?

Looks 100% fine actually. Let me look somewhat deeper into Cargo to see if I can import some similar ideas from that.

> shouldn’t a tool like evoke consider using the actual generated commands instead of just a directory?

That idea is one that appeals to those using cmake, but it is useless to those looking at a project from the outside. The code should be the guiding basis for what you’re doing, and people reading code should be able to figure out what goes where based on its names. CMake by design allows you to specify everything as crooked as it likes, and while we could make build tools read whatever cmake outputs, humans won’t.

We need pressure in the direction of projects being readable, and one of those sources of pressure is having a build system look at the project exactly like humans would. As long as you don’t do any weird thing, Evoke should work - and if Evoke doesn’t work, you should first wonder why, or what you’re doing.