Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Guidance on naming - when to say "Amaranth HDL" versus just "Amaranth". #660

Open
martinling opened this issue Dec 13, 2021 · 7 comments
Open

Comments

@martinling
Copy link

martinling commented Dec 13, 2021

It would be useful to have some guidance on preferred usage of the project's new name.

The full title of the project is now "Amaranth HDL", but in most instances within the documentation it is referred to simply as "Amaranth".

For updating existing references in comments and documentation, simply doing a search & replace from "nMigen" to "Amaranth HDL" generates some usage that feels awkward to me, and is inconsistent with the project's own usage. Yet in some instances it must be correct to use the full title.

I have just reviewed greatscottgadgets/luna#156 on this point, and I'd like to know if my intuition on usage was correct there.

Whatever the answer, it would be great to put some explicit guidance on usage in the Amaranth documentation.

@whitequark
Copy link
Member

whitequark commented Dec 14, 2021

The Amaranth project consists of a hardware definition language, a toolchain that processes it, and other associated libraries of code, such as the board definitions, the SoC toolkit, and so on. Roughly, the Amaranth project is what lives in the https://github.com/amaranth-lang organization.

"Amaranth HDL" refers more specifically to the language and the core toolchain (which, due to its design, are essentially the same entity). Roughly, the Amaranth HDL is what lives in the module you use when you import amaranth. This repository could have been called amaranth-hdl, though it isn't.

The documentation refers to the "Amaranth language", "Amaranth standard library", "Amaranth simulator", "Amaranth build system" and so on. These are all parts of "Amaranth HDL"; the language syntax, the standard library, and the rest of the components are designed and built together, but it can be useful to refer to them individually.

"Amaranth SoC" refers to the module you get when you import amaranth_soc, which lives in the amaranth-soc repository. The same applies to the other associated projects.

Of course, colloquial language being what it is, people use "Amaranth" to refer to the project as a whole, to the code in this repository, or to the language syntax in particular. And that's fine! You can always use the more specific terms to disambiguate, and really as long as it's clear what's being talked about.


In your PR you've been using the terms that feel the most clear in the context, and I think we're on the same page, there.

@modwizcode
Copy link
Contributor

modwizcode commented Dec 14, 2021

We've been using Amaranth specifically on it's own to refer to the language in general. It amounts to a shorthand for the language itself. We've ended up using Amaranth HDL to refer to the overall entity of the combined sum of parts. This isn't perfectly in alignment with what you've said @whitequark, I wonder if that convention is close enough to feel comfortable to you.

@martinling
Copy link
Author

martinling commented Dec 14, 2021

In your PR you've been using the terms that feel the most clear in the context, and I think we're on the same page, there.

That's good to know, thanks. It seemed like the right approach but I wanted to confirm.

I think it could be helpful for others to add something about this to the documentation - just putting more or less what you wrote above in a section of the introduction would suffice.

@diegoherranz
Copy link

diegoherranz commented Mar 12, 2022

"Amaranth HDL" refers more specifically to the language and the core toolchain (which, due to its design, are essentially the same entity)

Just to make my mind clear, that's what was called FHDL for Migen?
Thanks!

@whitequark
Copy link
Member

whitequark commented Mar 12, 2022

I don't draw any particular parallels with Migen; most of the architectural decisions that remain derived from it (e.g. everything related to fragments) are liabilities anyway.

@diegoherranz
Copy link

diegoherranz commented Mar 12, 2022

OK, thanks.

@whitequark
Copy link
Member

whitequark commented Apr 5, 2022

Keeping this issue open until we have something on this topic in the documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

No branches or pull requests

4 participants