Hi all, For the most part, we try to follow the Google C++ conventions. I don't think these existed when gem5/m5 was started, but we follow them pretty closely. For namespace names, see https://google.github.io/styleguide/cppguide.html#Namespace_Names.
I quite strongly would like to see the namespace for gem5 be *all lower case*. I'm looking at this purely from the point of view of a *new user*, not a developer (which is what we should do! there are *way* more gem5 users than developers). If we make everyone always use Gem5::<function> in their code, we will *never* be able to convince people to use the "gem5" branding in papers, documentation, blog posts, etc. I believe that if we make the *external* gem5 namespace a capital "G" we will be fundamentally changing the gem5 branding. We can have a conversation about changing the gem5 brand if we really want to, but that isn't this conversation. I am *strongly* against creating a namespace with a capital "G". This goes against our branding, goes against common namespace naming practices (in both the STL and Google's style), and it will confuse our users. Jason On Sun, May 2, 2021 at 4:23 PM Gabe Black via gem5-dev <[email protected]> wrote: > Hi Daniel, just about the panic, fatal, etc, macros, that's a pretty > sticky issue since those are so prevalent and are *nearly* > functions, except annoyingly it's very hard to capture line/file > information without using a macro. The way they are isn't ideal since they > are macros with simple names, but changing them would be really painful and > come with its own drawbacks. This is why I tried finding a way to make them > not macros, and I *almost* was able to. I don't have a solution right now, > but just wanted to point out that this is a bit trickier than, say, > changing M5_UNUSED to GEM5_UNUSED. > > Gabe > > On Sun, May 2, 2021 at 2:46 PM Daniel Carvalho via gem5-dev < > [email protected]> wrote: > >> Hello, devs, >> >> >> It's been over 2 weeks since the first mail, so I think it is safe to >> assume nobody else will vote. We have reached 3 votes in favor of "gem5", >> and 2 in favor of "Gem5". However, after going through the codebase and >> thinking thoroughly, I have decided to change my vote to "Gem5". The vast >> majority of namespaces in the codebase follow the PascalCase style, so it >> be one more thing breaking consistency; classes, enums and others would >> have to be renamed to enforce the lowercase rule, which would case even >> more conflicts; and some functions and sections of the code would become >> confusing due to the expected case of structures. Data for argumentation >> have been uploaded to the respective Jira issue. >> >> >> As changing my opinion means that the decision tips to the other >> possibility, it would be fair to extend voting a couple more days to give >> time for people to object, in case they were counting on the general census >> matching theirs. The deadline to vote is on **Wednesday, April 5th**. After >> that, the patches pending on this decision can resume. >> >> >> Finally, just to make sure we are on the same page, because I forgot to >> consider the function-like macros (fatal, panic, etc). the update for >> macros would rename them as GEM5_MACRO_NAME, instead of keeping >> GEM5_macro_name. That is, fatal -> GEM5_FATAL and so on. >> >> >> Regards, >> >> Daniel >> >> I still favor namespace gem5 - it'd be the "external external" API, i.e. >> we probably wouldn't be using it within src/ that much, and it would be >> used by other simulators... >> >> >> This is why I'm strongly in favor of lowercase gem5. When external >> projects link to gem5 (which is *going* to happen), I think it's much >> better to use the normative gem5 spelling. It would be very confusing for >> people to use Gem5 in the code but gem5 in documentation/papers. >> >> ``` >> class MyExternalObj: public gem5::SimObject >> { >> }; >> ``` >> >> Jason >> >> >> >> On Mon, Apr 19, 2021 at 6:40 AM Bobby Bruce via gem5-dev < >> [email protected]> wrote: >> >> Nothing gets software devs as engaged as when discussing naming >> conventions :). >> >> I vote for "gem5" (lowercase) namespace, with all caps MACROS, but my >> sole reason for this is I've grown to flinch whenever I see "Gem5", which I >> admit isn't the best argument. >> >> I echo Daniel's comment that I care more about having a rule and moving >> past this than what that rule should be. >> >> -- >> Dr. Bobby R. Bruce >> Room 2235, >> Kemper Hall, UC Davis >> Davis, >> CA, 95616 >> >> web: https://www.bobbybruce.net >> >> >> On Sun, Apr 18, 2021 at 3:44 PM Daniel Carvalho via gem5-dev < >> [email protected]> wrote: >> >> Overall, there are way more uses of "gem5" than "Gem5" in the codebase, >> and most of the instances that break the identity rule could be easily >> fixed; however, there are cases that generate inconvenience: classes >> starting with lowercase, and situations where gem5 is in the middle of the >> var name (like "haveGem5Extension") make the code harder to >> read/understand. In this sense, the uppercase version generates better >> code. >> >> >> I still favor namespace gem5 - it'd be the "external external" API, i.e. >> we probably wouldn't be using it within src/ that much, and it would be >> used by other simulators and within our SystemC bridge (more on that later) >> - however, since we already have some exceptions, it wouldn't be the end >> of the world having it start with a capital letter. >> >> >> In the end, I personally do not care about which approach is taken, but >> the decision taken must be taken as a community. Therefore, it would be >> nice if we could have participation from other contributors to make the >> final decision less susceptible to changes/complaints in the future. >> >> >> Regarding when to use it: >> IMHO (and not thoroughly thought out), all .cc and .hh and objects within >> src/ should be subject to the namespace. Objects declared there are >> declared and maintained by gem5. Because of that there would probably be >> very few instances of namespace resolution within src/, so we should keep >> avoiding "using namespace" and being verbose about it. Finally, we also >> probably want to encourage users to define their objects inside the gem5 >> namespace to make it less unlikely that they will give up on uploading >> their contributions due to the different styles, and the laziness to adapt >> code. This means that disturbance in user code would be minimal: they would >> simply add "namespace (G|g)em5 {" in the beginning and "} // namespace >> (G|g)em5" at the end, instead of multiple "(G)|gem5::" instances. >> >> >> Regards, >> >> Daniel >> For the record, if the namespaces you found using snake_case start with >> sc_, those are for systemc and are mandated by that standard. The one >> exception, sc_gem5, is one I made up which is closely associated with the >> other systemc namespaces and is named similarly to them for consistency. >> >> Gabe >> >> On Thu, Apr 15, 2021 at 1:51 AM Giacomo Travaglini < >> [email protected]> wrote: >> >> My vote goes to 1 and A as well >> >> My sole argument is consistency; in general I'd rather start a namespace >> with a lowercase. So that when we have something >> like a scope resolution we know we are dealing with a namespace and not a >> class. But that's off-topic. >> >> Namespace names are anyway not covered by our coding style, so it's >> probably worth adding an entry. >> >> https://www.gem5.org/documentation/general_docs/development/coding_style/ >> >> From a quick grep I can see most of our namespaces follow the PascalCase >> type, though there are some namespaces using snake_case convention. >> >> Giacomo >> >> > -----Original Message----- >> > From: Gabe Black via gem5-dev <[email protected]> >> > Sent: 15 April 2021 09:03 >> > To: gem5 Developer List <[email protected]> >> > Cc: Gabe Black <[email protected]> >> > Subject: [gem5-dev] Re: gem5 namespace >> > >> > My vote is for 1 and A. >> > >> > We have style rules for a reason, and that is because not following them >> > causes technical problems like name collisions, and makes it less >> obvious >> > when reading code what things are and what they're doing. It's a bit >> > hypocritical to say that we should follow style rules and completely >> ignore >> > the aesthetic rule when capitalizing GEM5_, but then say that the >> aesthetic >> > rule should win when dealing with the namespace. >> > >> > This is further inconsistent with the Gem5Internal namespace, the Gem5 >> > class in SCons, the Gem5Op instruction format used for ARM, and the >> > Gem5Imm constant used for ARM semihosting. It would also cause a >> collision >> > with any variable called gem5, a completely legal and reasonable name >> to use, >> > *especially* in code outside of gem5 which might be using it to refer to >> > something related to gem5 which it is interacting with. >> > >> > There are no other instances where we let superficial aesthetic >> conventions >> > like this overrule technical considerations. We don't add _tm to the >> end of >> > trademarked names, we don't call AtomicSimpleCPU the atomic simple CPU >> > since that's not a valid class name, and a hundred other examples of >> where >> > prose takes a back seat because this is not prose, this is a conceptual >> machine >> > people happen to be able to read. >> > >> > Our website is the place for branding and identity and marketing, our >> code is >> > not. >> > >> > Gabe >> > >> > On Wed, Apr 14, 2021 at 7:28 AM Jason Lowe-Power via gem5-dev <gem5- >> > [email protected] <mailto:[email protected]> > wrote: >> > >> > >> > Thanks for putting this all together, Daniel! >> > >> > My opinion is the same as yours: option 2 and macro A. >> > >> > One other thing we need to do is to standardize and document when >> > and where you need to use the gem5 namespace. For instance, do we need >> > to update *all* headers to be in the gem5 namespace? If not, when is an >> > object in the gem5 namespace and when it is not? What about `using >> > namespace gem5`? Can/must all .cc files include this? >> > >> > Since this is a relatively big change to the coding standards which >> > could cause significant frustration to our users, we should be sure to >> > document and standardize *before* we make any code changes. >> > >> > Cheers, >> > Jason >> > >> > >> > On Wed, Apr 14, 2021 at 6:48 AM Daniel Carvalho via gem5-dev >> > <[email protected] <mailto:[email protected]> > wrote: >> > >> > >> > Hello, devs, >> > >> > >> > >> > We currently have a recurring issue, which is the lack of a >> > gem5 namespace. >> > This generates collision with other libraries and user code. >> > >> > >> > >> > A Jira ticket has been created to point out the issue last year: >> > >> > >> > https://gem5.atlassian.net/jira/software/c/projects/GEM5/issues/G >> > EM5-730 >> > >> > >> > And this topic has been brought up a few times: >> > >> > >> > https://www.mail-archive.com/gem5- >> > [email protected]/msg37770.html >> > >> > https://gem5- >> > review.googlesource.com/c/public/gem5/+/40878 >> > >> > https://www.mail-archive.com/gem5- >> > [email protected]/msg36453.html >> > >> > >> > Finally, there were already patches that were consequences >> > of lack of a gem5 >> > namespace: >> > >> > >> > https://gem5- >> > review.googlesource.com/c/public/gem5/+/32175 >> > >> > https://gem5- >> > review.googlesource.com/c/public/gem5/+/40878 >> > >> > >> > A similar issue exists for macros, and an existing proposal to >> > solve it already >> > exists, which is to add a "GEM5_" prefix. It follows the coding >> > style, which >> > dictates that "preprocessor symbols (constants and macros) >> > should be all >> > caps with underscores": >> > >> > >> > >> > https://gem5.atlassian.net/jira/software/c/projects/GEM5/issues/G >> > EM5-912 >> > >> > >> > It does not seem to be controversial to add this namespace; >> > however, there is >> > still one blocker to greenlight its creation: what will be its >> > name. There are >> > no explicit rules regarding namespace naming; however, they >> > are typically >> > declared starting with an uppercase letter followed by >> > lowercase letters. So, >> > theoretically, gem5's namespace should be "Gem5". This, >> > however, conflicts >> > with gem5's identity: "“gem5” should always have a >> > lowercase “g”" >> > (see http://www.gem5.org/getting_started/). >> > >> > >> > >> > We should decide as a community what is the best approach >> > to take, so I'll >> > list the options and will request you to cast your votes. If you >> > would like >> > to add remarks to the discussion, feel free to do so. >> > >> > >> > >> > NAMESPACE: >> > >> > >> > 1 - namespace Gem5 {} >> > >> > >> > 2 - namespace gem5 {} >> > >> > >> > >> > MACROS: >> > >> > >> > A - GEM5_MACRO_NAME >> > >> > >> > B - gem5_MACRO_NAME >> > >> > >> > Personally, I think that identity precedes coding style, so >> > *option 2* should >> > be taken. Yet, in a slightly inconsistent manner, I would vote >> > for macro >> > *option A*. My argument being that it would be more >> > convenient to type it >> > with all caps, and that it would be implied from the identity >> > that it refers to >> > instances of the identity containing lowercase letters, which >> > is not the case >> > of "GEM5_". >> > >> > Best, >> > Daniel >> > >> > >> > _______________________________________________ >> > gem5-dev mailing list -- [email protected] <mailto:gem5- >> > [email protected]> >> > To unsubscribe send an email to [email protected] >> > <mailto:[email protected]> >> > %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s >> > >> > _______________________________________________ >> > gem5-dev mailing list -- [email protected] <mailto:gem5- >> > [email protected]> >> > To unsubscribe send an email to [email protected] >> > <mailto:[email protected]> >> > %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s >> >> IMPORTANT NOTICE: The contents of this email and any attachments are >> confidential and may also be privileged. If you are not the intended >> recipient, please notify the sender immediately and do not disclose the >> contents to any other person, use it for any purpose, or store or copy the >> information in any medium. Thank you. >> >> _______________________________________________ >> gem5-dev mailing list -- [email protected] >> To unsubscribe send an email to [email protected] >> %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s >> >> _______________________________________________ >> gem5-dev mailing list -- [email protected] >> To unsubscribe send an email to [email protected] >> %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s >> >> _______________________________________________ >> gem5-dev mailing list -- [email protected] >> To unsubscribe send an email to [email protected] >> %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s > > _______________________________________________ > gem5-dev mailing list -- [email protected] > To unsubscribe send an email to [email protected] > %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
_______________________________________________ gem5-dev mailing list -- [email protected] To unsubscribe send an email to [email protected] %(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
