Ticket #2125 (new RFC)

Opened 3 years ago

Last modified 3 years ago

rename parrot.h to internals.h or private.h or equivalent

Reported by: pmichaud Owned by:
Priority: minor Milestone:
Component: core Version: master
Severity: low Keywords:
Cc: Language:
Patch status: Platform:

Description

Several lines at the beginning of parrot.h read:

/* Only parrot core files should include this file.
   Extensions should include <parrot/extend.h>.
   Programs embedding parrot should include <parrot/embed.h>.
*/

A far more effective approach would be to rename "parrot.h" to "internals.h" or "private.h" or something that makes it much more obvious that the contents are meant for internal use only. People looking to Parrot source code for examples of how to write PMCs, dynpmcs or dynops are unlikely to read the contents of parrot.h and see the warning.

Pm

Change History

Changed 3 years ago by jkeenan

Will this require a deprecation cycle?

Changed 3 years ago by whiteknight

That comment in parrot.h is misleading, and I've just pushed an update for it. parrot.h is often required in extending situations, because extend.h is woefully incomplete. We haven't taken any effort to make a separate extending API beyond the individual APIs of our various subsystems.

As for renaming the file, I don't think it brings us any benefit considering the amount of work involved. -1 from me, although I am happy to update any documentation that could be more clear.

Jim: This definitely would require a deprecation cycle.

Changed 3 years ago by whiteknight

  • priority changed from normal to minor
  • type changed from bug to RFC
  • version changed from 3.4.0 to master
  • component changed from none to core
  • severity changed from medium to low
Note: See TracTickets for help on using tickets.