doc: RFC: husht command line and top-level behavior #1

glen · 2024-09-19T16:01:57Z

glen commented

2024-09-19 16:01:57 +00:00

@Vectornaut please review/comment on whether the proposed operation of husht in terms of where it finds its files and where it puts them seems suitable for how this tool is likely to be used. Also any comments on the command-line format/conventions so far (it's quite bare bones at the moment) are welcome. Thanks.

glen added 1 commit 2024-09-19 16:01:57 +00:00

doc: RFQ: husht command line and top-level behavior ed9525bb9b

glen requested review from Vectornaut 2024-09-19 16:02:07 +00:00

glen changed title from ~~doc: RFQ: husht command line and top-level behavior~~ to doc: RFC: husht command line and top-level behavior

2024-09-20 02:49:30 +00:00

Vectornaut commented

2024-09-26 20:08:27 +00:00

This seems reasonable overall. I'd lean toward imitating the interface conventions of rustc and rustfmt, with rustc probably being a closer analogue in purpose and usage.

In particular, I'd imitate the separate -o and --out-dir flags that rustc uses to specify output locations. The default behavior described in the RFC would then become:

The default value of --out-dir is rust
The default value of -o is nothing.

I can't find documentation of what happens when rustc wants to output multiple files, but the -o flag (which overrides --out-dir) has been set. Maybe anything that could cause rustc to output multiple files (like --emit options) would override -o? It seems like most --emit options cause rustc to emit a single file per option, so that might be an important usage difference between rustc and husht. I imagine husht mostly being used on multiple files at a time, so maybe husht should only have the --out-dir option.

This seems reasonable overall. I'd lean toward imitating the interface conventions of `rustc` and `rustfmt`, with `rustc` probably being a closer analogue in purpose and usage. In particular, I'd imitate the separate [`-o`](https://doc.rust-lang.org/rustc/command-line-arguments.html#option-o-output) and [`--out-dir`](https://doc.rust-lang.org/rustc/command-line-arguments.html#--out-dir-directory-to-write-the-output-in) flags that `rustc` uses to specify output locations. The default behavior described in the RFC would then become: - The default value of `--out-dir` is `rust` - The default value of `-o` is nothing. I can't find documentation of what happens when `rustc` wants to output multiple files, but the `-o` flag (which overrides `--out-dir`) has been set. Maybe anything that could cause `rustc` to output multiple files (like [`--emit`](https://doc.rust-lang.org/rustc/command-line-arguments.html#--emit-specifies-the-types-of-output-files-to-generate) options) would override `-o`? It seems like most `--emit` options cause `rustc` to emit a single file per option, so that might be an important usage difference between `rustc` and `husht`. I imagine `husht` mostly being used on multiple files at a time, so maybe `husht` should only have the `--out-dir` option.

glen added 1 commit 2024-10-15 04:51:52 +00:00

doc: Adjust proposed husht command-line option per feedback. 519da3ca45

glen commented

2024-10-15 04:53:40 +00:00

OK, @Vectornaut , I have adjusted the proposed command-line options per your suggestions, I think. It also simplifies the operation, so I think it's a win all around. Please re-review, and if it looks like a good starting proposal now, squash-merge this PR. Thanks!

Vectornaut commented

2024-10-15 22:21:37 +00:00

This looks reasonable!

One subtlety: since the output directory may be inside the current directory, and it may contain .toml files, maybe we should specify that the contents of the output directory are ignored? This could get annoying if you're switching between multiple output directories, and at least one of them is in the current directory, but maybe we could iron that out later.

Our project will have .css and .html files alongside the application code. Do I understand correctly that these are supposed to be kept in the rust directory, so the Husht converter will drop the Rust code next to them, and then the rust directory can be served with Trunk for testing?

I might change the example to better match a typical Rust project directory structure: I'm used to Cargo.toml being outside the src directory. Have you seen examples where Cargo.toml is inside src?

Proposed example revision

For example, suppose all the .hsh and .toml files in the current directory are laid out like this:

Cargo.toml
src
├─ main.hsh
└─ sub
   └─ crate.hsh

Then husht src would write:

rust
├─ main.rs
└─ sub
   └─ crate.rs

On the other hand just husht (or, equivalently, husht .) would write:

rust
├─ Cargo.toml
└─ src
   ├─ main.rs
   └─ sub
      └─ crate.rs

This looks reasonable! One subtlety: since the output directory may be inside the current directory, and it may contain `.toml` files, maybe we should specify that the contents of the output directory are ignored? This could get annoying if you're switching between multiple output directories, and at least one of them is in the current directory, but maybe we could iron that out later. Our project will have `.css` and `.html` files alongside the application code. Do I understand correctly that these are supposed to be kept in the `rust` directory, so the Husht converter will drop the Rust code next to them, and then the `rust` directory can be served with Trunk for testing? I might change the example to better match a typical Rust project directory structure: I'm used to `Cargo.toml` being outside the `src` directory. Have you seen examples where `Cargo.toml` is inside `src`? ### Proposed example revision For example, suppose all the `.hsh` and `.toml` files in the current directory are laid out like this: ``` Cargo.toml src ├─ main.hsh └─ sub └─ crate.hsh ``` Then `husht src` would write: ``` rust ├─ main.rs └─ sub └─ crate.rs ``` On the other hand just `husht` (or, equivalently, `husht .`) would write: ``` rust ├─ Cargo.toml └─ src ├─ main.rs └─ sub └─ crate.rs ```

glen commented

2024-10-15 22:27:46 +00:00

maybe we should specify that the contents of the output directory are ignored?

Please see line 36 of README.md; if you feel this information should be elsewhere or state differently or highlighted better in some way, please let me know.

> maybe we should specify that the contents of the output directory are ignored? Please see line 36 of README.md; if you feel this information should be elsewhere or state differently or highlighted better in some way, please let me know.

glen commented

2024-10-15 22:34:37 +00:00

Our project will have .css and .html files alongside the application code. Do I understand correctly that these are supposed to be kept in the rust directory, so the Husht converter will drop the Rust code next to them, and then the rust directory can be served with Trunk for testing?

Ah, excellent point. No, I think that the "source" .css and .html files should definitely not be in what is clearly a "build" or "target" directory, but rather in some clear source location -- even if in the end they are copied into the build directory verbatim. But should husht be the one to do that copying? On the one hand, it might be convenient. On the other hand, CSS and HTML have nothing intrinsically to do with Husht or Rust, so how would it make sense for husht to touch them?

Thoughts?

> Our project will have `.css` and `.html` files alongside the application code. Do I understand correctly that these are supposed to be kept in the `rust` directory, so the Husht converter will drop the Rust code next to them, and then the `rust` directory can be served with Trunk for testing? Ah, excellent point. No, I think that the "source" .css and .html files should definitely _not_ be in what is clearly a "build" or "target" directory, but rather in some clear source location -- even if in the end they are copied into the build directory verbatim. But should husht be the one to do that copying? On the one hand, it might be convenient. On the other hand, CSS and HTML have nothing intrinsically to do with Husht or Rust, so how would it make sense for husht to touch them? Thoughts?

Vectornaut commented

2024-10-16 21:17:27 +00:00

Personally: I'd like to think of my Husht project directory as a mirror of what will end up in the Rust target directory, with Husht source replaced with Rust source. (I'd be happy to use some configuration tool to exclude files that shouldn't end up in the target directory.) The underlying principle, I think, is that developing a project in Husht should be just like developing the same project in Rust, except for the modified syntax.

Historically: I'd imagine that Civet and similar tools must have ways to do this. Maybe we should imitate them?

**Personally:** I'd like to think of my Husht project directory as a mirror of what will end up in the Rust target directory, with Husht source replaced with Rust source. (I'd be happy to use some configuration tool to exclude files that shouldn't end up in the target directory.) The underlying principle, I think, is that developing a project in Husht should be just like developing the same project in Rust, except for the modified syntax. **Historically:** I'd imagine that Civet and similar tools must have ways to do this. Maybe we should imitate them?

glen commented

2024-10-16 21:52:56 +00:00

I have no objections to organizing the source files of our project as we like. The question is, does making husht copy anything besides .hsh and .toml clutter husht, or does needing another command to do that copy clutter our build process? Civet ignores anything but .civet, .ts, .js and it puts its resulting files alongside their sources by default, a scheme I am not a fan of.

I am leaning toward having husht mangle .hsh files and copy all other files verbatim, with destination by the same rules for .hsh files. Then we don't even need to mention .toml files. So that seems like no more complicated a rule, and could be handy. Sound OK for a first try?

I have no objections to organizing the source files of our project as we like. The question is, does making husht copy anything besides .hsh and .toml clutter husht, or does needing another command to do that copy clutter our build process? Civet ignores anything but .civet, .ts, .js and it puts its resulting files alongside their sources by default, a scheme I am not a fan of. I am leaning toward having husht mangle .hsh files and copy all other files verbatim, with destination by the same rules for .hsh files. Then we don't even need to mention .toml files. So that seems like no more complicated a rule, and could be handy. Sound OK for a first try?

glen commented

2024-10-16 22:09:25 +00:00

I might change the example to better match a typical Rust project directory structure: I'm used to Cargo.toml being outside the src directory. Have you seen examples where Cargo.toml is inside src?

No, and that is no accident, because as far as my investigations could reveal, the tools that use Cargo.toml will only work with it at the top level and do not even have any options to point to a Cargo.toml file somewhere else.

This really rubs me the wrong way, and I deliberately want husht to allow us to not have to have Cargo.toml in the top level directory of our project:

With more and more tools needing config files and all of them clamoring to be in the top level, that directory becomes an an unmanageable zoo of files. The clear solution to me is to have a place for them, like the etc/ directory I introduced recently in numberscope.
There's a certain arrogance/blindness to the potential virtues of a multi-language project inherent in the attitude "well our configuration has to be at the top level"
Not even having options to point elsewhere feels like just another symptom of the ingrained rigidity of the Rust community, which does bug me.

Their whole thing of "we all have to do it the same way so we can all read each other's stuff" seems to me like a straw man that is pushing groupthink and underestimating the ability of others to grasp the way you're doing things a bit differently and perhaps see the potential virtues of the other way.

So as far as I can see, the copying conventions of husht will make it easy to have cargo.toml wherever we like, and have it end up in the top level in the rust directory, where the rust tools will be happy with it because for them, the rust directory will be the toplevel directory. And I specifically prefer it not at the top level. This is not a Rust project; it's a geometry project that plans to use Rust as one, perhaps the most important one but still just one, tool. So I will leave the code organization in the example as is, but I do like your nifty diagrams and will emulate them. Thanks!

> I might change the example to better match a typical Rust project directory structure: I'm used to `Cargo.toml` being outside the `src` directory. Have you seen examples where `Cargo.toml` is inside `src`? No, and that is no accident, because as far as my investigations could reveal, the tools that use Cargo.toml will **only** work with it at the top level and do **not** even have any options to point to a Cargo.toml file somewhere else. This really rubs me the wrong way, and I deliberately want husht to allow us to not have to have Cargo.toml in the top level directory of our project: 1) With more and more tools needing config files and all of them clamoring to be in the top level, that directory becomes an an unmanageable zoo of files. The clear solution to me is to have a place for them, like the etc/ directory I introduced recently in numberscope. 2) There's a certain arrogance/blindness to the potential virtues of a multi-language project inherent in the attitude "well our configuration has to be at the top level" 3) Not even having options to point elsewhere feels like just another symptom of the ingrained rigidity of the Rust community, which does bug me. Their whole thing of "we all have to do it the same way so we can all read each other's stuff" seems to me like a straw man that is pushing groupthink and underestimating the ability of others to grasp the way you're doing things a bit differently and perhaps see the potential virtues of the other way. So as far as I can see, the copying conventions of husht will make it easy to have cargo.toml wherever we like, and have it end up in the top level in the rust directory, where the rust tools will be happy with it because for them, the rust directory will be the toplevel directory. And I specifically prefer it not at the top level. This is not a Rust project; it's a geometry project that plans to use Rust as one, perhaps the most important one but still just one, tool. So I will leave the code organization in the example as is, but I do like your nifty diagrams and will emulate them. Thanks!

Vectornaut commented

2024-10-16 22:20:13 +00:00

So as far as I can see, the copying conventions of husht will make it easy to have cargo.toml wherever we like, and have it end up in the top level in the rust directory

Are you planning to add a special rule for handling any file named Cargo.toml, which will automatically copy it to the top level of the Husht output directory, and halt with an error if there's more than one? Or do you mean that the current planned behavior for Husht already provides enough flexibility in where to place Cargo.toml?

> So as far as I can see, the copying conventions of husht will make it easy to have cargo.toml wherever we like, and have it end up in the top level in the rust directory Are you planning to add a special rule for handling any file named `Cargo.toml`, which will automatically copy it to the top level of the Husht output directory, and halt with an error if there's more than one? Or do you mean that the current planned behavior for Husht already provides enough flexibility in where to place `Cargo.toml`?

glen commented

2024-10-16 23:08:26 +00:00