Coding Style

Basically we follow the GNU Coding Standards. We define additional conventions for PUPA here.

Naming Conventions

All global symbols (i.e. functions, variables, types, and macros) must have the prefix pupa_ or PUPA_. The all capital form is used only by macros.

Functions

If a function is global, its name must be prefixed with pupa_ and must consist of only small letters. If the function belongs to a specific function module, the name must also be prefixed with the module name. For example, if a function is for file systems, its name is prefixed with pupa_fs_. If a function is for FAT file system but not for all file systems, its name is prefixed with pupa_fs_fat_. The hierarchy is noted this way.

After a prefix, a function name must start with a verb (such as get or is). It must not be a noun. Some kind of abbreviation is permitted, as long as it wouldn't make code less readable (e.g. init).

If a function is local, its name may not start with any prefix. It must start with a verb.

Variables

The rule is mostly the same as functions, as noted above. If a variable is global, its name must be prefixed with pupa_ and must consist of only small letters. If the variable belongs to a specific function module, the name must also be prefixed with the module name. For example, if a function is for dynamic loading, its name is prefixed with pupa_dl_. If a variable is for ELF but not for all dynamic loading systems, its name is prefixed with pupa_dl_elf_.

After a prefix, a variable name must start with a noun or an adjective (such as name or long) and it should end with a noun. Some kind of abbreviation is permitted, as long as it wouldn't make code less readable (e.g. i18n).

If a variable is global in the scope of a single file (i.e. it is declared with static), its name may not start with any prefix. It must start with a noun or an adjective.

If a variable is local, you may choose any shorter name, as long as it wouldn't make code less readable (e.g. i).

Types

The name of a type must be prefixed with pupa_ and must consist of only small letters. If the type belongs to a specific function module, the name must also be prefixed with the module name. For example, if a type is for OS loaders, its name is prefixed with pupa_loader_. If a type is for Multiboot but not for all OS loaders, its name is prefixed with pupa_loader_linux_.

The name must be suffixed with _t, to emphasize the fact that it is a type but not a variable or a function.

Macros

If a macro is global, its name must be prefixed with PUPA_ and must consist of only large letters. Other rules are the same as functions or variables, depending on whether a macro is used like a function or a variable.

Directory Hierarchy

I'm not sure... The directory hierarchy is the most difficult issue in PUPA. We must consider all of "arch-specific vs. generic", "cpu-specific vs. vendor-specific" and "native vs. emulation".

One possible idea is to have direcotries in parallel:

generic/
  dir/
    subdir1/
    subdir2/

i386/
  dir/
    subdir1/
    subdir2/

i386-pc/
  dir/
    subdir1/
    subdir2/

emu-i386/
  dir/
    subdir1/
    subdir2/

emu-i386-pc/
  dir/
    subdir1/
    subdir2/

Clearly that's too ugly. Another idea is similar to glibc:

generic/
  dir/
    subdir1/
    subdir2/

i386/
  common/
    dir/
      subdir1/
      subdir2/
  pc/
    dir/
      subdir1/
      subdir2/

emu/
  common/
    dir/
     subdir1/
     subdir2/
  i386/
    dir/
      subdir1/
      subdir2/
...

I don't know if that is really manageable!

Especially the emulation layer is complicated, because it depends not only on an architecture type (i.e. cpu and vendor) but also on an OS type on which it runs (e.g. GNU/Linux). So, a question is what name is appropriate, say, when a piece of emulation code depends on i386-pc and runs on GNU/Linux. emu/i386/pc/linux/? emu/linux/i386/pc/?

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.