[discussion] changing the project name / acronym

[japaric]

Over the course of the two years I have been working on this project I have received several comments expressing displeasure over the acronym chosen for the project (RTFM). These comments have been along the lines of:

• "The acronym of the project is terrible for searching it on the web because it coincides with the acronym for 'Read The Fucking Manual'."

• "Some corporate environments may frown upon the acronym."

• Some people have pointed out the disconnect (contradiction?) between the acronym and Rust's goal of being a welcoming, inclusive and empowering programming language / community.

Of course, I have also heard some people say that they find the acronym funny. However, those comments have been few in comparison to the first kind of comments. As the project has been growing in popularity the number of comments of disapproval I get has increased as well; I think the upcoming minor release is a good time to address this issue.

This thread is to discuss the possibility changing the name of the project or at the very least changing the acronym (e.g. to RTmass). I would greatly appreciate people sharing their thoughts on why they find that the current acronym is no good and / or how the project would benefit from changing its name / acronym. Name and acronym suggestions are welcome as well.

A name / acronym change would entail renaming the crate for the upcoming minor release (v0.5.0) and using this new name for the GitHub organization proposed in RFC rtfm-rs/cortex-m-rtfm#203.

---

I would gladly welcome a name that better conveys that the framework is for building any kind of multitasking / event-driven embedded application. I have often heard phrases like "RTFM is for building real-time applications" implying that one would only use RTFM for coding real time applications; this is clearly not true as evidenced by the many non-real-time projects built with RTFM.

Finally, I must stress that renaming the project or changing its acronym would not change or invalidate its history. This project, regardless of its name, will continue to be related to the Real Time for the Masses language and all the research associated to it -- this connection is stated in the project's README and book and will remain there.

[perlindgren]

Hi Folks

As the originator of the project, I have mixed feelings about changing the name. I could think of Low OVerhead Embedded, as an alternative. That would allow us to build systems with LOVE!!!!

[little-arhat]

The only issue I have with current name is that it's very similar to cortex-m-rt so I often end up in wrong directory or page, thanks to autocomplete. I guess cortex-m could be dropped as in theory this library is not limited to cortex-m, but then name would indeed sound a bit weird.

As an alternative I suggest something like mrt — Metal Real Time — following mio. (mrt can also be expandend as mu or micro).

[placrosse]

While I personally have no problem with rtfm, and think it would be very poor professional judgement for someone to not use it solely because of the name, @perlindgren 's suggestion would have a powerful positive effect.

Unfortunately, there's already a crate:

https://crates.io/crates/love

Perhaps love-rt would work (adding real-time back in). The ability to handle real time, when necessary, is a key feature which should not be hidden

[placrosse]

And to @japaric , I suspect many people found it somewhat amusing, but did not feel compelled to spend your time by informing you of their feelings.

[ssokolow]

My main issue with it is the searchability. LOVE would have had the same problem whenever someone didn't bother to write the full love-rt so I'd prefer something where, if it uses a common word, it's formatted without a dash that might encourage people to abbreviate it. (eg. camelcase instead of anything resembling snake case.)

[korken89]

I faced the same issue when working on the C++ version of RTFM, and in the end I asked the embedded C++ community for help. After a lot of discussions we chose crect (pronounced correct) for Compile-time Reactive Scheduler or correct by design. Not the best of names, but it worked really well for the C++ community.

When it comes to here, I agree that the RTFM names give off a non-professional tone and a replacement should be found. However what the replacement it, I am not sure.

[austinglaser]

I think one of boats' blog posts from a while back is relevant here. In particular:

names that are just made up out of nowhere are better than names that are constructed from internal jargon of the project domain, unless you expect all users to already be familiar with that jargon and that domain ... if you intend to introduce users to the complexities of this subject through your project, its much better to come up with a random, flashy name for it that is at best vaguely related to the subject of it.

I think it's worth putting on the table something that isn't an acronym or a directly embedded-related term, or even a name to which we can attach a thin metaphor (I spent some time thinking of "lightweight metals," but all good names seemed to be taken).

