Project:SELinux/CodingStyle

Our coding-style is based on the reference project StyleGuide.

Organization of code in .te files
When a policy module is adapted by Gentoo, but is available in the reference policy, then all changes made for Gentoo specifically (and not yet upstreamed) must be put at the end of the file, inside a  block. This is necessary so that the main file can be easily updated with upstream changes (no patch collisions). The coding style for the main document, and the large  block at the end, are the same. Treat them as two separate files.

When changes must be made inline (for instance to remove interface calls we do not want) comment out the interface calls and add a comment right above it startin with "Gentoo:", like so:

Gentoo-specific change in the policy

The type enforcement rules should have the following organization.

First, the declarations are provided. These are, in order:
 * 1) Boolean declarations (using the   block, for base policy)
 * 2) Tunable declarations (using the   blocks, for modular policy)
 * 3) Attribute declarations
 * 4) Type declarations

Next, the local policy rules are provided, in blocks ordered alphabetically by the domain (in case the policy module handles multiple domains), but with the "main" domain first, and ignoring unconfined domains.

The order inside the policy rules is as follows:
 * 1) Self rules, starting with the *capability* and *process* object classes
 * 2) Rules applicable to the objects owned by the module itself, sorted by object type alphabetically
 * 3) Calls to the kernel layer module, first the kernel module itself and then in alphabetical order
 * 4) Calls to the system layer module, in alphabetical order
 * 5) Calls to all other modules, in alphabetical order
 * 6) Build option blocks (using  )
 * 7) Conditional policy blocks (using  )
 * 8) Tunable policy blocks (using  )
 * 9) Optional policy blocks (using  )

Finally, unconfined access rules are added, following the same structure as the local policy rules.

Tunables
Tunables must be documented with the in-line documentation system, like so:

Using in-line documentation for tunables

Always start a boolean with the module name itself.

Please try to use boolean names that match the following use cases, if possible:
 * TODO

Attributes
TODO

Type declarations
TODO

Organization of code in .if files
Interface files should be organized as follows:
 * 1) Templates
 * 2) Domain related interfaces
 * 3) Role interfaces
 * 4) Run interfaces
 * 5) Domain transition interfaces
 * 6) Execution interfaces
 * 7) Transformation interfaces (which assign attributes to types), sorted alphabetically by primary object type or attribute
 * 8) Access interfaces
 * 9) Alphabetically by primary object type or attribute, then
 * 10) Increasing in access level (getattr, setattr, read, append, write, rw, create, filetrans, rename, delete, manage, relabelto, relabelfrom, relabel), then
 * 11) Access interface before dontaudit (if a   interface is added)
 * 12) Admin interfaces
 * 13) If multiple components are used, order alphabetically by component, with the "master" admin interface last
 * 14) Unconfined interface

Templates
Templates should always end with  in the name.

Domain related interfaces
A role interface is meant to be assigned to user domains and contain all the necessary privileges to work with and interact with a specific type.
 * The first argument must be the role, and the second argument the userdomain type.

A run interface is meant to be assigned to other domains (which can be user domains) and contains only the necessary privileges to execute and transition to the domain (including role privileges).
 * The first argument must be the domain type, and the second argument the role.
 * The interface must call the  interface

Example run interface

Transformation interfaces
TODO

Access interfaces
TODO

Organization of code in .fc files
The organization in the .fc files is as follows:
 * 1) Alphabetically by path, then
 * 2) Increasing in depth, then
 * 3) First regular expressions, and then exact matches