I'll probably dump a couple suggestions I think will fit this mold in a follow-up comment.

[austinglaser]

Some output of my brain's psuedo-random name generator (all checked to be free on crates.io):

• bauble
• sunjammer
• juggler (cause it juggles tasks/resources)
• implant (a synonym for embed)
• unos ("UNOS is Not an OS")

[ssokolow]

I'm rather partial to portmanteaus and two-word phrases because they're still easy to search, they're easy to make pronounceable, and they lend themselves well to providing a good mnemonic hook via intrinsic meaning so that, if you wandered past but didn't need it, and some of the design elements caught your eye, you're likely to also remember what it was called when you do need it.

The TaskJuggler time-management software is a good example of that.

[dbrgn]

Incredible but true: The crate fearless doesn't exist yet. Fearless embedded real-time systems with Rust.

[TeXitoi]

Fearless interruptions!

[TeXitoi]

I personally like the RTFM name because it's easy to remember. I can understand that we want to choose to avoid the impolite reference.

[TeXitoi]

To take the example of the tokio project, I searched for cities in which we can write IRQ inside. I've found:

• Kirkuk, Iraq -> Kirquk
• Irkutsk, Russia -> Irqutsk
• Birkenhead, United Kingdom -> Birqenhead
• Jirkov -> Jirqov
• Kirkland, USA or Canada -> Kirqland
• Sirkap, Greco-Bactrian -> Sirqap

[ssokolow]

It never even occurred to me that tokio had anything to do with the city.

Since I generally stick to Django's mature ecosystem for network-related needs, and don't have much need for async outside that domain, aside from wanting generators so I can replicate design patterns I use in Python, I always assumed it was a portmanteau of some variation on the word "token" and I/O.

[placrosse]

What if RTFM just used the entire acronym and became RTFTM ?

It no longer matches the well-known "problem abbreviation" while sticking to @perlindgren 's full original name.

It is now unique, and search-engine friendly.

[burjui]

@placrosse RTFTM doesn't sound nearly as good. Anyway, personally, I find the reason for the renaming not convincing.

Firstly, "rust rtfm" works fine both in Google and DuckDuckGo. We, software engineers, are generally smart enough to add "rust" to the query when searching for a Rust project.

Secondly, there are always people too soft to take a joke, even if the joke is not designed to irritate anyone. This is a perfect example: obviously, the author of the project does not dislike the users to the point of sending them to read the documentation in such a rude form. I feel silly explaining it. Everyone understands that this is just a reference, but some people want attention, so they become offended by random stuff to get it.

Thirdly, renaming the project involves renaming it in documentation, source files, crate names and whatnot. To me it seems a big waste of time for no gain whatsoever.

All this talk about being welcoming and inclusive is mostly muddying the water, to be honest. You get code for free, it comes with documentation and examples, authors respond to comments and fix bugs. For me, it's quite welcoming. But okay, fine. Just change "masses" to "people" (or "ponies"), and RTFM will become RTFP. No more "confusion" and bad feelings.

[placrosse]

@burjui I agree with your points, and find the name fine as it is. There are plenty of acronyms with multiple meanings. I was simply offering a suggestion which would be a very minimal change, if one has to occur. Your suggestion is fine, but, like mine, also has all the negatives of renaming crates, changing code, etc. for something which may not end up as a gain at all.

[Bashe]

While writing that I also like & peffer the original name, it came to my mind that simplest acronym can be RRT (Rusty Real-Time)... or maybe R2RT (Rust to Real-Time) (wink wink to R2D2)... And then the mascot can become Ferris sitting in the R2D2 body... ;)

[japaric]

All the implementation work required for the v0.5 release has been completed and all the existing docs have been updated (PR rtfm-rs/cortex-m-rtfm#205 is ready to be merged).

Before we make a release we have to make a decision on this issue (and add user docs about the experimental multi-core API -- tracked in rtfm-rs/cortex-m-rtfm#227).

The potential solutions ordered by increasing implementation effort are:

a. Maintain the status quo (leave the project / crate name as it is)

b. Change only the acronym / crate name (e.g. RTftM, RTM, RTmass, etc.)

c. Change the name of the project and the acronym / crate name. There have been many proposals in this thread.

Options (b) and (c) are not a lot of work -- they are certainly much less work than the doc updates done in rtfm-rs/cortex-m-rtfm#205 -- and anyone can make a PR to update all the references to the old name.

@korken89 @perlindgren @texitoi we have heard several opinions in this thread. What do you think we should do?

I'm personally fine with either (a) and (b). I like the project name but never been much of a fan of the acronym though I can live with it. (c) sounds like it may take a while to make a decision on so if the decision is that acronym must go then I would pick option (b).

[jamwaffles]

Option (a.) please. I think we'd be giving up the momentum that the rtfm acronym has in the community for little to no benefit. I haven't seen any strong objections in this thread, although some good alternatives have been raised. If a name change is strongly desired, I'd prefer to move away from an acronym entirely (so option c.)

[dbrgn]

For the record, suggestions for alternative names in this thread:

• LOVE (Low OVerhead Embedded)
• mrt (Metal Real Time)
• bauble, sunjammer, juggler, implant, unos
• fearless
• kirquk, irqutsk, birqenhead, jirqov, kirqland, sirqap

Hope I didn't miss anything.

[TeXitoi]

I personally don't care. The faster the decision is taken, the better for me.

[korken89]

While I don't like the RTFM acronym, I agree with @jamwaffles - no strong objections has been given, even if there are a lot of alternatives. My general opinion is that we should postpone this until stronger motivations are given as RTFM is starting to get well known.

[korken89]

But one might also want to do this sooner rather than later, as the longer we wait the more cemented the RTFM acronym will be.

[perlindgren]

Taking a step back to the origins of Real Time For the Masses.

We (LTU) developed an extension to C, adding tasks, resources, synchronous and asynchrounous message passing, with timing semantics. The experimental compiler produced efficient executables and provided race free concurrency but suffered from the memory unsafety inherent to the C language.

This language extension was called rtfm-core, (as providing core functionality). On top of that we devised a memory safe (but very simple) object oriented language (rtfm-cOOre). The cOOre compiler translated the OO model into rtfm-core (later to be compiled into an executable).

While the core/cOOre languages served perfectly the purpose of an experimental testbed for language design and static real-time analysis, developing and maintaining new languages/frameworks takes a lot of effort and resources.

I came across Rust and started experimenting with different ways to leverage on the Rust ownership model. In that process I came across Japaric and arranged for Jorge to join LTU (issued a stipend for Masters studies, with courses, projects, and finally the Thesis work all related to Rust RTFM).

The first incarnation of Rust RTFM was type based (for checking soundness), while latter releases undertake a similar approach used in the original rtfm-core compiler. In fact, cortex-m-rtfm now implements most of the functionality of rtfm-core (still lacking some of the analysis regarding message queue size computations). But most importantly, Rust RTFM leverages on the Rust ownership model, programs in Rust RTFM are memory safe (so we don't need another language overlay like cOOre to get memory safety).

So what does this background story bring to the naming?

Well, we could piggy back on the heritage to rtfm-core. But that would still leave us with the "rtfm" part, which can be still seen as being offensive. One idea would be to drop the fm, leaving us with rt, but cortex-m-rt is already occupying that name. But rt-core could be an alternative (giving us the crate name cortex-m-rt-core. Yes its lengthy, but searches for just rt-core will likely get you there (on crates.io).

Also, I believe that rt-core associates well with the idea of providing core functionality for real-time application development (besides also adhering to the originating work on rtfm-core (the C extension discussed above).

rt can stand for Real-Time (and cut short as being part of a bigger picture Real-Time For the Masses). rt can stand for Resources and Tasks (reflecting the underlying model) rt-core is easy to pronounce, and sticks (I tried it on some random cats :).

Previously I suggested "Low OVerhead Embedded" (LOVE). While having a positive ring to it, it lacks the connection to the underlying model and prior work (so in comparison rt-core is a better alternative).

So should we change name? I have mixed feelings, RTFM has gained some traction, personally I find it amusing and it sticks, and objections are not that strong from what seen in this thread.

In case we decide on a crate name change, rt-core makes most sense IMHO.

Best regards / Per

[Bashe]

+1 on rt-core

[perlindgren]

A side note on rt-core. There is ongoing work exploring the potential of building further OS like abstractions on top of cortex-m-rtfm. Early results are very promising and indicate that current primitives provided by rtfm (rt-core or what we decide to name it), is sufficient.

We could even set the long term goal to merge rt and rt-core, as rt-core just provides safe abstractions over interrupts, exceptions, resources etc., and as such provides the lowest level, user facing abstraction need. /Per

[korken89]

rt-core seems quite good indeed - but how will it clash with cortex-m-rt?

[perlindgren]

The full crate name could be cortex-m-rt-core, so no real clash. Ideally we should merge in the functionality of cortex-m-rt into cortex-m-rt-core, since cortex-m-rt-core offers the lowest level of safe abstractions. If we really need an unsafe layer, cortex-m-rtshould be named cortex-m-rt-sys. (Following the idea of sys being unsafe bindings.)

Best Per

[korken89]

Indeed, more that it was overlapping with cortex-m-rt, but this I think is acceptable.

---

On the note on merging crates vs a sys crate, this is a matter for the Embedded WG - but we can raise the idea there.

[nickray]

Opinions: The "core" in rt-core is too generic to mean much, the rt (assuming it means real-time) clashes with rt as in run-time, and on the whole the naming seems to emphasize the real-time aspect too much. When I point people to RTFM, with the intent of advertising its merits as organisational principal, and light-weight scheduler making full use of hardware (the NVIC), the first response is always a tangential discussion about "you may not need real-time".

Summary: If the consensus is to change name (I personally see no reason), I think the perfect new name is still waiting to be discovered. I'd hope for something catchy :)

[perlindgren]

Hi @nickray and others, thanks for your input.

Regarding name, rt-core extends core with resources and tasks (as well as real-time).

Regarding you may not need real time I do believe that is a common misconception. As soon your application interacts with the environment, there are typically some real-time constraints involved. Say servicing a serial input (USART), the buffer will overflow (eventually) if your driver/application does not meet the timely requirements. I have yet to see some application that is free of such implicit timing requirements.

Elaborating on "real-time". What is the expected behavior and consequences of missing to meet the timing requirements? In a "hard real-time" setting, we consider the system to be at fault. In the best of worlds you have a design methodology/real-time kernel that allows you to assess the real-time properties at compile time and give guarantees to meeting the requirements. Guess what, RTFM gives you that (though the cortex-m-rtfm model still lacks the notions of inter-arrival of events and deadlines from the work on Real-Time For the Masses). The Rust re-implementation follows the same model, and the response time analysis has been experimentally implemented also in the Rust version (used/experimented on by students in courses at LTU).

Alternatively (and more commonly) the systems operate under soft real-time constraints, where failures merely imply a degraded quality of service. Also in this aspect RTFM shines, with its low overhead and to the point task and resource abstractions. However its actually harder to write applications which should gracefully handle failed timing requirements. Take the USART example above, if we have to be prepared for the case where we may loose USART data. Say the application is to de-serialize some incoming data, ooops, now we need a parser with error recovery and a protocol for re-sends. (The example is not fully watertight, you may argue that error recovery should be implemented for all communications, also in the case of hard real-time, but that depends wether the communication is considered a point of failure.) Well, in any case the point is - the seemingly simple case of soft-real time actually puts you as a designer in a troublesome situation, where you may assume essentially nothing and you should "do the best possible" in all such situations. This may imply data aging, adopting techniques for cost/benefit optimization, etc. Good thing is that RTFM gives you the tools to do that (even if its a much harder problem to solve than the "hard-real time" setting first discussed). Examples of using the base-line information for messages in order to optimize QoS is an interesting topic for demonstration and developing guidelines.

So for anything that goes beyond the scope of replicating an "arduino sketch", real-time cannot be slept on, although as you mention @nickray , the common (mis) conception is that you don't need real time.

Back to the original question about naming. I still think RTFM is a good enough acronym and that we can stick to cortex-m-rtfm for the release of version 5. If we encounter problems regarding uptake/acceptance due to the acronym, we can again re-consider the crate name.

Best regards Per

[perlindgren]

Sorry, my bad closed by mistake....

[burjui]

What you call a mistake is actually a reasonable thing to do. Sorry to say that, but none of the names proposed here are better. And the whole "problem" to start with is just a bunch of sissies feeling insecure about an acronym, which obviously can mean different things. Sorry for not being over-the-top PC, but I am much more interested in the code. The project is not called rtard or something even close to that, come on.

[korken89]

Well, there seems to be no consensus in changing the name - I hence propose that we do not change name and wait for better feedback on a name change.

cc @japaric @TeXitoi

[japaric]

Agree with @korken89. Since there's no strong push from the team to change the name and no strong proposal for a new name I formally propose to keep the name as it is for v0.5.0. Let's do the checkbox thing and give some time for people to express their thoughts:

• [x] @japaric
• [x] @korken89
• [x] @TeXitoi https://github.com/rtfm-rs/cortex-m-rtfm/issues/208#issuecomment-531584920
• [x] @perlindgren

[TeXitoi]

OK for me (on mobile, can't Rick)

[linuxtim]

Whilst I don't think RTFM is a terrible name, I can certainly see it harming adoption in some areas, and I agree that if the name is to be changed, then sooner the better.

Maybe it'd be good to leave this (or another issue) open to collect other possible names for a while, then after some time have a vote on the best replacement name, finally another vote on rtfm vs. favourite_new_name? Sounds a little convoluted but should be reasonably quick to carry out?

With that in mind, I'll throw a few into the ring. All are old ("middle") English words, which helps with the search-engine-namespacing issue to some extent.

Anwald (to rule or plan / in power / authority) Endent (a written agreement) Gidour (guide / ruler / protector)

[ssokolow]

Another option would be to change out the "F" for a "4" so that "Real-Time For the Masses" is written as "RT4M".

...or, if you want fewer existing Google results and more of a rhythm to its pronunciation, "RT4TM". (RT 4T M)

[perlindgren]

To further fuel the discussion:

ROST - Here we have R and T for Real-Time, and/or R refer to Resources, T for Tasks. The cool thing with that name is that ROST is the direct translation of Rust in Swedish (paying heritage to LTU/Sweden and Real-Time For the Masses). At some point we thought of implementing the ROS robot operating system in RTFM (with hard real-time guarantees) and name that ROST, but that is still on the TODO list.

TRust - Here we have R and T for Real-Time, and/or R refer to Resources, T for Tasks. It has a nice ring to it (although a bit overused in the Rust community, but likely not outside of it, so it should be Ok).

TRust indicates the kind of "trust" TRust would bring, memory safety of Rust + deadlock free concurrency, and even more, the kind of insurances we can offer by static analysis of the task/resource set. (The latter we have only scraped the surface so far.) Who would not want a scheduler they can TRust.

Note: The crate name trust is already taken by Jorge, we can offer to swap the crate names, he can have RTFM ;)

[japaric]

Plenty of time has been given for the final comment period so this RFC will now be closed. That is we will not change the project name or acronym for the v0.5.0 release.

However, there's still the possibility of changing the name in one of the futures minor releases (v0.6.0 or later). As others have suggested a poll seems like would be the most effective to pick a new name; then that new name can be turned into a concrete proposal (a proper RFC).

Thanks everyone for the input on this discussion.